# 部署说明 ## 本地开发 API 默认监听 `http://localhost:3001`,管理后台默认监听 `http://localhost:3000`。后台开发服务器会把 `/api` 请求代理到 API,并移除 `/api` 前缀,因此本地不需要额外配置跨域。 ## 生产架构 生产环境只使用 Docker Compose 运行 PostgreSQL;API 和 Admin 运行在 VPS 宿主机上。API 由 Node.js 24 + PM2 运行在 `3001`,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 ``` ## 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` 不能复用示例值或开发值。媒体上传使用 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 ``` 脚本要求账号已完成初始密码修改,品牌发布检查全部通过,公开工作区已发布且至少有一项业务。凭据只从环境变量读取,不能写入仓库。