Files
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

222 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署说明
## 本地开发
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` 前缀的剥离行为。