audio_codebuddy/.qoder/repowiki/zh/content/部署运维/容器化部署.md

容器化部署

本文引用的文件

• DEPLOY.md
• docker-nginx/docker-compose.yml
• docker-nginx/bookapi.conf
• docker-nginx/README.md
• server/package.json
• server/src/config/index.ts
• server/src/middleware/security.ts
• server/src/middleware/cache.ts
• server/src/middleware/performance.ts
• server/src/services/logger.service.ts
• server/src/middleware/rate-limiter.ts
• server/src/middleware/auth.js
• server/test-api.js

目录

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

简介

本文件面向AI有声书生成平台的容器化部署，围绕以下目标展开：

• Docker镜像构建流程与多阶段优化思路
• 镜像安全配置与最小权限原则
• docker-compose编排：服务依赖、网络与卷挂载
• Nginx反向代理：负载均衡、SSL终止、静态资源处理
• 容器健康检查、资源限制与日志收集
• 监控指标、性能调优与故障排查

项目结构

本仓库包含后端服务、前端UniApp工程、部署文档与Nginx容器化代理样例。与容器化部署直接相关的关键位置如下：

• 后端服务位于 server 目录，包含应用入口、中间件、配置与服务模块
• Nginx容器化代理位于 docker-nginx 目录，提供本地开发环境下的反向代理

• 部署文档 DEPLOY.md 提供了传统PM2部署与Docker方案的参考

  graph TB
  subgraph "宿主机"
  Dev["开发者工作站"]
  Prod["生产服务器"]
  end
  subgraph "容器编排"
  NGINX["Nginx 反向代理<br/>端口映射 80:80"]
  BACKEND["后端服务<br/>端口映射 3000:3000"]
  REDIS["Redis 缓存"]
  MYSQL["MySQL 数据库"]
  end
  Dev --> |"HTTP/HTTPS"| NGINX
  NGINX --> |"反代 /api"| BACKEND
  BACKEND --> |"读写"| REDIS
  BACKEND --> |"读写"| MYSQL
  Prod --> |"运维/监控"| NGINX
  Prod --> |"运维/监控"| BACKEND
  

图示来源

• docker-nginx/docker-compose.yml:1-12
• server/src/config/index.ts:73-75

章节来源

• DEPLOY.md:1-251
• docker-nginx/docker-compose.yml:1-12

核心组件

• Nginx反向代理：负责域名解析、静态资源分发、WebSocket升级、上游健康转发
• 后端服务：基于Koa框架的应用，提供API、鉴权、限流、缓存、日志与安全中间件
• 缓存与数据库：Redis用于限流与缓存，MySQL用于持久化
• 健康检查与日志：通过/health端点与日志中间件输出运行状态与请求详情

章节来源

• server/src/config/index.ts:69-117
• server/src/middleware/security.ts:1-154
• server/src/middleware/cache.ts:1-45
• server/src/middleware/performance.ts:1-109
• server/src/services/logger.service.ts:39-92
• server/src/middleware/rate-limiter.ts:1-119

架构总览

下图展示容器化部署的典型拓扑：Nginx作为入口，后端服务提供API与业务逻辑，Redis与MySQL分别承担缓存与数据存储。

graph TB
Client["客户端浏览器/小程序"] --> Nginx["Nginx 反向代理"]
Nginx --> API["后端服务 /api/*"]
Nginx --> Static["静态资源 / (前端构建产物)"]
API --> Redis["Redis 缓存"]
API --> DB["MySQL 数据库"]
API --> Logger["日志服务"]
API --> Monitor["性能监控"]

图示来源

• docker-nginx/bookapi.conf:1-15
• server/src/config/index.ts:73-75

详细组件分析

Nginx反向代理（docker-compose）

• 服务名称与镜像：使用官方nginx:latest
• 端口映射：宿主80映射容器80
• 卷挂载：将本地bookapi.conf挂载至/etc/nginx/conf.d/bookapi.conf，实现热更新
• 上游地址：通过host.docker.internal:3000指向宿主机后端（开发环境）
• 重启策略：unless-stopped

• 验证方式：curl http://bookapi.rrbrr.com/api/health

  sequenceDiagram
  participant C as "客户端"
  participant N as "Nginx 容器"
  participant B as "后端容器"
  C->>N : "HTTP 请求 (bookapi.rrbrr.com)"
  N->>N : "解析 conf.d/bookapi.conf"
  N->>B : "proxy_pass http : //host.docker.internal : 3000"
  B-->>N : "响应 (JSON/HTML)"
  N-->>C : "返回响应"
  

图示来源

• docker-nginx/docker-compose.yml:1-12
• docker-nginx/bookapi.conf:1-15

章节来源

• docker-nginx/docker-compose.yml:1-12
• docker-nginx/bookapi.conf:1-15
• docker-nginx/README.md:1-41

后端服务（Koa应用）

• 应用入口与脚本：通过package.json的scripts控制开发、构建与启动
• 配置加载：dotenv加载环境变量，config/index.ts集中管理端口、JWT、模型、上传等配置

• 中间件体系：

  • 安全中间件：XSS防护、SQL注入检测、敏感数据脱敏、安全响应头
  • 缓存中间件：基于Redis的读写缓存
  • 速率限制：内存/Redis双栈限流，支持按IP、用户、接口维度
  • 性能监控：统计总请求数、平均响应时间、慢请求、错误率
  • 日志中间件：统一格式化HTTP请求日志

  • 鉴权中间件：支持可选鉴权与Token校验

    flowchart TD
    Start(["请求进入"]) --> Security["安全中间件<br/>XSS/SQL注入/响应头"]
    Security --> Cache["缓存中间件<br/>命中则返回"]
    Cache --> Rate["限流中间件<br/>内存/Redis"]
    Rate --> Perf["性能监控中间件<br/>统计指标"]
    Perf --> Handler["业务处理器<br/>控制器/服务层"]
    Handler --> Log["日志中间件<br/>HTTP日志"]
    Log --> Resp(["返回响应"])
    

图示来源

• server/src/middleware/security.ts:1-154
• server/src/middleware/cache.ts:1-45
• server/src/middleware/rate-limiter.ts:1-119
• server/src/middleware/performance.ts:1-109
• server/src/services/logger.service.ts:39-92
• server/src/middleware/auth.js:1-35

章节来源

• server/package.json:1-60
• server/src/config/index.ts:69-117
• server/src/middleware/security.ts:1-154
• server/src/middleware/cache.ts:1-45
• server/src/middleware/rate-limiter.ts:1-119
• server/src/middleware/performance.ts:1-109
• server/src/services/logger.service.ts:39-92
• server/src/middleware/auth.js:1-35

健康检查与日志

• 健康检查：后端提供/health端点，Nginx可据此进行健康探测
• 日志：统一使用winston输出到文件，支持HTTP请求日志与错误日志

章节来源

• server/test-api.js:8-15
• server/src/services/logger.service.ts:39-92

依赖关系分析

• 服务依赖
  • 后端依赖Redis与MySQL（由配置与中间件使用体现）
  • Nginx依赖后端容器（通过proxy_pass指向）
• 网络设置
  • Nginx容器暴露80端口；后端容器暴露3000端口
  • 开发环境通过extra_hosts将host.docker.internal解析为宿主机网关

• 卷挂载

  • Nginx挂载conf.d配置文件以实现热更新

  • 后端可通过卷挂载上传目录或日志目录（依据实际部署）

    graph LR
    NGINX["Nginx 容器"] -- "80/tcp" --> Host["宿主机:80"]
    BACKEND["后端容器"] -- "3000/tcp" --> Host
    NGINX --> |"proxy_pass"| BACKEND
    BACKEND --> |"Redis"| REDIS["Redis 容器"]
    BACKEND --> |"MySQL"| MYSQL["MySQL 容器"]
    

图示来源

• docker-nginx/docker-compose.yml:1-12
• server/src/config/index.ts:73-75

章节来源

• docker-nginx/docker-compose.yml:1-12
• server/src/config/index.ts:73-75

性能考虑

• 限流策略
  • 全局限流、登录限流、短信验证码限流、TTS生成限流、文件上传限流
  • Redis可用时优先使用Redis限流，否则回退到内存限流
• 缓存策略
  • 对热点接口使用Redis缓存，命中即返回，降低后端压力
• 性能监控
  • 统计总请求数、平均响应时间、慢请求阈值、错误率，并通过响应头返回响应时间
• 日志与追踪
  • HTTP请求日志统一格式化，便于聚合与检索

章节来源

• server/src/middleware/rate-limiter.ts:1-119
• server/src/middleware/cache.ts:1-45
• server/src/middleware/performance.ts:1-109
• server/src/services/logger.service.ts:39-92

故障排查指南

• 后端无法启动
  • 检查端口占用与环境变量（.env）
  • 查看PM2日志或容器日志
• 前端无法访问
  • 检查Nginx配置语法与静态资源路径
  • 查看Nginx访问/错误日志
• 数据库连接失败
  • 检查MySQL服务状态与连接串配置
• 健康检查失败
  • 使用curl验证/health端点
  • 检查后端日志定位异常

章节来源

• DEPLOY.md:199-214
• server/test-api.js:8-44

结论

本容器化方案以Nginx为入口，后端采用Koa中间件体系实现安全、限流、缓存与可观测性，结合Redis与MySQL满足高并发与可靠性需求。通过docker-compose实现快速编排与热更新，配合健康检查与日志采集，可支撑生产级部署与运维。

附录

Docker镜像构建与多阶段优化（建议）

• 基础镜像选择：使用官方Node.js Alpine作为基础镜像，减小体积
• 多阶段构建建议：
  • 构建阶段：安装依赖并执行构建，产出dist
  • 运行阶段：仅复制dist与运行时依赖，避免打包源码与开发依赖
• 最小权限与非root运行：以非root用户运行应用，限制文件权限
• 安全扫描：在CI中集成镜像漏洞扫描
• 健康检查：在Dockerfile中添加HEALTHCHECK，探测/health端点
• 资源限制：在docker-compose中设置CPU/内存限制与重启策略

docker-compose编排要点

• 服务命名与重启策略：unless-stopped
• 网络隔离：使用自定义bridge网络，限制容器间直接通信
• 卷管理：明确声明卷（如上传目录、日志目录）并设置权限
• 环境变量：通过env文件集中管理，避免明文硬编码

Nginx反向代理配置要点

• 负载均衡：多实例后端时使用upstream与轮询/权重策略
• SSL终止：在Nginx层启用TLS，使用Let’s Encrypt自动化证书
• 静态资源：开启缓存与压缩，分离前端构建产物与后端API
• WebSocket：正确传递Upgrade/Connection头部，保持长连接

容器健康检查、资源限制与日志

• 健康检查：/api/health或/health端点，返回200即健康
• 资源限制：CPU/内存/文件描述符上限，避免资源争抢
• 日志：stdout/stderr结合集中日志采集（如Fluent Bit/ELK）