Traefik 入门 FAQ：HTTP 状态码、TLS 证书与路由配置排查指南

本文基于 Traefik 官方入门文档 docs/content/getting-started/faq.md 编写，系统讲解 Traefik 动态反向代理的运行机制：为什么某些请求会返回 404/502/503、如何用 catchall 路由定制这些状态码、file provider 下 TLS 证书为何不会自动重载、代理时默认注入哪些转发头、以及 Traefik 如何存储与挑选 TLS 证书。读完后你将能够对照源码路径定位问题根因，并给出可复现的静态/动态配置修复方案。

动态反向代理：理解 Traefik 状态码行为的背景

Traefik 是一个动态反向代理（dynamic reverse proxy）。虽然文档中常以文件示例演示配置选项，但 Traefik 的核心能力是动态可配置性——它会实时响应各个 provider（配置提供者）在实例生命周期内产生的配置变化。

其中需要区分两层配置（参见 配置总览）：

• 安装配置（install configuration）是静态的，在启动时通过文件提供；
• 各类 provider（如 file provider）则在 Traefik 运行期间持续动态地向路由配置贡献变更。

此外，配置中还包含 EntryPoint 与 Router 两个不同层次的概念：EntryPoint 可以理解为传输层（TCP）上的监听器，而 Router 则更偏向表示层（TLS）与应用层（HTTP）。一个给定的 EntryPoint 下可以挂任意多个 Router。

换句话说，对于一个 EntryPoint 而言，某一时刻经过它的流量并不必然只属于某一种协议——可能是 HTTP，也可能不是；可能走了 TLS，也可能没有。更不必说动态配置的变更还会让流量随时间而变化。

因此在这种动态上下文中，某个 entryPoint 的静态配置完全不能告诉你：经过该 entryPoint 的流量将如何被路由，甚至不能确定它能否被路由——即是否存在匹配该流量类型的 Router。这正是下文各状态码行为的根源。

为什么 Traefik 返回 404 Not Found？

Traefik 在以下情况返回 404 响应码：

• 请求到达一个没有任何 Router 的 EntryPoint；
• HTTP 请求到达一个没有 HTTP Router 的 EntryPoint；
• HTTPS 请求到达一个没有 HTTPS Router 的 EntryPoint；
• 请求到达一个有 HTTP/HTTPS Router、但规则无法匹配的 EntryPoint。

从 Traefik 的视角看，只要一个请求无法匹配到任何 router，正确的响应码就是 404 Not Found。

那么为什么不是 503 Service Unavailable？因为 Traefik 无法确认“匹配不到路由”只是一个临时状态。Traefik 的路由配置是动态的、由多个 provider 聚合而成，在任何时刻都不可能假设某条路由“应该”被处理或“不应该”被处理。

该行为与 RFC 7231 保持一致。 关于 503 的定义（摘录自 RFC 7231 第 6.6.4 节）：

The server is currently unable to handle the request due to a
temporary overloading or maintenance of the server. The implication
is that this is a temporary condition which will be alleviated after
some delay. If known, the length of the delay MAY be indicated in a
Retry-After header. If no Retry-After is given, the client SHOULD
handle the response as it would for a 500 response.

    Note: The existence of the 503 status code does not imply that a
    server must use it when becoming overloaded. Some servers may wish
    to simply refuse the connection.

在源码层面，当请求在 HTTP muxer 中无法匹配任何路由时，Traefik 会以 404 应答，这一行为在 muxer 测试 中有大量用例覆盖（未匹配的路径、Host、Method 均断言 http.StatusNotFound），与文档描述完全一致。

为什么返回 502 Bad Gateway？

当联系上游服务（upstream service）时发生错误，Traefik 返回 502 响应码。也就是说：请求已经匹配到了 Router 并找到了 Service，但代理到后端时连接失败（后端不可达、拒绝连接等），这是网关层面的错误，责任在“代理到上游”这一步。

为什么返回 503 Service Unavailable？

当 Router 已被匹配，但没有可用的服务器能处理该请求时，Traefik 返回 503。常见于以下两种场景：

1. 某个 service 被显式配置为没有 servers；
2. 某个 service 启用了 healthcheck（健康检查），而所有服务器当前均不健康。

从源码结构看，这一行为由各个负载均衡器实现直接给出：WRR、HRW、P2C、LeastTime 等负载均衡器在“没有可用服务器”时统一调用 http.Error(rw, errNoAvailableServer.Error(), http.StatusServiceUnavailable)，例如 wrr.go、hrw.go、p2c.go、leasttime.go，failover 策略同样返回 503（failover.go）。routerfactory_test.go 也对无服务器场景断言了 http.StatusServiceUnavailable。

用 catchall 路由把 404 换成其他状态码

有时 404 与其他组件或服务（例如 CDN）配合不佳。此时你可能希望 Traefik 一律返回 503 而非 404。

实现方式：添加一个 catchall router——给它最低的优先级，并让它指向一个没有 servers 的 service。当没有其他 Router 匹配时，它就能接住所有请求。

下面是一个仅使用 file provider（YAML）的配置示例：

静态配置（traefik.yml）：

# traefik.yml

entryPoints:
  web:
    address: :80

providers:
  file:
    filename: dynamic.yaml

动态配置（dynamic.yaml）：

# dynamic.yaml

http:
  routers:
    catchall:
      # attached only to web entryPoint
      entryPoints:
        - "web"
      # catchall rule
      rule: "PathPrefix(`/`)"
      service: unavailable
      # lowest possible priority
      # evaluated when no other router is matched
      priority: 1

  services:
    # Service that will always answer a 503 Service Unavailable response
    unavailable:
      loadBalancer:
        servers: {}

要点说明：

• entryPoints: ["web"] 让该路由只挂到 web 入口点；
• rule: "PathPrefix(/)" 是 catchall 规则，可匹配任意路径；
• priority: 1 是最低优先级，保证只有在其他 Router 均未匹配时才会被求值；
• unavailable service 的 loadBalancer.servers 为空（{}），由上文 503 的机制可知，它永远返回 503 Service Unavailable。

专用服务提示： 如果你需要的响应码不是 503、或者需要自定义响应消息，上述 catchall 路由的原理依然成立，只需把 unavailable service 改成满足需求的形态即可（例如指向一个专门的错误响应后端）。

为什么 TLS 证书内容变化后没有被重新加载？

使用 file provider 时，只有被监视的配置文件本身被修改时，才会触发配置更新。

因此，当证书是通过文件路径定义的、而该证书文件的实际内容发生了变化时，不会触发配置更新——因为 file provider 监视的是配置文件，不是证书文件的内容。

要让 Traefik 感知新证书内容，必须强制触发一次动态配置更新。一个办法是制造一次文件通知（file notification），例如对配置文件执行 touch 命令：

touch /path/to/your/dynamic-config.yml

这样 file provider 会重新读取配置、重新聚合证书，新证书内容随之生效。这一“按文件变更触发”的机制在 file provider 源码 与 configurationwatcher.go 的配置监听逻辑中可以得到印证。

代理 HTTP 请求时，默认注入了哪些转发头（Forwarded Headers）？

默认情况下，Traefik 代理请求时会自动添加以下头：

属性（Property）	HTTP Header
客户端 IP（Client's IP）	X-Forwarded-For, X-Real-Ip
主机（Host）	X-Forwarded-Host
端口（Port）	X-Forwarded-Port
协议（Protocol）	X-Forwarded-Proto
代理服务器主机名（Proxy Server's Hostname）	X-Forwarded-Server

在源码中，这些头的注入发生在代理核心 proxy.go 中：X-Forwarded-For、X-Real-IP、X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-Proto 会追加当前请求信息，若请求中已携带这些头则进行合并（如 proxy.go#L131-L137 中对已有 X-Forwarded-Host、X-Forwarded-Proto 的读取与拼接）。更完整的参数说明（如各 forwardedHeaders.* 开关）可参考 entrypoints 文档中 Opt ForwardedHeaders 连接部分。

Traefik 如何存储与提供服务 TLS 证书？

存储 TLS 证书

TLS 证书的来源有两个：

1. 由路由配置（routing configuration）直接提供（例如 file provider 的 tls.certificates 字段）；
2. 由证书解析器（Certificate resolvers）提供（例如 ACME/Let's Encrypt）。

对每张 TLS 证书，Traefik 都会生成一个**标识符（identifier）**作为存储的键。该标识符由证书的 SAN 中 DNSNames 与 IPAddresses 按字母序排序后拼接而成。

示例：

X509v3 Subject Alternative Name	TLS Certificate Identifier
DNS:example.com, IP Address:127.0.0.1	127.0.0.1,example.com
DNS:example.com, DNS:*.example.com	*.example.com,example.com

该标识符用于存储 TLS 证书，以便后续处理 TLS 连接时使用。这个操作在每次配置变更时都会执行（可参见 certificate_store.go 与 tlsmanager.go 中的证书注册逻辑）。

重名覆盖规则： 如果多张 TLS 证书拥有相同的 SAN 定义（即相同标识符），只有先被处理的那张会被保留。由于动态配置聚合自所有 provider，在处理它们以收集 TLS 证书时，无法保证处理顺序。这意味着随着配置的持续应用，某个标识符最终保留下来的证书可能发生变化。

提供（挑选）TLS 证书

对于每个到来的连接，Traefik 会为客户端提供的 server name 提供“最佳匹配”的 TLS 证书。

挑选过程分两步：

1. 把候选证书收窄为与 server name 匹配的那部分列表；
2. 将匹配列表按标识符字母序排序，然后选取列表中的最后一张。

示例：

匹配到的证书标识符	排序后的证书标识符	最终提供的证书标识符
127.0.0.1,example.com、*.example.com,example.com	*.example.com,example.com、127.0.0.1,example.com	127.0.0.1,example.com
*.example.com,example.com、example.com	*.example.com,example.com、example.com	example.com

第一行示例值得注意：精确域名 127.0.0.1,example.com 虽然与泛域名证书都能匹配 server name，但排序后位于末尾，因此被优先提供——排序规则决定了“最具体”的证书赢得选择，这与多数反向代理“精确域名优先于通配符”的直觉是一致的。该选择逻辑由 tlsmanager.go 中的 GetCertificate 流程实现。

TLS 证书缓存

虽然 Traefik 为每个到来的连接都提供“最佳匹配”证书，但借助缓存机制避免了每个连接都执行一次挑选过程的开销：

• 一张 TLS 证书一旦被选为某 server name 的“最佳”证书，就会被缓存一小时，后续同 server name 的连接直接复用，不再重新挑选；
• 但是，当新的配置被应用时，缓存会被重置，确保新证书/新配置立即生效。

“field not found” 错误是什么意思？

如果看到类似这样的报错：

error: field not found, node: -badField-

说明在动态配置或静态配置中遇到了未知属性——即配置项写错了名字、拼写有误，或用了当前版本不支持的字段。

检查配置文件是否格式正确的一种方式，是用 JSON Schema 来校验：

• 静态配置的 JSON Schema（schemastore 上的 traefik-v2.json）；
• 动态配置的 JSON Schema（schemastore 上的 traefik-v2-file-provider.json）。

注：以上 JSON Schema 托管于 schemastore 等外部站点，文档仅将其作为校验手段提及；本仓库不托管这些 Schema 文件。

为什么某些资源（routers、middlewares、services…）没有被创建/应用？

一个通用排查技巧：如果某个资源在动态配置被求值后被丢弃/未被创建，应当先去日志里找错误。

• 如果找到错误，它就证实了创建资源过程中出了问题；错误信息通常能帮助定位配置中的错误并指导修复。
• 使用 file provider 时，同样可以用上文提到的动态配置 JSON Schema 来校验配置文件是否格式正确。

配置聚合阶段各资源是逐个创建、失败即记录并跳过的，这一行为可从 configurationwatcher.go 与 aggregator.go 的处理链路中推断：配置变更被 watch 到后经聚合器分发，任何创建失败都会以错误日志形式呈现，而不是静默丢弃。

为什么 Let's Encrypt 通配符证书用 DNS 挑战续期/签发会失败？

如果你正在尝试用 DNS 挑战续期通配符证书，却得到如下错误：

msg="Error renewing certificate from LE: {example.com [*.example.com]}"
providerName=letsencrypt.acme error="error: one or more domains had a problem:
[example.com] acme: error presenting token: gandiv5: unexpected authZone example.com. for fqdn example.com."

原因可能是 CNAME 支持所致。此时你应当：

1. 确认你的基础设施已经为不依赖 CNAME 的 DNS 挑战正确配置（例如 _acme-challenge 记录可以直接写入权威 DNS zone）；
2. 尝试禁用 CNAME 支持：

LEGO_DISABLE_CNAME_SUPPORT=true

设置该环境变量后，ACME 客户端（LEGO）在验证 DNS 挑战时不再跟随 CNAME 跳转，可避免上述 unexpected authZone 类错误。ACME 相关的实现与 provider 行为可参考 provider/acme 源码目录。

小结

这篇 FAQ 的核心逻辑链是：Traefik 是动态反向代理，因此其状态码行为、证书加载与资源应用都围绕“配置随时在变”这一前提设计：

现象	直接原因	排查/修复入口
404 Not Found	请求匹配不到任何 Router	检查 EntryPoint 上是否配置了 Router、规则是否匹配；可用 catchall 路由改成 503
502 Bad Gateway	联系上游服务时出错	检查 service 的后端地址与后端服务本身
503 Service Unavailable	Router 已匹配但没有可用服务器（空 servers 或全部不健康）	检查 loadBalancer 的 servers 与健康检查结果
证书内容变更未生效	file provider 只监视配置文件，不监视证书内容	touch 配置文件强制触发动态配置更新
未知字段错误	配置中出现未知属性	用 JSON Schema 校验配置文件
资源未被应用	资源创建失败	查看错误日志定位配置错误
通配符证书 DNS 挑战失败	CNAME 支持引发 authZone 不匹配	设置 LEGO_DISABLE_CNAME_SUPPORT=true

配合本文引用的源码路径（muxer 状态码测试、各负载均衡器的 503 应答、转发头注入、TLS 证书存储与挑选逻辑），你可以将文档层面的结论逐一落到实现层面验证。