From b1d5c2b4b09a241dc6adb038e90d105aa7e6da94 Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 12 Oct 2026 00:23:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E7=94=9F=E4=BA=A7?= =?UTF-8?q?=E5=8F=91=E5=B8=83=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deployment.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/deployment.md b/docs/deployment.md index e4f7ff7..f7d5549 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -39,3 +39,65 @@ 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" +```