# 生产部署

<cite>
**本文引用的文件**   
- [DEPLOY_PROD.md](file://DEPLOY_PROD.md)
- [DEPLOY.md](file://DEPLOY.md)
- [deploy-prod.sh](file://deploy-prod.sh)
- [deploy.sh](file://deploy.sh)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf)
- [AUTO_DEPLOY.md](file://AUTO_DEPLOY.md)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/middleware/security.ts](file://server/src/middleware/security.ts)
- [server/src/middleware/rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [server/src/services/sentry.service.ts](file://server/src/services/sentry.service.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/services/logger.service.ts](file://server/src/services/logger.service.ts)
- [server/src/services/redis.service.ts](file://server/src/services/redis.service.ts)
- [server/src/services/storage.service.ts](file://server/src/services/storage.service.ts)
- [server/src/modules/book-generator/FAULT_TOLERANCE.md](file://server/src/modules/book-generator/FAULT_TOLERANCE.md)
- [server/src/modules/book-generator/README.md](file://server/src/modules/book-generator/README.md)
</cite>

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

## 简介
本文件面向AI有声书生成平台的生产部署，覆盖从服务器准备、CI/CD流水线、自动化部署与回滚、负载均衡与SSL、安全加固、监控与告警到A/B、蓝绿与金丝雀发布策略，以及应急响应与灾备方案。文档严格依据仓库现有部署脚本、配置与模块化实现进行梳理，并提供可操作的流程图与时序图帮助工程团队落地。

## 项目结构
- 后端服务位于 server 目录，采用 Node.js + Koa 架构，使用 PM2 管理进程；生产部署脚本负责构建、同步、安装依赖、生成Prisma客户端、启动服务与Nginx重载。
- 前端为 uni-app-vue3 构建产物，部署于 Nginx 静态目录。
- Nginx 通过宝塔面板管理，提供HTTP/HTTPS、反向代理、HSTS、缓存与访问日志。
- 自动化部署通过 Gogs Webhook + Python Webhook 服务或 Git Hook 实现，支持一键触发与回滚。
- 安全与性能方面包含安全中间件、速率限制、Sentry 错误监控、Winston 日志、Redis 缓存与 OSS/本地存储抽象。

```mermaid
graph TB
subgraph "生产服务器"
FE["前端静态资源<br/>/data/ai/audio/frontend/build/h5"]
BE["后端服务<br/>PM2 + dist/app.js"]
DB["MySQL 8.0 (Docker)<br/>single-mysql"]
REDIS["Redis"]
OSS["阿里云 OSS"]
Nginx["Nginx (宝塔面板)"]
end
Internet["互联网"] --> Nginx
Nginx --> FE
Nginx --> BE
BE --> DB
BE --> REDIS
BE --> OSS
```

**图表来源**
- [DEPLOY_PROD.md: 36-46:36-46](file://DEPLOY_PROD.md#L36-L46)
- [DEPLOY.md: 64-116:64-116](file://DEPLOY.md#L64-L116)
- [docker-nginx/docker-compose.yml: 1-12:1-12](file://docker-nginx/docker-compose.yml#L1-L12)

**章节来源**
- [DEPLOY_PROD.md: 3-46:3-46](file://DEPLOY_PROD.md#L3-L46)
- [DEPLOY.md: 3-116:3-116](file://DEPLOY.md#L3-L116)

## 核心组件
- 自动化部署脚本
  - deploy-prod.sh：本地构建前端与后端，打包上传，服务器侧安装 Node.js/PM2，安装依赖，复制生产环境配置，生成Prisma客户端，启动PM2服务，提示Nginx配置位置。
  - deploy.sh：与 deploy-prod.sh 类似，但更强调宝塔面板配置与HTTPS重定向。
- Nginx 配置
  - 宝塔面板管理，80重定向至443，配置SSL证书、HSTS、缓存、访问/错误日志、API反向代理。
  - docker-nginx 提供独立容器化示例，bookapi.conf 将 /api 代理至后端。
- 安全与性能
  - 安全中间件：XSS/SQL注入防护、敏感数据脱敏、安全响应头。
  - 速率限制：内存/Redis双栈限流器，支持API、登录、短信、TTS、上传等维度。
  - Sentry：生产采样率与错误过滤，配合Koa中间件捕获异常。
  - 性能监控：请求计数、平均耗时、慢请求、端点级指标与HTTP日志。
  - Redis：连接池、重试策略、键操作、批量删除、过期控制。
  - 存储：OSS/本地存储统一抽象，支持上传、下载、删除、签名URL。
- 容错与可靠性
  - 书籍生成容错：AI调用指数退避重试、节点级超时、进度监控三级告警、自动恢复、WebSocket实时通知。
- CI/CD 与回滚
  - Gogs Webhook + Python Webhook 服务或 Git Post-Receive Hook，支持一键部署与回滚。
  - 一键部署脚本 deploy.sh 与 deploy-prod.sh 提供回滚与重试能力。

**章节来源**
- [deploy-prod.sh: 1-171:1-171](file://deploy-prod.sh#L1-L171)
- [deploy.sh: 1-209:1-209](file://deploy.sh#L1-L209)
- [server/src/middleware/security.ts: 1-154:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/rate-limiter.ts: 1-120:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [server/src/services/sentry.service.ts: 1-113:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/middleware/performance.ts: 1-110:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [server/src/services/logger.service.ts: 1-114:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/services/redis.service.ts: 1-274:1-274](file://server/src/services/redis.service.ts#L1-L274)
- [server/src/services/storage.service.ts: 1-278:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [server/src/modules/book-generator/FAULT_TOLERANCE.md: 1-334:1-334](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L1-L334)

## 架构总览
生产环境采用“Nginx + 后端PM2 + MySQL + Redis + OSS”的组合，Nginx统一入口，负责TLS终止、静态资源缓存、API反向代理与访问日志。后端通过速率限制、安全中间件与Sentry保障稳定性与可观测性。书籍生成模块具备完善的容错与进度监控，确保长耗时任务的可靠性。

```mermaid
graph TB
Client["客户端"] --> Nginx["Nginx (HTTPS/HSTS)"]
Nginx --> API["后端API (/api/*)"]
Nginx --> Static["静态资源 (/)"]
API --> Koa["Koa 应用"]
Koa --> Security["安全中间件"]
Koa --> Limiter["速率限制"]
Koa --> Perf["性能监控"]
Koa --> Sentry["Sentry 错误监控"]
Koa --> Redis["Redis 缓存"]
Koa --> Storage["存储服务 (OSS/本地)"]
Koa --> DB["MySQL (Docker)"]
```

**图表来源**
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)
- [server/src/middleware/security.ts: 6-27:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/rate-limiter.ts: 49-72:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/performance.ts: 29-76:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [server/src/services/sentry.service.ts: 7-43:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/src/services/redis.service.ts: 3-38:3-38](file://server/src/services/redis.service.ts#L3-L38)
- [server/src/services/storage.service.ts: 13-35:13-35](file://server/src/services/storage.service.ts#L13-L35)

## 详细组件分析

### 自动化部署与回滚（CI/CD）
- Gogs Webhook 集成
  - 服务器端部署 webhook-deploy.py，systemd 服务自启动，Nginx 将 /webhook 转发至本地端口。
  - Gogs 仓库配置 Webhook URL 与 Secret，触发后自动拉取代码、构建、PM2 重启。
- Git Hook 回退方案
  - 若无Python，可在服务器 Git 仓库设置 post-receive Hook，检测 master 分支推送并执行构建与重启。
- 一键部署脚本
  - deploy.sh：备份旧文件，解压新包，安装依赖，生成Prisma客户端，PM2重启，Nginx重载。
  - deploy-prod.sh：本地构建，打包上传，服务器侧安装 Node.js/PM2，复制 .env.production -> .env，生成Prisma客户端，PM2启动。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Gogs as "Gogs 仓库"
participant Nginx as "Nginx"
participant Webhook as "Webhook 服务"
participant Server as "服务器"
participant PM2 as "PM2"
Dev->>Gogs : 推送代码
Gogs->>Nginx : Webhook 请求 (URL+Secret)
Nginx->>Webhook : 反向代理 /webhook
Webhook->>Server : 拉取代码/执行部署脚本
Server->>Server : 备份/解压/安装依赖/生成Prisma
Server->>PM2 : 重启后端服务
PM2-->>Dev : 服务可用
```

**图表来源**
- [AUTO_DEPLOY.md: 5-66:5-66](file://AUTO_DEPLOY.md#L5-L66)
- [AUTO_DEPLOY.md: 68-78:68-78](file://AUTO_DEPLOY.md#L68-L78)
- [deploy.sh: 54-89:54-89](file://deploy.sh#L54-L89)
- [deploy-prod.sh: 79-127:79-127](file://deploy-prod.sh#L79-L127)

**章节来源**
- [AUTO_DEPLOY.md: 1-142:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [deploy.sh: 1-209:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh: 1-171:1-171](file://deploy-prod.sh#L1-L171)

### Nginx 与 SSL/TLS
- 宝塔面板管理，80端口重定向至443，启用TLSv1.2/1.3、HSTS、Alt-Svc，配置SSL证书与私钥。
- API反向代理：将 /api/ 请求转发至后端 3100 端口，设置真实IP与协议头。
- 静态资源：前端H5构建产物目录，开启缓存与访问/错误日志。
- docker-nginx 提供容器化示例，将 /api 代理至 host.docker.internal:3000。

```mermaid
flowchart TD
Start(["请求进入"]) --> Port80{"是否HTTP 80?"}
Port80 --> |是| Redirect["301 重定向到 HTTPS"]
Port80 --> |否| TLS["TLS 终止 (宝塔)"]
TLS --> APIProxy{"路径是否 /api/* ?"}
APIProxy --> |是| ProxyToBE["代理到 127.0.0.1:3100"]
APIProxy --> |否| ServeStatic["返回前端静态资源"]
ProxyToBE --> End(["响应"])
ServeStatic --> End
```

**图表来源**
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)
- [docker-nginx/bookapi.conf: 1-15:1-15](file://docker-nginx/bookapi.conf#L1-L15)

**章节来源**
- [DEPLOY_PROD.md: 146-245:146-245](file://DEPLOY_PROD.md#L146-L245)
- [docker-nginx/docker-compose.yml: 1-12:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf: 1-15:1-15](file://docker-nginx/bookapi.conf#L1-L15)

### 安全加固与合规
- 安全中间件
  - XSS防护：递归清理请求体与查询参数，设置安全响应头。
  - SQL注入检测：正则匹配常见攻击模式，拦截非法输入。
  - 敏感数据脱敏：对密码、令牌等字段进行脱敏输出。
- 速率限制
  - 内存/Redis双栈限流器，支持API、登录、短信、TTS、上传等维度，自动设置 Retry-After。
- Sentry 错误监控
  - 生产环境采样率与错误过滤，结合Koa中间件捕获异常并附带上下文。
- 日志与审计
  - Winston 统一日志格式，分别输出到控制台、错误文件、综合日志与HTTP请求日志。
- Redis 安全
  - 连接重试策略、错误日志、连接状态监控，避免因缓存不可用导致服务降级。

**章节来源**
- [server/src/middleware/security.ts: 1-154:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/rate-limiter.ts: 1-120:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [server/src/services/sentry.service.ts: 1-113:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/services/logger.service.ts: 1-114:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/services/redis.service.ts: 1-274:1-274](file://server/src/services/redis.service.ts#L1-L274)

### 性能监控与可观测性
- 性能中间件：统计总请求数、平均响应时间、慢请求、端点级指标与错误率，输出响应头。
- HTTP日志中间件：记录请求方法、URL、状态、耗时、IP与UA，便于审计与分析。
- Sentry：异常捕获与性能采样，辅助定位热点问题。
- Prometheus/Grafana（建议）：可扩展指标采集与可视化（本仓库未提供具体配置文件）。

**章节来源**
- [server/src/middleware/performance.ts: 1-110:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [server/src/services/logger.service.ts: 74-102:74-102](file://server/src/services/logger.service.ts#L74-L102)
- [server/src/services/sentry.service.ts: 7-43:7-43](file://server/src/services/sentry.service.ts#L7-L43)

### 存储与缓存
- 存储服务：统一抽象 OSS 与本地存储，支持上传、下载、删除、签名URL与目录级操作。
- Redis：连接池、重试、键操作、批量删除、过期控制与连接测试，保证高可用与可维护性。

**章节来源**
- [server/src/services/storage.service.ts: 1-278:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [server/src/services/redis.service.ts: 1-274:1-274](file://server/src/services/redis.service.ts#L1-L274)

### 书籍生成容错与长耗时任务
- AI调用重试：指数退避（最多3次），记录错误并WebSocket通知。
- 节点级超时：大纲/节/小节/内容等节点设定不同超时阈值，超时触发自动恢复。
- 进度监控：10/20/30分钟三级告警，自动恢复最多2次，避免无限循环。
- WebSocket通知：12种通知类型，覆盖重试、失败、超时、恢复等场景。

```mermaid
flowchart TD
Start(["开始节点"]) --> CallLLM["调用 LLM (指数退避重试)"]
CallLLM --> Retry{"重试次数 < 3 ?"}
Retry --> |是| Wait["等待 2^n 秒"] --> CallLLM
Retry --> |否| Fail["标记失败 + 通知用户"]
CallLLM --> Timeout{"节点超时?"}
Timeout --> |是| AutoRecovery["自动恢复 (最多2次)"]
Timeout --> |否| Complete["节点完成 + 通知用户"]
AutoRecovery --> Requeue["重新入队"] --> CallLLM
```

**图表来源**
- [server/src/modules/book-generator/FAULT_TOLERANCE.md: 13-84:13-84](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L13-L84)
- [server/src/modules/book-generator/FAULT_TOLERANCE.md: 86-146:86-146](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L86-L146)

**章节来源**
- [server/src/modules/book-generator/FAULT_TOLERANCE.md: 1-334:1-334](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L1-L334)

### A/B、蓝绿与金丝雀发布策略
- A/B 测试
  - 通过 Nginx upstream 分流或后端灰度路由，按用户特征/实验组分配流量。
  - 建议：结合 Cookie/Header 标识分流，逐步扩大流量比例。
- 蓝绿部署
  - 预热新版本服务与数据库迁移，Nginx 切换到新实例，失败快速切回。
  - 建议：使用 PM2 集群与健康检查，确保零停机切换。
- 金丝雀发布
  - 以小比例流量（如 5%-10%）导入新版本，结合Sentry与性能指标观察，逐步放大。

[本节为通用发布策略说明，未直接分析具体源码文件，故不附加“章节来源”]

## 依赖关系分析
- 后端依赖
  - 环境变量与模型配置：从 .env 与 models.json 加载，支持DashScope TTS与多模型切换。
  - 速率限制依赖 Redis（可用时）或内存限流器。
  - 存储服务依赖 OSS SDK 或本地文件系统。
- Nginx 依赖
  - 宝塔面板配置文件与证书路径，API反向代理与静态资源根目录。
- 自动化依赖
  - Gogs Webhook、Python Webhook 服务、systemd 服务单元、PM2。

```mermaid
graph LR
Env[".env / models.json"] --> Config["配置加载"]
Redis["Redis"] --> Limiter["速率限制"]
OSS["OSS"] --> Storage["存储服务"]
LocalFS["本地文件系统"] --> Storage
Nginx["Nginx 配置"] --> API["后端API"]
API --> Limiter
API --> Storage
API --> DB["MySQL"]
```

**图表来源**
- [server/src/config/index.ts: 1-117:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/middleware/rate-limiter.ts: 1-43:1-43](file://server/src/middleware/rate-limiter.ts#L1-L43)
- [server/src/services/storage.service.ts: 13-35:13-35](file://server/src/services/storage.service.ts#L13-L35)
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)

**章节来源**
- [server/src/config/index.ts: 1-117:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/middleware/rate-limiter.ts: 1-120:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [server/src/services/storage.service.ts: 1-278:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)

## 性能考量
- 限流与熔断
  - 全局限流与登录/短信/TTS/上传等专项限流，避免突发流量冲击。
  - Redis可用时优先使用分布式限流器，不可用时回退内存限流器。
- 缓存与存储
  - Redis 作为热点数据缓存，减少数据库压力；存储服务统一对接OSS/本地，降低耦合。
- 日志与监控
  - HTTP请求日志与性能指标结合，识别慢端点与异常峰值。
- Nginx 缓存
  - 静态资源长期缓存与HSTS，降低带宽与CPU消耗。

[本节提供通用指导，未直接分析具体源码文件，故不附加“章节来源”]

## 故障排查指南
- 后端服务无法启动
  - 查看 PM2 日志与错误日志，手动运行验证端口占用与 .env 配置。
- 数据库连接失败
  - 检查 Docker 容器状态、重启容器、测试连接与 .env 配置。
- Nginx 502 错误
  - 检查后端进程、端口监听、本地健康检查与 Nginx 配置语法。
- 重启所有服务
  - PM2 重启后端、Nginx 重载、必要时重启 MySQL 容器。
- 自动化部署失败
  - 检查 webhook 服务状态与日志、PM2 日志、Nginx 访问/错误日志。

**章节来源**
- [DEPLOY_PROD.md: 318-393:318-393](file://DEPLOY_PROD.md#L318-L393)
- [AUTO_DEPLOY.md: 97-111:97-111](file://AUTO_DEPLOY.md#L97-L111)

## 结论
本部署文档基于仓库现有脚本与模块，给出了生产环境的部署流程、自动化与回滚策略、安全加固、监控与可观测性实践，并提供了A/B、蓝绿与金丝雀发布的实施建议。建议在现有基础上补充Prometheus/Grafana指标采集、数据库备份与灾备演练，持续完善生产治理。

## 附录

### 部署前检查清单
- 服务器与网络
  - 服务器可达、防火墙开放、SSH密钥配置正确。
  - Nginx 与宝塔面板可用，SSL证书已配置。
- 后端
  - Node.js/PM2 已安装，.env 生产配置齐全，数据库与Redis连通。
  - Prisma schema 与迁移已准备，OSS/本地存储可用。
- 前端
  - H5 构建产物已生成，静态资源目录权限正确。
- CI/CD
  - Gogs Webhook 已配置，Secret 一致，Nginx 反代 /webhook。
  - Git Hook（可选）已设置，post-receive 脚本可执行。

**章节来源**
- [DEPLOY.md: 140-159:140-159](file://DEPLOY.md#L140-L159)
- [AUTO_DEPLOY.md: 68-78:68-78](file://AUTO_DEPLOY.md#L68-L78)

### 部署后验证步骤
- 健康检查
  - 访问后端健康端点与前端首页，确认 Nginx 与后端均正常。
- 日志与监控
  - 查看 PM2 日志、Nginx 访问/错误日志、Sentry 异常与性能指标。
- 功能验证
  - 登录、书籍生成、TTS、播放、支付（如涉及）等关键路径验证。

**章节来源**
- [DEPLOY.md: 147-159:147-159](file://DEPLOY.md#L147-L159)
- [DEPLOY_PROD.md: 18-25:18-25](file://DEPLOY_PROD.md#L18-L25)

### 监控配置建议
- 指标采集
  - 使用 Prometheus 抓取后端性能指标与HTTP日志，结合 Grafana 可视化。
- 告警策略
  - 基于错误率、P95/P99 延迟、Redis/DB 连接失败、Nginx 5xx 等设置告警。
- 日志聚合
  - 将 Winston 日志与 Nginx 日志接入集中式日志系统，支持检索与告警。

[本节为通用建议，未直接分析具体源码文件，故不附加“章节来源”]