118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# 部署说明
|
|
|
|
## 本地开发
|
|
|
|
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=<production-brand-id>
|
|
SEED_ADMIN_PASSWORD=<first-boot-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` 启动,由进程管理器负责重启与日志。
|
|
|
|
部署产物中的模板预览入口是 `apps/admin/dist/template-preview/index.html`,资源位于同级 `assets`、`css`、`js` 目录,线上必须保留 `/template-preview/` 前缀。
|
|
|
|
首次部署可以执行一次 `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
|
|
```
|
|
|
|
脚本要求账号已完成初始密码修改,品牌发布检查全部通过,公开工作区已发布且至少有一项业务。凭据只从环境变量读取,不能写入仓库。
|