解锁 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。

二、常用指令一览

指令	功能要点
proxy_pass	指定后端地址：IP:端口、主机名或 unix:/path；可用变量动态决定。
proxy_bind	绑定本地源 IP（或 transparent 透传客户端 IP）发起出站连接。
proxy_connect_timeout	与后端建链超时，默认 60s。
proxy_timeout	单向读写空闲超时，默认 10m；双向保持连接时长。
proxy_buffer_size	读取客户端/后端首包的缓冲区大小（默认 16k）。
proxy_download_rate / proxy_upload_rate	单连接限速（字节/秒），支持变量。
proxy_next_upstream / _tries / _timeout	连接失败或超时时尝试下 游，可设次数和总时长。
proxy_protocol	启用 PROXY 协议，反向代理真实 IP。
proxy_half_close	打开 TCP 半关闭，双向优雅断开。
proxy_session_drop	上游下线时立即终止所有存量会话（Plus 专享）。
proxy_socket_keepalive	启用 OS TCP Keepalive。
proxy_ssl on + proxy_ssl_ 系列*	客户端证书、加密协议、SNI、会话复用、CRL 等全套 TLS 配置。

三、典型配置案例

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 层发挥极致价值。