Nginx 实现TCP与UDP转发:新版与老版本配置详解

一、先搞清楚: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 代理。常见做法有两种:

  1. 使用第三方模块 nginx_tcp_proxy_module(由淘宝开源),仅支持 TCP,需要重新编译 Nginx。
  2. 放弃 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 以上版本,配置更简单、功能更完整、维护也更有保障。

相关推荐
飞奔的瓜牛1 小时前
Nginx 生产环境运维实践:常见问题、关注要点与日常维护
运维·nginx
飞奔的瓜牛11 小时前
Nacos 三节点集群部署手册:MySQL 持久化 + Nginx 负载均衡
mysql·nginx·负载均衡
Csvn1 天前
Nginx 静态站点与 location 匹配:优先级、alias、缓存头与 gzip
后端·nginx
多弗朗皮卡丘1 天前
网络基础:数据链路层与其他协议或技术
linux·网络·tcp/ip
考虑考虑1 天前
nginx拦截url
运维·后端·nginx
李纲明2 天前
WordPress 打开站点却直接下载文件或源码而不显示页面:先核 PHP 处理规则,再查 443 是否被其他站接管
nginx·wordpress·443·php解析·站点配置·devdiy·直接下载
Java码农也是农2 天前
一篇文章讲清 NGINX 反向代理:location、proxy_pass、负载均衡与排错
nginx·负载均衡·后端开发·反向代理·proxy_pass
爱和冰阔落3 天前
【Linux网络】TCP 半包粘包怎么解决?从长度报头、JSON 拆包到网络计算器完整实战
linux·运维·网络·tcp/ip
say_fall3 天前
【Linux网络编程】UDP套接字编程:系统编程组件、基础回显服务、InetAddr与地址转换、翻译服务与线程池聊天室
linux·服务器·网络·udp·vr