audio_codebuddy/.qoder/repowiki/zh/content/部署运维/生产部署.md

生产部署

本文引用的文件

• DEPLOY_PROD.md
• DEPLOY.md
• deploy-prod.sh
• deploy.sh
• docker-nginx/docker-compose.yml
• docker-nginx/bookapi.conf
• AUTO_DEPLOY.md
• server/src/config/index.ts
• server/src/middleware/security.ts
• server/src/middleware/rate-limiter.ts
• server/src/services/sentry.service.ts
• server/src/middleware/performance.ts
• server/src/services/logger.service.ts
• server/src/services/redis.service.ts
• server/src/services/storage.service.ts
• server/src/modules/book-generator/FAULT_TOLERANCE.md
• server/src/modules/book-generator/README.md

目录

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/本地存储抽象。

  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
• DEPLOY.md: 64-116:64-116
• docker-nginx/docker-compose.yml: 1-12:1-12

章节来源

• DEPLOY_PROD.md: 3-46:3-46
• DEPLOY.md: 3-116:3-116

核心组件

• 自动化部署脚本
  • 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
• deploy.sh: 1-209:1-209
• server/src/middleware/security.ts: 1-154:1-154
• server/src/middleware/rate-limiter.ts: 1-120:1-120
• server/src/services/sentry.service.ts: 1-113:1-113
• server/src/middleware/performance.ts: 1-110:1-110
• server/src/services/logger.service.ts: 1-114:1-114
• server/src/services/redis.service.ts: 1-274:1-274
• server/src/services/storage.service.ts: 1-278:1-278
• server/src/modules/book-generator/FAULT_TOLERANCE.md: 1-334:1-334

架构总览

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

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
• server/src/middleware/security.ts: 6-27:6-27
• server/src/middleware/rate-limiter.ts: 49-72:49-72
• server/src/middleware/performance.ts: 29-76:29-76
• server/src/services/sentry.service.ts: 7-43:7-43
• server/src/services/redis.service.ts: 3-38:3-38
• server/src/services/storage.service.ts: 13-35:13-35

详细组件分析

自动化部署与回滚（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启动。

    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
• AUTO_DEPLOY.md: 68-78:68-78
• deploy.sh: 54-89:54-89
• deploy-prod.sh: 79-127:79-127

章节来源

• AUTO_DEPLOY.md: 1-142:1-142
• deploy.sh: 1-209:1-209
• deploy-prod.sh: 1-171:1-171

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。

  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
• docker-nginx/bookapi.conf: 1-15:1-15

章节来源

• DEPLOY_PROD.md: 146-245:146-245
• docker-nginx/docker-compose.yml: 1-12:1-12
• docker-nginx/bookapi.conf: 1-15:1-15

安全加固与合规

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

章节来源

• server/src/middleware/security.ts: 1-154:1-154
• server/src/middleware/rate-limiter.ts: 1-120:1-120
• server/src/services/sentry.service.ts: 1-113:1-113
• server/src/services/logger.service.ts: 1-114:1-114
• server/src/services/redis.service.ts: 1-274:1-274

性能监控与可观测性

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

章节来源

• server/src/middleware/performance.ts: 1-110:1-110
• server/src/services/logger.service.ts: 74-102:74-102
• server/src/services/sentry.service.ts: 7-43:7-43

存储与缓存

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

章节来源

• server/src/services/storage.service.ts: 1-278:1-278
• server/src/services/redis.service.ts: 1-274:1-274

书籍生成容错与长耗时任务

• AI调用重试：指数退避（最多3次），记录错误并WebSocket通知。
• 节点级超时：大纲/节/小节/内容等节点设定不同超时阈值，超时触发自动恢复。
• 进度监控：10/20/30分钟三级告警，自动恢复最多2次，避免无限循环。

• WebSocket通知：12种通知类型，覆盖重试、失败、超时、恢复等场景。

  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
• server/src/modules/book-generator/FAULT_TOLERANCE.md: 86-146:86-146

章节来源

• server/src/modules/book-generator/FAULT_TOLERANCE.md: 1-334:1-334

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。

    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
• server/src/middleware/rate-limiter.ts: 1-43:1-43
• server/src/services/storage.service.ts: 13-35:13-35
• DEPLOY_PROD.md: 146-239:146-239

章节来源

• server/src/config/index.ts: 1-117:1-117
• server/src/middleware/rate-limiter.ts: 1-120:1-120
• server/src/services/storage.service.ts: 1-278:1-278
• DEPLOY_PROD.md: 146-239:146-239

性能考量

• 限流与熔断
  • 全局限流与登录/短信/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
• AUTO_DEPLOY.md: 97-111:97-111

结论

本部署文档基于仓库现有脚本与模块，给出了生产环境的部署流程、自动化与回滚策略、安全加固、监控与可观测性实践，并提供了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
• AUTO_DEPLOY.md: 68-78:68-78

部署后验证步骤

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

章节来源

• DEPLOY.md: 147-159:147-159
• DEPLOY_PROD.md: 18-25:18-25

监控配置建议

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

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