Web 服务器与网关 / 系统课时
配置 UDP 代理
配置 UDP 代理
本课解决 Nginx 如何代理基于 UDP 的服务请求。通过 stream 模块配置 UDP 转发规则,理解会话识别、响应次数和超时控制,并完成基础连通性验证。
学习目标
- 理解 Nginx stream 模块代理 UDP 服务的工作方式。
- 掌握 UDP upstream 与监听端口的配置方法。
- 学会使用测试工具验证 UDP 请求转发链路。
UDP 代理工作机制
UDP 与 TCP 不同,它没有连接建立和关闭过程,因此 Nginx 无法像 TCP 代理一样维护长连接状态。stream 模块会根据客户端地址、源端口等信息识别一次 UDP 会话,并在超时时间内关联后续数据包。
UDP 代理常用于 DNS、游戏通信、实时采集、监控上报等低延迟场景。Nginx 主要负责接收客户端数据报,将其转发到上游 UDP 服务,并把响应返回给客户端。

配置 UDP stream 代理
UDP 代理配置位于 stream 上下文中,而不是 http 上下文。需要先定义上游 UDP 服务组,再通过 server 块监听客户端端口。示例配置如下:
stream {
upstream dns_backend {
server <SERVER_IP>:<PORT>;
}
server {
listen <PORT> udp;
proxy_pass dns_backend;
proxy_timeout 5s;
proxy_responses 1;
}
}预期结果
Nginx 启动成功,并监听指定 UDP 端口。
客户端发送 UDP 数据包后,请求被转发到 dns_backend。
收到上游响应后,Nginx 返回数据给客户端。其中 listen <PORT> udp 表示监听 UDP 流量,proxy_pass 指定转发目标。proxy_timeout 控制无响应情况下会话保持时间,proxy_responses 用于限制等待的响应数量。
理解会话和响应控制
UDP 没有 TCP 那样的连接状态,因此代理行为依赖 Nginx 对数据包关系的临时记录。一次请求通常包含客户端请求、上游转发、响应返回三个阶段。
proxy_responses 适合响应数量明确的协议。例如 DNS 查询通常一次请求对应一次响应,可以设置为 1。如果应用存在多次响应,则需要根据协议特点调整。常见参数作用如下:
| 参数 | 作用 |
|---|---|
proxy_timeout |
控制 UDP 会话保持时间 |
proxy_responses |
控制期望收到的响应数量 |
proxy_pass |
指定 UDP 上游服务 |
测试 UDP 转发效果
可以使用支持 UDP 的测试工具验证端口是否能够正确转发。例如使用 nc 发送 UDP 数据。
printf "hello" | nc -u <NGINX_HOST> <PORT>预期结果
hello实际输出取决于后端 UDP 服务实现。如果后端没有响应,客户端只能发送数据但不会收到返回内容,需要继续检查监听端口、网络策略和上游服务状态。
常见失败处理
UDP 代理失败通常从以下顺序定位:
- 确认 Nginx 已编译并启用 stream 模块。
- 检查监听端口是否绑定成功。
- 检查防火墙是否允许 UDP 流量。
- 确认 upstream 地址和端口可访问。
- 根据日志调整超时时间。