一、先搞清楚:Nginx 能不能代理 TCP/UDP
Nginx 从 1.9.0 版本开始引入了 ngx_stream_core_module,也就是常说的 stream 模块,从此具备了四层(TCP/UDP)代理能力。在此之前,Nginx 只能做七层 HTTP 代理,无法直接转发 TCP 或 UDP 流量。
因此,配置方式需要分两种情况讨论:
- 老版本(1.9.0 之前) :Nginx 原生不支持 TCP/UDP 代理,需要借助第三方模块
nginx_tcp_proxy_module(仅支持 TCP),或者干脆改用 HAProxy、LVS 等工具。 - 新版(1.9.0 及之后) :使用官方内置的
stream模块,配置简洁,同时支持 TCP 和 UDP。
提示:stream 模块默认不编译 ,需要在编译时显式加上
--with-stream参数。UDP 代理还需要额外加上--with-stream_udp_module(1.9.13 起支持 UDP)。
二、新版配置(Nginx 1.9.0+,推荐)
2.1 确认 stream 模块是否可用
先检查当前 Nginx 是否已经编译了 stream 模块:
bash
nginx -V 2>&1 | tr ' ' '\n' | grep stream
如果输出中包含 --with-stream,说明可以直接使用;如果没有,需要重新编译或安装带 stream 模块的包(例如 CentOS 下使用 nginx-mod-stream)。
2.2 stream 配置块的位置
stream 块与 http 块同级,必须写在 main 上下文 中,不能放在 http 里面。通常有两种组织方式:
- 直接写在
/etc/nginx/nginx.conf的 main 层级; - 写在独立文件(如
/etc/nginx/stream.conf),然后在nginx.conf中用include引入。
2.3 TCP 代理配置
下面把本机 3306 端口收到的 MySQL 流量转发到后端 192.168.1.10:3306:
nginx
stream {
# 后端服务器组
upstream mysql_backend {
server 192.168.1.10:3306 weight=1 max_fails=3 fail_timeout=10s;
server 192.168.1.11:3306 weight=1 max_fails=3 fail_timeout=10s;
}
server {
listen 3306;
proxy_pass mysql_backend;
# 连接超时与转发超时
proxy_connect_timeout 5s;
proxy_timeout 300s;
透传客户端真实 IP(需后端支持 PROXY protocol)
proxy_protocol on;
}
}
关键指令说明:
| 指令 | 作用 |
|---|---|
listen |
监听端口,TCP 代理只写端口即可 |
proxy_pass |
指定后端地址或 upstream 名称 |
proxy_connect_timeout |
与后端建立连接的超时时间 |
proxy_timeout |
两次读写之间的空闲超时,长连接场景要调大 |
proxy_protocol |
开启 PROXY protocol,向后端传递真实源 IP |
2.4 UDP 代理配置
UDP 代理需要在 listen 后显式加上 udp 关键字。下面以 DNS 服务为例,把本机 53 端口转发到后端:
nginx
stream {
upstream dns_backend {
server 192.168.1.20:53;
server 192.168.1.21:53;
}
server {
listen 53 udp;
proxy_pass dns_backend;
# UDP 会话保持时间,默认 10m
proxy_timeout 10s;
proxy_responses 1;
}
}
UDP 相关要点:
listen 53 udp;中的udp不能省略,否则会被当作 TCP 监听。proxy_responses表示期望后端返回的响应包数量,DNS 一般设为1;不设置时 Nginx 会一直等待直到超时。- UDP 是无连接协议,
proxy_connect_timeout对 UDP 不生效,主要靠proxy_timeout控制会话生命周期。 - 同一个端口可以同时监听 TCP 和 UDP,只需写两条
listen。
2.5 同时代理 TCP 和 UDP 的完整示例
nginx
stream {
# TCP 后端
upstream tcp_backend {
server 10.0.0.11:8080;
server 10.0.0.12:8080;
}
# UDP 后端
upstream udp_backend {
server 10.0.0.21:9000;
}
TCP 监听
server {
listen 8080;
proxy_pass tcp_backend;
proxy_timeout 600s;
}
UDP 监听
server {
listen 9000 udp;
proxy_pass udp_backend;
proxy_timeout 30s;
proxy_responses 1;
}
}
2.6 负载均衡策略
stream 模块支持与 http 类似的负载均衡算法,通过 upstream 块内的指令指定:
- 轮询(默认):按顺序分发。
- weight :权重分配,如
server 10.0.0.11:8080 weight=3;。 - least_conn:最少连接数优先,适合长连接场景。
- hash :按指定 key 做一致性哈希,如
hash $remote_addr consistent;,可用于会话保持。
三、老版本配置(Nginx 1.9.0 之前)
3.1 老版本的现实情况
1.9.0 之前的 Nginx 官方版本没有 stream 模块,无法通过配置实现 TCP/UDP 代理。常见做法有两种:
- 使用第三方模块
nginx_tcp_proxy_module(由淘宝开源),仅支持 TCP,需要重新编译 Nginx。 - 放弃 Nginx,改用 HAProxy、LVS 等专业四层代理工具。
需要特别说明:老版本没有任何官方方案支持 UDP 代理,第三方模块也只覆盖 TCP。如果业务必须代理 UDP,只能升级 Nginx 或更换代理软件。
3.2 使用 nginx_tcp_proxy_module 编译
该模块需要与 Nginx 源码一起编译,步骤如下:
bash
# 1. 下载 Nginx 源码(以 1.8.1 为例)
wget http://nginx.org/download/nginx-1.8.1.tar.gz
tar -zxvf nginx-1.8.1.tar.gz
cd nginx-1.8.1
2. 下载第三方 TCP 代理模块
git clone https://github.com/yaoweibin/nginx_tcp_proxy_module.git
3. 打补丁
patch -p1 < nginx_tcp_proxy_module/tcp.patch
4. 编译安装,加入模块
./configure --add-module=./nginx_tcp_proxy_module
make && make install
3.3 老版本的 TCP 代理配置
该模块使用 tcp 块,而不是 stream 块,配置写法与新版差异较大:
nginx
tcp {
upstream mysql_backend {
server 192.168.1.10:3306;
server 192.168.1.11:3306;
# 健康检查
check interval=3000 rise=2 fall=3 timeout=1000;
}
server {
listen 3306;
proxy_pass mysql_backend;
# 连接超时
proxy_connect_timeout 5s;
# 空闲超时
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}
}
与新版的主要差异:
| 对比项 | 老版本(tcp 块) | 新版(stream 块) |
|---|---|---|
| 配置块名 | tcp |
stream |
| UDP 支持 | 不支持 | 支持(listen ... udp) |
| 超时指令 | proxy_read_timeout / proxy_send_timeout |
统一为 proxy_timeout |
| 健康检查 | 模块自带 check 指令 |
依赖 max_fails / fail_timeout |
| 维护状态 | 已停止维护 | 官方持续维护 |
四、配置校验与生效
无论新版还是老版本,修改配置后都应先校验再重载:
bash
# 校验配置语法
nginx -t
平滑重载,不中断现有连接
nginx -s reload
如果 nginx -t 报错 unknown directive "stream",说明当前 Nginx 未编译 stream 模块,需要重新编译或安装对应模块包。
五、常见问题排查
- 连接被拒绝 :检查
listen端口是否被占用,防火墙与安全组是否放行。 - UDP 无响应 :确认
listen后加了udp,并合理设置proxy_responses。 - 长连接频繁断开 :调大
proxy_timeout,数据库、WebSocket 等场景尤其要注意。 - 后端拿不到真实客户端 IP :开启
proxy_protocol on;,同时后端服务需支持 PROXY protocol。 - 老版本编译失败:第三方模块与 Nginx 版本强绑定,补丁可能不兼容,建议直接升级到新版。
六、最佳实践
https://download.csdn.net/download/lgz847368331/93854842
七、总结
新版 Nginx 通过内置的 stream 模块,用统一的 stream { server { listen ...; proxy_pass ...; } } 结构即可完成 TCP 与 UDP 代理,UDP 只需在 listen 后加 udp 关键字。老版本(1.9.0 之前)没有官方四层代理能力,只能借助第三方 nginx_tcp_proxy_module 实现 TCP 转发,且完全不支持 UDP。生产环境建议直接使用 1.9.0 以上版本,配置更简单、功能更完整、维护也更有保障。