Files
persionalBrand/docs/deployment.md
T

133 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署说明
## 本地开发
API 默认监听 `http://localhost:3001`,管理后台默认监听 `http://localhost:3000`。后台开发服务器会把 `/api` 请求代理到 API,并移除 `/api` 前缀,因此本地不需要额外配置跨域。
## 生产架构
生产环境只使用 Docker Compose 运行 PostgreSQL;API 和 Admin 运行在 VPS 宿主机上。API 由 Node.js 24 + PM2 运行在 `3001`,Admin 静态服务运行在 `3010`,Traefik file provider 负责路由。用户媒体目录位于发布目录之外,发布时只补充缺失的种子图片,不覆盖上传文件。
每次发布先创建 PostgreSQL `pg_dump` 备份,再执行 Prisma migration 和公网健康检查;检查失败时恢复应用版本和 Traefik 路由。数据库 migration 不自动回滚,必须使用备份恢复或人工处理。
`docker-compose.prod.yml` 只负责 PostgreSQL,不再定义 API、Admin 或业务镜像。
## 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=<production-brand-id>
SEED_ADMIN_PASSWORD=<first-boot-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 和 Traefik 路由,并运行公网验证。
首次部署可以执行一次 `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
```
脚本要求账号已完成初始密码修改,品牌发布检查全部通过,公开工作区已发布且至少有一项业务。凭据只从环境变量读取,不能写入仓库。