孙玲的空间很多对 Nginx 的认知还停留在 HTTP 反向代理这一层，实际上 Nginx 在 1.9.0 版本中就已经引入了 stream 模块，专门用来处理 TCP 和 UDP 的四层转发。这篇文章不讨论“给 Nginx 某个服务做负载均衡”这种老生常谈，而是把 stream 模块当作一个独立能力来拆解：它解决什么问题、配置长什么样、TCP 和 UDP 的差异在哪里、实测会遇到哪些坑，以及我把数据库入口、内部 DNS 转发接入这套体系后的真实心得。
1. 藏在 Web 服务器里的四层代理：先搞清楚你究竟要转发什么
在动手配 Nginx 之前，我建议先别急着写配置。你要想明白一件事：TCP/UDP 代理和 HTTP 反向代理，看上去都是在做“转发”，但它们的工作层级完全不同。HTTP 反向代理跑在七层，能看懂 Host、URI、Cookie、Header，所以可以做路由、限流、缓存、改写。而 stream 模块跑在四层，它只负责把内核收到的 TCP 连接或 UDP 报文按策略转给后端，不关心包里面装的到底是什么应用协议。
这意味着什么？意味着你准备用 Nginx stream 代理解析过的 MySQL 流量，那就只能在连接层做转发，没法认库表级别去拦 SQL；想给 Redis 做代理，就只能基于 IP、端口、源地址做策略，不存在“key 开头是某个前缀就转发到某节点”的说法。四层代理的边界就是把连接送对、把流量传稳、把后端状态管好，超过这个范围的需求，应该回到七层去解决。
1.1 TCP 是“会话式”的，UDP 是“报文式”的，代理逻辑完全不同
TCP 代理相对好理解：客户端通过三次握手与 Nginx 建立一条连接，Nginx 再通过三次握手与后端建立一条连接，两条连接建立完成后，Nginx 就负责把客户端发来的字节流搬到后端，再把后端返回的字节流搬回客户端。这个过程本质上是连接中转，Nginx 不需要知道传输的内容是 SQL、Redis 命令还是自定义 RPC。
UDP 就不同了。UDP 本身没有连接状态，客户端发一个数据报，Nginx 需要自己维护一个伪会话，才能决定这个报文要转发给哪个后端，以及后端返回的报文要还给哪个客户端。这个伪会话的 key 一般是五元组：源地址、源端口、目的地址、目的端口、协议类型。只要客户端后续报文还是相同五元组，Nginx 就认为是在同一个 UDP 会话里，会把报文送往同一个后端。这个特性非常关键，后面配置 UDP 代理时会直接影响参数选择。
1.2 什么时候不该硬上 Nginx 来做四层转发？
Nginx 的 stream 模块当然不是万能的。如果公司已经有 LVS、HAProxy 这一套独立四层入口，或者业务 PPS 已经高到需要 DPDK/专用网关，那没必要为了“统一技术栈”强行把流量接到 Nginx 上。Nginx stream 的优势是配置语义丰富、跟现有 Nginx 体系能共用一套监控和日志方案、部署成本低；劣势是单机转发吞吐和 PPS 不如专用的内核态方案，尤其是在小包场景下差距会更加明显。
我个人的使用边界是：内部服务的入口收敛、测试环境流量调度、中小规模集群的 TCP/UDP 负载均衡，这类场景用 Nginx stream 完全够用；如果公司流量已经跑到需要单独规划网关机器硬件、要做 DPDK 优化的级别，那该上专用方案就上专用方案。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与第一份配置：先确认 Nginx 有 stream 能力，再谈转发
很多人在配置过程中踩坑，第一步就出在 Nginx 编译参数上。stream 模块并不是所有发行版默认编译进 Nginx 的。你拿系统自带的 nginx 包执行 nginx -V，可能在 configure arguments 里根本没有 --with-stream，这时候后面的所有配置都不会生效。
2.1 当前 Nginx 是否具备 TCP/UDP 代理能力，一分钟自查
在终端执行：
bash复制nginx -V 2>&1 | tr ' ' '\n' | grep stream
如果输出里能看到 --with-stream 和 --with-stream_ssl_module，说明当前 Nginx 支持 TCP/UDP 代理。如果没有任何输出，你就要考虑两个解决方案：一是重新编译 Nginx，在 configure 阶段加入相应模块；二是改用 nginx.org 官方仓库提供的预编译包，官方主线版本通常会带上 stream 模块。
需要特别提醒的是：如果你的 Nginx 是通过 load_module 方式加载动态模块，那要确认是否加载了 ngx_stream_module.so。有的发行版把四层模块拆成了独立动态模块，没有主动加载，主配置文件里写 stream 块时会直接报出“unknown directive stream”之类的错误。
2.2 stream 块和 http 块是平级关系，不能写在 http 块里面
这个错误我见了不少次：有人把 stream 配置写进 HTTP 站点配置文件里，结果问题迟迟找不出来。stream 块在 Nginx 主配置文件中与 http 块、events 块平级，它不是 http 的子级。一个最小可用的 TCP 转发配置是这样的：
nginx复制stream {
upstream backend_tcp {
server 192.168.1.11:3306;
server 192.168.1.12:3306;
}
server {
listen 3306;
proxy_pass backend_tcp;
}
}
在配置文件里加完这一段后，执行 nginx -t 检查语法没问题，再 nginx -s reload 加载配置。此时外部客户端连接 Nginx 的 3306 端口，就能访问到后端的 MySQL 集群。
UDP 代理的写法类似，区别只在 listen 后面加 udp：
nginx复制stream {
server {
listen 53 udp;
proxy_pass 192.168.1.53:53;
}
}
需要注意的是，同一端口如果既想监听 TCP 又想监听 UDP，比如 DNS 场景需要 53 端口同时提供 TCP 和 UDP 查询，那就得在一个 stream server 块里写两个 listen：
nginx复制stream {
server {
listen 53 udp;
listen 53;
proxy_pass 192.168.1.53:53;
}
}
这种写法在语法检查时会同时监听两种协议，转发目标一致时会非常方便。
3. TCP 代理实操：从 MySQL 负载均衡看 upstream、会话保持和故障转移
TCP 代理最适合演示的场景，就是给 MySQL 或 Redis 这类数据库连接做入口负载均衡。不需要改后端任何配置，只需要把客户端原先直连的数据库地址换成 Nginx 地址，就能在一组只读从库之间做流量分发。下面我以一组 MySQL 只读节点为例，把完整配置和背后的原理一起拆开讲。
3.1 一套可用的 MySQL 只读入口配置
nginx复制stream {
upstream mysql_ro {
server 192.168.1.11:3306 max_fails=3 fail_timeout=30s;
server 192.168.1.12:3306 max_fails=3 fail_timeout=30s;
server 192.168.1.13:3306 max_fails=3 fail_timeout=30s backup;
}
server {
listen 3306;
proxy_pass mysql_ro;
proxy_connect_timeout 5s;
proxy_timeout 600s;
}
}
默认负载均衡算法是轮询，也就是每个新 TCP 连接依次分发给不同后端。这里加了三层保护：
max_fails=3表示连续三次连接后端失败，就判定后端不可用；fail_timeout=30s表示失败的计数窗口是 30 秒，同时后端被标记为不可用的持续时间也是 30 秒；backup表示第三个节点只在前面两个节点都不可用时才参与转发。
proxy_connect_timeout 5s 是 Nginx 尝试与后端建立 TCP 连接的超时时间，如果后端地址本身网络不通，不会让客户端无限等下去。proxy_timeout 600s 是连接空闲超时。注意，这个超时不是连接最大存活时间，而是“连接上超过 600 秒没有任何数据交互”才会断开。对 MySQL 这类长连接服务，如果客户端或服务端有 keepalive 机制，proxy_timeout 要比 keepalive 周期设置得更大，否则 Nginx 会先掐断空闲连接。
3.2 会话粘滞：轮询不是所有业务的正确选择
用轮询做 MySQL 只读负载均衡，有一个麻烦场景：如果客户端用了 MySQL 的会话状态或者临时表，连接被分发到不同节点，后续请求就会失去上下文。这个问题本质上不是 TCP 代理能解决的，因为四层代理看不到 SQL 内容，只能在 TCP 层做会话保持。
Nginx stream 里做会话保持，常用的方式是 hash 指令。最简单的方案是按客户端源 IP 做哈希，让同一个源 IP 的连接总是转给同一个后端：
nginx复制upstream mysql_ro {
hash $remote_addr consistent;
server 192.168.1.11:3306;
server 192.168.1.12:3306;
}
consistent 关键字意味着使用一致性哈希算法，后端节点变化时，只有一部分会话受影响。如果你的客户端都经过了一层 NAT 网关，所有连接看起来都来自同一批 IP，那这台 Nginx 上配置哈希的意义就很有限了。这种情况下需要客户端在协议层把会话标识传过来，但四层代理拿不到协议内容，只能从 TCP 选项、源端口等有限字段里找办法。事实上，绝大多数用 Nginx stream 做数据库负载均衡的场景，真正依赖的是连接池做长连接复用，然后让每个客户端进程固定连某一个 Nginx 暴露端口，再通过不同端口路由到不同分片。会话粘滞需求并不常见。
3.3 后端口健康检查：不可能只靠 max_fails
max_fails 这种被动健康检查有个盲区：它只在转发流量给后端失败时才计数。一个 MySQL 节点如果进程还活着，但复制已经中断，此时新的查询依然会被分发过去。TCP 层的“连接建立成功”，并不等于业务层面的“查询能正常返回”。如果对可用性要求高，就应该引入主动健康检查机制，从外部周期性地探测后端服务。
开源版 Nginx 的 stream 模块本身不提供主动 health_check，所以我在实际项目里一般会另起一个探活进程或者脚本，定期用 MySQL 客户端执行 SELECT 1，失败时就通过 Nginx API 动态下线节点：把对应 upstream server 标记为 down。Nginx 商业版的 stream health_check 指令可以直接完成这个动作，开源版则可以用第三方工具配合。这里想强调的思路是：四层代理的健康检查粒度，永远要结合业务层来做，代理层能保住的是连接层面的高可用，业务层面的高可用还得依赖上层监控和调度。
4. UDP 代理实操：DNS 转发、响应数量参数与无连接协议的坑
UDP 代理不像 TCP 那样“建立连接后转发数据”直观，它更像是一个带有智能会话表的报文转发器。Nginx 在 1.9.0 支持 TCP，在 1.9.13 开始加入 UDP 代理能力，所以如果你用的是比较老的版本，首先要升级。我最早几个月用的 Nginx 只有 stream TCP，想代理 DNS 一直做不了，后来才发现版本太老，换到 1.16 才顺手。
4.1 内部 DNS 转发是 UDP 代理最常见的练兵场景
假设公司内网有多台 DNS 解析服务器，希望所有内部客户端的 DNS 查询先经过一层 Nginx，再由 Nginx 转发到后端的 DNS 服务器。一方面可以收敛 DNS 入口地址，另一方面可以为后端 DNS 节点做简单负载均衡。
最简配置：
nginx复制stream {
upstream dns_backend {
server 192.168.1.53:53;
server 192.168.1.54:53;
}
server {
listen 192.168.1.100:53 udp reuseport;
proxy_pass dns_backend;
proxy_responses 1;
proxy_timeout 10s;
}
}
这里有几个 UDP 独有的参数需要逐一解释。
udp 告诉 Nginx 这个 listen 端口用于处理 UDP 报文。reuseport 是 Linux 内核 3.9 以上支持的能力，它允许内核将同一个 UDP 端口上的报文负载均衡到多个 Nginx worker 进程，而不是由单个 worker 收包后再转交。对 UDP 这种无连接协议来说，能否并行收包对性能影响很大，我建议只要内核支持就默认加上。
proxy_responses 1 表示 Nginx 预期每个客户端请求，最多会收到后端 1 个 UDP 回包。这个数字非常重要，原因是 Nginx 需要决定一个 UDP 会话什么时候可以结束。如果后端 DNS 正常情况下每个查询只回 1 个包，那 proxy_responses 1 配合 proxy_timeout 10s 的意思是：Nginx 收到这个回包后会话进入待回收状态，10 秒内如果同一个五元组没有新请求，就销毁会话。假如你的后端某个协议会回多个包，而 proxy_responses 设置成了 1，那么后续的包就会被 Nginx 丢弃，客户端表现为响应不完整。
设置成 0 的话，则意味着 Nginx 不等待后端回包，只看 proxy_timeout 来清理会话，适合纯发不管的业务，但也意味着 Nginx 无法知道一个会话是否还有意义，会话表可能会堆积。
4.2 按五元组维持 UDP 会话是代理正确性的基础
我在调试 UDP 代理时发现，很多人想不通“为什么 UDP 的会话会被 Nginx 单独维护”。原因很简单：UDP 本身无连接，但代理场景需要有个虚拟连接，否则后端回包时 Nginx 不知道要还给谁。Nginx 在收到客户端第一个 UDP 报文时，会创建一个会话条目，记录源地址、源端口、目标地址、目标端口和协议类型，并选择一个后端把报文转发过去。之后只要是相同五元组的请求，都会被路由到同一个后端。
这个机制带来一个明显好处：同一台客户端上，如果有一个应用用固定端口反复查询同一个 DNS 服务，Nginx 会把这些查询都转给同一个后端，避免后端的 UDP 服务状态被多个节点打散。如果某个 UDP 服务的逻辑是“客户端必须先用源端口 A 发起握手，再用同一端口发数据”，那这个五元组会话可以保证所有后续报文都走同一后端，整个交互过程不会断。
一个容易踩的坑是：如果客户端大量使用不同的源端口，每次查询都可能被 Nginx 识别为不同会话，导致后端的负载均衡非常均匀，但也会产生大量会话表项。虽然 Nginx 会自动清理超时会话，但在高发送速率场景下，还是要注意观察内存和上游连接数状况。
4.3 TCP 和 UDP 代理的超时语义差别不要弄混
TCP 的 proxy_timeout 表示空闲连接超时，连接空闲超过该值就断开。UDP 的 proxy_timeout 表示“一个 UDP 会话在没有后续请求时最多存活多久”，它不表示某条 TCP 连接的空闲时间。初次接触时，我用 TCP 的思路去理解 UDP，把 proxy_timeout 设置成 5 秒，结果客户端每次 DNS 查询之间只要间隔超过 5 秒，Nginx 就销毁会话。貌似没问题，但一旦碰到客户端同时发出多条 DNS 查询，并且后端响应慢于预期，就可能出现会话提前被清理，回包无家可归。
另一个实用细节：UDP 后端不可达时的表现也和 TCP 不同。TCP 后端端口不通时，Nginx 立刻在握手阶段感知到失败，会返回错误给客户端。UDP 没有握手，Nginx 把报文发出去后就只能等 ICMP Port Unreachable，这个错误未必会精确对应到原始会话。所以排查 UDP 代理问题时，不要只用 TCP 的直觉思考，要结合连接跟踪表和抓包一起分析。
5. 压测与内核调参：文件描述符、端口范围和连接队列
Nginx 的 stream 模块配置本身不难，难的是把流量真打上来之后，操作系统这一层是否扛得住。我第一次做 TCP 代理压测时，后端 MySQL 节点还很悠闲，Nginx 机器却先出现大量连接失败，日志里提示无法建立新连接。这不是 Nginx 配置问题，而是内核资源已经见底。
5.1 Nginx 进程模型对四层代理的影响
Nginx 默认有一个 master 进程和多个 worker 进程。每个 TCP 连接都会由一个 worker 进程的事件循环接管，UDP 报文则由监听同一端口的 worker 进程处理。如果某个 worker 进程卡在同步磁盘 IO 或 CPU 占用率过高，受影响的就不仅仅是一个客户端，而是所有分配到该 worker 的连接。
四层代理场景下，Nginx 的瓶颈通常不在 CPU，而在文件描述符数量、连接表项、内存和内核连接队列。tcpdump 抓包看到客户端 SYN 发出，但 Nginx 没有响应，往往就是 backlog 队列满了。与之相关的内核参数：
bash复制sysctl -w net.core.somaxconn=65535
sysctl -w net.ipv4.tcp_max_syn_backlog=65535
somaxconn 决定了 listen 队列的最大长度，它受 Nginx listen 指令里的 backlog 参数共同影响。高并发短连接场景下，如果这个队列太小，连接刚建立就被内核丢弃，客户端看到的就是偶发超时。
5.2 UDP 代理压测还可能撞上本地端口耗尽
UDP 会话数量大时，Nginx worker 进程可能会消耗很多本地端口来跟后端通信。每条到后端的 UDP “伪连接”在转发时都要占用一个本地 socket 四元组。当后端是同一个 IP 同一个端口，而客户端源端口又比较集中时，Nginx 机器可用的本地端口范围会很快消耗完。
调整方法：
bash复制sysctl -w net.ipv4.ip_local_port_range="1024 65535"
这扩大了可用本地端口区间，但也要注意不能无限制扩大，端口范围过大会让 conntrack 表项增多，反而增加内存消耗。
另外，使用 reuseport 后，多个 worker 进程会各自独立监听同一个 UDP 端口。如果只有一个客户端在打流，往往只能打到一个 worker 上，这不代表 Nginx 本身不行，而是单流的天然限制。做 UDP 压测时建议用多源端口、多客户端的模式，否则很难以真实结果判断能力上限。
5.3 文件描述符上限是 L4 代理最容易翻车的地方
Nginx 配置里可以设置 worker_rlimit_nofile，系统层面又有进程文件描述符上限。每个 TCP 连接在 Nginx 侧至少消耗 1 个文件描述符，如果是 TCP 代理，还要算上与后端连接的描述符。如果系统限制是 1024，那几百个连接就可能触发 too many open files，服务开始间歇性不可用。
我通常会在 nginx.conf 里设置：
nginx复制worker_rlimit_nofile 65535;
events {
worker_connections 65535;
}
这里有一个容易忽略的点：worker_connections 是指每个 worker 进程最大连接数，不是整个 Nginx 进程。如果有 4 个 worker，理论上限大约是 4 × 65535，但还要扣掉每个连接用到的额外描述符。压测前先 ulimit -n 确认进程实际限制，还要把系统层面的 /etc/security/limits.conf 一起调整，否则配置写了也可能不生效。
压测工具方面，TCP 代理可以用 iperf3 打大流量，看 Nginx 作为中转节点时上下行带宽是否对称。UDP 代理也可以用 iperf3 的 UDP 模式，但要注意压测时发送带宽要设置明确，例如 iperf3 -c 127.0.0.1 -u -b 500M，避免客户端无限制地发，把网络链路打满。看到两边带宽接近、丢包率不要异常上升，基本可以判断代理转发性能是可接受的。如果丢包率很高，优先排查 MTU、缓存和网卡队列，而不是先怀疑 Nginx。
6. 真实环境的排错经验：日志、黑白名单与抓包验证
四层代理和七层代理有一个显著区别：七层代理能记录 HTTP 状态码、URI、响应时间，四层代理的排错线索相对少得多。很多服务连接一断，错误信息只有“Connection reset by peer”或“Operation timed out”，光靠 Nginx 默认日志很难定位。所以我在生产环境里通常会提前把 stream 的访问日志配好，让关键连接留下痕迹。
6.1 让 stream 日志记录真实客户端 IP 和连接状态
stream 模块有自己的 log_format，和 http 的不通用。一段比较完整的配置长这样：
nginx复制stream {
log_format basic '$remote_addr [$time_local] '
'$protocol $status $bytes_sent $bytes_received '
'$session_time "$upstream_addr"';
access_log /var/log/nginx/stream_access.log basic;
server {
listen 3306;
proxy_pass backend_tcp;
}
}
重启后，每一个 TCP 连接结束，或者 UDP 会话被清理时，都会产生一条日志。注意 stream access_log 默认是在连接关闭后记录，UDP 场景下则是在会话销毁时记录。这意味着你看到的日志可能会比客户端实际请求时间晚，尤其是 proxy_timeout 设置得比较长时，不要因此误判。
如果客户端和 Nginx 之间还套了其他负载均衡设备，想要在日志中保留原始来源，可以启用 PROXY protocol。后端软件也要支持 PROXY protocol，才能解析出真实的客户端 IP。这是一个相对复杂的联动配置，但当你发现访问日志里所有的 $remote_addr 都是同一台内网网关时，就会理解为什么需要它。
6.2 Connection reset 和 timeout 到底怎么逐层排查
客户端连接 Nginx 直接报 reset，第一反应要分清 reset 是从哪一侧发出。我在一台 Linux 机器上执行：
bash复制ss -tnp | grep 3306
如果能看到 Nginx 与客户端之间处于 ESTABLISHED 状态，但与后端之间没有连接，那说明 reset 发生在 Nginx 和后端之间的连接建立阶段。此时再检查后端的 iptables、内网防火墙、后端服务监听状态。
如果客户端与 Nginx 的连接也建立不起来，就要用 tcpdump 抓 Nginx 入口网卡：
bash复制tcpdump -ni eth0 port 3306 -c 100
看 SYN 包有没有到网卡，到了网卡却没有响应，大概率是 backlog 队列满或监听 socket 所在进程出问题。如果 SYN 包根本没到，问题在 Nginx 之前的路由、防火墙或云平台安全组。
还有一种比较隐蔽的情况：Nginx 与后端建立连接成功，但客户端发来的数据没有转发出去。原因可能是后端把 RST 发到了 Nginx，Nginx 把这一个字节流错误地回给了客户端。通过抓包可以清楚看到 RST 的方向，再顺着方向去查对应服务的状态。
6.3 UDP 排错绕不开连接跟踪和抓包
UDP 代理排错时，第一步不是看 Nginx 配置，而是看系统的连接跟踪表里有没有对应会话：
bash复制conntrack -L | grep 53
如果会话存在且状态正常，说明报文确实被内核接管了。接着抓包看 Nginx 和后端之间的交互：
bash复制tcpdump -ni eth0 udp port 53
我曾经遇到过一个很奇怪的场景：客户端通过 Nginx 查询 DNS 时，只有第一条查询能成功，后面全部超时。最后抓包发现后端的回包没有回到 Nginx，而是直接回到了客户端。原因是 Nginx 在转发时没有做好源地址转换，后端基于源 IP 的响应策略把包直接发给了原始客户端。解决办法是在 stream server 块配置 proxy_bind，指定 Nginx 用特定网卡地址去连接后端，确保后端认为所有请求都来自同一台 Nginx，回包路径才正确。
如果你看到 UDP 客户端持续发送请求，但后端一次都没有收到，那先检查 Nginx listen 指令是否真的带了 udp 关键字。漏掉这个关键字时，配置文件语法没错，Nginx 却只监听 TCP 端口，客户端发 UDP 自然石沉大海。这种低级错误在操作台前很容易被忽略，所以我配置完 UDP 服务后，会立刻用 ss -ulnp | grep 端口号 确认监听协议类型。
从我在多个项目里的体会来看，Nginx 做 TCP/UDP 代理最大的特点不是功能有多花哨，而是它把四层网关的运维模式拉回到了熟悉的 Nginx 体系内，语法、日志、热加载方式都有连贯性。但正因为它和 HTTP 反向代理在概念上有诸多相似，又容易让人下意识套用七层思路，所以配置前搞清楚连接和报文的差异，压测前想清楚内核参数和进程模型，排错时利用好抓包和连接跟踪，会比背下任何一段示例配置都更有价值。如果手中正好有一批内部 TCP/UDP 服务需要收敛入口，不妨先从最小配置做起，再逐步加入健康检查、会话超时和访问日志，这样踩坑成本是最低的。