xuelong
3dd5731751
- move the relational data center to MySQL and a standalone workbench\n- add Interface Center API credentials, policies, logs, and DBeaver SSH guidance\n- harden authentication and deployment while retiring unused management surfaces
129 lines
5.7 KiB
Markdown
129 lines
5.7 KiB
Markdown
# 数据中心 MySQL 与接口中心部署说明
|
||
|
||
## 已确定的系统边界
|
||
|
||
- PostgreSQL：继续保存账号、权限、图谱项目与 Schema 等系统元数据。
|
||
- FalkorDB：继续保存已发布知识图谱节点和关系。
|
||
- MySQL：只负责“数据中心”的关系型业务数据。
|
||
- 接口中心：只通过受控 HTTPS API 访问 MySQL 数据中心，不允许外部用户执行任意 SQL。
|
||
- DBeaver：仅供受信任的数据管理员通过 SSH 隧道管理 MySQL，使用独立 MySQL 用户和 `GRANT` 权限；不复用接口密钥，也不公开 MySQL 端口。
|
||
- SQL 控制台：生产默认只读；写入通过数据表页面执行，以保留记录级变更历史，物理删除始终禁止。
|
||
|
||
每个数据中心数据库都是真实 MySQL Database：中文名称只用于页面显示，英文数据库编码直接作为物理 MySQL 数据库名。前端数据中心的现有 URL、布局和 `/v1/admin/data-platform/*` 契约保持不变。
|
||
|
||
## 配置
|
||
|
||
关键环境变量：
|
||
|
||
```dotenv
|
||
DATA_MYSQL_URL=mysql://data_center:strong-password@mysql:3306/platform_control
|
||
DATA_MYSQL_REQUIRED=true
|
||
DATA_MYSQL_POOL_MIN_SIZE=2
|
||
DATA_MYSQL_POOL_MAX_SIZE=20
|
||
INTERFACE_API_SECRET=another-long-random-secret
|
||
DATA_MYSQL_DIRECT_ACCESS_ENABLED=false
|
||
MYSQL_HOST_BIND=127.0.0.1
|
||
MYSQL_PORT=3307
|
||
DATA_MYSQL_DIRECT_TRANSPORT=SSH 隧道（强制）
|
||
DATA_MYSQL_SSH_TUNNEL_REQUIRED=true
|
||
DATA_MYSQL_SSH_HOST=server.example.com
|
||
DATA_MYSQL_SSH_PORT=22
|
||
DATA_MYSQL_SSH_AUTH_METHOD=SSH 私钥 / SSH Agent
|
||
DATA_MYSQL_ADMIN_HOST=127.0.0.1
|
||
DATA_MYSQL_ADMIN_PORT=3307
|
||
DATA_MYSQL_ADMIN_ACCOUNT_POLICY=一人一号 · 单库授权 · 禁止 root
|
||
DATA_MYSQL_AUDIT_ENABLED=false
|
||
DATA_SQL_CONSOLE_WRITE_ENABLED=false
|
||
DATA_BACKUP_ENABLED=false
|
||
```
|
||
|
||
`MYSQL_HOST_BIND` 在生产环境必须保持 `127.0.0.1`。`DATA_MYSQL_DIRECT_ACCESS_ENABLED` 只表示管理员接入是否完成运维配置，不会开放端口；本项目不提供公开 MySQL 直连模式。只有数据库审计真实启用后，才把 `DATA_MYSQL_AUDIT_ENABLED` 改成 `true`。
|
||
|
||
应用会记录 API 调用、记录新增/修改/软删除以及 SQL 控制台的成功、失败和拒绝
|
||
事件；SQL 审计只保存语句 SHA-256，不保存可能包含敏感值的原文。DBeaver 绕过
|
||
应用，因此仍必须由数据库审计能力单独留痕，未完成前不得开放长期写权限。
|
||
|
||
生产 MySQL 开启 ROW Binlog、`sync_binlog=1` 与
|
||
`innodb_flush_log_at_trx_commit=1`，用于时间点恢复与事务落盘；加密备份脚本和
|
||
恢复要求见 `docs/DEPLOYMENT.md`。
|
||
|
||
`platform_control` 保存数据库目录、表定义、数据审计、接口客户端、密钥哈希、权限策略与接口调用日志。完整接口密钥不会保存，只保存带服务端 pepper 的 HMAC-SHA256 哈希。
|
||
|
||
## 首次部署
|
||
|
||
```bash
|
||
docker compose up -d mysql
|
||
docker compose up -d --build api
|
||
```
|
||
|
||
接口中心页面：`/admin/system/interfaces`。
|
||
|
||
页面以“服务器被访问”为方向：`DBeaver 管理接入`只给受信任的数据管理员展示 SSH 隧道参数，`HTTPS API`负责电脑、设备和业务系统的身份、密钥、最小权限与调用日志。接口中心不会主动连接外部数据库。
|
||
|
||
## DBeaver 安全连接
|
||
|
||
DBeaver 不使用 URL 模式直接填写服务器公网地址。按两组参数配置：
|
||
|
||
1. `SSH` 标签页：`Host/IP=服务器域名`、`Port=22`、认证方式使用私钥或 SSH Agent；
|
||
2. `Main` 标签页：`Server Host=127.0.0.1`、`Port=3307`、`Database=获授权数据库编码`；
|
||
3. 关闭 `Show all databases`；
|
||
4. 使用运维为当前人员签发的独立 MySQL 账号，禁止使用 `root` 和后端服务账号 `data_center`；
|
||
5. 默认只授予 `SELECT`，写入和结构修改权限按需临时授予。
|
||
|
||
运维人员可在服务器上创建或撤销独立账号：
|
||
|
||
```bash
|
||
./scripts/mysql_admin_account.sh create zhangsan tourism_data read
|
||
./scripts/mysql_admin_account.sh create lisi tourism_data write
|
||
./scripts/mysql_admin_account.sh revoke zhangsan
|
||
```
|
||
|
||
脚本只授予指定数据库权限：`read` 为 `SELECT/SHOW VIEW`，`write` 额外包含
|
||
`INSERT/UPDATE/DELETE`，不授予建库、删库、授权、文件或系统库权限；账号连续
|
||
失败 5 次锁定一天，密码 90 天过期。MySQL 端口仍必须绑定回环地址，账号的
|
||
`'%'` 主机范围不能替代网络隔离。
|
||
|
||
接口中心不会显示或复制 MySQL 密码。服务器安全组只允许受控来源访问 SSH 与 HTTPS，不开放 `3307`。
|
||
|
||
外部数据接口前缀：`/v1/openapi/data`。调用时使用：
|
||
|
||
```http
|
||
Authorization: Bearer YOUR_API_KEY
|
||
```
|
||
|
||
## 迁移旧数据中心
|
||
|
||
先预览，不写入：
|
||
|
||
```bash
|
||
python3 scripts/migrate_data_center_postgres_to_mysql.py
|
||
```
|
||
|
||
确认计划后执行：
|
||
|
||
```bash
|
||
python3 scripts/migrate_data_center_postgres_to_mysql.py --execute
|
||
```
|
||
|
||
如果目标 MySQL 中已存在同编码数据库，脚本默认拒绝覆盖。只有确认目标可以重建时才使用：
|
||
|
||
```bash
|
||
python3 scripts/migrate_data_center_postgres_to_mysql.py --execute --replace-target
|
||
```
|
||
|
||
迁移会保留记录 UUID、创建/更新时间、软删除状态和数据变更审计，从而避免实体引用失效；不会修改 PostgreSQL 源数据，也不会操作 FalkorDB 或知识图谱。
|
||
|
||
## 权限模型
|
||
|
||
一条接口策略包含：
|
||
|
||
1. 客户端（电脑、应用、合作方或设备）；
|
||
2. 数据库；
|
||
3. 数据表或全部表；
|
||
4. `metadata/read/create/update/delete` 动作；
|
||
5. 可读字段与可写字段；
|
||
6. 可选的行级 JSON 范围，例如 `{"district":"荔波县"}`；
|
||
7. 启用/停用状态。
|
||
|
||
接口客户端无法访问 `platform_control`、MySQL 系统库或其他业务数据库，也不能通过 API 执行 SQL。每次接口调用都会记录客户端、动作、资源范围、状态码、耗时和来源 IP。
|