# 容器化部署

<cite>
**本文引用的文件**
- [DEPLOY.md](file://DEPLOY.md)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf)
- [docker-nginx/README.md](file://docker-nginx/README.md)
- [server/package.json](file://server/package.json)
- [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/cache.ts](file://server/src/middleware/cache.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/middleware/rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [server/src/middleware/auth.js](file://server/src/middleware/auth.js)
- [server/test-api.js](file://server/test-api.js)
</cite>

## 目录
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方案的参考

```mermaid
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](file://docker-nginx/docker-compose.yml#L1-L12)
- [server/src/config/index.ts:73-75](file://server/src/config/index.ts#L73-L75)

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

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

章节来源
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/middleware/security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/cache.ts:1-45](file://server/src/middleware/cache.ts#L1-L45)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/logger.service.ts:39-92](file://server/src/services/logger.service.ts#L39-L92)
- [server/src/middleware/rate-limiter.ts:1-119](file://server/src/middleware/rate-limiter.ts#L1-L119)

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

```mermaid
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](file://docker-nginx/bookapi.conf#L1-L15)
- [server/src/config/index.ts:73-75](file://server/src/config/index.ts#L73-L75)

## 详细组件分析

### 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

```mermaid
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](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

章节来源
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [docker-nginx/README.md:1-41](file://docker-nginx/README.md#L1-L41)

### 后端服务（Koa应用）
- 应用入口与脚本：通过package.json的scripts控制开发、构建与启动
- 配置加载：dotenv加载环境变量，config/index.ts集中管理端口、JWT、模型、上传等配置
- 中间件体系：
  - 安全中间件：XSS防护、SQL注入检测、敏感数据脱敏、安全响应头
  - 缓存中间件：基于Redis的读写缓存
  - 速率限制：内存/Redis双栈限流，支持按IP、用户、接口维度
  - 性能监控：统计总请求数、平均响应时间、慢请求、错误率
  - 日志中间件：统一格式化HTTP请求日志
  - 鉴权中间件：支持可选鉴权与Token校验

```mermaid
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](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/cache.ts:1-45](file://server/src/middleware/cache.ts#L1-L45)
- [server/src/middleware/rate-limiter.ts:1-119](file://server/src/middleware/rate-limiter.ts#L1-L119)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/logger.service.ts:39-92](file://server/src/services/logger.service.ts#L39-L92)
- [server/src/middleware/auth.js:1-35](file://server/src/middleware/auth.js#L1-L35)

章节来源
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/middleware/security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/middleware/cache.ts:1-45](file://server/src/middleware/cache.ts#L1-L45)
- [server/src/middleware/rate-limiter.ts:1-119](file://server/src/middleware/rate-limiter.ts#L1-L119)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/logger.service.ts:39-92](file://server/src/services/logger.service.ts#L39-L92)
- [server/src/middleware/auth.js:1-35](file://server/src/middleware/auth.js#L1-L35)

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

章节来源
- [server/test-api.js:8-15](file://server/test-api.js#L8-L15)
- [server/src/services/logger.service.ts:39-92](file://server/src/services/logger.service.ts#L39-L92)

## 依赖关系分析
- 服务依赖
  - 后端依赖Redis与MySQL（由配置与中间件使用体现）
  - Nginx依赖后端容器（通过proxy_pass指向）
- 网络设置
  - Nginx容器暴露80端口；后端容器暴露3000端口
  - 开发环境通过extra_hosts将host.docker.internal解析为宿主机网关
- 卷挂载
  - Nginx挂载conf.d配置文件以实现热更新
  - 后端可通过卷挂载上传目录或日志目录（依据实际部署）

```mermaid
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](file://docker-nginx/docker-compose.yml#L1-L12)
- [server/src/config/index.ts:73-75](file://server/src/config/index.ts#L73-L75)

章节来源
- [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)

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

章节来源
- [server/src/middleware/rate-limiter.ts:1-119](file://server/src/middleware/rate-limiter.ts#L1-L119)
- [server/src/middleware/cache.ts:1-45](file://server/src/middleware/cache.ts#L1-L45)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/logger.service.ts:39-92](file://server/src/services/logger.service.ts#L39-L92)

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

章节来源
- [DEPLOY.md:199-214](file://DEPLOY.md#L199-L214)
- [server/test-api.js:8-44](file://server/test-api.js#L8-L44)

## 结论
本容器化方案以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）