forked from wangziqi/gongxue-base
154 lines
6.8 KiB
Markdown
154 lines
6.8 KiB
Markdown
# 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
|