xiongyuxing/gongxue-base
1
0
Fork 0
forked from wangziqi/gongxue-base
Code Pull Requests Activity
Files
f219eb0bf82c5cf6d15770c02d00ccc6398a2f18
gongxue-base/scripts/deploy/README.md
Codex 39f7332f33 feat: establish production SaaS foundation
2026-07-12 19:26:57 +08:00

19 KiB
Raw Blame History

SaaS 题库服务器部署手册

本手册覆盖两类场景：

  1. 全新测试/预生产服务器的隔离 bootstrap。
  2. 现有云服务器从旧原地覆盖脚本升级到版本化原子发布。

生产发布器默认 fail closed。缺少真实数据库 readiness、三端 runtime config、生产 evidence、浏览器烟测环境或服务重启权限时，发布必须失败，不能通过关闭门禁或伪造 evidence 绕过。

先选择入口

场景 入口 配置模型 状态
全新生产服务器 仓库根目录 deploy.sh /opt/tiku-saas/shared/ 推荐
现有云服务器 scripts/deploy/bin/deploy.sh 安装到 /opt/tiku-saas/bin/deploy.sh /etc/tiku-saas/ 兼容升级入口
全新测试/预生产服务器 本手册的 staging bootstrap 完全独立目录、数据库、域名和凭据 当前无一键 staging profile

两套生产脚本的变量名不同，不能混用 env 模板：

  • 根脚本：REPO_URL、BRANCH、DEPLOY_ROOT，模板为根目录 deploy.env.example。
  • 兼容脚本：GIT_REPO、GIT_BRANCH、APP_ROOT，模板为 scripts/deploy/env/deploy.env.example。

服务器长期更新命令可以继续保持：

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

但首次发布当前基线前，必须先升级 /opt/tiku-saas/bin/deploy.sh、部署配置、API/Worker env 和 systemd units。发布脚本不会自动更新自己，也不会自动安装 Nginx 或 systemd 模板。

发布能力与边界

新版生产部署器会：

  1. 获取固定分支的最新 commit，并在独立候选 release 安装锁定依赖。
  2. 运行 TypeScript、仓库安全扫描、runtime audit 和 Taro 供应链审计。
  3. 构建 API、Worker、学生 H5、租户后台 H5、平台后台 H5。
  4. 注入三端公开 runtime config，运行严格 guard、manifest、25 项静态 smoke 和 33 项真实浏览器交互 smoke。
  5. 运行生产 env readiness；可选执行 migration；随后运行数据库 readiness。
  6. 使用与 commit、artifact 和 SHA-256 绑定的真实 production launch evidence。
  7. 原子切换应用与 Web release，重启服务，验证 API /health 和线上 H5 hash。
  8. 失败时恢复上一份代码和 Web release。

脚本不会：

  • 创建数据库或对象存储备份。
  • 回滚已经提交的 migration。
  • 自动更新 /etc/systemd/system、宝塔 Nginx 或 /etc/tiku-saas/*.env。
  • 逐一确认所有 Worker backlog、Provider、外部告警和业务数据正确性。
  • 自动创建首个平台超管。

因此 migration 必须先备份并演练向后兼容。代码/Web 回滚不能被当作数据库回滚。

域名与目录

参考域名：

api.tjszsb.com       Node.js API
app.tjszsb.com       学生 H5
admin.tjszsb.com     租户后台 H5
console.tjszsb.com   平台后台 H5
supabase.tjszsb.com  Supabase Gateway/Auth/Data API
studio.tjszsb.com    Supabase Studio，必须限制来源

现有生产兼容布局：

/opt/tiku-saas/source              Gitea 源码副本，只用于 fetch/build
/opt/tiku-saas/releases            版本化候选应用
/opt/tiku-saas/current             当前应用 release 软链接
/opt/tiku-saas/repo                systemd 当前运行副本
/opt/tiku-saas/bin/deploy.sh       服务器外置兼容部署器
/srv/tiku-saas/www                 当前三端 Web release 软链接
/srv/tiku-saas/www-releases        版本化 Web release
/etc/tiku-saas/deploy.env          部署配置和只读 Gitea 凭据
/etc/tiku-saas/api.env             API 生产 env
/etc/tiku-saas/worker.env          Worker 生产 env
/etc/tiku-saas/runtime-config/     三端公开 runtime config
/etc/tiku-saas/production-launch-evidence.json
/etc/tiku-saas/launch-artifacts/   与 evidence 配套的证据文件

根部署器使用 /opt/tiku-saas/shared/ 保存 deploy env、readiness env、runtime config 和 evidence。systemd 模板目前仍从 /etc/tiku-saas/api.env 与 /etc/tiku-saas/worker.env 读取运行配置，因此使用根脚本时也必须维护这两个文件；shared/.env 只用于候选 release 的 readiness，关键 API 配置必须与 /etc/tiku-saas/api.env 保持一致，避免双配置漂移。现有服务器优先使用兼容入口，减少这项差异。

凭据

  • 已经出现在聊天、工单、截图或日志里的 token 必须吊销。
  • 服务器优先使用只读 SSH deploy key；Gitea SSH 端口为 2222。
  • 使用 HTTPS 时，token 只放权限为 600/640 的服务器 env，由临时 GIT_ASKPASS 注入。
  • token 不得写入 Git remote、脚本、README 或命令历史。
  • DATABASE_ADMIN_URL、DATABASE_MIGRATION_URL 只从密码管理器临时注入，不长期写入 deploy/API/Worker env。

SSH remote：

ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git

新测试服务器

测试服务器必须与生产完全隔离：

/opt/tiku-saas-staging
/srv/tiku-saas-staging
/etc/tiku-saas-staging
staging-api.example.com
staging-app.example.com
staging-admin.example.com
staging-console.example.com
独立 PostgreSQL/Supabase、Auth、bucket 和 Provider 测试账号

数据库安全标记必须是：

environment=staging
allow_destructive_tests=false

API 与 Worker 应继续使用 NODE_ENV=production，这样能验证生产配置 fail-fast。staging 不能使用 production 数据库、bucket、支付/短信密钥或真实用户流量，也不能运行 supabase db reset、db:smoke-seed:test、test:api、test:rls 和会写入集成夹具的 Worker 测试。

当前仓库没有经过验证的一键 staging profile。两套 deploy 脚本在 production 模式下都会强制真实 launch gate，launch evidence 也不能用本地 mock 伪造。首次测试服务器采用下面的分阶段 bootstrap；在 staging profile 被单独实现和验证前，不要直接套用生产 /opt/tiku-saas、/srv/tiku-saas 和 /etc/tiku-saas 路径。

1. 固定候选 commit

sudo install -d -o deploy -g deploy /opt/tiku-saas-staging/source
sudo -u deploy git clone \
  ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git \
  /opt/tiku-saas-staging/source
sudo -u deploy git -C /opt/tiku-saas-staging/source checkout <reviewed-commit-sha>

不要在验证期间继续移动候选分支。

2. 安装与构建预检

cd /opt/tiku-saas-staging/source
sudo -u deploy npm ci --workspaces --include-workspace-root --include=dev
sudo -u deploy npm run check:api
sudo -u deploy npm run check:worker
sudo -u deploy npm run check:taro
sudo -u deploy npm run security:repo
sudo -u deploy npm run audit:runtime
sudo -u deploy npm run audit:taro:supply-chain
sudo -u deploy npm run build:api
sudo -u deploy npm run build:worker
sudo -u deploy npm run build:taro:h5:student
sudo -u deploy npm run build:taro:h5:tenant
sudo -u deploy npm run build:taro:h5:platform

服务器必须安装 Chrome/Chromium，或设置 TARO_H5_SMOKE_BROWSER 指向受支持浏览器。随后运行：

sudo -u deploy npm run smoke:taro:h5
sudo -u deploy env TARO_H5_INTERACTION_OUTPUT_DIR=/tmp/tiku-h5-staging \
  npm run smoke:taro:h5:interaction

这一步只证明候选产物和本地 mock 旅程，不是生产 evidence。

3. 数据库 bootstrap 与 migration

先创建数据库和对象存储快照，再 dry-run runtime role 计划：

cd /opt/tiku-saas-staging/source
npm run bootstrap:db-runtime-roles

由真正 PostgreSQL superuser 应用一次：

DATABASE_ADMIN_URL='<secret-managed-superuser-url>' \
npm run bootstrap:db-runtime-roles -- \
  --apply --confirm=BOOTSTRAP_BACKEND_RUNTIME_ROLES

bootstrap 不设置角色密码。用密码管理器为 tiku_api、tiku_worker 设置独立强密码，再把相应连接分别写入 staging API/Worker env。

全新数据库在 migrations 后没有业务租户数据，生产 readiness 会因没有 active tenant 而阻断。使用受控管理流程创建 staging 的 master tenant、active domain、branding/settings 和必要 Provider 配置；不要执行 supabase/seed.sql，它是本地开发 seed，会把数据库标为 local 并写入 mock 数据。

由标准 migration role 应用迁移：

DATABASE_MIGRATION_URL='<secret-managed-migration-url>' \
supabase db push --db-url "$DATABASE_MIGRATION_URL"

然后使用 API 运行角色验证：

set -a
source /etc/tiku-saas-staging/api.env
set +a
npm run readiness:production
npm run readiness:production:db

migration 是前向操作。失败时按备份恢复方案处理，不依赖 deploy symlink 回滚。

4. runtime config 与受控激活

从 scripts/deploy/runtime-config/*.example.json 创建 staging 文件。浏览器 H5 使用 Origin 解析租户时，tenantCode 保持空字符串；只允许公开 HTTPS URL 和 Supabase publishable key。

在尚未具备 staging 原子发布 profile 时，先由运维在隔离路径安装 systemd/Nginx，明确每一个 WorkingDirectory、EnvironmentFile、端口、域名和 Web root 都指向 *-staging。不得直接复制当前生产 unit 后仍保留 /opt/tiku-saas/repo 或 /etc/tiku-saas。

完成真实 staging Auth/CORS/Provider/三类 persona、Worker 和线上 H5 检查后，将报告保存到 staging 自己的 evidence bundle。production launch evidence 仍只能由最终生产候选生成，不能从 staging 复制冒充。

现有服务器一次性升级

1. 冻结与备份

  1. 将完整基线合并到 Gitea，记录待部署 SHA。
  2. 备份 PostgreSQL、对象存储、/etc/tiku-saas、旧部署脚本、旧运行目录和宝塔 Nginx 配置。
  3. 验证备份可读，并记录数据库恢复与代码/Web 回滚步骤。
  4. 首次 migration 推荐独立执行“备份 -> migration -> DB readiness -> evidence”，正式应用发布时恢复 RUN_DB_MIGRATIONS=false。

2. 准备 source checkout

从一个不依赖旧部署脚本的临时目录获取新代码：

sudo install -d -o deploy -g deploy /opt/tiku-saas/source
sudo -u deploy git clone \
  ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git \
  /opt/tiku-saas/source
sudo -u deploy git -C /opt/tiku-saas/source checkout <reviewed-commit-sha>

若目录已存在，只允许 clean checkout：

sudo -u deploy git -C /opt/tiku-saas/source status --short
sudo -u deploy git -C /opt/tiku-saas/source fetch origin main --prune
sudo -u deploy git -C /opt/tiku-saas/source checkout main
sudo -u deploy git -C /opt/tiku-saas/source merge --ff-only origin/main

3. 升级外置部署脚本

先备份，再安装兼容入口：

sudo cp -a /opt/tiku-saas/bin/deploy.sh \
  /opt/tiku-saas/bin/deploy.sh.backup-$(date +%Y%m%d%H%M%S)

sudo install -o root -g deploy -m 0750 \
  /opt/tiku-saas/source/scripts/deploy/bin/deploy.sh \
  /opt/tiku-saas/bin/deploy.sh

不要期待仓库 pull 自动更新 /opt/tiku-saas/bin/deploy.sh。

4. 更新配置

备份 /etc/tiku-saas/deploy.env、api.env 和 worker.env，再逐项 diff 模板，不要覆盖真实 secrets：

diff -u /etc/tiku-saas/deploy.env \
  /opt/tiku-saas/source/scripts/deploy/env/deploy.env.example || true
diff -u /etc/tiku-saas/api.env \
  /opt/tiku-saas/source/scripts/deploy/env/api.env.example || true
diff -u /etc/tiku-saas/worker.env \
  /opt/tiku-saas/source/scripts/deploy/env/worker.env.example || true

必须确认：

SOURCE_REPO_DIR=/opt/tiku-saas/source
REPO_DIR=/opt/tiku-saas/repo
RELEASES_DIR=/opt/tiku-saas/releases
WWW_ROOT=/srv/tiku-saas/www
WWW_RELEASES_DIR=/srv/tiku-saas/www-releases
RUN_TARO_SUPPLY_CHAIN_AUDIT=true
RUN_DB_READINESS=true
RUN_LAUNCH_GATE=true
SYSTEMD_UNITS="tiku-api.service tiku-workers.target"
HEALTHCHECK_URL=http://127.0.0.1:8787/health

API DATABASE_URL 必须使用 tiku_api，Worker 必须使用 tiku_worker。真实 env 的权限推荐为 root:deploy 0640。

Provider 密钥不要仅凭 env 模板判断“已经配置完成”。PNVS、OAuth、支付和租户级密钥以 app_private.tenant_secrets 及对应 Provider 配置为真实来源，必须通过仓库配置/诊断脚本和 production readiness 验证。对象存储及 Worker scanner 等进程级配置才由 API/Worker env 提供。

连接池要按进程总量预算：默认 9 个常驻 Worker 若每个 DB_POOL_MAX=5，仅 Worker 上限约 45 个连接；再加 API、timer/oneshot、Supabase 内部服务和运维连接。正式启用前应结合 PostgreSQL max_connections 和 PgBouncer 配额调整，而不是逐个进程孤立设置。

5. 升级 Worker 调度

不要使用通配复制后遗留旧 unit。显式安装当前清单：

sudo systemctl stop tiku-worker.service 2>/dev/null || true
sudo systemctl disable tiku-worker.service 2>/dev/null || true
sudo rm -f /etc/systemd/system/tiku-worker.service

for unit in \
  tiku-api.service \
  tiku-worker@.service \
  tiku-worker-job@.service \
  tiku-worker-monthly-usage.service \
  tiku-worker-monthly-usage.timer \
  tiku-worker-platform-audit-alerts.timer \
  tiku-worker-platform-billing.timer \
  tiku-worker-platform-dunning.timer \
  tiku-worker-platform-usage.timer \
  tiku-worker-student-supervision.timer \
  tiku-workers.target
do
  sudo install -o root -g root -m 0644 \
    "/opt/tiku-saas/source/scripts/deploy/systemd/$unit" \
    "/etc/systemd/system/$unit"
done

sudo systemctl daemon-reload
sudo systemctl enable tiku-api.service tiku-workers.target

不要在新的应用 release 尚未构建并同步到 /opt/tiku-saas/repo 前启动 tiku-workers.target。

连续 Worker 为 CRM、commerce、provider bills、催缴通知、审计通知、assets、imports、public banks 和 exports；定时任务负责计费、用量、月结超额、催缴、审计告警和学习督导。

6. systemd 权限

部署器以 deploy 用户运行，但需要重启 tiku-api.service 和 tiku-workers.target。首次升级前检查：

sudo -u deploy systemctl is-active tiku-api.service
sudo -u deploy systemctl restart tiku-api.service

第二条如果要求交互认证，部署会在切换阶段失败。不要给 deploy NOPASSWD: ALL。选择其一：

  • 用受审 root wrapper 只允许 restart/is-active 这两个顶层 unit，并把 RESTART_COMMAND 指向 wrapper。
  • 配置精确的 PolicyKit 规则，只允许 deploy 管理本项目 unit。
  • 由 root 执行受控部署器，同时确保 clone/npm/release 文件所有权仍为 deploy，并重新验证脚本权限模型。

完成最小权限方案后，必须在非交互会话中验证。

7. 数据库、runtime config 与 evidence

按“新测试服务器”中的数据库步骤完成：

  1. superuser runtime role/extension bootstrap。
  2. 为 tiku_api/tiku_worker 设置独立密码。
  3. 标准 migration role 应用 migration。
  4. readiness:production 和 readiness:production:db。

三端 runtime config 路径：

/etc/tiku-saas/runtime-config/h5-student.runtime-config.json
/etc/tiku-saas/runtime-config/h5-tenant-admin.runtime-config.json
/etc/tiku-saas/runtime-config/h5-platform-admin.runtime-config.json

tenantCode 默认留空，由三个生产 Origin 解析租户；只有明确的固定租户预览/小程序模式才填写。

production evidence 必须绑定待发布 commit。兼容脚本默认读取：

/etc/tiku-saas/production-launch-evidence.json

相对 artifact 路径从 evidence 所在目录解析，因此完整 bundle 应为：

/etc/tiku-saas/production-launch-evidence.json
/etc/tiku-saas/launch-artifacts/*

只复制 evidence JSON 而不复制 artifacts 会 fail closed。staging、本地 mock 或旧 commit 的 evidence 不能复用。

8. 宝塔/Nginx

宝塔服务器继续保留它管理的站点文件，不要直接套用普通 /etc/nginx/sites-available 命令。人工对照 scripts/deploy/nginx/tjszsb.com.conf.example 同步：

  • /srv/tiku-saas/www/{student,tenant-admin,platform-admin} 三端路径。
  • SPA history fallback。
  • runtime-config.json no-store。
  • 带 hash 静态资源长期缓存。
  • API forwarded headers、body limit、超时和必要限流。
  • Supabase Gateway/Studio HTTPS 与 Studio 来源限制。

若宝塔站点根目录必须位于 /www/wwwroot，用受控软链接指向 /srv/tiku-saas/www/*，不要复制第二份静态文件形成漂移。

9. 正式执行

服务器需有 Node.js 20、npm、Git、rsync、curl、Supabase CLI，以及 Chrome/Chromium。浏览器不在标准路径时设置 TARO_H5_SMOKE_BROWSER。

先确认 source clean、evidence commit 和待发布 SHA 一致，再运行：

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

如果本次数据库已独立迁移完成，保持：

RUN_DB_MIGRATIONS=false

部署器在任何激活前完成候选构建和门禁；应用/Web 切换、服务重启、API health 或线上 H5 hash 失败会触发代码/Web回滚。

发布后验收

脚本只检查顶层 target active 和 API /health，发布后还必须人工运行：

systemctl --failed --no-pager
systemctl is-active tiku-api.service tiku-workers.target
systemctl list-dependencies tiku-workers.target --no-pager
systemctl list-timers 'tiku-worker-*' --all --no-pager
systemctl status 'tiku-worker@*.service' --no-pager
journalctl -u tiku-api.service -n 100 --no-pager
journalctl -u 'tiku-worker@*.service' -n 200 --no-pager
curl -fsS http://127.0.0.1:8787/health

随后验证：

  • 三个生产域名的 index.html、runtime config、登录和主入口。
  • /api/tenant/resolve 的 Origin/CORS。
  • 真实 Auth/JWKS、PNVS 短信、支付/退款回调、对象存储签名与扫描。
  • Worker backlog、失败重试、timer 下次执行时间和外部告警渠道。
  • 错误率、P95/P99、数据库连接池、慢 SQL、锁等待、磁盘和日志轮转。

回滚

自动回滚只覆盖应用代码和三端 Web：

/opt/tiku-saas/current
/opt/tiku-saas/repo
/srv/tiku-saas/www

数据库 migration、对象存储写入、外部 Provider 状态和已产生业务事件不会自动回滚。数据库恢复必须使用发布前已验证的快照/备份，并由负责人单独决策。

手工代码/Web 回滚前，先记录失败 release 和日志，再将软链接切回上一 release、同步运行目录、重启服务并复核 API/H5。不要使用 git reset --hard 处理服务器运行目录。

安全检查清单

  • 暴露 token 已吊销，服务器只读凭据已轮换。
  • 待发布 commit 已冻结，source checkout clean。
  • PostgreSQL、对象存储和 /etc/tiku-saas 已备份并验证可读。
  • tiku_api/tiku_worker bootstrap、独立密码和 migration role 已完成。
  • 三端 runtime config 只有公开字段，tenantCode 策略正确。
  • 旧 tiku-worker.service 已停止、禁用并删除。
  • 新 Worker units/timers/target 已安装，deploy 重启权限最小化。
  • Chrome/Chromium 可用于 33 项 H5 交互 smoke。
  • evidence commit、artifacts、hash 和人工 attestation 完整。
  • 宝塔/Nginx history fallback、缓存、CORS、CSP 和 forwarded headers 已复核。
  • 首个平台超管通过 Auth-bound bootstrap 创建并留有审计。
  • 发布后逐 Worker、timer、Provider、日志和监控验收完成。

参考