6.3 KiB
部署说明
本地开发
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 上临时拉取源码并构建。
日常发布只执行一条命令:
pnpm deploy:release
命令会自动构建 Admin 和 API、生成带 manifest 的发布包、生成 SHA-256、上传到 DEPLOY_TARGET(默认 oracle_arm)、在 VPS 校验并安装、备份数据库、执行 migration、切换服务和 Traefik,最后检查 Admin、模板预览、API 和媒体。需要更换目标或域名时通过环境变量配置:
DEPLOY_TARGET=oracle_arm PUBLIC_BASE_URL=https://wechat.app.que01.top pnpm deploy:release
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 不能复用示例值或开发值。媒体上传使用 S3 兼容对象存储和预签名直传,生产环境必须配置独立的 OBJECT_STORAGE_PUBLIC_URL、最小权限访问密钥和专用 bucket。微信相关变量只在启用对应能力时配置,同样不能提交真实凭据。
2. 构建发布包
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/ 前缀。
也可以把生产产物整理成统一发布目录:
pnpm deploy:package
脚本生成带完整文件清单和 SHA-256 的版本目录及归档,归档旁边会生成 .sha256 文件。上传到 VPS 后由 deploy/install-release.mjs 复用 pnpm store 安装依赖、备份数据库、执行迁移、切换 PM2、systemd 和 Traefik 路由,并运行公网验证。切流前必须通过 Traefik 容器访问 Admin 上游的检查。
首次部署可以执行一次 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"} 后再切换流量。随后用管理员账号执行:
- 登录 Admin,确认当前品牌和角色;
- 读取
/admin/releases/readiness,所有检查必须通过; - 修改一条业务草稿,确认保存成功;
- 在“配置与发布”发布当前草稿;
- 请求公开工作区,确认新内容已出现在小程序数据中;
- 将业务内容还原后再次发布,避免验收内容残留。
公开工作区请求示例:
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
脚本要求账号已完成初始密码修改,品牌发布检查全部通过,公开工作区已发布且至少有一项业务。凭据只从环境变量读取,不能写入仓库。