Traefik UDP 路由（UDP Router）配置完全指南：入口点绑定、服务转发与会话超时机制

2026-09-07 19:08:42作者：曹令琨Iris

UDP Router 是 Traefik 将入站 UDP 数据包路由到后端服务的核心枢纽，本指南基于 UDP 路由参考文档展开，结合仓库源码剖析其配置字段、入口点绑定规则、会话跟踪与超时机制。读完本文，你将掌握在 YAML、TOML、Docker Labels 与 Consul/ECS Tags 等不同 Provider 中正确声明 UDP 路由、关联 UDP 服务、并利用入口点级 timeout 精细控制会话生命周期的完整方法。

UDP Router 是什么：面向无连接协议的路由模型

与 HTTP、TCP Router 不同，UDP Router 工作于传输层，负责把到达入口点的 UDP 数据包连接到能够处理它们的服务上。由于 UDP 本身是**无连接（connectionless）**协议，其路由模型有以下几条关键特性：

没有可供匹配的请求语义：不存在 HTTP 的 URL Path，也没有 TCP TLS 那样的 Host/SNI 可供路由规则匹配，UDP Router 不会基于路径或域名做分发；
本质是一个包级负载均衡器：UDP Router 将数据包分发给后端服务，本身承担的就是转发与负载均衡职责；
只能指向 UDP 服务：UDP Router 的目标服务只能是 UDP 类型的服务（LoadBalancer 或 Weighted 加权服务），无法转发给 HTTP 或 TCP 服务；
依赖“会话”维护状态：尽管 UDP 无连接，但 Traefik 的实现通过**会话（Session）**跟踪客户端与后端之间的持续通信，以便知道后端返回的响应包该转发回哪个客户端；
每个入口点只能挂一个 UDP Router（详见下文源码分析）。

这些特性直接决定了 UDP Router 的配置结构极其精简：只需要确定它挂在哪个/哪些入口点，以及转发给哪个 UDP 服务。

完整配置示例：四种声明方式

UDP Router 的配置主体由两个字段组成——entryPoints（绑定入口点）与 service（转发目标服务）。以下四种方式来自参考文档，分别覆盖 File Provider 的动态配置（YAML/TOML）、Docker 容器 Labels 与 Consul Catalog/ECS 等基于 KV 的 Tags：

udp:
  routers:
    my-udp-router:
      entryPoints:
        - "udp-ep"
        - "dns"
      service: my-udp-service

[udp.routers]
  [udp.routers.my-udp-router]
    entryPoints = ["udp-ep", "dns"]
    service = "my-udp-service"

labels:
  - "traefik.udp.routers.my-udp-router.entrypoints=udp-ep,dns"
  - "traefik.udp.routers.my-udp-router.service=my-udp-service"

{
  "Tags": [
    "traefik.udp.routers.my-udp-router.entrypoints=udp-ep,dns",
    "traefik.udp.routers.my-udp-router.service=my-udp-service"
  ]
}

Labels 与 Tags 形式遵循 Traefik 统一的 traefik.udp.routers.<router-name>.<option> 命名规则，多个入口点用逗号分隔。整段配置中的服务名 my-udp-service 对应动态配置里 udp.services 段下声明的一个 UDP 服务（例如一个指向某组 DNS 服务器地址的 LoadBalancer），具体声明方式见 UDP 服务参考。

配置选项详解

字段	描述	默认值	是否必填
`entryPoints`	路由器所绑定（监听）的入口点列表。若未指定，UDP Router 默认挂到所有 UDP 类型的入口点上。	所有 UDP 入口点	否
`service`	负责处理被匹配到的 UDP 数据包的服务名称。UDP 服务通常是负载均衡器类型，将数据包分发到多个后端服务器。详见 UDP Service。	—	是

两点在实际部署中最容易踩坑：

入口点的协议类型必须匹配：配置中绑定的入口点（如 udp-ep、dns）需要在静态配置中被声明为 network: udp（对应静态配置 entryPoints.<name>.udp 段）。若把 UDP Router 绑定到一个只监听了 TCP 的入口点，该 Router 不会按预期生效。
service 缺失是致命错误：从 UDP Router 管理器实现可以看到，构建阶段会显式校验服务名：

if routerConfig.Service == "" {
    err := errors.New("the service is missing on the udp router")
    routerConfig.AddError(err, true)
    logger.Error().Err(err).Send()
    continue
}

即当路由配置未声明 service 时，该 Router 会被标记为错误状态并跳过构建（不会 panic，但在 dashboard 与日志中会体现为失败路由）。此外，若 service 指向的 UDP 服务在 udp.services 中不存在或未声明类型，服务管理器同样会返回错误，见 UDP 服务管理器中 BuildUDP 的校验逻辑（the UDP service %q does not exist）。

源码印证：为什么每个入口点只能有一个 UDP Router

与 HTTP Router 的“多路由按规则优先级逐一匹配”机制完全不同，UDP 场景下 Traefik 采用一个入口点一个处理器的模型。在 UDP Router 管理器的 BuildHandlers 中可以看到明确处理逻辑：

if len(routers) > 1 {
    logger.Warn().Msg("Config has more than one udp router for a given entrypoint.")
}
...
// As UDP support only one router per entrypoint, we only take the first one.
entryPointHandlers[entryPointName] = handlers[0]

也就是说：

当多个 UDP Router 绑定到同一入口点时，Traefik 会记录一条 warning 日志，提示“该入口点配置了不止一个 UDP Router”；
由于 UDP 本身缺乏 HTTP/TCP 那样的路由匹配维度，无法在这些 Router 之间做语义化选择，最终实现只取第一个有效 Router 的处理器挂到入口点上。

这进一步解释了为何在写 UDP 路由配置时应按入口点精心规划 Router 数量——同入口点下的多余 Router 不会起到分流作用，反而会产生告警干扰排障。构建时 Router 之间按名称降序排列处理（sort.Slice 后遍历），完整调用链是：入口点名称 → GetUDPRoutersByEntryPoints 取得该入口点关联的 Router 集合 → 服务管理器 BuildUDP 生成目标服务的 UDP Handler。

从底层接口看，UDP Handler 是对 HTTP Handler 的 UDP 对应物，见 Handler 接口定义：

type Handler interface {
    ServeUDP(conn *Conn)
}

而真正的转发工作由 UDP 反向代理完成：ServeUDP 中先 net.Dial("udp", p.target) 建立到后端的 socket，再启动两条 goroutine 用 io.CopyBuffer 双向搬运客户端↔后端的数据包；拷贝缓冲区按最大 UDP 数据报尺寸初始化，以保证单个数据报被原子地读写、不会出现分包丢失（见 connCopy 中 maxDatagramSize 缓冲区与注释）。

UDP Router 与 UDP 服务如何关联

Router 的 service 字段只能引用 UDP 类型的服务。仓库当前支持的 UDP 服务形态见 UDP 服务参考文档：

LoadBalancer（服务器级负载均衡）：定义一组后端 servers（每个为 IP:Port 地址），Router 收到的数据包在该组后端间分发。代码路径对应 UDP 服务管理器中为每个合法地址构建 udp.NewProxy 并加入加权轮询负载均衡器（udp.NewWRRLoadBalancer()）的过程——服务列表先被随机打乱，地址无法通过 net.SplitHostPort 校验的 server 会被跳过并记录错误日志。
Weighted（加权服务级负载均衡，别名 WRR）：在多个已声明的 UDP 服务之间按权重分配，权重字段默认值为 1。当前支持通过 File Provider 与 Kubernetes CRD（IngressRouteUDP）声明。

推荐的最小化可运行示例（File Provider 动态配置，YAML）：

udp:
  routers:
    dns-router:
      entryPoints:
        - "dns"
      service: dns-servers

  services:
    dns-servers:
      loadBalancer:
        servers:
          - address: "10.0.0.2:53"
          - address: "10.0.0.3:53"

会话跟踪与超时：让“无连接”协议拥有状态

文档明确强调：尽管 UDP 无连接，Traefik 的 UDP Router 实现依然依赖会话来维护客户端与后端之间持续通信的状态，其根本目的是让代理知道后端返回的响应包应该转发回哪个客户端地址。

每个会话都关联一个超时值，当会话在一段指定的空闲时间内没有任何流量活动时，会被自动清理回收。会话超时并非在 Router 上配置，而是在静态配置的入口点级别设置：

entryPoints:
  udp-ep:
    address: ":9000/udp"
    udp:
      timeout: 3

[entryPoints.udp-ep]
  address = ":9000/udp"

  [entryPoints.udp-ep.udp]
    timeout = 3

也就是说，超时策略属于“监听侧”属性：同一入口点上挂载的 UDP Router 会话，统一受该入口点 entryPoints.<name>.udp.timeout 约束。这一参数对两类业务意义截然不同：

对 DNS（53/UDP）这类一问一答、数据报极小的业务，会话只需在请求-响应窗口内存活，超时可设得很短以快速回收资源；
对 QUIC/HTTP3、大流量媒体等长时双向通信的业务，需要根据心跳或保活间隔适当调大超时，避免合法会话被中途回收导致响应包丢失。

入口点的完整声明方式（network: udp 语义、address 写法等）参见入口点（EntryPoints）配置文档。

Router 命名规则

编写 UDP Router（以及各类 Router）名称时需遵守以下约定：

名称中不允许出现 @ 字符——@ 在 Traefik 中用作 Provider 限定名（qualified name）的分隔符，例如 foo@docker 表示由 Docker Provider 生成的名为 foo 的资源；因此 Router 名本身禁止包含它；
名称应具备描述性并遵循团队自身的命名规范，便于在 dashboard、日志与指标中定位；
在 Provider 特定配置中（如 Docker、Kubernetes CRD），Router 名通常基于服务名自动生成，用户无需（也通常不应）手动指定。

小结与配置检查清单

UDP Router 是整个 UDP 流量入口中最薄的一层配置，正因其精简，每一处都值得精确核对。部署前建议按下列清单自查：

静态配置中入口点是否以 UDP 网络类型监听（address 使用 /udp 后缀并启用对应 udp 段）；
Router 的 entryPoints 是否引用了UDP 类型入口点；未填写时将自动挂到全部 UDP 入口点，需确认是否符合预期；
service 是否必填且指向真实存在的 UDP 服务，避免出现 service is missing on the udp router 或 the UDP service ... does not exist 类错误；
同一入口点是否只声明了一个 UDP Router，避免多余 Router 触发告警并被忽略；
是否结合业务交互模式，为入口点配置了合适的 udp.timeout 会话超时。