Nginx 反向代理实战指南：从动态解析到 WebSocket

在现代微服务架构中，Nginx 不仅仅是一个静态资源服务器，更充当着核心网关的角色。它负责流量的路由、负载均衡以及协议的转换。本文将结合具体的生产环境配置实例，详细解析 Nginx 在处理 API 转发、路径重写（Rewrite）以及长连接代理时的最佳实践。

1. 核心前置：动态域名解析与 Resolver

在容器化环境（如 Docker、Kubernetes）中，服务实例的 IP 地址通常是动态变化的。如果在 Nginx 配置文件中直接使用 proxy_pass http://backend:8080;，Nginx 仅会在启动或重载配置时解析一次域名。若后端服务重启IP变更，Nginx 将无法感知，导致“Host not found”或连接超时。

为了解决这个问题，通常采用 “变量定义 Upstream” 的技巧，强制 Nginx 在每次请求时重新解析域名。但这要求必须显式配置 resolver 指令。

关键配置示例

 

 1 http {
 2     # 定义 DNS 解析器
 3     # Docker 环境通常使用 127.0.0.11
 4     # 公网环境可使用 8.8.8.8 或 1.1.1.1
 5     resolver 127.0.0.11 valid=30s; 
 6     
 7     # 解析超时时间
 8     resolver_timeout 5s;
 9 
10     server {
11         listen 80;
12         # ... 后续 location 配置
13     }
14 }

　　

技术解析：

• resolver: 指定 Nginx 用于解析 upstream 域名的 DNS 服务器地址。

• valid: 设置 DNS 缓存的有效期。在动态性极高的环境中，适当降低该值（如 10s-30s）可以更敏捷地感知后端变化。

---

2. 场景演练：常规 API 代理与路径剥离

最常见的反代需求是将前端的特定前缀请求（如 /prd-api/）转发给后端服务，但在转发时需要去除该前缀。

配置实例：/prd-api/

 

nginx

 1 location /prd-api/ {
 2     # 1. 使用变量定义 Upstream，配合 resolver 实现动态解析
 3     set $backend_upstream http://backend:8080;
 4 
 5     # 2. 路径重写：剥离 /prd-api/ 前缀
 6     # 请求 /prd-api/users -> /users
 7     rewrite ^/prd-api/(.*)$ /$1 break;
 8 
 9     # 3. 转发请求
10     proxy_pass $backend_upstream;
11 
12     # 4. 传递标准 Header，确保后端获取真实客户端信息
13     proxy_set_header Host $host;
14     proxy_set_header X-Real-IP $remote_addr;
15     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16     proxy_set_header X-Forwarded-Proto $scheme;
17 }

 

技术解析：

• set $backend_upstream: 结合前文提到的 resolver，此写法确保了 Nginx 在运行时动态解析 backend 域名，增强了服务的容错性。

• rewrite ... break: 正则表达式 ^/prd-api/(.*)$ 捕获了 URI 后半部分，并重组为 /$1。break 标志位至关重要，它指示 Nginx 停止当前 rewrite 阶段的匹配，直接使用修改后的 URI 进行 proxy_pass 处理。

---

3. 场景演练：API 路径映射

在某些复杂场景下，前端暴露的路由结构与后端服务的实际路由结构并不一致，这时需要进行路径映射替换，而不仅仅是剥离前缀。

配置实例：/ai-api/

 

nginx

 1 # Proxy for AI analysis API
 2 location /ai-api/ {
 3     set $analysis_upstream http://analysis:8199;
 4 
 5     # 路径映射：将 /ai-api/xxxx 映射为 /api/xxxx
 6     rewrite ^/ai-api/(.*)$ /api/$1 break;
 7 
 8     proxy_pass $analysis_upstream;
 9 
10     proxy_set_header Host $host;
11     proxy_set_header X-Real-IP $remote_addr;
12     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
13     proxy_set_header X-Forwarded-Proto $scheme;
14 }

 

技术解析：

• 该配置实现了业务逻辑的解耦。对外暴露的是业务相关的 /ai-api/，而对内则路由到了通用分析服务的 /api/ 接口。这种屏蔽内部实现细节的做法增强了系统的安全性与灵活性。

---

4. 场景演练：WebSocket 协议升级

WebSocket 是一种全双工通信协议，常用于实时消息推送。由于 Nginx 默认使用 HTTP/1.0 连接上游，且不传递 Upgrade 头部，直接反代会导致 WebSocket 握手失败。

配置实例：/ws-api/

 

nginx

 1 # Proxy for WebSocket (frontend -> PC Backend)
 2 location /ws-api/ {
 3     set $backend_upstream http://backend:8081;
 4 
 5     # 复杂的路径重写：前端 /ws-api/ -> 后端 /websocket/server/
 6     rewrite ^/ws-api/(.*)$ /websocket/server/$1 break;
 7 
 8     proxy_pass $backend_upstream;
 9 
10     # --- WebSocket 核心配置 Start ---
11     
12     # 1. 必须使用 HTTP/1.1，HTTP/1.0 不支持 Keep-alive 和 Upgrade
13     proxy_http_version 1.1;
14     
15     # 2. 传递 Upgrade 头部，告知后端进行协议升级
16     proxy_set_header Upgrade $http_upgrade;
17     proxy_set_header Connection "upgrade";
18     
19     # --- WebSocket 核心配置 End ---
20 
21     proxy_set_header Host $host;
22     proxy_set_header X-Real-IP $remote_addr;
23     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
24     proxy_set_header X-Forwarded-Proto $scheme;
25     
26     # 建议：适当延长读取超时时间，避免长连接因空闲被切断
27     proxy_read_timeout 3600s;
28 }

 

技术解析：

• proxy_http_version 1.1: 这是 WebSocket 反代的基石。

• Header 传递: $http_upgrade 变量包含了客户端请求中的 Upgrade 头部值（通常为 "websocket"）。显式设置 Connection "upgrade" 是完成握手协议升级的必要步骤。

• 超时设置: WebSocket 通常保持长连接，默认的 60 秒超时往往不足，建议根据业务需求调整 proxy_read_timeout。

---

总结

通过合理配置 resolver 实现动态解析，利用 rewrite 处理灵活的路径路由，以及正确设置 Header 支持 WebSocket 协议，Nginx 能够高效地支撑起复杂的微服务流量转发需求。在实际生产部署中，保持配置的模块化与可读性同样至关重要。