# 数据中心 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。