# Nginx反向代理

<cite>
**本文引用的文件列表**
- [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf)
- [docker-nginx/README.md](file://docker-nginx/README.md)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [book.rrbrr.com.conf](file://book.rrbrr.com.conf)
- [docs/DEPLOY.md](file://docs/DEPLOY.md)
- [deploy.sh](file://deploy.sh)
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/middleware/cache.ts](file://server/src/middleware/cache.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构与入口](#项目结构与入口)
3. [核心组件与配置总览](#核心组件与配置总览)
4. [架构概览](#架构概览)
5. [详细组件解析](#详细组件解析)
6. [依赖关系分析](#依赖关系分析)
7. [性能优化与最佳实践](#性能优化与最佳实践)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向AI有声书生成平台的运维与开发人员，系统化梳理Nginx反向代理配置，重点解析以下方面：
- server块与location规则
- upstream集群与负载均衡策略
- 静态资源服务与缓存策略
- SSL/TLS证书与HTTPS重定向
- 超时、缓冲区、连接数等性能优化
- 健康检查与故障转移建议

## 项目结构与入口
本仓库包含两套Nginx配置入口：
- Docker开发环境：通过docker-nginx目录中的配置文件与compose编排，将bookapi.rrbrr.com反向代理至本地后端（默认端口3000）。
- 生产环境：book.rrbrr.com.conf提供静态资源、API代理、证书与安全头等完整配置；另有部署脚本与文档中给出的Nginx示例。

```mermaid
graph TB
subgraph "Docker开发环境"
DConf["docker-nginx/bookapi.conf"]
DCmp["docker-nginx/docker-compose.yml"]
DReadme["docker-nginx/README.md"]
end
subgraph "生产环境"
PConf["book.rrbrr.com.conf"]
PDeploy["deploy.sh"]
PDoc["docs/DEPLOY.md"]
end
DCmp --> DConf
DReadme --> DConf
PDoc --> PConf
PDeploy --> PConf
```

**图表来源**
- [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)
- [book.rrbrr.com.conf:1-40](file://book.rrbrr.com.conf#L1-L40)
- [docs/DEPLOY.md:254-286](file://docs/DEPLOY.md#L254-L286)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

**Section sources**
- [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)
- [book.rrbrr.com.conf:1-40](file://book.rrbrr.com.conf#L1-L40)
- [docs/DEPLOY.md:254-286](file://docs/DEPLOY.md#L254-L286)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

## 核心组件与配置总览
- Docker开发环境（bookapi.conf）
  - 监听80端口，server_name为bookapi.rrbrr.com
  - location / 反向代理到host.docker.internal:3000
  - 设置HTTP/1.1、Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto等头部
- 生产环境（book.rrbrr.com.conf）
  - 监听80端口，返回301重定向至https
  - 443端口监听，启用http2，配置SSL证书与加密套件
  - 静态资源缓存：/uploads/与/audio/目录expires 7d；通用静态资源expires 1y
  - API代理：/api/代理到127.0.0.1:3100
  - SPA回退：/路由fallback到index.html
  - 安全头：Strict-Transport-Security、Alt-Svc等
- 文档与脚本
  - docs/DEPLOY.md提供传统部署的Nginx示例与SSL配置步骤
  - deploy.sh展示生产环境443站点的SSL与API代理配置

**Section sources**
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [book.rrbrr.com.conf:1-40](file://book.rrbrr.com.conf#L1-L40)
- [docs/DEPLOY.md:254-286](file://docs/DEPLOY.md#L254-L286)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

## 架构概览
下图展示了从客户端到后端服务的典型请求路径，以及静态资源与API代理的关键节点。

```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant N as "Nginx(80/443)"
participant S as "静态资源(/uploads,/audio,*.ext)"
participant A as "API代理(/api/)"
participant B as "后端服务(3000/3100)"
U->>N : "HTTP/HTTPS 请求"
alt "静态资源"
N->>S : "命中静态location"
S-->>U : "带Cache-Control/Expires的静态文件"
else "API请求"
N->>A : "转发到后端"
A->>B : "反向代理"
B-->>A : "响应"
A-->>U : "返回API结果"
end
```

**图表来源**
- [book.rrbrr.com.conf:8-38](file://book.rrbrr.com.conf#L8-L38)
- [docker-nginx/bookapi.conf:6-13](file://docker-nginx/bookapi.conf#L6-L13)

## 详细组件解析

### Docker开发环境：bookapi.conf
- server块
  - 监听80，server_name为bookapi.rrbrr.com
- location /
  - proxy_pass指向host.docker.internal:3000
  - 设置HTTP/1.1与关键头部（Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto）
- docker-compose
  - 映射80:80，挂载bookapi.conf，extra_hosts注入host.docker.internal

```mermaid
flowchart TD
Start(["请求进入"]) --> Port80["监听80端口"]
Port80 --> ProxyPass["location / 反向代理到 host.docker.internal:3000"]
ProxyPass --> Headers["设置X-Forwarded-*头部"]
Headers --> Backend["到达后端服务(3000)"]
Backend --> Resp["返回响应"]
Resp --> End(["结束"])
```

**图表来源**
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [docker-nginx/docker-compose.yml:5-11](file://docker-nginx/docker-compose.yml#L5-L11)

**Section sources**
- [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/README.md:1-41](file://docker-nginx/README.md#L1-L41)

### 生产环境：book.rrbrr.com.conf
- 80端口server块
  - 返回301重定向至https
- 443端口server块
  - http2开启
  - SSL证书与私钥路径配置
  - 加密套件与TLS协议版本
  - 会话票据、会话缓存与超时
  - 安全头：Strict-Transport-Security、Alt-Svc
  - 错误页：497重定向至HTTPS
- 静态资源location
  - /uploads/与/audio/目录别名映射，并设置7天缓存与immutable
  - 通用静态资源(js/css/png/jpg/gif/svg/woff/woff2/ttf/eot)1年缓存与immutable
- API代理location
  - /api/代理到127.0.0.1:3100，设置Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto
- SPA回退
  - /路由使用try_files回退到index.html

```mermaid
flowchart TD
A["80端口"] --> R301["301重定向到https"]
B["443端口"] --> SSL["加载证书与加密套件"]
SSL --> Static["静态资源缓存策略"]
SSL --> API["/api/代理到后端"]
SSL --> SPA["SPA回退到index.html"]
Static --> Done["完成"]
API --> Done
SPA --> Done
```

**图表来源**
- [book.rrbrr.com.conf:1-40](file://book.rrbrr.com.conf#L1-L40)

**Section sources**
- [book.rrbrr.com.conf:1-40](file://book.rrbrr.com.conf#L1-L40)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

### 静态资源服务与缓存策略
- 目录级缓存
  - /uploads/与/audio/：expires 7d，Cache-Control "public, immutable"
- 通用静态资源
  - js/css/png/jpg/jpeg/gif/ico/svg/woff/woff2/ttf/eot：expires 1y，Cache-Control "public, immutable"
- SPA回退
  - /路由使用try_files回退到index.html，适配Vue单页应用

```mermaid
flowchart TD
Req["请求静态资源"] --> Match{"匹配目录或扩展名"}
Match --> |/uploads/*| U["设置7天缓存与immutable"]
Match --> |/audio/*| Au["设置7天缓存与immutable"]
Match --> |*.ext(js/css/...)| Ext["设置1年缓存与immutable"]
Match --> |其他| Fallback["SPA回退index.html"]
U --> Resp["返回带缓存头的静态文件"]
Au --> Resp
Ext --> Resp
Fallback --> Resp
```

**图表来源**
- [book.rrbrr.com.conf:17-38](file://book.rrbrr.com.conf#L17-L38)

**Section sources**
- [book.rrbrr.com.conf:17-38](file://book.rrbrr.com.conf#L17-L38)

### SSL/TLS与HTTPS重定向
- 80端口：301重定向至https
- 443端口：http2开启，配置证书与私钥路径
- 加密套件与TLS版本：TLSv1.1/1.2/1.3，禁用MD5
- 会话票据与缓存：ssl_session_tickets on，shared:SSL:10m，超时10m
- 安全头：Strict-Transport-Security、Alt-Svc
- 错误页：497重定向至HTTPS

```mermaid
sequenceDiagram
participant C as "客户端"
participant N as "Nginx 80"
participant N443 as "Nginx 443"
C->>N : "HTTP请求"
N-->>C : "301重定向到https"
C->>N443 : "HTTPS请求"
N443-->>C : "返回受保护内容(含安全头)"
```

**图表来源**
- [book.rrbrr.com.conf:3,150-186:3-4](file://book.rrbrr.com.conf#L3-L4)
- [book.rrbrr.com.conf:150-186](file://book.rrbrr.com.conf#L150-L186)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

**Section sources**
- [book.rrbrr.com.conf:3,150-186:3-4](file://book.rrbrr.com.conf#L3-L4)
- [book.rrbrr.com.conf:150-186](file://book.rrbrr.com.conf#L150-L186)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)

### API代理与后端交互
- Docker开发环境
  - location /代理到host.docker.internal:3000
  - 设置X-Forwarded-Proto，便于后端识别原始协议
- 生产环境
  - /api/代理到127.0.0.1:3100
  - 设置Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto

```mermaid
sequenceDiagram
participant C as "客户端"
participant N as "Nginx"
participant B as "后端服务"
C->>N : "请求 /api/*"
N->>B : "转发到后端(3000/3100)"
B-->>N : "响应"
N-->>C : "返回API结果"
```

**图表来源**
- [docker-nginx/bookapi.conf:6-13](file://docker-nginx/bookapi.conf#L6-L13)
- [book.rrbrr.com.conf:8-15](file://book.rrbrr.com.conf#L8-L15)

**Section sources**
- [docker-nginx/bookapi.conf:6-13](file://docker-nginx/bookapi.conf#L6-L13)
- [book.rrbrr.com.conf:8-15](file://book.rrbrr.com.conf#L8-L15)

### 负载均衡策略与上游集群
- 当前配置未显式声明upstream块
  - Docker开发环境：直接代理到单一后端host.docker.internal:3000
  - 生产环境：/api/代理到127.0.0.1:3100
- 建议（概念性说明）
  - 若需多实例负载均衡，可在Nginx中定义upstream并选择轮询或加权轮询
  - 健康检查可通过Nginx内置的fail_timeout与max_fails参数实现基础探测
  - 对于高并发场景，结合后端PM2集群或多容器部署更稳妥

[本节为概念性说明，不直接分析具体源码文件]

## 依赖关系分析
- Nginx与后端服务
  - Nginx作为统一入口，负责静态资源缓存、API代理与SSL终止
  - 后端服务提供业务接口与静态资源挂载（/uploads）
- Docker开发环境
  - docker-compose将Nginx容器与后端容器解耦，通过extra_hosts解析host.docker.internal
- 生产环境
  - Nginx直接代理到本地后端进程（127.0.0.1:3100）

```mermaid
graph LR
Client["客户端"] --> Nginx["Nginx(80/443)"]
Nginx --> Static["静态资源(/uploads,/audio,*.ext)"]
Nginx --> API["API代理(/api/)"]
API --> Backend["后端服务(3000/3100)"]
```

**图表来源**
- [book.rrbrr.com.conf:8-38](file://book.rrbrr.com.conf#L8-L38)
- [docker-nginx/docker-compose.yml:5-11](file://docker-nginx/docker-compose.yml#L5-L11)

**Section sources**
- [book.rrbrr.com.conf:8-38](file://book.rrbrr.com.conf#L8-L38)
- [docker-nginx/docker-compose.yml:5-11](file://docker-nginx/docker-compose.yml#L5-L11)

## 性能优化与最佳实践
- 缓冲区与超时
  - 在高并发或大文件传输场景，建议在location中设置proxy_buffering、proxy_buffer_size、proxy_busy_buffers_size、proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout等参数（概念性建议）
- 连接数限制
  - 结合后端进程数量与系统ulimit，合理设置worker_connections与worker_processes（概念性建议）
- Gzip压缩
  - 对文本类资源启用gzip，减少带宽占用（概念性建议）
- 静态资源缓存
  - 已在生产配置中对静态资源设置长缓存与immutable，建议配合文件指纹化进一步提升缓存命中率（概念性建议）
- 健康检查与故障转移
  - 建议在upstream中配置backup与fail_timeout，实现基础健康检查与故障转移（概念性建议）
- 后端性能指标
  - 后端提供性能监控中间件与指标路由，可用于评估Nginx代理下的整体性能（参考server/src/middleware/performance.ts与server/src/app.ts中的路由）

**Section sources**
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/app.ts:92-97](file://server/src/app.ts#L92-L97)

## 故障排查指南
- Docker开发环境
  - hosts文件未正确映射bookapi.rrbrr.com导致无法访问
  - host.docker.internal无法解析时，改用宿主机局域网IP
  - 配置修改后通过docker-compose exec nginx nginx -s reload重载
- 生产环境
  - 443证书路径与权限问题导致SSL握手失败
  - /api/代理目标端口错误或后端未监听
  - 静态资源缓存头导致浏览器缓存旧版本，建议清理浏览器缓存或强制刷新
- 通用
  - 查看Nginx错误日志与访问日志定位问题
  - 使用curl或浏览器开发者工具检查响应头与状态码

**Section sources**
- [docker-nginx/README.md:30-41](file://docker-nginx/README.md#L30-L41)
- [book.rrbrr.com.conf:150-186](file://book.rrbrr.com.conf#L150-L186)

## 结论
- Docker开发环境提供轻量级反向代理，适合本地联调
- 生产环境配置覆盖静态资源缓存、API代理、SSL与安全头，满足上线需求
- 如需更高可用与弹性，可在Nginx中引入upstream与健康检查机制，并结合后端多实例部署

[本节为总结性内容，不直接分析具体源码文件]

## 附录

### A. Docker开发环境快速上手
- 启动与停止
  - 启动：cd docker-nginx && docker-compose up -d
  - 停止：docker-compose down
  - 重载：docker-compose exec nginx nginx -s reload
- 验证
  - curl http://bookapi.rrbrr.com/api/health

**Section sources**
- [docker-nginx/README.md:5-28](file://docker-nginx/README.md#L5-L28)

### B. 生产环境Nginx示例与SSL配置
- 传统部署示例（来自docs/DEPLOY.md）
  - 包含静态资源、API代理与上传目录缓存的Nginx配置片段
- SSL证书
  - 使用Let's Encrypt免费证书的安装流程
- 生产脚本片段
  - 展示443站点的SSL、API代理与安全头配置

**Section sources**
- [docs/DEPLOY.md:254-286](file://docs/DEPLOY.md#L254-L286)
- [docs/DEPLOY.md:299-305](file://docs/DEPLOY.md#L299-L305)
- [deploy.sh:109-141](file://deploy.sh#L109-L141)