Files
persionalBrand/docs/deployment.md
T
que01 44fe7a0142 fix: 打通小程序代码上传链路
小程序上传此前连续失败,根因分散在状态机、产物路径、模块导入、私钥解析和进程隔离上,逐项修复:

- 构建进度改用 updateBuild 只写 buildStatus/buildLogs,不再用 updateStatus 记录进度,避免状态机拒绝自我迁移而返回 409
- 产物目录锚定仓库根目录,不再随 API 进程工作目录变成 apps/api/apps/taro/dist
- miniprogram-ci 为 CommonJS 包,动态导入后从 default 归一化取 Project/upload,替换原有的类型断言
- 上传私钥统一还原成合法 PEM;输入框曾把换行吞成单行,导致 OpenSSL 解码失败,现保存时校验、上传时自动修复存量数据
- 上传改在独立子进程执行,miniprogram-ci 崩溃或超时不再终止 API 进程,失败返回 502 并保留微信原始错误
- 构建超过 MINIAPP_BUILD_STALE_MS 无进度即视为中断,允许重新上传,避免任务永久卡在 building
- 构建前校验请求地址与 AppID,请求地址支持在品牌配置中维护,环境变量仅作回落,避免再打出指向 localhost 的包
- 小程序 /media/ 按请求地址的 origin 解析,不再依赖网关剥离 /api 前缀

新增对应单测与集成断言,并更新部署说明。
2026-10-13 21:58:48 +08:00

170 lines
9.2 KiB
Markdown
Raw 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
```
数据库备份自动保留最近 7 份;备份归档在状态检查中通过 `pg_restore -l` 校验可读性。备份失败会清理未完成的临时文件,不自动删除数据库数据。发布成功后保留当前版本、上一版本和最近 5 个发布目录。状态检查同时报告 PM2 自启、磁盘空间、备份时间/可读性及发布目录数量。
备份当前仍在同一台 VPS 上,不等同于灾难恢复副本。应将 `shared/backups/*.dump` 定期复制到独立主机或对象存储,并至少每季度在隔离数据库执行一次恢复演练;不得在生产数据库上测试恢复。整机重启演练需在维护窗口执行,确认 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
```
本地 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` 不能复用示例值或开发值。媒体上传使用 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. 小程序代码上传
后台“配置与发布 → 小程序发布”会调用对应模板的小程序构建,并把产物上传到微信。构建产物根目录由 `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 分钟)没有进度更新,会被视为中断并允许重新发起上传。
`API_BASE_URL` 与 AppID 是**编译期常量**,构建时写入小程序包,无法在后台热改。上传前按以下顺序解析并校验,任一项不合法就直接拒绝构建,避免把指向 `localhost` 的包上传到微信:
- 请求地址:后台「配置与发布 → 小程序上传配置」里的“小程序请求地址”优先;未配置时回落到 `MINIAPP_API_BASE_URL`,再回落到 `PUBLIC_BASE_URL` 加 `MINIAPP_API_PATH`(默认 `/api`)。非 `https` 的公网地址会被拒绝。因此换域名只需在后台改这一项并重新上传代码,不用改服务端环境变量。
- AppID:同样以后台“小程序上传配置”里的 AppID 为准,回落 `WEAPP_APP_ID`;`undefined`、`touristappid` 等占位值会被拒绝。
该域名必须与微信后台“开发设置 → 服务器域名 → request 合法域名”完全一致,否则小程序打开即报“加载失败,请重试”。后台“小程序上传配置”会直接展示当前生效的请求域名,便于上线前比对。
小程序包内的 `/media/...` 按请求地址的 origin 解析(例如 `https://host/api` → `https://host/media/...`),与网关的 `/media` 路由保持一致,不依赖 `/api` 前缀的剥离行为。