Files
persionalBrand/docs/deployment.md
T
que01 d0a0eeea8c
CI / Browser smoke (pull_request) Successful in 58s
CI / Static checks (pull_request) Successful in 1m32s
CI / API integration (pull_request) Successful in 1m27s
CI / Production build (pull_request) Successful in 2m7s
feat: 支持按品牌配置微信登录凭据
2026-10-23 22:07:39 +08:00

14 KiB
Raw Blame History

部署说明

本地开发

API 默认监听 http://localhost:3001,管理后台默认监听 http://localhost:3000。后台开发服务器会把 /api 请求代理到 API,并移除 /api 前缀,因此本地不需要额外配置跨域。

生产架构

生产环境只使用 Docker Compose 运行 PostgreSQL;API 和 Admin 运行在 VPS 宿主机上。API 由 Node.js 24 + PM2 运行在 3001,并由 user-level systemd unit 在登录会话之外恢复 PM2 进程;Admin 静态服务由 user-level systemd 运行在 3010,Traefik file provider 负责路由。Traefik 所在 Docker 网段必须允许访问宿主机 3010,但不需要向公网开放该端口。用户媒体目录位于发布目录之外,发布时只补充缺失的种子图片,不覆盖上传文件。

每次发布先创建 PostgreSQL pg_dump 备份,再执行 Prisma migration 和公网健康检查;检查失败时恢复应用版本和 Traefik 路由。数据库 migration 不自动回滚,必须使用备份恢复或人工处理。

docker-compose.prod.yml 只负责 PostgreSQL,不再定义 API、Admin 或业务镜像。Gitea 用于保存源码、发布包和 SHA-256 校验文件;生产机只安装经过校验的发布包,不在 VPS 上临时拉取源码并构建。

日常发布只执行一条命令:

pnpm deploy:release

命令会自动构建 Admin 和 API、生成带 manifest 的发布包、生成 SHA-256、上传到 DEPLOY_TARGET(默认 oracle_arm)、在 VPS 校验并安装、备份数据库、执行 migration、切换服务和 Traefik,最后检查 Admin、模板预览、API 和媒体。需要更换目标或域名时通过环境变量配置:

DEPLOY_TARGET=oracle_arm PUBLIC_BASE_URL=https://wechat.app.que01.top pnpm deploy:release

查看线上状态:

pnpm deploy:status

数据库备份分两类:

  • 发布备份:每次 pnpm deploy:release 在 migration 前创建,按版本名保留最近 7 份。
  • 定时备份:由 user-level personal-brand-backup.timer 每天 03:30(VPS 本地时区)执行,写入 shared/backups/scheduled-*.dump,默认保留 14 天。

定时任务的脚本副本位于 shared/backup-db.mjs 和 shared/database-backup.mjs,不依赖当前 release 目录,回滚后仍可运行。每次备份先用 pg_dump -Fc 写入临时文件,再用 pg_restore -l 校验;校验失败会删除损坏文件并让本次任务失败。备份失败会清理未完成的临时文件,不自动删除数据库数据。发布成功后保留当前版本、上一版本和最近 5 个发布目录。

状态检查会验证备份定时器处于 active、最新备份不超过 36 小时(可用 BACKUP_MAX_AGE_HOURS 调整),并通过 pg_restore -l 校验可读性。状态检查同时报告 PM2 自启、磁盘空间、备份时间和发布目录数量。

如需异地副本,在 shared/.env.production 配置 BACKUP_OFFSITE_TARGET(rsync 目标,例如 backup@example-host:/srv/personal-brand-backups/),并为 ubuntu 用户预先配置 SSH key。未配置时备份只保留在同一台 VPS 上,不等同于灾难恢复副本。至少每季度应在隔离数据库执行一次恢复演练,不得在生产数据库上测试恢复;整机重启演练需在维护窗口执行,确认 Admin、API、PostgreSQL 和公网路由恢复后再结束维护。

Nginx 反向代理

生产环境建议使用同源路径:

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

location /api/ {
  proxy_pass http://127.0.0.1:3001/;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Request-ID $request_id;
}

生产构建会先把所有已接入模板的 H5 renderer 编译进一个静态预览应用,再将其放到 Admin 的 /template-preview/ 下。线上无需启动 Vite,也无需为每个模板运行单独服务。构建管理后台与预览应用时使用:

pnpm build:admin:preview

部署时将 apps/admin/dist 作为同一个静态站点发布。预览 iframe 与 Admin 同源,运行时根据品牌公开工作区中的 visualTemplateKey 选择已打包的模板 renderer,并通过 /api 读取已发布数据;管理员正在编辑的草稿由 Admin 经 postMessage 投影到 iframe,不会写回公开 API。

本地开发只需启动一个多模板 H5 服务和 Admin:

pnpm preview:templates
VITE_APP_BASE_PATH=/ ADMIN_PORT=3000 pnpm --filter @personal-brand/admin dev

预览与小程序产物在构建时遮蔽 Taro 标识符(见 ADR 0025),因此生产预览与小程序包只通过包内构建脚本产出:pnpm build:admin:preview、pnpm --filter @personal-brand/taro build:weapp。直接运行 taro build 不会执行遮蔽,产物会带出技术栈指纹;遮蔽后仍检测到指纹时构建会失败,pnpm deploy:package 还会在打包前校验 apps/admin/dist,命中指纹即中止发布。

本地 Admin 默认连接 http://localhost:3002 上的统一预览服务。VITE_TEMPLATE_PREVIEW_URL 只用于部署时覆盖预览应用地址,不再按模板配置 URL map。

如果希望 API 服务自身也带前缀,可设置 API_PREFIX=api。使用 Nginx 去前缀转发时保持默认空值即可,避免重复 /api/api。

生产发布

1. 准备环境

生产进程至少需要以下变量,缺失时必须停止部署:

NODE_ENV=production
DATABASE_URL=postgresql://user:password@host:5432/database
SESSION_SECRET=long-random-production-secret
DEFAULT_BRAND_ID=<production-brand-id>
SEED_ADMIN_PASSWORD=<first-boot-admin-password>

DATABASE_URL 使用最小权限数据库账号。SESSION_SECRET 不能复用示例值或开发值。DEFAULT_BRAND_ID 供未携带 brandSlug 的公共请求使用,缺失时 API 返回 503,不会回退到硬编码品牌。

CLIENT_ERROR_THROTTLE_STORE 默认为 memory,与当前 PM2 单实例模式匹配。扩展到多实例前必须先执行数据库迁移并改为 postgres,否则每个实例会各自限流与去重,实际阈值会被实例数量放大。

CORS_ORIGINS 默认为空并关闭跨域访问;只有 Admin 或预览应用从其他 origin 调用 API 时,才配置逗号分隔的 HTTPS origin allow-list。

本次部署会为管理员账号引入 tokenVersion。既有 admin token 会因缺少当前版本号而失效,管理员需要重新登录;之后修改密码会立即撤销同一账号的旧 token。媒体上传使用 S3 兼容对象存储和预签名直传,生产环境必须配置独立的 OBJECT_STORAGE_PUBLIC_URL、最小权限访问密钥和专用 bucket。微信相关变量只在启用对应能力时配置,同样不能提交真实凭据。

2. 构建发布包

pnpm install --frozen-lockfile
pnpm deploy:package

apps/admin/dist 是部署产物,包含 Admin 静态站点和已构建的模板预览应用。生产 API 使用 PM2 启动,配置位于发布包的 deploy/ecosystem.config.cjs。

部署产物中的模板预览入口是 apps/admin/dist/template-preview/index.html,资源位于同级 assets、css、js 目录,线上必须保留 /template-preview/ 前缀。

也可以把生产产物整理成统一发布目录:

pnpm deploy:package

脚本生成带完整文件清单和 SHA-256 的版本目录及归档,归档旁边会生成 .sha256 文件。上传到 VPS 后由 deploy/install-release.mjs 复用 pnpm store 安装依赖、备份数据库、执行迁移、切换 PM2、systemd 和 Traefik 路由,并运行公网验证。切流前必须通过 Traefik 容器访问 Admin 上游的检查。

首次部署可以执行一次 pnpm db:seed 创建管理员与演示品牌。已有生产环境禁止重复执行种子命令;模板示例内容只能由管理员在后台对指定品牌显式导入,不能把示例数据扩展到全局种子。

3. 发布前门禁

发布构建前在本机或 CI 执行:

pnpm check
pnpm template:doctor
pnpm build
pnpm --filter @personal-brand/api test:integration

pnpm template:doctor 必须确认所有接入模板的未解决问题为 0。集成测试需要使用独立测试数据库,不得重建开发数据。

4. 部署后健康检查

curl -fsS "$API_BASE_URL/health"

预期返回 {"status":"ok","service":"personal-brand-api"} 后再切换流量。随后用管理员账号执行:

  1. 登录 Admin,确认当前品牌和角色;
  2. 读取 /admin/releases/readiness,所有检查必须通过;
  3. 修改一条业务草稿,确认保存成功;
  4. 在“配置与发布”发布当前草稿;
  5. 请求公开工作区,确认新内容已出现在小程序数据中;
  6. 将业务内容还原后再次发布,避免验收内容残留。

公开工作区请求示例:

curl -fsS "$API_BASE_URL/public/workspace?brandSlug=$BRAND_SLUG"

上述四步验收可以用统一脚本执行:

API_BASE_URL=https://api.example.com \
BRAND_SLUG=$BRAND_SLUG \
ADMIN_USERNAME=$ADMIN_USERNAME \
ADMIN_PASSWORD=$ADMIN_PASSWORD \
pnpm deploy:verify

脚本要求账号已完成初始密码修改,品牌发布检查全部通过,公开工作区已发布且至少有一项业务。凭据只从环境变量读取,不能写入仓库。

5. 模板契约迁移后的发布快照刷新

BrandRelease 是公开工作区的唯一数据源,发布后内容不可变。模板包升级或兼容性声明修正不会自动改写历史发布,必须显式刷新快照,否则公开工作区会继续返回旧契约(例如旧的 supportedIndustryTemplates)。

先在生产 release 目录执行 dry-run:

node deploy/republish-stale-template-contracts.mjs

脚本逐品牌比较当前发布快照与数据库重建快照:

  • current:无需处理;
  • contract-stale:仅模板契约字段变化,可重发;
  • content-diverged:品牌内容(brand、offerings、forms、trustContents、capabilities 等)与已发布快照不同,禁止自动重发,必须在 Admin 审查草稿后手动发布;
  • not-ready:发布检查未通过,先修复阻断项。

确认输出后加 --apply 执行。历史遗留字段删除必须显式放行,不能默认忽略:

node deploy/republish-stale-template-contracts.mjs --apply \
  --allow-removed-key=brand.config.visualTemplateKey

--allow-removed-key 只允许“旧值存在、新值缺失”的删除;该字段被改成其他值或与其他内容差异同时出现时仍会拦截。--apply 退出码为 1 表示至少一个品牌被拦截,应按上面的分类处理,不要重复盲目执行。

重发后验证公开契约:

curl -fsS "$API_BASE_URL/public/workspace?brandSlug=$BRAND_SLUG" |
  jq '{publication, visualTemplate}'

6. 小程序代码上传

后台“配置与发布 → 小程序发布”会调用对应模板的小程序构建,并把产物上传到微信。构建产物根目录由 MINIAPP_ARTIFACT_ROOT 控制,相对路径按仓库根目录解析(不是 API 进程的工作目录),默认 apps/taro/dist;单个模板的产物固定为 <root>/<template-package-key>/weapp,缺少 app.json 即判定构建失败并保留构建日志。生产环境仍按 ADR 0023,优先在 CI 或专用发布 Worker 中构建,API 只负责上传。

微信代码上传在独立子进程中执行,miniprogram-ci 崩溃或超时不会影响 API 服务。任务若停在 building 超过 MINIAPP_BUILD_STALE_MS(默认 15 分钟)没有进度更新,会被视为中断并允许重新发起上传。

上传子进程的工作目录固定为 MINIAPP_UPLOAD_WORKSPACE(默认 os.tmpdir()/personal-brand-miniapp-upload)。miniprogram-ci 的 SummerCompiler 用 path.join("", md5(projectPath + "|summer")) 建缓存目录,这是相对路径,若沿用 API 进程的工作目录就会在仓库里留下 32 位十六进制目录;把工作目录放到系统临时目录后,该缓存落在临时目录内,仓库保持干净。

API_BASE_URL 与 AppID 是编译期常量,构建时写入小程序包,无法在后台热改。上传前按以下顺序解析并校验,任一项不合法就直接拒绝构建,避免把指向 localhost 的包上传到微信:

  • 请求地址:后台「配置与发布 → 小程序配置」里的“小程序请求地址”优先;未配置时回落到 MINIAPP_API_BASE_URL,再回落到 PUBLIC_BASE_URL 加 MINIAPP_API_PATH(默认 /api)。非 https 的公网地址会被拒绝。因此换域名只需在后台改这一项并重新上传代码,不用改服务端环境变量。
  • AppID:同样以后台“小程序配置”里的 AppID 为准,回落 WEAPP_APP_ID;undefined、touristappid 等占位值会被拒绝。

微信登录同样使用该品牌的 AppID,但 AppSecret 由后台“小程序配置”单独维护。服务端使用 MINIAPP_CREDENTIAL_ENCRYPTION_KEY(未配置时回退 SESSION_SECRET)加密保存 AppSecret,登录时按 brandSlug 读取对应品牌的凭据,不使用全局 WECHAT_APP_SECRET,也不会跨品牌回退。修改 AppSecret 后立即生效,不需要重新上传小程序代码;修改 AppID 时必须同时填写该 AppID 对应的 AppSecret。

该域名必须与微信后台“开发设置 → 服务器域名 → request 合法域名”完全一致,否则小程序打开即报“加载失败,请重试”。后台“小程序配置”会直接展示当前生效的请求域名,便于上线前比对。

小程序包内的 /media/... 按请求地址的 origin 解析(例如 https://host/api → https://host/media/...),与网关的 /media 路由保持一致,不依赖 /api 前缀的剥离行为。