Web 服务器与网关 / 系统课时

配置 UDP 代理

配置 UDP 代理

本课解决 Nginx 如何代理基于 UDP 的服务请求。通过 stream 模块配置 UDP 转发规则,理解会话识别、响应次数和超时控制,并完成基础连通性验证。

学习目标

  • 理解 Nginx stream 模块代理 UDP 服务的工作方式。
  • 掌握 UDP upstream 与监听端口的配置方法。
  • 学会使用测试工具验证 UDP 请求转发链路。

UDP 代理工作机制

UDP 与 TCP 不同,它没有连接建立和关闭过程,因此 Nginx 无法像 TCP 代理一样维护长连接状态。stream 模块会根据客户端地址、源端口等信息识别一次 UDP 会话,并在超时时间内关联后续数据包。

UDP 代理常用于 DNS、游戏通信、实时采集、监控上报等低延迟场景。Nginx 主要负责接收客户端数据报,将其转发到上游 UDP 服务,并把响应返回给客户端。

Nginx stream UDP 代理数据流示意图

配置 UDP stream 代理

UDP 代理配置位于 stream 上下文中,而不是 http 上下文。需要先定义上游 UDP 服务组,再通过 server 块监听客户端端口。示例配置如下:

nginx
stream {
    upstream dns_backend {
        server <SERVER_IP>:<PORT>;
    }

    server {
        listen <PORT> udp;
        proxy_pass dns_backend;
        proxy_timeout 5s;
        proxy_responses 1;
    }
}

预期结果

text
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 数据。

bash
printf "hello" | nc -u <NGINX_HOST> <PORT>

预期结果

text
hello

实际输出取决于后端 UDP 服务实现。如果后端没有响应,客户端只能发送数据但不会收到返回内容,需要继续检查监听端口、网络策略和上游服务状态。

常见失败处理

UDP 代理失败通常从以下顺序定位:

  • 确认 Nginx 已编译并启用 stream 模块。
  • 检查监听端口是否绑定成功。
  • 检查防火墙是否允许 UDP 流量。
  • 确认 upstream 地址和端口可访问。
  • 根据日志调整超时时间。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 UDP 代理

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通