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 指令。

关键配置示例

 

http {
    # 定义 DNS 解析器
    # Docker 环境通常使用 127.0.0.11
    # 公网环境可使用 8.8.8.8 或 1.1.1.1
    resolver 127.0.0.11 valid=30s; 
    
    # 解析超时时间
    resolver_timeout 5s;

    server {
        listen 80;
        # ... 后续 location 配置
    }
}

 

　　

技术解析：

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

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

---

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

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

配置实例：/prd-api/

 

nginx

location /prd-api/ {
    # 1. 使用变量定义 Upstream，配合 resolver 实现动态解析
    set $backend_upstream http://backend:8080;

    # 2. 路径重写：剥离 /prd-api/ 前缀
    # 请求 /prd-api/users -> /users
    rewrite ^/prd-api/(.*)$ /$1 break;

    # 3. 转发请求
    proxy_pass $backend_upstream;

    # 4. 传递标准 Header，确保后端获取真实客户端信息
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

 

技术解析：

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

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

---

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

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

配置实例：/ai-api/

 

nginx

# Proxy for AI analysis API
location /ai-api/ {
    set $analysis_upstream http://analysis:8199;

    # 路径映射：将 /ai-api/xxxx 映射为 /api/xxxx
    rewrite ^/ai-api/(.*)$ /api/$1 break;

    proxy_pass $analysis_upstream;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

 

技术解析：

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

---

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

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

配置实例：/ws-api/

 

nginx

# Proxy for WebSocket (frontend -> PC Backend)
location /ws-api/ {
    set $backend_upstream http://backend:8081;

    # 复杂的路径重写：前端 /ws-api/ -> 后端 /websocket/server/
    rewrite ^/ws-api/(.*)$ /websocket/server/$1 break;

    proxy_pass $backend_upstream;

    # --- WebSocket 核心配置 Start ---
    
    # 1. 必须使用 HTTP/1.1，HTTP/1.0 不支持 Keep-alive 和 Upgrade
    proxy_http_version 1.1;
    
    # 2. 传递 Upgrade 头部，告知后端进行协议升级
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    # --- WebSocket 核心配置 End ---

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 建议：适当延长读取超时时间，避免长连接因空闲被切断
    proxy_read_timeout 3600s;
}

 

技术解析：

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

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

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

---

总结

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