# 多环境部署

<cite>
**本文引用的文件**
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [deploy-package/server/config/index.js](file://deploy-package/server/config/index.js)
- [DEPLOY.md](file://DEPLOY.md)
- [DEPLOY_PROD.md](file://DEPLOY_PROD.md)
- [AUTO_DEPLOY.md](file://AUTO_DEPLOY.md)
- [server/webhook-deploy.py](file://server/webhook-deploy.py)
- [deploy-prod.sh](file://deploy-prod.sh)
- [deploy.sh](file://deploy.sh)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向AI有声书生成平台，提供覆盖开发、测试、生产的多环境部署策略与实施指南。内容涵盖：
- 环境差异化配置（数据库、API端点、第三方服务密钥）
- 环境变量使用模式与配置文件加载优先级
- CI/CD流水线（自动化测试、构建、打包、部署触发）
- 环境切换最佳实践（配置热更新、蓝绿/灰度发布）
- 监控与告警（性能指标、错误日志、容量规划）

## 项目结构
该仓库包含后端服务、前端应用、部署脚本与Nginx/Docker配置。关键部署相关目录与文件如下：
- server/src/config：运行时配置加载与模型管理
- deploy-package/server/config：打包后配置（兼容JS）
- docker-nginx：本地开发反向代理示例
- 自动化部署脚本：deploy-prod.sh、deploy.sh、webhook-deploy.py
- 文档：DEPLOY.md、DEPLOY_PROD.md、AUTO_DEPLOY.md

```mermaid
graph TB
A["开发环境<br/>本地/容器"] --> B["测试环境<br/>测试服务器"]
B --> C["生产环境<br/>线上服务器"]
A --> D["构建产物<br/>server/dist, frontend/build/h5"]
D --> E["部署脚本<br/>deploy.sh / deploy-prod.sh"]
E --> F["PM2 进程管理<br/>server"]
F --> G["Nginx 反向代理<br/>book.rrbrr.com / bookapi.rrbrr.com"]
G --> H["后端服务<br/>监听端口"]
G --> I["静态资源<br/>前端H5"]
```

图表来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)

章节来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)

## 核心组件
- 配置加载与模型管理
  - 通过dotenv加载根目录环境变量，结合models.json统一管理模型清单与默认值
  - 提供模型切换逻辑（基于错误类型判断是否切换）
- 自动化部署链路
  - 一键部署脚本负责构建、打包、同步、安装依赖、生成Prisma客户端、PM2启动
  - Webhook服务接收Gogs/GitHub推送，执行部署脚本
- 反向代理与域名
  - Nginx配置后端API与前端静态资源分发；生产环境由宝塔面板管理

章节来源
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [deploy-package/server/config/index.js:1-111](file://deploy-package/server/config/index.js#L1-L111)
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [DEPLOY.md:61-116](file://DEPLOY.md#L61-L116)

## 架构总览
多环境部署采用“脚本驱动 + 反向代理 + 进程管理”的组合模式，支持一键部署与Webhook触发部署。

```mermaid
graph TB
Dev["开发者"] --> SCM["代码仓库(Gogs/GitHub)"]
SCM --> WH["Webhook 接收器<br/>webhook-deploy.py"]
WH --> Deploy["部署脚本<br/>deploy.sh / deploy-prod.sh"]
Deploy --> Build["构建产物<br/>server/dist, frontend/build/h5"]
Build --> PM2["PM2 进程管理"]
PM2 --> Nginx["Nginx 反向代理"]
Nginx --> API["后端API"]
Nginx --> FE["前端静态资源"]
```

图表来源
- [AUTO_DEPLOY.md:3-85](file://AUTO_DEPLOY.md#L3-L85)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)

## 详细组件分析

### 环境变量与配置加载
- 加载顺序与优先级
  - 项目根目录加载 .env（dotenv）
  - 读取 models.json 作为模型配置源
  - 运行时通过 process.env 覆盖默认值（端口、数据库、JWT、TTS等）
- 关键配置项
  - 服务端口与环境：NODE_ENV、SERVER_PORT
  - 数据库连接：MONGODB_URI（开发）/ DATABASE_URL（生产）
  - JWT：JWT_SECRET、JWT_EXPIRES_IN
  - 第三方服务：DASHSCOPE_API_KEY、DASHSCOPE_MODEL、DASHSCOPE_TTS_MODELS、DASHSCOPE_USE_REALTIME、DASHSCOPE_REALTIME_MODEL
  - 存储与缓存：STORAGE_TYPE、REDIS_*、OSS_*（生产）
- 模型管理
  - 统一列出vendors/models，按类型过滤启用模型，支持自动切换

```mermaid
flowchart TD
Start(["启动"]) --> LoadEnv["加载 .env"]
LoadEnv --> ReadModels["读取 models.json"]
ReadModels --> MergeCfg["合并默认配置与环境变量"]
MergeCfg --> Export["导出 config 对象"]
Export --> End(["运行"])
```

图表来源
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [deploy-package/server/config/index.js:1-111](file://deploy-package/server/config/index.js#L1-L111)

章节来源
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [DEPLOY_PROD.md:105-144](file://DEPLOY_PROD.md#L105-L144)

### 开发环境
- 本地开发
  - 使用 docker-nginx 本地反向代理，映射80端口，便于联调
  - 通过 .env 注入开发数据库与第三方服务密钥
- 前后端联调
  - 前端H5直连后端API（通过Nginx转发），便于调试

章节来源
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [server/src/config/index.ts:73-75](file://server/src/config/index.ts#L73-L75)

### 测试环境
- 配置要点
  - 使用独立数据库（MySQL 8.0 Docker容器）
  - 通过 .env 设置 DATABASE_URL、Redis、OSS等
  - Nginx配置与生产类似，但指向测试后端端口
- 部署流程
  - rsync同步前后端产物至测试服务器
  - 安装依赖、生成Prisma客户端、PM2启动
  - 验证健康检查与API连通性

章节来源
- [DEPLOY_PROD.md:264-294](file://DEPLOY_PROD.md#L264-L294)
- [DEPLOY.md:105-116](file://DEPLOY.md#L105-L116)

### 生产环境
- 服务器与端口
  - 服务器IP：8.159.134.106
  - 前端路径：/data/ai/audio/frontend/build/h5
  - 后端端口：3100（PM2启动时指定）
  - SSH端口：22622
- 配置要点
  - .env中设置 NODE_ENV=production、SERVER_PORT=3100、JWT_SECRET、DASHSCOPE_*、DATABASE_URL、REDIS_*、OSS_*
  - Nginx由宝塔面板管理，配置文件位于 /www/server/panel/vhost/nginx/
  - 健康检查：/api/health
- 部署流程
  - 一键脚本 deploy-prod.sh 完成构建、打包、同步、安装依赖、复制生产配置、生成Prisma客户端、PM2启动
  - 手动部署步骤与一键脚本等价，便于理解与排障

章节来源
- [DEPLOY_PROD.md:3-65](file://DEPLOY_PROD.md#L3-L65)
- [DEPLOY_PROD.md:105-144](file://DEPLOY_PROD.md#L105-L144)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)

### CI/CD流水线
- 触发机制
  - Git Push → Gogs Webhook → 服务器 webhook-deploy.py → 自动部署脚本 → PM2重启
- 服务配置
  - systemd服务：webhook.service，监听本地端口（默认8080），读取WEBHOOK_SECRET与WEBHOOK_PORT
  - Nginx转发：/webhook → 127.0.0.1:8080
- 安全建议
  - 使用HTTPS与强Secret
  - 可限制IP仅允许Gogs服务器访问 /webhook
- 替代方案
  - 无Python环境时，可用Git post-receive hook + Nginx + Bash脚本实现

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Gogs as "Gogs 仓库"
participant Nginx as "Nginx"
participant WH as "webhook-deploy.py"
participant Script as "deploy.sh"
participant PM2 as "PM2"
participant Srv as "后端服务"
Dev->>Gogs : 推送代码
Gogs->>Nginx : 触发 /webhook
Nginx->>WH : 转发请求
WH->>Script : 执行部署脚本
Script->>PM2 : 重启 server
PM2->>Srv : 启动/重启进程
Dev-->>Gogs : 部署完成
```

图表来源
- [AUTO_DEPLOY.md:3-85](file://AUTO_DEPLOY.md#L3-L85)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [deploy.sh:178-201](file://deploy.sh#L178-L201)

章节来源
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)
- [deploy.sh:178-201](file://deploy.sh#L178-L201)

### 环境切换最佳实践
- 配置热更新
  - 通过 .env 分环境管理，生产环境使用 .env.production 并在部署时复制为 .env
  - 第三方服务密钥与数据库连接字符串按环境隔离
- 蓝绿/灰度发布
  - 建议：使用多实例+负载均衡（Nginx upstream）进行蓝绿切换；灰度发布可通过Nginx基于Header/Cookie分流
  - 当前脚本未内置蓝绿/灰度逻辑，可在Nginx层扩展
- 模型自动切换
  - 基于错误类型判断（限流、配额、服务不可用等）自动切换可用模型，提升稳定性

章节来源
- [server/src/config/index.ts:45-67](file://server/src/config/index.ts#L45-L67)
- [DEPLOY_PROD.md:115-144](file://DEPLOY_PROD.md#L115-L144)

### 监控与告警
- 性能指标
  - Nginx访问/错误日志：/var/log/nginx/ 与宝塔日志目录
  - PM2进程状态与日志：pm2 status / pm2 logs server
- 错误日志监控
  - 后端：pm2 logs server --lines 50
  - Nginx：tail -f /var/log/nginx/access.log / error.log
- 容量规划建议
  - CPU/内存：根据并发请求与TTS生成任务峰值评估
  - 存储：上传文件与生成视频目录容量监控
  - 数据库：MySQL 8.0容器资源与备份策略

章节来源
- [DEPLOY.md:187-197](file://DEPLOY.md#L187-L197)
- [DEPLOY_PROD.md:318-375](file://DEPLOY_PROD.md#L318-L375)

## 依赖关系分析
- 配置模块
  - server/src/config/index.ts 读取 .env 与 models.json，导出统一配置对象
  - deploy-package/server/config/index.js 为打包后JS版本，行为一致
- 部署脚本
  - deploy.sh：通用部署脚本（本地Windows路径示例）
  - deploy-prod.sh：生产一键脚本（含Node.js检测、复制生产配置、PM2启动）
- 自动化
  - webhook-deploy.py：HTTP服务，校验签名后执行部署脚本
  - systemd服务：webhook.service，随系统启动

```mermaid
graph LR
Env[".env"] --> Cfg["server/src/config/index.ts"]
Models["models.json"] --> Cfg
Cfg --> App["后端应用"]
Deploy["deploy.sh"] --> PM2["PM2"]
Prod["deploy-prod.sh"] --> PM2
WH["webhook-deploy.py"] --> Deploy
SVC["webhook.service"] --> WH
```

图表来源
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

章节来源
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

## 性能考量
- 反向代理
  - Nginx开启HTTP/2、缓存静态资源、压缩与安全头，降低后端压力
- 进程管理
  - PM2自动重启与开机自启，保障高可用
- 数据库
  - 生产使用Docker MySQL 8.0，建议开启慢查询日志与连接池参数优化
- 存储
  - OSS对象存储与Redis缓存配合，减少IO压力

## 故障排查指南
- 后端无法启动
  - 检查端口占用与 .env 配置，查看PM2日志
- 前端无法访问
  - 检查Nginx配置与静态资源路径
- 数据库连接失败
  - 检查MySQL容器状态与 .env 中 DATABASE_URL
- Nginx 502
  - 检查后端进程监听端口与PM2状态
- Webhook部署失败
  - 检查签名、日志与系统服务状态

章节来源
- [DEPLOY.md:199-251](file://DEPLOY.md#L199-L251)
- [DEPLOY_PROD.md:318-375](file://DEPLOY_PROD.md#L318-L375)
- [AUTO_DEPLOY.md:97-142](file://AUTO_DEPLOY.md#L97-L142)

## 结论
本部署文档提供了从开发到生产的完整配置与流程说明，并给出了CI/CD自动化与监控告警建议。建议在现有脚本基础上扩展蓝绿/灰度发布能力，并完善测试环境的自动化回归与性能压测流程，以进一步提升交付质量与稳定性。

## 附录
- 常用命令
  - PM2：status、logs、restart、save、startup
  - Nginx：-t、reload、restart
  - MySQL（Docker）：进入容器、备份、迁移
- 安全加固
  - 强制HTTPS、强Secret、IP白名单、定期审计日志