xiongyuxing/gongxue-base

Fork 0

forked from wangziqi/gongxue-base

Files

Codex 9e5bfa0fdb docs: add PNVS deployment handoff notes

2026-07-03 23:05:07 +08:00

14 KiB

Raw Blame History

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 协作不漂移：

/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 公开运行时配置

建议创建独立低权限用户：

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

宝塔服务器实际落地记录

2026-07-01 首次上云使用的是 Alibaba Cloud Linux 3 + 宝塔面板环境。该服务器的 80/443 已由宝塔 Nginx 接管，主配置不在 /etc/nginx，而在：

/www/server/nginx/conf/nginx.conf
/www/server/panel/vhost/nginx/*.conf

因此在这类服务器上不要执行 systemctl start nginx、不要写 /etc/nginx/sites-available，也不要覆盖宝塔生成的站点配置。宝塔 Nginx 的测试和重载命令是：

/www/server/nginx/sbin/nginx -t -c /www/server/nginx/conf/nginx.conf
/www/server/nginx/sbin/nginx -s reload

本次保留企业目录隔离方案：

/opt/tiku-saas/repo        Gitea 工作副本
/opt/tiku-saas/bin         服务器部署脚本
/srv/tiku-saas/www         H5 发布产物
/srv/tiku-saas/data        运行数据
/srv/tiku-saas/backups     备份
/etc/tiku-saas             真实 env、Gitea token、运行时配置

宝塔新增站点时会拦截 /srv 作为网站根目录。不要因此把密钥、仓库或运行数据搬进 /www。只为 H5 静态站点创建 /www/wwwroot 下的软链接：

mkdir -p /www/wwwroot/tiku-saas
ln -sfn /srv/tiku-saas/www/student /www/wwwroot/tiku-saas/student
ln -sfn /srv/tiku-saas/www/tenant-admin /www/wwwroot/tiku-saas/tenant-admin
ln -sfn /srv/tiku-saas/www/platform-admin /www/wwwroot/tiku-saas/platform-admin
chown -h deploy:deploy /www/wwwroot/tiku-saas/student
chown -h deploy:deploy /www/wwwroot/tiku-saas/tenant-admin
chown -h deploy:deploy /www/wwwroot/tiku-saas/platform-admin

宝塔面板中新增三个纯静态站点：

域名	宝塔根目录
`app.tjszsb.com`	`/www/wwwroot/tiku-saas/student`
`admin.tjszsb.com`	`/www/wwwroot/tiku-saas/tenant-admin`
`console.tjszsb.com`	`/www/wwwroot/tiku-saas/platform-admin`

每个站点需要保留 H5 history fallback，并禁止缓存公开运行时配置：

location / {
    try_files $uri $uri/ /index.html;
}

location = /runtime-config.json {
    add_header Cache-Control "no-store" always;
    try_files $uri =404;
}

当前服务器已经验证过的基础环境：

Node.js: v20.20.2，系统级安装在 /usr/bin/node，deploy 用户可用
npm: 10.8.2，deploy 用户可用
Docker: 26.1.3
Docker Compose: v2.27.0
Nginx: 宝塔 /www/server/nginx/sbin/nginx，1.30.1

不要使用 root 的 nvm Node 路径作为生产运行时。若 deploy 用户看不到 Node/NPM，应安装系统级 NodeSource Node.js 20：

curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
dnf install -y nodejs
sudo -u deploy bash -lc 'command -v node; command -v npm; node -v; npm -v'

大陆服务器 npm ci 可能访问 npm 官方源超时。本次部署在 /etc/tiku-saas/deploy.env 中使用可配置 npm registry 和重试参数：

NPM_REGISTRY=https://registry.npmmirror.com
NPM_FETCH_RETRIES=5
NPM_FETCH_RETRY_MINTIMEOUT=20000
NPM_FETCH_RETRY_MAXTIMEOUT=120000
NPM_FETCH_TIMEOUT=300000

截至 2026-07-01 21:39，sudo -u deploy /opt/tiku-saas/bin/deploy.sh 已完成：

Gitea main 拉取到 /opt/tiku-saas/repo。
npm ci 安装依赖。
npm run security:repo，结果 0 finding。
node scripts/production-launch-gate-test.js，通过。
API 和 worker 构建通过。
学生端、租户后台、平台后台三套 Taro H5 构建通过。
H5 发布到 /srv/tiku-saas/www/student、/srv/tiku-saas/www/tenant-admin、/srv/tiku-saas/www/platform-admin。
三个 runtime-config.json 已安装到各自 H5 根目录。

Taro H5 构建存在 webpack asset size warning，这是前端包体优化事项，不影响当前部署继续进行。后续可做拆包、按需加载和 KaTeX 字体裁剪。

服务器接管和故障恢复

2026-07-03 最新接管状态：

Gitea main 已包含 PNVS 短信认证、后台登录修复和旧题库视觉对齐版本，最新提交应至少是 8f69838。
服务器仓库仍在 /opt/tiku-saas/repo，归属用户应为 deploy:deploy。
生产 API 已能启动，https://api.tjszsb.com/api/tenant/resolve?host=app.tjszsb.com 已返回 master 租户。
Supabase self-hosted 运行在 /opt/tiku-saas/supabase-project，Kong 通过 Nginx 暴露到 https://supabase.tjszsb.com。
线上 H5 公开配置文件在 /srv/tiku-saas/www/*/runtime-config.json，密钥只允许放 supabasePublishableKey 这类公开 key。
短信登录推荐生产使用 AUTH_SMS_PROVIDER=aliyun-pnvs。阿里云 AccessKey/Secret 只写入 app_private.tenant_secrets(secret_scope='sms', secret_key='aliyun-pnvs')，不要写进 /etc/tiku-saas/api.env 或 H5 runtime-config.json。

接管服务器时先做只读检查：

cd /opt/tiku-saas/repo
sudo -u deploy git status --short
sudo -u deploy git log -3 --oneline
sudo -u deploy git remote -v
systemctl status tiku-api --no-pager -l
systemctl status tiku-worker --no-pager -l
docker compose -f /opt/tiku-saas/supabase-project/docker-compose.yml ps

Gitea SSH 使用 2222 端口，推荐服务器 deploy 用户的 remote 使用完整 SSH URL：

sudo -u deploy git -C /opt/tiku-saas/repo remote set-url origin ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git
sudo -u deploy ssh -o BatchMode=yes -T -p 2222 git@git.gongxue100.com
sudo -u deploy git -C /opt/tiku-saas/repo pull origin main

也可以写 /home/deploy/.ssh/config，但必须包含 Port 2222：

Host git.gongxue100.com
  HostName git.gongxue100.com
  User git
  Port 2222
  IdentityFile /home/deploy/.ssh/tiku_saas_deploy
  IdentitiesOnly yes

如果 Taro 构建长时间没有输出，先判断它是真在编译还是已经卡死。构建中的 Taro/webpack 可能会有一段时间安静，但如果 dist 目录大小和最近修改时间 30 秒以上都不变，就按卡住处理：

ps -eo pid,ppid,user,stat,etime,%cpu,%mem,cmd | grep -E 'npm|node|taro|webpack' | grep -v grep
du -sh /opt/tiku-saas/repo/apps/taro/dist/h5-student
sleep 30
du -sh /opt/tiku-saas/repo/apps/taro/dist/h5-student
find /opt/tiku-saas/repo/apps/taro/dist/h5-student -type f -mmin -5 | head -20

确认卡住后，先在原终端 Ctrl+C。如果仍有残留 Taro 构建进程，再只结束这条构建链路，不要杀生产 API、Supabase 或其它 Node 服务：

ps -eo pid,ppid,user,stat,etime,%cpu,%mem,cmd | grep -E 'npm run build:taro|taro build --type h5|webpack' | grep -v grep
kill <pid>
sleep 3
kill -9 <pid>

然后清理单端产物并带 CI/内存参数重跑。先单独跑学生端，成功后再跑另外两端：

cd /opt/tiku-saas/repo
rm -rf apps/taro/dist/h5-student
sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:student

rm -rf apps/taro/dist/h5-tenant-admin apps/taro/dist/h5-platform-admin
sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:tenant
sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:platform

三端构建成功后再发布：

sudo -u deploy /opt/tiku-saas/bin/deploy.sh

如果只是想接管代码开发，不要从服务器 apps/taro/dist 或 /srv/tiku-saas/www 拷贝产物；它们只是发布结果，源码以 Gitea main 为准。

首次安装

安装基础组件：Docker、Docker Compose、Node.js 20+、Nginx、Certbot、Git、rsync、flock。
按 Supabase 官方 self-hosting Docker 文档部署 Supabase。生产必须启用 HTTPS 反向代理，Supabase 官方也要求生产自托管部署使用 HTTPS。
把本目录模板复制到服务器：

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

编辑 /etc/tiku-saas/*.env 和 /etc/tiku-saas/runtime-config/*.json，填入真实生产配置。
安装 systemd 服务：

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

安装 Nginx 配置：

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

申请 HTTPS 证书：

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 里。

更新发布

服务器上执行：

sudo -u deploy /opt/tiku-saas/bin/deploy.sh

脚本会执行：

获取 main 最新代码。
npm ci 安装锁定依赖。
运行仓库安全扫描和生产上线门禁测试。
构建 API、worker、学生 H5、租户后台 H5、平台后台 H5。
用 rsync --delete 发布静态产物。
复制服务器本地 runtime-config.json 到对应 Web 根目录。
重启 tiku-api 和 tiku-worker。
输出当前发布的 Git commit。

上线前检查

每次正式放量前至少执行：

npm run security:repo
node scripts/production-launch-gate-test.js
node scripts/launch-persona-smoke-test.js
npm run readiness:production

接入真实生产配置后，还要在服务器上补跑：

npm run readiness:production:db
npm run smoke:auth:remote
SMS_SMOKE_API_BASE_URL=https://api.tjszsb.com SMS_SMOKE_TENANT_ID=00000000-0000-0000-0000-000000000001 SMS_SMOKE_PHONE=replace-with-real-phone SMS_SMOKE_ORIGIN=https://admin.tjszsb.com npm run smoke:sms-login: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

14 KiB Raw Blame History Unescape Escape