Files
persionalBrand/docs/deployment.md
T

4.4 KiB

部署说明

本地开发

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

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

本地 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 不能复用示例值或开发值。微信与对象存储相关变量只在启用对应能力时配置,同样不能提交真实凭据。

2. 构建与迁移

pnpm install --frozen-lockfile
pnpm build:admin:preview
pnpm --filter @personal-brand/api db:migrate:deploy

apps/admin/dist 是部署产物,包含 Admin 静态站点和已构建的模板预览应用。生产 API 使用 pnpm --filter @personal-brand/api start 启动,由进程管理器负责重启与日志。

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

首次部署可以执行一次 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

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