Nginx 工程实践 -- 16. Stream 四层代理(TCP/UDP)
前面十几篇都在 http {} 里做事,Nginx 真正强大的地方还在于它的 stream {} 块:一个不解析 HTTP、工作在 L4 的转发引擎。数据库、缓存、消息队列、SSH、DNS、游戏后端,只要是 TCP/UDP,都能交给它做负载均衡、TLS 终止和按 SNI 分流。理解 stream 与 http 的边界,是把它用对的前提。
flowchart LR
C["TCP 客户端"] --> S["stream
listen 3306"]
S --> U["upstream 组
后端 A / B"]
C2["TLS 客户端"] --> P["listen 443
ssl_preread on"]
P --> M["map $ssl_preread_server_name"]
M -->|"a.example"| U1["后端 A"]
M -->|"b.example"| U2["后端 B"]
一、stream 与 http 是两套上下文
stream {} 与 http {} 平级,指令、模块、变量都不通用:
stream里没有location、root、rewrite、proxy_set_header的 HTTP 语义,也没有$request_uri这类 HTTP 变量;- 共享的是
upstream {}之外的通用能力:listen、server、日志、连接超时、负载均衡算法; - 编译时需要
--with-stream(多数发行版默认已带,可用nginx -V确认)。
1 | |
二、TCP 转发与 upstream 负载均衡
和七层一样,先在 stream {} 里定义 upstream,再在 server 里引用:
1 | |
- 支持加权轮询、
least_conn、hash、会话保持等,与第 12 篇七层负载均衡的算法一致; proxy_timeout是两次读写操作之间的空闲超时,不是整个连接的总时长,长连接要按业务调大;- 健康检查在开源版 stream 里没有七层那样的
max_fails自动摘除(ngx_stream_upstream_hc_module属于商业订阅),需要外部探活或借助njs。
三、UDP 转发
listen 加 udp 参数,配合 proxy_responses 控制期望的响应包数:
1 | |
常用于 DNS、Syslog、QUIC 实验等场景。注意 UDP 无连接,proxy_timeout 决定单个"会话"的存活判断。
四、TLS 与 ssl_preread:按 SNI 分流
stream 可以自己终止 TLS(ssl_certificate / ssl_certificate_key 在 server 里配置),也可以不解密、只做"偷看"SNI 的盲转发——这就是 ngx_stream_ssl_preread_module:
1 | |
这样一份 Nginx 就能把不同域名的 TLS 连接原样转发给不同后端,由后端自己终止 TLS,避免在网关重复配置证书。
五、resolver 与变量化地址
stream 里 proxy_pass 写域名时,默认在配置加载时解析一次。后端地址会变(容器编排、DNS 轮询)时,用变量 + resolver 让它在运行时解析:
1 | |
resolver支持valid=控制缓存时长,避免每次连接都查 DNS;- 变量化后每次连接重新解析,DNS 轮询天然生效。
六、常见坑
| 坑 | 说明 |
|---|---|
没编译 --with-stream | stream 指令直接报 unknown directive,需重编译或用带该模块的包 |
与 http 抢同一端口 | http 与 stream 的 listen 端口冲突,需分开 |
proxy_timeout 理解成总时长 | 它是空闲超时,长连接要调大,否则被误断 |
| 用七层指令 | proxy_set_header、proxy_buffering 在 stream 里不存在 |
| 期望自动健康检查 | 开源版 stream 无主动健康检查,需外部探活 |
| 域名解析只发生在启动时 | 加 resolver + 变量,才能动态解析 |
| SNI 分流配置写错 | map 的 key 是 $ssl_preread_server_name,值是地址,别写反 |
参考链接
- Nginx 官方文档:ngx_stream_core_module ——
stream、listen、resolver、变量; - Nginx 官方文档:ngx_stream_proxy_module ——
proxy_pass、proxy_timeout、proxy_responses; - Nginx 官方文档:ngx_stream_upstream_module —— 四层负载均衡与算法;
- Nginx 官方文档:ngx_stream_ssl_preread_module —— 不解密读取 SNI;
- Nginx 官方文档:ngx_stream_ssl_module —— 四层 TLS 终止。
小结
stream {}与http {}平级、指令不通用,工作在 L4;- TCP/UDP 都能转发,负载均衡算法与七层一致;
ssl_preread on可不解密按 SNI 分流,把 TLS 留给后端;- 动态后端用
resolver+ 变量化proxy_pass; - 开源版 stream 没有主动健康检查,需要外部探活。
系列导航
Nginx 工程实践 -- 16. Stream 四层代理(TCP/UDP)
https://bubao.github.io/posts/a6b7c8d9.html
