迁移：各版本之间需要执行的步骤¶

本指南详细介绍 Traefik v3 不同版本之间的升级步骤。每节涵盖不兼容变更、弃用事项，以及平稳过渡所需的配置更新。

v3.7.16¶

Kubernetes CRD 与 Ingress-NGINX 提供者：中间件中的 Secret 引用¶

在 v3.7.16 之前，中间件路由配置中保存的是提供者从 Kubernetes Secret 读取的实际值。

从 v3.7.16 开始，配置改为保存 Secret 键引用，格式为 urn:k8s:secret:<secret name>:<key>。 Traefik 在构建中间件时读取实际值，因此中间件行为保持不变。 API、仪表盘和支持转储中显示的是这些引用。

v3.7.15¶

CONNECT 请求¶

从 v3.7.15 开始，无论客户端使用哪个 HTTP 版本，Traefik 都会以 501 Not Implemented 拒绝所有 CONNECT 请求， 不会将其转发给后端。

HTTP/1 CONNECT 请求自 v3.7.9 起已经被拒绝。 通过 HTTP/2 或 HTTP/3 发送的 CONNECT 请求在某些情况下看起来能够工作， 但它们没有专门处理，而安全的 CONNECT 隧道需要专门处理机制。 出于安全原因，Traefik 现在也会拒绝这些请求。

拒绝发生在路由之前，因此这些请求不会记录到访问日志中， 只有在 DEBUG 日志级别下才能看到。

如需通过 Traefik 暴露的正向代理建立流量隧道，应改用 TCP 路由器。

Kubernetes Gateway API 提供者：后端协议¶

在 v3.7.15 之前，如果 Service 端口未设置 appProtocol，且端口为 443 或端口名以 https 开头， Kubernetes Gateway API 提供者会使用 HTTPS 访问 HTTPRoute 的后端。

从 v3.7.15 开始，端口号和端口名不再决定是否使用 HTTPS， 这类后端将通过明文 HTTP 访问。 这遵循 Gateway API 规范：只有 Service 端口的 appProtocol 或 BackendTLSPolicy 决定后端连接协议。 如需继续使用 HTTPS，将 Service 端口的 appProtocol 设置为 https，或为 Service 附加 BackendTLSPolicy。

v3.7.14¶

Ingress-NGINX 提供者：生成名称¶

在 v3.7.14 之前，Ingress-NGINX 提供者生成路由器、服务、serversTransports 和 TLS 选项名称时， 会将 Ingress 和 Secret 名称中的点替换为连字符。 因此，my.ingress 和 my-ingress 两个资源会生成相同名称，其中一个会静默覆盖另一个。

从 v3.7.14 开始，资源名称原样保留：名为 my.ingress 的 Ingress 所生成路由器， 现在是 default-my.ingress-rule-0-path-0，不再是 default-my-ingress-rule-0-path-0。 依赖旧名称的仪表盘、告警和 API 查询必须相应更新。

带有 nginx.ingress.kubernetes.io/ssl-passthrough 注解的 Ingress，在 HTTP 入口点上生成的路由器和中间件也会重命名。 现在使用来源 Ingress 规则和路径命名，即 <namespace>-<ingress>-rule-<rule index>-path-<path index>，不再是 <namespace>-<ingress>-<host>-http。

Kubernetes Gateway API 提供者：同等匹配请求的路由¶

在 v3.7.14 之前，同一监听器上的两条路由可能生成完全相同的路由器规则。 例如，一条路由没有主机名，另一条使用监听器的主机名时，就会发生这种情况。 两个路由中的一个会处理请求，但无法确定是哪一个， 每次重载配置时所选路由也可能变化。

从 v3.7.14 开始，只有优先级最高的路由处理请求。 规范优先选择较早创建的路由，时间相同时，再按 {namespace}/{name} 字母顺序选择第一条。 Traefik 不会为其他路由创建路由器。 Traefik 会记录警告，并给出实际处理该规则的路由器名称。

Kubernetes Gateway API 提供者：TLSRoute 路由器名称¶

在 v3.7.14 之前，TLSRoute 附加到共享同一入口点的多个 TLS 监听器时，会生成同名路由器， 最后只保留一个。

从 v3.7.14 开始，TLSRoute 路由器名称的哈希后缀还会根据路由器规则计算， 因此所有 TLSRoute 路由器以及由其派生的服务名称都会变化。 依赖旧名称的仪表盘、告警和 API 查询必须相应更新。

OpenTelemetry 指标：指数直方图¶

在 v3.7.14 之前，traefik_*_request_duration_seconds 直方图始终以显式桶导出， 即使 OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION 已设置为 base2_exponential_bucket_histogram 也是如此。

从 v3.7.14 开始，这些直方图遵循该环境变量， metrics.otlp.explicitBoundaries 选项仅适用于显式桶直方图。 启用指数聚合后，依赖这些直方图桶序列的仪表盘和告警必须更新。

v3.7.13¶

h2c 升级请求¶

从 v3.7.13 开始，Traefik 不再将 Upgrade: h2c 和 HTTP2-Settings 请求头 转发给后端。

Traefik 未实现已弃用的 h2c 升级机制，只支持通过预先知悉方式建立的未加密 HTTP/2。 转发这些请求头会让后端接受一个 Traefik 本身并未与客户端协商的升级。

之前接受这类升级的后端，现在会通过 HTTP/1.1 处理这些请求。 如需使用未加密 HTTP/2 连接后端，声明服务器时使用 h2c 协议：

## Dynamic configuration
http:
  services:
    my-service:
      loadBalancer:
        servers:
        - url: "h2c://private-ip-server-1:8080"

## Dynamic configuration
[http.services]
  [http.services.my-service.loadBalancer]

    [[http.services.my-service.loadBalancer.servers]]
      url = "h2c://private-ip-server-1:8080"

暴露协议设置而不是服务器 URL 的提供者也采用相同方式， 可使用 traefik.http.services.<service_name>.loadbalancer.server.scheme=h2c 标签、 Kubernetes CRD 的 scheme: h2c 选项， 或 Kubernetes Ingress 的 traefik.ingress.kubernetes.io/service.serversscheme: h2c 注解。

请求目标验证¶

从 v3.7.13 开始，如果请求目标是无根形式，也就是协议名后跟的内容不以斜杠开头， 则请求会以 400 Bad Request 被拒绝。 这种目标不属于 rfc9112#section-3.2 允许的四种形式。

无根目标（例如 http:example.com/admin）没有路径， 因此可以绕过路径处理和路由规则，同时仍指定后端资源。 此项拒绝行为不可配置，因为允许这类目标会重新引入绕过问题。

验证发生在路由之前，因此拒绝的请求不会记录到访问日志， 只有在 DEBUG 日志级别下才能看到。

Consul Catalog 与 Nomad：服务配置冲突¶

Consul Catalog 和 Nomad 提供者分别构建每个服务实例的配置， 再将它们合并。在 v3.7.13 之前，实例通过规范化后的节点、服务名称和服务标识符拼接串标识， 这种方式存在歧义：两个不同实例可能生成相同标识符， 除最后一个以外的实例配置都会被静默丢弃。

从 v3.7.13 开始，标识符不再有歧义，每个实例都会参与合并。

v3.7.12¶

AliasHeadersStrategy¶

从 v3.7.12 开始，新增入口点选项 aliasHeadersStrategy， 替代并弃用在 v3.6.20 中引入的 underscoreHeadersStrategy。

Go 只按照连字符规范化请求头名称，因此将 X-Auth-User、X_Auth_User 和 X.Auth.User 视为三个不同请求头； 而根据请求头生成变量名的后端（CGI、WSGI、PHP、NGINX 等）会将名称转换为大写， 并将所有非字母、非数字字符替换为下划线： 对于这些后端，三个名称都对应同一个 HTTP_X_AUTH_USER 变量。

underscoreHeadersStrategy 只处理名称中包含下划线的请求头， 其他别名形式不受影响；这个选项自身行为没有变化。 下划线只是能够产生别名的字符之一：HTTP 请求头名称中允许的字符，除字母、数字和连字符外都可以产生别名， 即 !、#、$、%、&、'、*、+、.、^、_、`、| 以及 ~。aliasHeadersStrategy 会处理所有这些字符：

• keep（默认值）：原样转发具有别名名称的请求头。
• delete：如果请求头名称包含既非字母、数字也非连字符的字符，则静默删除该请求头。
• reject：如果请求携带的请求头名称包含既非字母、数字也非连字符的字符，则以 400 Bad Request 响应拒绝请求。

默认值为 keep，因此保留现有行为。

entryPoints:
  websecure:
    address: ':443'
    http:
      aliasHeadersStrategy: delete

[entryPoints.websecure]
  address = ":443"

  [entryPoints.websecure.http]
    aliasHeadersStrategy = "delete"

--entryPoints.websecure.address=:443
--entryPoints.websecure.http.aliasHeadersStrategy=delete

设置 underscoreHeadersStrategy 会记录弃用警告。 同时为两个选项配置不同的值，会使安装配置无效。

对于未配置本选项的每个入口点，Traefik 现在会在启动时记录警告， 因为管理请求头的中间件依靠它防止别名名称造成的伪造。

更多信息请参阅入口点的 aliasHeadersStrategy 选项 以及具有别名名称的请求头文档。

TCP 与 UDP 加权服务：负权重¶

构建 TCP 或 UDP 加权服务时，现在会拒绝负权重。 这种配置之前会让负载均衡器在持锁状态下无限循环选择， 消耗一个 CPU 核心，并阻塞该服务后续所有连接，直到重启 Traefik。

声明负权重的加权服务现在会在 API 中显示为 disabled，并附带错误， 引用它的路由器不会创建。 将负权重改为正数，或使用 0 将子服务移出轮转。

TCP 与 UDP 加权服务：子服务错误¶

TCP 或 UDP 加权服务的子服务无法构建时，例如子服务不存在， 父加权服务现在会在 API 中显示为 disabled 并附带错误， 与 HTTP 加权服务已有行为一致。 此前这类父服务既不报告错误，也不报告状态。

这只改变报告结果：之前引用父服务的路由器就已经不会创建。

v3.7.11¶

安全命名配置选项¶

从 v3.7.11 开始，新增提供者选项 safeNaming，为 Kubernetes CRD 提供者生成的 路由器、中间件和服务启用防冲突命名，替代当前命名方式； 当前命名方式可能在跨命名空间或不同资源之间产生冲突。

生成名称根据源对象身份派生，不再扁平化并规范化拼接； 为路由生成的名称也根据路由索引派生，而不再根据规则。 例如，default 命名空间中名为 whoami 的 Kubernetes Service 和名为 test.route 的 IngressRoute：

default-whoami-80                          ->    default_whoami_80
default-test-route-6b204d94623b3df4370c    ->    default_test.route_0

该选项默认关闭，保留现有行为。

更多信息请参阅提供者的 safeNaming 文档。

冲突的 TLS 选项¶

TLS 选项配置在路由器上，但在路由发生之前的 TLS 握手阶段就会应用， 因此它们映射的是路由规则中的主机名，而不是路由器本身。 同一入口点上多个路由器使用不同 TLS 选项服务同一个主机名时， Traefik 无法确定应用哪组选项，会针对该主机名回退到 default TLS 选项。

由于 default TLS 选项是冲突解决的回退配置，它们不应比可能被替换的选项更宽松： 例如，依赖双向 TLS 身份验证（clientAuth）的路由器，在主机名冲突后回退到不要求客户端认证的 default TLS 选项时， 就不再强制验证客户端。 更多详情请参阅 GHSA-g55h-rg46-x9c5。

从 v3.7.11 开始，新增安装配置选项 core.strictTLSOptions 可以关闭这一回退： 参与冲突的路由器会标为错误，完全不构建。

该选项默认关闭，以保留现有行为，但建议启用：

## Install configuration
core:
  strictTLSOptions: true

## Install configuration
[core]
  strictTLSOptions = true

## Install configuration
--core.strictTLSOptions=true

更多信息请参阅冲突的 TLS 选项文档。

Kubernetes CRD：集群级默认 TLSOption 与 TLSStore¶

在 Kubernetes CRD 提供者中，名为 default 的 TLSOption 和 TLSStore 都是集群级资源， 无论定义在哪个命名空间都一样。因此，只要有权在一个命名空间创建此类资源， 就能替换那些未显式引用 TLS 选项的路由器的 TLS 策略，包括双向 TLS 身份验证。

从 v3.7.11 开始，新增提供者选项 defaultTLSResourcesNamespace， 可将这些资源限定在集群运维人员控制的命名空间。

该选项默认为空，以保留现有行为，但建议设置：

## Install configuration
providers:
  kubernetesCRD:
    defaultTLSResourcesNamespace: traefik

## Install configuration
[providers.kubernetesCRD]
  defaultTLSResourcesNamespace = "traefik"

## Install configuration
--providers.kubernetescrd.defaultTLSResourcesNamespace=traefik

更多信息请参阅 Kubernetes CRD 提供者文档。

v3.7.10¶

Kubernetes Gateway API 提供者：生成的路由器、中间件与服务名称¶

从 v3.7.10 开始，Kubernetes Gateway API 提供者生成路由器名称时，哈希后缀根据路由、Gateway 和监听器的全部标识字段计算，不再只根据路由规则。 这样可以避免不同路由的命名空间、名称、Gateway 和监听器恰好拼接为相同字符串时，生成同一个路由器名称。

生成的路由器名称整体形式保持不变：

<route kind>-<route namespace>-<route name>-gw-<gateway namespace>-<gateway name>-ep-<entry point>-<rule index>-<hash>

但 <hash> 后缀会变化，因为不再只按路由规则计算。

例如，default 命名空间中名为 http-app-1 的 HTTPRoute，之前生成路由器 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-af329269dd38031b03e3，现在改为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-799bcbf0c2317c5d1c93。

中间件名称基于路由器名称派生，因此也相应变化，例如 <router name>-requestheadermodifier-0。

此前，生成的服务名称只基于后端引用构造：

<backend namespace>-<backend name>-<port>

现在则加上生成该服务的路由规则前缀：

<router name>-svc-<backend namespace>-<backend name>-<backend index>

例如，default 命名空间中的 whoami 后端，之前以 default-whoami-http-80@kubernetesgateway 暴露，现在改为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-799bcbf0c2317c5d1c93-svc-default-whoami-0@kubernetesgateway。

Kubernetes Gateway API 提供者¶

从 v3.7.10 开始，Kubernetes Gateway API 提供者支持规范 v1.6.1。

TCPRoute 在 Gateway API v1.6.0 中进入标准通道，并新增 v1 版本。 Traefik v3.7 仍通过 v1alpha2 版本监听 TCPRoute， 但标准通道 CRD 已不再提供此版本。

如果使用 TCPRoute 并升级到 Gateway API v1.6.1 CRD， 必须安装实验通道 CRD。 Traefik 中启用 TCPRoute 支持仍需要 experimentalChannel 选项。

Traefik v3.7 仍向后兼容 v1.5.x CRD：只有要使用 v1.6.1 资源时，才必须升级集群中的 CRD。

可选：应用 v1.6.1 CRD：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/standard-install.yaml

实验通道（TCPRoute 必需）：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/experimental-install.yaml

v3.7.9¶

HTTP/1 CONNECT 请求¶

从 v3.7.9 开始，HTTP/1 CONNECT 请求会以 501 Not Implemented 响应被拒绝。

变更之前 HTTP/1 CONNECT 请求本来就无法工作，现在通过明确拒绝反映这一点。

v3.7.8¶

Kubernetes CRD：Errors 中间件的 errorRequestHeaders¶

Errors 中间件在 v3.6.15 中引入的 errorRequestHeaders 选项， 此前未暴露给 Kubernetes CRD 提供者。 从 v3.7.8 开始，可以在 Middleware CRD 中配置它。

使用此选项之前，必须先更新集群中的 Kubernetes CRD，再升级 Traefik。 应用 v3.7 的 CRD 清单：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

更多信息请参阅错误页面中间件文档。

v3.7.7¶

通配符 Host 匹配器¶

从 v3.7.7 开始，Host 匹配器将单独的 * 视为匹配所有主机，与 TCP HostSNI(*) 匹配器一致。 Host(`*`) 现在会匹配所有请求，不论主机是什么，包括完全没有主机的请求。

此前，* 被视为单个通配符标签，因此 Host(`*`) 只匹配单段主机名，例如 localhost，不匹配 example.com 这样的多段主机名。

更多信息请参阅 HTTP 路由规则文档。

v3.7.6¶

Kubernetes Gateway API 提供者：生成的服务与中间件名称¶

从 v3.7.6 开始，Kubernetes Gateway API 提供者生成服务与中间件名称时，会根据所属路由规则派生，不再只根据后端引用。 这样可以避免引用相同后端的不同路由规则在单个生成配置上发生冲突。

此前，生成的服务名称只基于后端引用构造：

<backend namespace>-<backend name>-<port>

现在则加上生成该服务的路由规则前缀：

<route kind>-<route namespace>-<route name>-gw-<gateway namespace>-<gateway name>-ep-<entry point>-<rule index>-<rule hash>-svc-<backend namespace>-<backend name>-<backend index>

例如，default 命名空间中的 whoami 后端，之前以 default-whoami-http-80@kubernetesgateway 暴露，现在改为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-af329269dd38031b03e3-svc-default-whoami-0@kubernetesgateway。

UnderscoreHeadersStrategy¶

从 v3.6.20 开始，新增入口点选项 underscoreHeadersStrategy， 定义路由前如何处理名称中带下划线的请求头：

• keep（默认值）：原样转发带下划线的请求头。
• delete：名称中包含下划线的请求头会从请求中静默删除。
• reject：只要请求携带名称中包含下划线的请求头，就以 400 Bad Request 响应拒绝。

默认值为 keep，因此保留现有行为。

这个选项存在，是因为下划线在 HTTP 请求头名称中是合法字符，但 Go 只根据连字符规范化请求头名称。 因此，管理连字符形式请求头的中间件，例如通过 ForwardAuth 的 authResponseHeaders 设置 X-Auth-User， 看不到对应下划线形式，例如 X_Auth_User，也就无法覆盖或删除它。

许多后端会把两种形式映射到同一个变量（CGI、WSGI、PHP、NGINX 等）： 对它们而言，X-Auth-User 与 X_Auth_User 是同一个请求头。 针对这类后端，客户端可以用下划线变体绕过只管理连字符形式的中间件， 让后端读取伪造值，绕过中间件原本提供的保护。

v3.7.3¶

Kubernetes Gateway API 提供者¶

从 v3.7.3 开始，Kubernetes Gateway API 提供者所用 Kubernetes 客户端的 QPS 和 Burst 分别增加到 50 和 100，即 Kubernetes 客户端默认值的 10 倍。

为符合 Kubernetes Gateway API 规范，提供者需要密集写入状态更新。 此变更有助于避免 Kubernetes API 限速造成的性能问题；这种限速可能延长新路由配置的部署时间。

这些值可通过提供者选项 kubernetesGateway.qps 和 kubernetesGateway.burst 配置。

BasicAuth 中间件¶

从 v3.7.3 开始，BasicAuth 中间件必须具有非空用户配置才能成功构建。 此前，中间件可以成功构建，但对所有请求始终返回 401 状态码。 现在会报错，所有使用该中间件的路由器都会被卸载。相同请求将收到 404，而不是 401。

StripPrefix 与 StripPrefixRegex 中间件¶

从 v3.7.3 开始，如果移除所配置前缀后得到的路径与其规范化形式不同， 即包含规范化时会折叠的 . 或 .. 片段， StripPrefix 和 StripPrefixRegex 中间件会以 400 Bad Request 拒绝请求。

这样可以避免上游服务将移除前缀后的路径解释为另一个资源。

配置前缀为 /api 时的示例：

v3.7.1¶

Kubernetes 提供者：crossProviderNamespaces¶

在 v3.7.1 中，Kubernetes CRD、Ingress 和 Gateway 提供者新增 crossProviderNamespaces 选项。

Traefik 允许从一个提供者引用另一个提供者的资源，即跨提供者引用。

但对于 Kubernetes 提供者， 这类引用（例如 myservice@kubernetescrd）允许用户跨越命名空间边界， 也能暴露原本只有运维人员应有权暴露的 @internal 服务。

新增的 crossProviderNamespaces 选项限定哪些命名空间中的 Kubernetes 资源可以使用跨提供者引用。

行为如下：

更多信息请参阅 Kubernetes CRD、Kubernetes Ingress 和 Kubernetes Gateway 提供者文档。

v3.7.0¶

Ingress NGINX 提供者¶

从 v3.7.0 开始，Ingress NGINX 提供者支持 nginx.ingress.kubernetes.io/custom-headers 注解，将自定义响应头加入转发给客户端的响应。

因此，对应 RBAC 新增了 configmaps 权限，参阅 KubernetesIngressNGINX 提供者 RBAC。

必要的 RBAC 更新：

  ...
  - apiGroups:
      - ""
    resources:
      - configmaps
    verbs:
      - list
      - watch  
  ...

Kubernetes Gateway API 提供者¶

从 v3.7.0 开始，Kubernetes Gateway API 提供者支持规范 v1.5.1， 需要更新 Gateway API CRD。

TLSRoute 已进入标准通道，不再需要 experimentalChannel 选项。 experimentalChannel 现在仅供 TCPRoute 使用。

应用更新后的 CRD：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

实验通道：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/experimental-install.yaml

Kubernetes CRD 提供者¶

要通过 Kubernetes CRD 提供者使用 retry 中间件的新选项或新增的 ingressClassName 字段，需要更新 CRD。

应用更新后的 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

通配符 Host 与 HostSNI¶

自 v3.7.0 起，Host 和 HostSNI 匹配器支持通配符子域匹配，例如 *.example.com。 单层通配符前缀可以匹配域名下的所有直接子域。 例如，*.example.com 匹配 foo.example.com，但不匹配 foo.bar.example.com 或 example.com 本身。

该功能仅在 v3 规则语法（默认语法）下可用。

通配符域名的 TLSOptions¶

自 v3.7.0 起，TLSOptions 可以关联到使用通配符 Host 和 HostSNI 匹配器的路由器，例如 Host(*.example.com)。 因此可以为通配符域名配置不同 TLS 选项。

此前，TLSOptions 选择仅限于精确 Host 匹配；使用 HostRegexp 或通配符时会回退到默认 TLS 选项，并给出类似警告：No domain found in rule HostRegexp(...) the TLS option foo cannot be applied。

注意：HostRegexp 匹配器仍不支持 TLSOptions，应改用通配符 Host 匹配器。

v3.6.25¶

Kubernetes Gateway API 提供者：生成的路由器、中间件和服务名称¶

从 v3.6.25 开始，Kubernetes Gateway API 提供者根据路由、Gateway 和监听器的全部标识字段计算生成的路由器名称的哈希后缀，而不再仅根据路由规则计算。 这可以防止命名空间、名称、Gateway 和监听器恰好拼接为同一字符串的不同路由，因生成相同的路由器名称而发生冲突。

生成的路由器名称仍保持相同的整体格式：

<route kind>-<route namespace>-<route name>-gw-<gateway namespace>-<gateway name>-ep-<entry point>-<rule index>-<hash>

但 <hash> 后缀会发生变化，因为它不再仅根据路由规则计算。

例如，default 命名空间中名为 http-app-1 的 HTTPRoute，以前生成的路由器为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-af329269dd38031b03e3，现在生成的名称为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-799bcbf0c2317c5d1c93。

中间件名称由路由器名称派生，因此也会相应变化，例如 <router name>-requestheadermodifier-0。

以前，生成的服务名称仅根据后端引用构建：

<backend namespace>-<backend name>-<port>

现在，名称会加上其所属路由规则的前缀：

<router name>-svc-<backend namespace>-<backend name>-<backend index>

例如，default 命名空间中的 whoami 后端，以前暴露为 default-whoami-http-80@kubernetesgateway，现在暴露为 httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-799bcbf0c2317c5d1c93-svc-default-whoami-0@kubernetesgateway。

v3.6.24¶

Kubernetes CRD：Errors 中间件的 errorRequestHeaders¶

在 v3.6.15 中为 Errors 中间件引入的 errorRequestHeaders 选项， 此前未向 Kubernetes CRD 提供者开放。 从 v3.6.24 开始，可以在 Middleware CRD 中配置它。

若要使用此新选项，必须先更新集群中的 Kubernetes CRD，再升级 Traefik。 为此，请应用 v3.6 的 CRD 清单：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

更多详情请参阅 Error Pages 中间件文档。

HTTP/1 CONNECT 请求¶

从 v3.6.24 开始，HTTP/1 CONNECT 请求会被拒绝，并返回 501 Not Implemented 响应。

在此变更之前，HTTP/1 CONNECT 请求也无法正常工作，因此现在明确拒绝这类请求。

v3.6.22¶

UnderscoreHeadersStrategy¶

从 v3.6.22 开始，新增入口点选项 underscoreHeadersStrategy，用于定义在路由之前如何处理 名称中包含下划线的请求头：

• keep（默认）：包含下划线的请求头按原样转发。
• delete：名称中包含下划线字符的请求头会被静默移除。
• reject：任何携带名称中包含下划线字符的请求头的请求，都会被拒绝并返回 400 Bad Request 响应。

默认值为 keep，因此保留现有行为。

引入此选项的原因是，下划线是 HTTP 请求头名称中的有效字符，但 Go 只基于连字符规范化请求头名称。 因此，管理连字符形式请求头的中间件（例如 ForwardAuth 的 authResponseHeaders 选项设置的 X-Auth-User） 无法看到该请求头的下划线变体（例如 X_Auth_User），因而无法覆盖或移除它。

许多后端会将这两种形式映射到同一变量（CGI、WSGI、PHP、NGINX 等）：对它们而言，X-Auth-User 和 X_Auth_User 是同一个请求头。针对此类后端，客户端可以将下划线变体偷偷传过仅管理 连字符形式的中间件，让后端读取伪造的值，从而绕过中间件本应提供的保护。

v3.6.19¶

Kubernetes Gateway API 提供者¶

从 v3.6.19 开始，Kubernetes Gateway API 提供者使用的 Kubernetes 客户端的 QPS 和 Burst 值分别提高到 50 和 100（为 Kubernetes 客户端默认值的 10 倍）。

Kubernetes Gateway API 提供者会频繁写入状态更新，以符合 Kubernetes Gateway API 规范。 此变更有助于避免 Kubernetes API 限流引起的性能问题，这类问题可能增加构建新路由配置时的准备时间。

可以通过提供者选项 kubernetesGateway.qps 和 kubernetesGateway.burst 配置这些值。

BasicAuth 中间件¶

从 v3.6.19 开始，BasicAuth 中间件要求用户配置非空，才能成功构建。 以前，中间件可以成功构建，但对于任何请求都始终返回 401 状态码。 现在会产生错误，并卸载所有使用此中间件的路由器。对于同一个请求，会返回 404 状态码，而不是 401 状态码。

StripPrefix 和 StripPrefixRegex 中间件¶

从 v3.6.19 开始，StripPrefix 和 StripPrefixRegex 中间件在移除配置的前缀后，如果生成的路径与其规范化形式不同， 就会拒绝请求（400 Bad Request） （例如，路径包含会在规范化时被折叠的 . 或 .. 段）。

这可以防止上游服务将移除前缀后的路径解释为不同的资源。

配置前缀为 /api 时的示例：

v3.6.17¶

Kubernetes 提供者：crossProviderNamespaces¶

在 v3.6.17 中，Kubernetes CRD、Ingress 和 Gateway 提供者新增了 crossProviderNamespaces 选项。

Traefik 允许从一个提供者引用另一个提供者的资源（跨提供者引用）。

然而，在 Kubernetes 提供者的场景中， 这些引用（例如 myservice@kubernetescrd）允许用户跨越命名空间边界， 还允许暴露本应只有运维人员才能暴露的 @internal 服务。

新的 crossProviderNamespaces 选项限制了哪些命名空间中的 Kubernetes 资源可以使用跨提供者引用。

行为如下：

更多详情请参阅 Kubernetes CRD、Kubernetes Ingress 和 Kubernetes Gateway 提供者文档。

v3.6.16¶

Docker 提供者：最低 Docker Engine 版本¶

从 v3.6.16 开始，Docker 提供者要求 Docker API 版本为 v1.40 或 更高版本（Docker Engine v19.03）。 使用较旧（已结束生命周期）的 Docker Engine 版本的用户，应更新 Docker Engine，或通过 DOCKER_API_VERSION 环境变量覆盖 Traefik 使用的 API 版本。

v3.6.15¶

在 v3.6.15 中，Errors 中间件新增了 errorRequestHeaders 选项。

默认行为保持不变：所有原始请求头都会转发给错误页面服务。 如果错误页面服务位于不同的信任域，请考虑使用 errorRequestHeaders 限制要转发的请求头。

更多详情请参阅 Error Pages 中间件文档。

v3.6.14¶

Kubernetes CRD：Chain 中间件与 allowCrossNamespace¶

在 v3.6.14 中，Chain 中间件现在遵循 Kubernetes CRD 提供者的 allowCrossNamespace 选项。 以前，无论 allowCrossNamespace 如何配置，Chain 都可以引用其他命名空间中的中间件。

如果 allowCrossNamespace 设为 false（默认值），且 Chain 中间件引用了与自身不在同一命名空间中的中间件， 现在会拒绝整个 Chain 并记录错误。

ForwardAuth 中间件：trustForwardHeader¶

从 v3.6.14 开始，trustForwardHeader 选项已弃用，将在下一个主版本中移除。 请通过 forwardedHeaders.trustedIPs 选项在入口点层级配置可信 IP， 并在此中间件上将 trustForwardHeader 设为 true。

未显式设置 trustForwardHeader 时，Traefik 会记录警告，因为此时的行为不一致： 部分 X-Forwarded-* 请求头（例如 X-Forwarded-For、X-Forwarded-Proto）会被移除，其他请求头（例如 X-Forwarded-Prefix）则按原样转发。

要消除此警告并避免安全问题，请在 ForwardAuth 中间件配置中显式将 trustForwardHeader 设为 true 或 false。

更多详情请参阅 ForwardAuth 中间件文档。

v3.6.9¶

ForwardAuth 中间件的 maxResponseBodySize 配置¶

在 v3.6.9 中，ForwardAuth 中间件配置新增了 maxResponseBodySize 选项。 此选项的默认值为 -1，表示不限制响应体大小。 但强烈建议将此选项设为适当的值，以避免性能和安全问题， 例如 DoS 攻击和内存耗尽。

更多详情请参阅 ForwardAuth 中间件文档。

Kubernetes CRD 提供者¶

若要在 Kubernetes CRD 提供者中使用 ForwardAuth 中间件新增的 maxResponseBodySize 选项，需要更新 CRD。

应用更新后的 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

v3.6.8¶

健康检查请求路径¶

从 v3.6.8 开始，会验证配置的健康检查请求路径是否为相对 URL；如果不是，健康检查将失败。

v3.6.7¶

编码字符配置的默认值¶

从 v3.6.7 开始，编码字符相关选项的默认值为 true。 这意味着，Traefik 默认不会拒绝路径中包含某组特定编码字符的请求。 现在需要由用户自行配置编码字符的安全加固措施。

以下编码字符可以通过将相应选项设为 false 来禁止：

注意：此检查不针对查询参数执行， 只针对请求路径执行，路径定义见 RFC3986 第 3 节。

更多详情请参阅入口点 encodedCharacters 选项文档， 其中提供了进一步说明。

v3.6.4¶

请求路径中的编码字符¶

从 v3.6.4 开始，出于安全考虑，Traefik 默认会拒绝路径中包含某组特定编码字符的请求。

收到此类请求时，Traefik 会返回 400 Bad Request 状态码。

以下是默认拒绝的编码字符，以及允许相应字符的配置选项：

更多详情请参阅入口点 encodedCharacters 选项文档。

v3.6.2¶

Ingress NGINX 提供者¶

KubernetesIngressNGINX 提供者在 v3.6.2 中不再是实验性功能，无需 experimental.kubernetesIngressNGINX 选项即可启用。

已弃用的配置：

experimental:
  kubernetesIngressNGINX: true

[experimental]
    kubernetesIngressNGINX=true

--experimental.kubernetesIngressNGINX=true

迁移步骤：

1. 从 experimental 部分移除 kubernetesIngressNGINX 选项
2. 按照 kubernetesIngressNGINX 提供者文档配置提供者

v3.6.0¶

Kubernetes Gateway API 提供者¶

从 v3.6.0 开始，Kubernetes Gateway API 提供者仅支持 v1.4.0 版本的规范， 因此需要更新 Gateway API CRD。

应用更新后的 CRD：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

对于实验通道：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml

Kubernetes CRD 提供者¶

若要在 Kubernetes CRD 提供者中使用新的 leasttime 负载均衡算法，需要更新 CRD。

应用更新后的 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

v3.5.4¶

OpenTelemetry 证书指标重命名¶

从 v3.5.4 开始，使用 OpenTelemetry 时，traefik_tls_certs_not_after_milliseconds 指标重命名为 traefik_tls_certs_not_after_seconds。 此变更使指标名称与其实际精度单位保持一致：该单位为秒。

v3.5.2¶

弃用 ProxyProtocol 选项¶

从 v3.5.2 开始，TCP LoadBalancer 的 proxyProtocol 选项已弃用。 现在可以在 TCPServersTransport 层级配置此选项，详情请参阅文档。

Kubernetes CRD 提供者¶

要在 Kubernetes CRD 提供者中使用新的 proxyprotocol 选项，需要更新 CRD。

应用更新后的 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.5/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

v3.5.0¶

可观测性¶

路由器和入口点的 TraceVerbosity¶

从 v3.5.0 开始，入口点和路由器均提供新的 traceVerbosity 选项。 此选项用于控制链路追踪 span 的详细程度。 路由器可以覆盖从其入口点继承的值。

影响：

• 如果依赖链路追踪，请检查配置并显式设置所需的详细程度。
• 现有配置在未被覆盖时默认使用 minimal，因此生成的 span 会比以前更少。

可选值如下：

• minimal：为路由器处理的每个请求生成一个服务端 span 和一个客户端 span。
• detailed：针对路由器处理的每个请求，为执行的每个中间件额外创建 span。

请参阅更新后的入口点和动态路由器文档。

K8s 资源属性¶

从 v3.5.0 开始，启用 OTel 链路追踪、日志或指标后，语义约定属性 k8s.pod.name 和 k8s.pod.uid 会自动注入 OTel 资源属性。

为此，需要在 Traefik 的 Kubernetes RBAC 中添加以下权限：

  ...
  - apiGroups:
      - ""
    resources:
      - pods
    verbs:
      - get
  ...

v3.4.5¶

多路径 TCP¶

从 v3.4.5 开始，已移除 v3.4.2 中引入的多路径 TCP 支持。 在某些平台上，启用 MPTCP 似乎会导致 Traefik 停止，并输出以下错误日志：

• set tcp X.X.X.X:X->X.X.X.X:X: setsockopt: operation not supported

不过，仍可通过在 GODEBUG 环境变量中设置 multipathtcp 变量重新启用它，详见相关 Go 文档。

v3.4.1¶

请求路径规范化¶

从 v3.4.1 开始，请求路径会按 RFC 3986 标准进行规范化，以提高一致性和安全性。

规范化过程：

1. 非保留字符解码： 将 %2E（.）等字符解码为其字面形式
2. 大小写规范化： 将百分号编码字符转为大写（%2e 变为 %2E）

这遵循 RFC 3986 百分号编码规范化和大小写规范化标准。

处理顺序：

1. 路径规范化（无法禁用）
2. 路径清理（如已启用）

路由中的保留字符处理¶

从 v3.4.1 开始，路由器规则匹配期间，RFC 3986 定义的保留字符会保持编码状态，以防止路由歧义。

这一变化为何重要： 保留字符解码后会改变请求路径的含义。在路由期间保持其编码状态，可以防止安全漏洞，并使路由行为可预期。

请求路径匹配示例¶

下表说明路径匹配行为的变化：

v3.3 至 v3.4¶

Kubernetes CRD 提供者¶

负载均衡策略更新¶

从 v3.4 开始，HTTP 服务定义支持更多负载均衡策略，以更好地分配流量。

应用更新后的 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

新增策略值：

• wrr（加权轮询）
• p2c（二选一，Power of Two Choices）

详情请参阅 HTTP 服务负载均衡文档。

ServersTransport CA 证书配置¶

ServersTransport 和 ServersTransportTCP CRD 新增了 rootCAs 选项。它支持通过 ConfigMap 和 Secret 提供 CA 证书，并取代 rootCAsSecrets 选项。

应用更新：

# Update CRDs
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

# Update RBACs
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml

新的配置格式：

---
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: foo
  namespace: bar
spec:
  rootCAs:
    - configMap: ca-config-map
    - secret: ca-secret

---      
apiVersion: traefik.io/v1alpha1
kind: ServersTransportTCP
metadata:
  name: foo
  namespace: bar
spec:
  rootCAs:
    - configMap: ca-config-map
    - secret: ca-secret

规则语法配置¶

v3.4 中的规则语法配置选项将在下一个主要版本移除。

已弃用选项：

• core.defaultRuleSyntax（静态配置）
• ruleSyntax（路由器选项）

这些选项是从 v2 语法迁移到 v3 语法的过渡辅助选项。请确保在下一个主要版本发布前，所有路由器规则都使用 v3 语法。

v3.3.6¶

请求路径清理¶

从 v3.3.6 开始，传入请求的路径在处理前会自动清理，以保障安全性和一致性。

变更内容：

以下路径片段现在会被解析并折叠：

• /../（父目录引用）
• /./（当前目录引用）
• 重复的斜杠片段（//）

禁用清理：

# EntryPoint HTTP configuration
entryPoints:
  web:
    address: ":80"
    http:
      sanitizePath: false  # Not recommended

风险示例： 如果禁用路径清理，而含有“/”字符的 Base64 数据又未进行 URL 编码，就可能导致不安全的路由行为。

v3.3.5¶

Compress 中间件的默认编码¶

v3.3.5 调整了默认压缩算法的顺序，优先使用 gzip 压缩。

新的默认值： gzip, br, zstd

此变更影响以下任一情况的请求：

• 在 Accept-Encoding 头中未指定偏好的算法
• 在 Accept-Encoding 头中未指定顺序偏好

此顺序调整有助于兼容可能不支持较新压缩算法的旧版客户端。

v3.3.4¶

OpenTelemetry 请求耗时指标¶

v3.3.4 对 OpenTelemetry 请求耗时指标的单位进行了标准化，使其与其他提供者及命名约定一致。

变更详情：

• 指标： traefik_(entrypoint|router|service)_request_duration_seconds
• 旧单位： 毫秒
• 新单位： 秒

此变更使所有指标提供者保持一致，并遵循标准命名约定。

v3.2 至 v3.3¶

ACME DNS 证书解析器¶

v3.3 重新组织了 DNS 质询配置选项，使其更清晰。

需要迁移：

链路追踪全局属性¶

v3.3 澄清了链路追踪配置，使其更准确地表达用途。

需要迁移：

• 旧选项： tracing.globalAttributes
• 新选项： tracing.resourceAttributes

旧选项名容易引起误解，因为它实际为采集器添加资源属性，而不是全局 span 属性。

v3.2.2¶

Swarm 提供者标签更新¶

v3.2.2 弃用了 Swarm 专用标签，这些标签将在未来版本中移除。

需要迁移：

v3.2.1¶

X-Forwarded-Prefix 头的变更¶

v3.2.1 开始，X-Forwarded-Prefix 头与其他 X-Forwarded-* 头采用相同的处理方式：如果来自不可信来源，Traefik 会将其移除。

此变更通过防止不可信客户端伪造请求头来提高安全性。配置详情请参阅转发头文档。

v3.1 至 v3.2¶

Kubernetes CRD 提供者¶

多个 CRD 新增了可选字段。这些更新向后兼容，只添加新功能。

应用最新 CRD：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.3/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

更新的资源：

• TraefikService (PR #11032)
• RateLimit 与 InFlightReq 中间件（PR #9747）
• Compress 中间件（PR #10943）

Kubernetes Gateway 提供者标准通道¶

从 v3.2 开始，Kubernetes Gateway 提供者支持 GRPCRoute 资源。

因此，需要在相应 RBAC 中（参阅 KubernetesGateway 提供者的 RBAC） 添加 grcroutes 和 grpcroutes/status 权限。

所需的 RBAC 更新：

...
- apiGroups:
    - gateway.networking.k8s.io
  resources:
    - grpcroutes
  verbs:
    - get
    - list
    - watch
- apiGroups:
    - gateway.networking.k8s.io
  resources:
    - grpcroutes/status
  verbs:
    - update
...

Kubernetes Gateway 提供者实验性通道¶

由于 Kubernetes Gateway v1.2.0-rc1 存在破坏性变更，启用实验性功能时，Traefik v3.3 仅支持 Kubernetes Gateway v1.2.x。

新功能：支持 BackendTLSPolicy

此提供者现在支持 BackendTLSPolicy 资源。

因此，需要在相应 RBAC 中（参阅 KubernetesGateway 提供者的 RBAC） 添加 backendtlspolicies 和 backendtlspolicies/status 权限。

所需的 RBAC 更新：

  ...
  - apiGroups:
      - ""
    resources:
      - configmaps
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - backendtlspolicies
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - gateway.networking.k8s.io
    resources:
      - backendtlspolicies/status
    verbs:
      - update
  ...

v3.1.0 至 v3.1.1¶

IngressClass 查找¶

disableIngressClassLookup 选项已弃用，将在下一个主要版本中移除。

需要迁移：

• 旧选项： disableIngressClassLookup
• 新选项： disableClusterScopeResources

新选项对集群作用域资源的发现提供更广泛的控制，包括 IngressClass 和 Node 资源。

v3.0 至 v3.1¶

Kubernetes 提供者的 RBAC¶

从 v3.1 开始，Traefik 的 Kubernetes 提供者使用 EndpointSlices API（要求 Kubernetes >=v1.21）发现服务端点。此变更还引入了 NodePort 负载均衡能力。

所有 Kubernetes 提供者都需要以下 RBAC 更新：

• 移除 endpoints 权限并添加 endpointslices：

# Remove this section from your RBAC
# - apiGroups: [""]
#   resources: ["endpoints"]
#   verbs: ["get", "list", "watch"]

# Add this section instead
- apiGroups:
    - discovery.k8s.io
  resources:
    - endpointslices
  verbs:
    - list
    - watch

• 添加 nodes 权限以支持 NodePort：

- apiGroups:
    - ""
  resources:
    - nodes
  verbs:
    - get
    - list
    - watch

Gateway API：KubernetesGateway 提供者¶

KubernetesGateway 提供者在 v3.1 中已不再是实验性功能，无需设置 experimental.kubernetesgateway 选项即可启用。

已弃用的配置：

experimental:
  kubernetesgateway: true

[experimental]
    kubernetesgateway=true

--experimental.kubernetesgateway=true

迁移步骤：

1. 从 experimental 部分移除 kubernetesgateway 选项
2. 按照 KubernetesGateway 提供者文档配置提供者