222 lines
14 KiB
Markdown
222 lines
14 KiB
Markdown
# 部署说明
|
||
|
||
## 本地开发
|
||
|
||
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 上临时拉取源码并构建。
|
||
|
||
日常发布只执行一条命令:
|
||
|
||
```bash
|
||
pnpm deploy:release
|
||
```
|
||
|
||
命令会自动构建 Admin 和 API、生成带 manifest 的发布包、生成 SHA-256、上传到 `DEPLOY_TARGET`(默认 `oracle_arm`)、在 VPS 校验并安装、备份数据库、执行 migration、切换服务和 Traefik,最后检查 Admin、模板预览、API 和媒体。需要更换目标或域名时通过环境变量配置:
|
||
|
||
```bash
|
||
DEPLOY_TARGET=oracle_arm PUBLIC_BASE_URL=https://wechat.app.que01.top pnpm deploy:release
|
||
```
|
||
|
||
查看线上状态:
|
||
|
||
```bash
|
||
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 反向代理
|
||
|
||
生产环境建议使用同源路径:
|
||
|
||
```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,也无需为每个模板运行单独服务。构建管理后台与预览应用时使用:
|
||
|
||
```bash
|
||
pnpm build:admin:preview
|
||
```
|
||
|
||
部署时将 `apps/admin/dist` 作为同一个静态站点发布。预览 iframe 与 Admin 同源,运行时根据品牌公开工作区中的 `visualTemplateKey` 选择已打包的模板 renderer,并通过 `/api` 读取已发布数据;管理员正在编辑的草稿由 Admin 经 `postMessage` 投影到 iframe,不会写回公开 API。
|
||
|
||
本地开发只需启动一个多模板 H5 服务和 Admin:
|
||
|
||
```bash
|
||
pnpm preview:templates
|
||
VITE_APP_BASE_PATH=/ ADMIN_PORT=3000 pnpm --filter @personal-brand/admin dev
|
||
```
|
||
|
||
预览与小程序产物在构建时遮蔽 Taro 标识符(见 [ADR 0025](adr/0025-build-output-stack-masking.md)),因此生产预览与小程序包只通过包内构建脚本产出:`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. 准备环境
|
||
|
||
生产进程至少需要以下变量,缺失时必须停止部署:
|
||
|
||
```bash
|
||
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. 构建发布包
|
||
|
||
```bash
|
||
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/` 前缀。
|
||
|
||
也可以把生产产物整理成统一发布目录:
|
||
|
||
```bash
|
||
pnpm deploy:package
|
||
```
|
||
|
||
脚本生成带完整文件清单和 SHA-256 的版本目录及归档,归档旁边会生成 `.sha256` 文件。上传到 VPS 后由 `deploy/install-release.mjs` 复用 pnpm store 安装依赖、备份数据库、执行迁移、切换 PM2、systemd 和 Traefik 路由,并运行公网验证。切流前必须通过 Traefik 容器访问 Admin 上游的检查。
|
||
|
||
首次部署可以执行一次 `pnpm db:seed` 创建管理员与演示品牌。已有生产环境禁止重复执行种子命令;模板示例内容只能由管理员在后台对指定品牌显式导入,不能把示例数据扩展到全局种子。
|
||
|
||
### 3. 发布前门禁
|
||
|
||
发布构建前在本机或 CI 执行:
|
||
|
||
```bash
|
||
pnpm check
|
||
pnpm template:doctor
|
||
pnpm build
|
||
pnpm --filter @personal-brand/api test:integration
|
||
```
|
||
|
||
`pnpm template:doctor` 必须确认所有接入模板的未解决问题为 `0`。集成测试需要使用独立测试数据库,不得重建开发数据。
|
||
|
||
### 4. 部署后健康检查
|
||
|
||
```bash
|
||
curl -fsS "$API_BASE_URL/health"
|
||
```
|
||
|
||
预期返回 `{"status":"ok","service":"personal-brand-api"}` 后再切换流量。随后用管理员账号执行:
|
||
|
||
1. 登录 Admin,确认当前品牌和角色;
|
||
2. 读取 `/admin/releases/readiness`,所有检查必须通过;
|
||
3. 修改一条业务草稿,确认保存成功;
|
||
4. 在“配置与发布”发布当前草稿;
|
||
5. 请求公开工作区,确认新内容已出现在小程序数据中;
|
||
6. 将业务内容还原后再次发布,避免验收内容残留。
|
||
|
||
公开工作区请求示例:
|
||
|
||
```bash
|
||
curl -fsS "$API_BASE_URL/public/workspace?brandSlug=$BRAND_SLUG"
|
||
```
|
||
|
||
上述四步验收可以用统一脚本执行:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
node deploy/republish-stale-template-contracts.mjs
|
||
```
|
||
|
||
脚本逐品牌比较当前发布快照与数据库重建快照:
|
||
|
||
- `current`:无需处理;
|
||
- `contract-stale`:仅模板契约字段变化,可重发;
|
||
- `content-diverged`:品牌内容(`brand`、`offerings`、`forms`、`trustContents`、`capabilities` 等)与已发布快照不同,**禁止自动重发**,必须在 Admin 审查草稿后手动发布;
|
||
- `not-ready`:发布检查未通过,先修复阻断项。
|
||
|
||
确认输出后加 `--apply` 执行。历史遗留字段删除必须显式放行,不能默认忽略:
|
||
|
||
```bash
|
||
node deploy/republish-stale-template-contracts.mjs --apply \
|
||
--allow-removed-key=brand.config.visualTemplateKey
|
||
```
|
||
|
||
`--allow-removed-key` 只允许“旧值存在、新值缺失”的删除;该字段被改成其他值或与其他内容差异同时出现时仍会拦截。`--apply` 退出码为 1 表示至少一个品牌被拦截,应按上面的分类处理,不要重复盲目执行。
|
||
|
||
重发后验证公开契约:
|
||
|
||
```bash
|
||
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` 前缀的剥离行为。
|