lunanting/cangku
1
0
Fork 1
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
cangku/remote-access/README.md

4.3 KiB
Raw Blame History

远程系统数据库部署

本项目的本地实例可以通过部署 Key 注册到中央运行环境。注册服务为每台设备创建独立的系统数据库账号、Redis ACL 账号和应用管理员，并签发短期 MySQL SSH 隧道证书；MySQL 继续只监听服务器回环地址，Redis 通过公网 TLS 端口提供服务。

本地使用

需要 Node.js 22、npm 和 OpenSSH 客户端。首次运行：

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 在终端中完成同一注册流程。

仅启动数据库隧道：

npm run remote:tunnel

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

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：

dns_cloudflare_api_token = <仅 DNS 编辑权限的 Token>

文件权限必须为 0600、所有者为 root。然后以 root 依次运行 provision-certificate.sh 和 install.sh；Certbot 会使用 DNS-01 验证并由系统定时器自动续期。该文件绝不能提交到 Git。

服务器使用 cangku-bootstrap systemd 服务、独立的受限 MySQL 发号账号和 SSH 用户证书 CA。常用命令：

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 证书在到期前仍可能建立受限隧道，但不能再登录系统数据库。