# 远程系统数据库部署

本项目的本地实例可以通过部署 Key 注册到中央系统数据库。注册服务为每台设备创建独立数据库账号并签发短期 SSH 隧道证书；MySQL 继续只监听服务器回环地址。

## 本地使用

需要 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 不会保存。成功后，数据库凭据写入被 Git 忽略的 `backend/.env`，SSH 私钥和证书写入 `.remote-access/`，文件权限仅限当前用户。

注册服务会在中央系统数据库中创建一个独立管理员。弹窗只显示一次管理员账号和随机密码，开发者必须立即保存；服务端不保存可再次查看的密码明文。

开发模式同时启动后端和前端。首次注册成功后，启动器会自动建立隧道并重启后端。没有浏览器时，可用 `npm run remote:setup` 在终端中完成同一注册流程。

仅启动数据库隧道：

```bash
npm run remote:tunnel
```

生产构建完成后，可启动隧道及后端：

```bash
npm run remote:start
```

默认本地数据库隧道端口为 `13307`，如被占用，可在注册前设置 `CANGKU_LOCAL_DB_PORT`。重新注册需使用 `npm run remote:setup -- --replace`，旧配置会改名备份；管理员还应在服务器停用旧设备。

## 权限和密钥边界

- 部署 Key 只用于设备注册，具有有效期和使用次数限制，不在仓库及本地配置中保存。
- 每台设备获得独立数据库用户名和密码，可单独停用。账号只能访问 `cangku_system`，不能访问服务器的其他数据库或管理数据库用户。
- 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 或数据库密码。Key 明文仅在创建时输出一次。停用设备会删除它的数据库账号；已签发的 SSH 证书在到期前仍可能建立受限隧道，但不能再登录系统数据库。