解锁 Nginx Stream 代理—全面掌握 ngx_stream_proxy_module

一、核心场景与价值

• 统一网关：对接各类后端协议（MySQL、Redis、DNS、MQTT 等），前端仅需统一配置 proxy_pass。
• 高可用容错：proxy_next_upstream + tries/timeout 实现集群故障自动切换。
• 流量控制：proxy_buffer_size、download_rate、upload_rate 精细控制吞吐。
• 安全加固：proxy_ssl_* 完整 TLS 客户端认证与加密；proxy_protocol 透传真实客户端 IP。

二、常用指令一览

三、典型配置案例

1. 基本 TCP 代理

   stream {server {listen 127.0.0.1:12345;proxy_pass 127.0.0.1:8080;}
   }
   

2. 故障转移与超时

   stream {upstream backend {server bk1.example.com:9000 max_fails=3 fail_timeout=30s;server bk2.example.com:9000;}server {listen 12345;proxy_connect_timeout      2s;      # 建链 2 秒超时proxy_timeout              30s;     # 空闲 30 秒断开proxy_next_upstream        on;proxy_next_upstream_tries  3;proxy_next_upstream_timeout 10s;proxy_pass                 backend;}
   }
   

3. UDP DNS 透传

   stream {server {listen        53 udp reuseport;proxy_timeout 5s;proxy_pass    8.8.8.8:53;proxy_responses 1;    # 期望 1 个响应proxy_requests 5;     # 5 个包后新会话}
   }
   

4. TLS 客户端向后端透传 SNI & 绑定源 IP

   stream {server {listen               443 ssl;ssl_certificate      /etc/nginx/cert.pem;ssl_certificate_key  /etc/nginx/key.pem;proxy_ssl            on;proxy_ssl_protocols  TLSv1.2 TLSv1.3;proxy_ssl_server_name on;                 # SNI 使用 proxy_pass 主机名proxy_ssl_name       $proxy_host;         # 可用变量覆盖proxy_ssl_trusted_certificate /etc/ca.pem;proxy_ssl_verify     on;proxy_ssl_verify_depth 2;proxy_bind           $remote_addr transparent;  # 出站透传客户端 IPproxy_pass           backend.example.com:8443;}
   }
   

四、优化建议与注意事项

1. 缓冲区与吞吐

   • 默认 proxy_buffer_size 16k；若协议首包超长（如大型握手），需放宽到 32k 或更高。
   • 限速指令对抗「五层洪水」神器，但与 limit_conn、limit_req 配合更佳。

2. 故障转移策略

   • proxy_next_upstream 默认仅 on/off，可结合 error、timeout、invalid_header 细化。
   • 上游需配置 max_fails + fail_timeout，才能在健康检查后自动隔离。

3. TLS 性能

   • 推荐 proxy_ssl_session_reuse on + proxy_ssl_certificate_cache（1.27.4+) 缓存客户端证书。
   • 对高并发纯代理场景可关闭 proxy_ssl_verify 以降低握手负载；生产环境慎用。

4. 透明代理 & PROXY 协议

   • proxy_bind … transparent 要求主机内核路由与 CAP_NET_RAW 权限（Linux worker 继承）。
   • 若前段使用 HAProxy 或 ELB，建议启用 proxy_protocol on 统一透传链路。

5. 半关闭与持久连接

   • 默认双向关闭时会等待 close_notify；proxy_half_close on 可更早释放单向关闭路径。

五、监控与排错

• 连接数与延迟：结合 stub_status 导出 ActiveConnections。
• 日志：在 access_log 中加入 $upstream_addr $status 监测后端异常。
• 抓包验证：对比 tcpdump 与应用日志，确认超时 / 半关闭行为。
• Plus API：对于 proxy_session_drop 可查询并手动终止失效后端的所有会话。

结语

ngx_stream_proxy_module 是 Nginx 在四层代理领域的核心模块，几乎涵盖了 连接管理、流量调度、容错恢复、安全加固 的全套需求。通过合理配置超时、限速、TLS 与故障转移，你可以搭建一个 高可用、高性能、可观测 的通用流量网关，承载 MySQL、Redis、DNS、MQTT 乃至自研协议的海量并发。深入理解指令语义与组合方式，将让你的 Nginx 在 L4 层发挥极致价值。