部署运维

本文面向准备把商业版后端部署到目标环境的研发和运维团队。目标不仅是说明如何启动，也包括确保服务上线后稳定运行、可排查、可维护。

上线前先确认 4 类信息

1. 运行方式

你准备如何运行后端：

• 直接 Node + 进程管理
• Docker / Docker Compose
• 挂到统一运维平台

2. 数据库与依赖

至少确认：

• PostgreSQL 地址
• 对象存储
• 日志目录
• AI 服务（如果要启用）

3. 安全策略

至少确认：

• Access / Refresh Token 密钥
• Cookie 域名与 HTTPS 策略
• CORS 白名单
• Swagger 是否暴露

4. 前端联动方式

至少确认：

• 前端访问哪个 API 域名
• 是否同域
• 是否依赖 Cookie 续期

常见部署方式

方式一：Node + 进程管理

适合已有服务器和标准 Node 运维环境的项目。

基本流程：

pnpm install
pnpm build
pnpm prisma:migrate:deploy
pnpm start:prod

方式二：Docker Compose

仓库已经提供 docker-compose.yml，其中包含：

• app
• postgres
• 可选 pgadmin

并且已经配置了：

• 应用健康检查
• PostgreSQL 健康检查
• 日志卷和数据库卷
• 默认端口映射

推荐的上线步骤

1. 准备 .env.production
2. 构建产物
3. 执行数据库迁移
4. 初始化默认角色、管理员和定时任务
5. 启动服务
6. 检查健康检查地址
7. 与前端做一次真实登录联调

上线后第一轮检查清单

建议至少逐项检查：

1. health 正常
2. 登录、刷新、退出流程正常
3. Swagger 是否按预期暴露或关闭
4. 文件上传下载正常
5. 定时任务状态符合预期
6. 日志目录正常写入

最常见的生产问题

问题一：服务能启动，但前端始终登录异常

优先检查：

• Cookie 域名
• HTTPS
• CORS
• 前端 API 地址

问题二：文件上传成功但访问失败

优先检查：

• 存储桶权限
• 公开访问域名
• STORAGE_PUBLIC_BASE_URL

问题三：定时任务看起来存在，但没有真正执行

优先检查：

• 任务状态
• 执行日志
• 时区配置

问题四：生产环境暴露了不该暴露的调试入口

优先检查：

• Swagger
• 过宽的 CORS
• 默认管理员密码是否已更换

部署建议

进入生产环境前，建议把这些内容形成配置记录：

• 运行方式
• 生产环境变量
• 数据库连接信息
• 对象存储配置
• API 域名
• 健康检查地址
• 运维排查入口

检查清单

后端上线完成后，建议确认：

• 服务、数据库、对象存储和日志目录在目标环境中可用。
• 健康检查地址已接入网关或监控平台。
• 登录、刷新、文件上传、定时任务和关键业务接口通过真实前端联调。
• Swagger、CORS、默认管理员、Token 密钥和 Cookie 策略符合生产安全要求。