67 lines
4.3 KiB
Markdown
67 lines
4.3 KiB
Markdown
# 远程系统数据库部署
|
||
|
||
本项目的本地实例可以通过部署 Key 注册到中央运行环境。注册服务为每台设备创建独立的系统数据库账号、Redis ACL 账号和应用管理员，并签发短期 MySQL SSH 隧道证书；MySQL 继续只监听服务器回环地址，Redis 通过公网 TLS 端口提供服务。
|
||
|
||
## 本地使用
|
||
|
||
需要 Node.js 22、npm 和 OpenSSH 客户端。首次运行：
|
||
|
||
```bash
|
||
npm --prefix backend ci
|
||
npm --prefix frontend ci
|
||
npm run remote:dev
|
||
```
|
||
|
||
首次执行 `npm run remote:dev` 后，浏览器会显示首次启动弹窗。填写 `https://ck.yydd.ai:8443/v1/enroll` 和管理员发放的部署 Key，然后点击“保存并获取配置”。Key 不会保存。成功后，系统数据库与 Redis 凭据写入被 Git 忽略的 `backend/.env`，SSH 私钥和证书写入 `.remote-access/`，文件权限仅限当前用户。
|
||
|
||
注册服务会在中央系统数据库中创建一个独立管理员，并把托管环境标记为已完成配置。弹窗只显示一次管理员账号和随机密码，开发者必须立即保存；服务端不保存可再次查看的密码明文。使用该管理员登录后直接进入系统，不再显示业务数据库、Redis、登录方式和对象存储配置向导。
|
||
|
||
开发模式同时启动后端和前端。首次注册成功后，启动器会自动建立隧道并重启后端。没有浏览器时，可用 `npm run remote:setup` 在终端中完成同一注册流程。
|
||
|
||
仅启动数据库隧道：
|
||
|
||
```bash
|
||
npm run remote:tunnel
|
||
```
|
||
|
||
生产构建完成后，可启动隧道及后端：
|
||
|
||
```bash
|
||
npm run remote:start
|
||
```
|
||
|
||
默认本地数据库隧道端口为 `13307`，如被占用，可在注册前设置 `CANGKU_LOCAL_DB_PORT`。Redis 直接使用注册接口返回的 `ck.yydd.ai:6380` TLS 地址。重新注册需使用 `npm run remote:setup -- --replace`，旧配置会改名备份；管理员还应在服务器停用旧设备。
|
||
|
||
## 权限和密钥边界
|
||
|
||
- 部署 Key 只用于设备注册，具有有效期和使用次数限制，不在仓库及本地配置中保存。
|
||
- 每台设备获得独立数据库用户名和密码，可单独停用。账号只能访问 `cangku_system`，不能访问服务器的其他数据库或管理数据库用户。
|
||
- 每台设备获得独立 Redis ACL 用户，只允许执行应用缓存所需命令；公网端口强制 TLS，密码不会提交到 Git。
|
||
- SSH 证书只允许登录 `cangku-tunnel`，该账号不能打开终端，只能把本地端口转发至服务器的 `127.0.0.1:3307`。
|
||
- SSH 主机密钥由注册服务固定下发并校验；注册接口使用 `ck.yydd.ai:8443` 的公开可信 HTTPS 证书，证书由 Certbot 定时任务自动续期。
|
||
- 本地实例设置 `CLOUD_DB_RUNTIME_PROFILE=public`，从中央系统数据库读取已配置的第三方公网数据库连接。
|
||
- 本地实例关闭后台同步任务，避免多台开发机重复执行定时同步。
|
||
|
||
数据库账号在 `cangku_system` 内拥有应用运行所需权限，包括表结构操作；它没有其他数据库权限，也没有 `GRANT OPTION` 或创建用户权限。只有受信任的开发者才能获得部署 Key。本地设备一旦失陷，设备账号和第三方数据库连接配置可能泄露，应立即由管理员停用该设备。
|
||
|
||
## 服务器管理
|
||
|
||
首次配置 `ck.yydd.ai` 的正式证书时，管理员需在服务器创建 `/etc/cangku-tls/cloudflare.ini`，内容为 Cloudflare 最小权限 API Token：
|
||
|
||
```ini
|
||
dns_cloudflare_api_token = <仅 DNS 编辑权限的 Token>
|
||
```
|
||
|
||
文件权限必须为 `0600`、所有者为 root。然后以 root 依次运行 `provision-certificate.sh` 和 `install.sh`；Certbot 会使用 DNS-01 验证并由系统定时器自动续期。该文件绝不能提交到 Git。
|
||
|
||
服务器使用 `cangku-bootstrap` systemd 服务、独立的受限 MySQL 发号账号和 SSH 用户证书 CA。常用命令：
|
||
|
||
```bash
|
||
sudo cangku-bootstrapctl list
|
||
sudo cangku-bootstrapctl create-key --label team --max-uses 20 --days 30
|
||
sudo cangku-bootstrapctl revoke-key <KEY_ID>
|
||
sudo cangku-bootstrapctl revoke-installation <INSTALLATION_ID>
|
||
```
|
||
|
||
`list` 不显示 Key、数据库密码或 Redis 密码。Key 明文仅在创建时输出一次。停用设备会删除它的数据库账号与 Redis ACL 用户并禁用应用管理员；已签发的 SSH 证书在到期前仍可能建立受限隧道，但不能再登录系统数据库。
|