chore: add cloud deployment templates

2026-07-01 20:09:02 +08:00
parent fa2c39119b
commit cc9b552684
13 changed files with 632 additions and 0 deletions
--- a/scripts/deploy/README.md
+++ b/scripts/deploy/README.md
@@ -0,0 +1,153 @@
+# tiku-supabase 云服务器部署说明
+
+本文档用于把当前仓库部署到云服务器，并和已经解析好的域名打通。仓库内只保存安全模板，真实密钥、数据库密码、支付密钥、短信密钥、对象存储密钥和 Gitea 部署凭证必须放在服务器 `/etc/tiku-saas/` 下，不能提交到 Git。
+
+## 域名规划
+
+建议先按下面 6 个域名落地：
+
+| 域名 | 用途 | 服务器转发 |
+| --- | --- | --- |
+| `api.tjszsb.com` | 自研业务 API，Taro/H5/小程序统一调用 | `127.0.0.1:8787` |
+| `app.tjszsb.com` | 学生 H5 题库端 | `/srv/tiku-saas/www/student` |
+| `admin.tjszsb.com` | 租户后台 H5 | `/srv/tiku-saas/www/tenant-admin` |
+| `console.tjszsb.com` | SaaS 平台后台 H5 | `/srv/tiku-saas/www/platform-admin` |
+| `supabase.tjszsb.com` | Supabase API gateway/Auth/Storage/PostgREST | Supabase gateway，通常是 `127.0.0.1:8000` |
+| `studio.tjszsb.com` | Supabase Studio 运维后台 | 仅允许固定 IP/VPN/内网访问 |
+
+`studio.tjszsb.com` 不建议裸露给公网。若必须临时开放，至少要加 Nginx IP 白名单、强密码、服务器防火墙和访问日志审计。
+
+## 服务器目录
+
+推荐使用固定目录，方便后续脚本和 AI 协作不漂移：
+
+```text
+/opt/tiku-saas/repo                 Git 工作副本
+/opt/tiku-saas/bin                  服务器本地执行脚本
+/srv/tiku-saas/www/student          学生端 H5 静态文件
+/srv/tiku-saas/www/tenant-admin     租户后台 H5 静态文件
+/srv/tiku-saas/www/platform-admin   平台后台 H5 静态文件
+/srv/tiku-saas/data                 运行期数据
+/srv/tiku-saas/backups              数据库和对象存储备份
+/etc/tiku-saas/deploy.env           部署脚本配置，含 Gitea 只读部署凭证
+/etc/tiku-saas/api.env              API 生产环境变量
+/etc/tiku-saas/worker.env           worker 生产环境变量
+/etc/tiku-saas/runtime-config/      三套 H5 公开运行时配置
+```
+
+建议创建独立低权限用户：
+
+```bash
+sudo useradd --system --create-home --shell /bin/bash deploy
+sudo mkdir -p /opt/tiku-saas/bin /srv/tiku-saas/www/student /srv/tiku-saas/www/tenant-admin /srv/tiku-saas/www/platform-admin /srv/tiku-saas/data /srv/tiku-saas/backups /etc/tiku-saas/runtime-config
+sudo chown -R deploy:deploy /opt/tiku-saas /srv/tiku-saas
+sudo chmod 750 /etc/tiku-saas
+```
+
+## 首次安装
+
+1. 安装基础组件：Docker、Docker Compose、Node.js 20+、Nginx、Certbot、Git、rsync、flock。
+2. 按 Supabase 官方 self-hosting Docker 文档部署 Supabase。生产必须启用 HTTPS 反向代理，Supabase 官方也要求生产自托管部署使用 HTTPS。
+3. 把本目录模板复制到服务器：
+
+```bash
+sudo mkdir -p /opt/tiku-saas/bin /etc/tiku-saas/runtime-config
+sudo cp scripts/deploy/bin/deploy.sh /opt/tiku-saas/bin/deploy.sh
+sudo cp scripts/deploy/env/deploy.env.example /etc/tiku-saas/deploy.env
+sudo cp scripts/deploy/env/api.env.example /etc/tiku-saas/api.env
+sudo cp scripts/deploy/env/worker.env.example /etc/tiku-saas/worker.env
+sudo cp scripts/deploy/runtime-config/h5-student.runtime-config.example.json /etc/tiku-saas/runtime-config/h5-student.runtime-config.json
+sudo cp scripts/deploy/runtime-config/h5-tenant-admin.runtime-config.example.json /etc/tiku-saas/runtime-config/h5-tenant-admin.runtime-config.json
+sudo cp scripts/deploy/runtime-config/h5-platform-admin.runtime-config.example.json /etc/tiku-saas/runtime-config/h5-platform-admin.runtime-config.json
+sudo chmod 700 /opt/tiku-saas/bin/deploy.sh
+sudo chmod 600 /etc/tiku-saas/*.env /etc/tiku-saas/runtime-config/*.json
+```
+
+4. 编辑 `/etc/tiku-saas/*.env` 和 `/etc/tiku-saas/runtime-config/*.json`，填入真实生产配置。
+5. 安装 systemd 服务：
+
+```bash
+sudo cp scripts/deploy/systemd/tiku-api.service /etc/systemd/system/tiku-api.service
+sudo cp scripts/deploy/systemd/tiku-worker.service /etc/systemd/system/tiku-worker.service
+sudo systemctl daemon-reload
+sudo systemctl enable tiku-api tiku-worker
+```
+
+6. 安装 Nginx 配置：
+
+```bash
+sudo cp scripts/deploy/nginx/tjszsb.com.conf.example /etc/nginx/sites-available/tiku-saas.conf
+sudo ln -s /etc/nginx/sites-available/tiku-saas.conf /etc/nginx/sites-enabled/tiku-saas.conf
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+7. 申请 HTTPS 证书：
+
+```bash
+sudo certbot --nginx -d api.tjszsb.com -d app.tjszsb.com -d admin.tjszsb.com -d console.tjszsb.com -d supabase.tjszsb.com -d studio.tjszsb.com
+```
+
+## Gitea 凭证
+
+优先推荐 SSH deploy key。若暂时使用 Gitea token，必须新建一个只读部署 token，并写入 `/etc/tiku-saas/deploy.env`，不要把 token 写进脚本、Git remote、命令历史或 README。
+
+已经在聊天、工单、截图里出现过的 token 都应当视为暴露，正式上云前请立即吊销并重新生成。
+
+`deploy.sh` 会通过临时 `GIT_ASKPASS` 给 `git clone/fetch` 提供账号和 token，避免 token 出现在 `git remote -v` 里。
+
+## 更新发布
+
+服务器上执行：
+
+```bash
+sudo -u deploy /opt/tiku-saas/bin/deploy.sh
+```
+
+脚本会执行：
+
+1. 获取 `main` 最新代码。
+2. `npm ci` 安装锁定依赖。
+3. 运行仓库安全扫描和生产上线门禁测试。
+4. 构建 API、worker、学生 H5、租户后台 H5、平台后台 H5。
+5. 用 `rsync --delete` 发布静态产物。
+6. 复制服务器本地 `runtime-config.json` 到对应 Web 根目录。
+7. 重启 `tiku-api` 和 `tiku-worker`。
+8. 输出当前发布的 Git commit。
+
+## 上线前检查
+
+每次正式放量前至少执行：
+
+```bash
+npm run security:repo
+node scripts/production-launch-gate-test.js
+node scripts/launch-persona-smoke-test.js
+npm run readiness:production
+```
+
+接入真实生产配置后，还要在服务器上补跑：
+
+```bash
+npm run readiness:production:db
+npm run smoke:auth:remote
+npm run perf:api:local
+```
+
+压测必须在目标云服务器、目标数据库参数、目标对象存储和目标 Nginx 配置下重新计算，本地 Windows 压测数据只能作为开发参考。
+
+## 关键安全要求
+
+- 前端只保存 `supabasePublishableKey`，严禁出现 service role、数据库密码、短信密钥、支付私钥。
+- 自研业务 API 默认只接受 Supabase JWT 或迁移期受控 app session，不允许前端携带平台管理密钥。
+- API、worker、Supabase、Nginx 日志要开启轮转，避免磁盘被日志打满。
+- 数据库至少每日备份，正式放量前要完成一次恢复演练。
+- 支付回调、短信回调、对象存储回调必须使用 HTTPS 域名，并在 API 层校验签名和租户归属。
+- Supabase Studio 必须限制访问来源。
+
+## 参考
+
+- Supabase self-hosting Docker: https://supabase.com/docs/guides/self-hosting/docker
+- Supabase reverse proxy and HTTPS: https://supabase.com/docs/guides/self-hosting/self-hosted-proxy-https
+- Supabase Auth self-hosting config: https://supabase.com/docs/guides/self-hosting/auth/config
+- Supabase self-hosted S3 storage: https://supabase.com/docs/guides/self-hosting/self-hosted-s3