Appearance
连接配置 · 使用说明（小白向）
本文说明：在天幕低代码里如何配置业务数据库连接，供数据模型、动态 API、自定义 API 使用。
适合：第一次建项目的数据库管理员、实施同学、后端开发。
关联：数据模型-使用说明 · 服务配置-使用说明
阅读建议
| 你是谁 | 建议先看 |
|---|---|
| 完全新手 | 第 2 章名词 → 第 4 章 5 分钟上手 |
| 本地 MySQL 开发 | 第 5.1 节本机连接 |
| 连接失败排查 | 第 9 章 FAQ |
1. 一句话
连接配置 = 告诉天幕平台「你的业务数据在哪个数据库、用什么账号连」。
配置好并激活后，才能在数据模型里同步表结构、发布动态 API。
text
连接配置（连哪台库）
↓
数据模型（表结构元数据）
↓
动态 API / 自定义 API（对外接口）2. 名词解释
| 名词 | 通俗解释 |
|---|---|
| 连接配置 | 一条数据库连接记录，含主机、端口、库名、账号等。 |
| 连接名称 | 给人看的别名，如「本地开发库」「生产 MySQL」。 |
| 连接类型 | MySQL、PostgreSQL、Oracle 等。动态 API 目前以 关系型库 为主。 |
| 未激活 / 已激活 / 异常 | 未激活=仅保存未启用；已激活=可用于数据模型；异常=最近一次测试失败。 |
| 测试连接 | 平台用 JDBC 临时连一次库，验证账号密码是否正确。 |
| 连接池 | 动态 API 运行时复用连接；参数 poolMin / poolMax 等在此配置。 |
| 平台创建库 | 保存连接时，若库不存在，可询问是否在服务器上自动建库（MySQL/MariaDB/PostgreSQL）。 |
3. 入口在哪里？
路径：项目 → 服务器管理 → 连接配置
页面顶部说明：管理数据库连接，支持多数据源、加密存储、连接池；本机 MySQL 建议主机填 127.0.0.1，无密码可留空。
4. 五分钟上手（本地 MySQL）
步骤 1：新建连接
- 点击 新建连接。
- 填写：
| 字段 | 示例 | 说明 |
|---|---|---|
| 连接名称 | 本地业务库 | 必填 |
| 连接类型 | MySQL | 下拉选择 |
| 连接方式 | 标准连接 | 一般选标准 |
| 主机地址 | 127.0.0.1 | 不要用 localhost 可避免部分 socket 问题 |
| 端口 | 3306 | 随类型自动带出默认端口 |
| 数据库名称 | my_shop | 业务库名 |
| 用户名 | root | |
| 密码 | （可留空） | 本地无密码 MySQL 可空 |
- 高级（可选）：字符集
utf8mb4、时区+08:00、连接池最小 2 / 最大 10。
步骤 2：测试连接
点击 测试连接。成功会显示延迟、数据库版本；失败请看错误信息（账号、库不存在、防火墙等）。
步骤 3：保存
点击 确定 保存。
- 若库不存在且类型支持自动建库，会弹窗询问是否创建；确认后平台在服务器上建库。
- 若库已存在，可能提示「将使用该数据库进行后续数据模型与动态 API」。
步骤 4：激活
列表中找到该连接 → 激活（或保存后状态变为已激活）。
只有已激活的连接才能被数据模型绑定。
步骤 5：下一步
进入 数据模型-使用说明，从数据源同步或新建模型。
5. 表单字段详解
5.1 标准连接（最常用）
| 字段 | 必填 | 说明 |
|---|---|---|
| 连接名称 | 是 | 项目内唯一，便于识别 |
| 连接类型 | 是 | MySQL / PostgreSQL / Oracle / SQL Server / SQLite / MariaDB 等 |
| 主机 / 端口 | 是 | 数据库服务器地址 |
| 数据库名称 | 是 | 要使用的 schema / database |
| Schema | 否 | PostgreSQL 等可能需要 |
| 用户名 / 密码 | 用户名必填 | 密码加密存储，编辑时留空表示不修改 |
| 使用 SSL | 否 | 按需开启 |
5.2 连接 URL 方式
选择 连接URL 后，可粘贴完整连接串，例如：
text
mysql://user:pass@host:3306/my_database适合运维已提供标准 URL 的场景。
5.3 SSH 隧道
选择 SSH隧道 时，需填 SSH 主机、端口、认证方式及数据库相对 SSH 的内网地址。
适用于数据库不对外网开放、只能通过跳板机访问的情况。
5.4 连接池参数
| 参数 | 默认 | 含义 |
|---|---|---|
| poolMin | 2 | 最小空闲连接 |
| poolMax | 10 | 最大连接数 |
| poolIdleTimeout | 30000 ms | 空闲回收时间 |
| poolAcquireTimeout | 60000 ms | 获取连接超时 |
动态 API 高并发时可适当调大 poolMax，需与 DBA 确认数据库 max_connections。
6. 列表操作说明
| 操作 | 作用 |
|---|---|
| 编辑 | 修改连接信息；改密码需填新密码 |
| 测试连接 | 即时验证，不改变激活状态 |
| 激活 / 停用 | 控制是否可用于数据模型 |
| 删除 | 删除连接记录；若库为平台创建，可能询问是否同步删除物理库 |
| 筛选 | 按名称、类型、状态过滤 |
7. 与后续模块的关系
| 模块 | 依赖连接配置 |
|---|---|
| 数据模型 | 每个模型必须绑定一条已激活连接 |
| 动态 API | 运行时通过模型的连接访问业务表 |
| 自定义 API（输出组装） | 查询计划需指定连接与库 |
| API 编排 | HTTP 节点可调用动态 API，间接依赖连接 |
注意：连接配置不是对外 HTTP 接口地址；对外地址在动态 API / 自定义 API 发布后出现。
8. 安全建议
- 生产环境使用专用只读/读写账号，不要用 root。
- 密码仅存在平台侧加密字段，勿在聊天里明文传播。
- 平台管理控制台账号 ≠ 业务库账号。
- 若连接泄露，在数据库侧改密并回平台更新连接。
9. 常见问题（FAQ）
9.1 测试连接成功，但数据模型同步失败？
- 确认连接状态为 已激活。
- 确认库中确有目标表，或有权 CREATE TABLE（同步建表时）。
- PostgreSQL 检查 schema 是否正确。
9.2 127.0.0.1 和 localhost 有区别吗？
本机 MySQL 有时 localhost 走 Unix Socket，127.0.0.1 走 TCP；连不上时可互换试一下。
9.3 Redis / MongoDB 能用于动态 API 吗？
连接类型列表中可能有这些选项，但动态 API CRUD 当前面向 JDBC 关系型库。NoSQL 连接预留扩展，请以实际版本能力为准。
9.4 一个项目可以配多个连接吗？
可以。不同数据模型可绑定不同连接（多数据源）。
9.5 改连接会影响已发布的 API 吗？
改 host、库名等可能导致运行时连错库；改后建议 重新发布 相关数据模型并做试调。
9.6 删除连接时提示物理库？
仅当该库是平台 自动创建 且库名未改时，才可能询问是否删除服务器上的库；生产库请谨慎确认。
10. 推荐阅读顺序
修订记录
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-05-22 | 初版：连接配置小白向使用说明 |