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
2
3
4
5
6
stream {
server {
listen 3306;
proxy_pass 127.0.0.1:3307;
}
}

二、TCP 转发与 upstream 负载均衡

和七层一样,先在 stream {} 里定义 upstream,再在 server 里引用:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
stream {
upstream pg_pool {
least_conn;
server 10.0.0.11:5432 weight=2;
server 10.0.0.12:5432;
server 10.0.0.13:5432 backup;
}

server {
listen 5432;
proxy_pass pg_pool;
proxy_connect_timeout 5s;
proxy_timeout 10m;
}
}
  • 支持加权轮询、least_conn、hash、会话保持等,与第 12 篇七层负载均衡的算法一致;
  • proxy_timeout 是两次读写操作之间的空闲超时,不是整个连接的总时长,长连接要按业务调大;
  • 健康检查在开源版 stream 里没有七层那样的 max_fails 自动摘除(ngx_stream_upstream_hc_module 属于商业订阅),需要外部探活或借助 njs。

三、UDP 转发

listen 加 udp 参数,配合 proxy_responses 控制期望的响应包数:

1
2
3
4
5
6
7
8
stream {
server {
listen 53 udp;
proxy_pass 10.0.0.20:53;
proxy_responses 1;
proxy_timeout 2s;
}
}

常用于 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
2
3
4
5
6
7
8
9
10
11
12
13
stream {
map $ssl_preread_server_name $backend {
a.example 10.0.0.21:443;
b.example 10.0.0.22:443;
default 10.0.0.21:443;
}

server {
listen 443;
ssl_preread on;
proxy_pass $backend;
}
}

这样一份 Nginx 就能把不同域名的 TLS 连接原样转发给不同后端,由后端自己终止 TLS,避免在网关重复配置证书。

五、resolver 与变量化地址

stream 里 proxy_pass 写域名时,默认在配置加载时解析一次。后端地址会变(容器编排、DNS 轮询)时,用变量 + resolver 让它在运行时解析:

1
2
3
4
5
6
7
8
9
stream {
server {
listen 8000;
resolver 127.0.0.11 valid=10s ipv6=off;
resolver_timeout 5s;
set $upstream "backend.internal:8000";
proxy_pass $upstream;
}
}
  • resolver 支持 valid= 控制缓存时长,避免每次连接都查 DNS;
  • 变量化后每次连接重新解析,DNS 轮询天然生效。

六、常见坑

坑说明
没编译 --with-streamstream 指令直接报 unknown directive,需重编译或用带该模块的包
与 http 抢同一端口http 与 stream 的 listen 端口冲突,需分开
proxy_timeout 理解成总时长它是空闲超时,长连接要调大,否则被误断
用七层指令proxy_set_header、proxy_buffering 在 stream 里不存在
期望自动健康检查开源版 stream 无主动健康检查,需外部探活
域名解析只发生在启动时加 resolver + 变量,才能动态解析
SNI 分流配置写错map 的 key 是 $ssl_preread_server_name,值是地址,别写反

参考链接

  1. Nginx 官方文档:ngx_stream_core_module —— stream、listen、resolver、变量;
  2. Nginx 官方文档:ngx_stream_proxy_module —— proxy_pass、proxy_timeout、proxy_responses;
  3. Nginx 官方文档:ngx_stream_upstream_module —— 四层负载均衡与算法;
  4. Nginx 官方文档:ngx_stream_ssl_preread_module —— 不解密读取 SNI;
  5. 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
作者
一念
发布于
2026年11月21日
许可协议