# 部署说明 ## 本地开发 API 默认监听 `http://localhost:3001`,管理后台默认监听 `http://localhost:3000`。后台开发服务器会把 `/api` 请求代理到 API,并移除 `/api` 前缀,因此本地不需要额外配置跨域。 ## 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= SEED_ADMIN_PASSWORD= ``` `DATABASE_URL` 使用最小权限数据库账号。`SESSION_SECRET` 不能复用示例值或开发值。微信与对象存储相关变量只在启用对应能力时配置,同样不能提交真实凭据。 ### 2. 构建与迁移 ```bash 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` 启动,由进程管理器负责重启与日志。 首次部署可以执行一次 `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" ```