从 Traefik v2 迁移到 v3 的配置详情¶

安装配置变更¶

SwarmMode¶

在 v3 中，Docker 提供者拆分为两个提供者：

Docker 提供者，不支持 Swarm。
Swarm 提供者，仅支持 Swarm。

v2 Docker 提供者使用 Swarm 的示例

文件 (YAML)

providers:
  docker:
    swarmMode: true

文件 (TOML)

[providers.docker]
    swarmMode=true

CLI

--providers.docker.swarmMode=true

此配置已不受支持，会阻止 Traefik 启动。

处理方法¶

在 v3 中，不应再为 Docker 提供者设置 swarmMode。如需使用 Swarm，应改用 Swarm 提供者。

Swarm 提供者使用示例

文件 (YAML)

providers:
  swarm:
    endpoint: "tcp://127.0.0.1:2377"

文件 (TOML)

[providers.swarm]
    endpoint="tcp://127.0.0.1:2377"

CLI

--providers.swarm.endpoint=tcp://127.0.0.1:2377

TLS.CAOptional¶

v3 移除了 Docker 提供者的 tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  docker:
    tls: 
      caOptional: true

文件 (TOML)

[providers.docker.tls]
    caOptional=true

CLI

--providers.docker.tls.caOptional=true

处理方法¶

从 Docker 提供者的安装配置中移除 tls.caOptional 选项。

Kubernetes Gateway API¶

实验通道资源（TLSRoute 和 TCPRoute）¶

在 v3 中，Kubernetes Gateway API 提供者默认不启用实验通道 API 资源支持。

处理方法¶

使用 experimentalChannel 选项启用实验通道 API 资源支持。

Kubernetes Gateway API 提供者启用实验通道支持的示例

文件 (YAML)

providers:
  kubernetesGateway:
    experimentalChannel: true

文件 (TOML)

[providers.kubernetesGateway]
    experimentalChannel = true
  # ...

CLI

--providers.kubernetesgateway.experimentalchannel=true

实验配置¶

HTTP3¶

在 v3 中，HTTP/3 不再是实验功能。无需关联的 experimental.http3 选项，即可在入口点启用；该选项现已移除。继续使用这个不受支持的选项会阻止 Traefik 启动。

v2 实验性 http3 选项使用示例

文件 (YAML)

experimental:
  http3: true

文件 (TOML)

[experimental]
    http3=true

CLI

--experimental.http3=true

处理方法¶

从安装配置的实验部分移除 http3 选项。配置 http3 的方法请参阅入口点配置文档。

Consul 提供者¶

namespace¶

Consul 提供者的 namespace 选项在 v2 中已弃用，在 v3 中正式移除。继续使用这个不受支持的选项会阻止 Traefik 启动。

v2 Consul namespace 选项使用示例

文件 (YAML)

consul:
  namespace: foobar

文件 (TOML)

[consul]
    namespace=foobar

CLI

--consul.namespace=foobar

处理方法¶

在 v3 中使用 namespaces 选项替代 namespace。

Consul namespaces 选项使用示例

文件 (YAML)

consul:
  namespaces:
    - foobar

文件 (TOML)

[consul]
    namespaces=["foobar"]

CLI

--consul.namespaces=foobar

TLS.CAOptional¶

v3 移除了 Consul 提供者的 tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  consul:
    tls: 
      caOptional: true

文件 (TOML)

[providers.consul.tls]
    caOptional=true

CLI

--providers.consul.tls.caOptional=true

处理方法¶

从 Consul 提供者的安装配置中移除 tls.caOptional 选项。

ConsulCatalog 提供者¶

namespace¶

ConsulCatalog 提供者的 namespace 选项在 v2 中已弃用，在 v3 中正式移除。继续使用这个不受支持的选项会阻止 Traefik 启动。

v2 ConsulCatalog namespace 选项使用示例

文件 (YAML)

consulCatalog:
  namespace: foobar

文件 (TOML)

[consulCatalog]
    namespace=foobar

CLI

--consulCatalog.namespace=foobar

处理方法¶

在 v3 中使用 namespaces 选项替代 namespace。

ConsulCatalog namespaces 选项使用示例

文件 (YAML)

consulCatalog:
  namespaces:
    - foobar

文件 (TOML)

[consulCatalog]
    namespaces=["foobar"]

CLI

--consulCatalog.namespaces=foobar

Endpoint.TLS.CAOptional¶

v3 移除了 ConsulCatalog 提供者的 endpoint.tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

Endpoint.TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  consulCatalog:
    endpoint:
      tls: 
        caOptional: true

文件 (TOML)

[providers.consulCatalog.endpoint.tls]
    caOptional=true

CLI

--providers.consulCatalog.endpoint.tls.caOptional=true

处理方法¶

从 ConsulCatalog 提供者的安装配置中移除 endpoint.tls.caOptional 选项。

Nomad 提供者¶

namespace¶

Nomad 提供者的 namespace 选项在 v2 中已弃用，在 v3 中正式移除。继续使用这个不受支持的选项会阻止 Traefik 启动。

v2 Nomad namespace 选项使用示例

文件 (YAML)

nomad:
  namespace: foobar

文件 (TOML)

[nomad]
    namespace=foobar

CLI

--nomad.namespace=foobar

处理方法¶

在 v3 中使用 namespaces 选项替代 namespace。

Nomad namespaces 选项使用示例

文件 (YAML)

nomad:
  namespaces:
    - foobar

文件 (TOML)

[nomad]
    namespaces=["foobar"]

CLI

--nomad.namespaces=foobar

Endpoint.TLS.CAOptional¶

v3 移除了 Nomad 提供者的 endpoint.tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

Endpoint.TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  nomad:
    endpoint:
      tls: 
        caOptional: true

文件 (TOML)

[providers.nomad.endpoint.tls]
    caOptional=true

CLI

--providers.nomad.endpoint.tls.caOptional=true

处理方法¶

从 Nomad 提供者的安装配置中移除 endpoint.tls.caOptional 选项。

Rancher v1 提供者¶

在 v3 中，Rancher v1 提供者已移除，因为 Rancher v1 已不再积极维护，而 Rancher v2 可通过标准 Kubernetes 提供者支持。

Traefik v2 的 Rancher v1 配置示例

文件 (YAML)

providers:
  rancher: {}

文件 (TOML)

[providers.rancher]

CLI

--providers.rancher=true

此配置已不受支持，会阻止 Traefik 启动。

处理方法¶

Rancher 2.x 依赖 Kubernetes，且没有自己的元数据端点供 Traefik 查询。因此，Rancher 2.x 用户应直接使用 Kubernetes CRD 提供者。

同时，从安装配置中移除所有 Rancher 提供者相关配置。

Marathon 提供者¶

Marathon 的维护已于2021年10月31日结束。在 v3 中，Marathon 提供者已移除。

v2 Marathon 提供者配置示例

文件 (YAML)

providers:
  marathon: {}

文件 (TOML)

[providers.marathon]

CLI

--providers.marathon=true

此配置已不受支持，会阻止 Traefik 启动。

处理方法¶

从安装配置中移除所有 Marathon 提供者相关配置。

HTTP 提供者¶

TLS.CAOptional¶

v3 移除了 HTTP 提供者的 tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  http:
    tls: 
      caOptional: true

文件 (TOML)

[providers.http.tls]
    caOptional=true

CLI

--providers.http.tls.caOptional=true

处理方法¶

从 HTTP 提供者的安装配置中移除 tls.caOptional 选项。

ETCD 提供者¶

TLS.CAOptional¶

v3 移除了 ETCD 提供者的 tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  etcd:
    tls: 
      caOptional: true

文件 (TOML)

[providers.etcd.tls]
    caOptional=true

CLI

--providers.etcd.tls.caOptional=true

处理方法¶

从 ETCD 提供者的安装配置中移除 tls.caOptional 选项。

Redis 提供者¶

TLS.CAOptional¶

v3 移除了 Redis 提供者的 tls.CAOptional 选项，因为 TLS 客户端身份验证是服务端选项，参见 https://pkg.go.dev/crypto/tls#ClientAuthType。

TLS.CAOptional 选项使用示例

文件 (YAML)

providers:
  redis:
    tls: 
      caOptional: true

文件 (TOML)

[providers.redis.tls]
    caOptional=true

CLI

--providers.redis.tls.caOptional=true

处理方法¶

从 Redis 提供者的安装配置中移除 tls.caOptional 选项。

InfluxDB v1¶

InfluxDB v1.x 的维护已于2021年结束。在 v3 中，InfluxDB v1 指标提供者已移除。

Traefik v2 的 InfluxDB v1 指标配置示例

文件 (YAML)

metrics:
  influxDB: {}

文件 (TOML)

[metrics.influxDB]

CLI

--metrics.influxDB=true

此配置已不受支持，会阻止 Traefik 启动。

处理方法¶

从安装配置中移除所有 InfluxDB v1 指标提供者相关配置。

Pilot¶

Traefik Pilot 自2022年10月4日起已不再提供。

v2 Pilot 配置示例

文件 (YAML)

pilot:
  token: foobar

文件 (TOML)

[pilot]
    token=foobar

CLI

--pilot.token=foobar

在 v2 中，Pilot 配置已经弃用且不再生效；现在已不受支持，会阻止 Traefik 启动。

处理方法¶

从安装配置中移除所有 Pilot 相关配置。

Kubernetes Ingress 路径匹配¶

在 v3 中，Kubernetes Ingress 默认路径匹配不再支持正则表达式。

处理方法¶

可以采用两种处理方式：

按照 v2 语法解释默认路径匹配器 PathPrefix。可以通过安装配置对全部路由器全局设置，也可以通过 traefik.ingress.kubernetes.io/router.rulesyntax 注解按路由器设置。
将路径正则表达式调整为 Go 正则语法兼容格式，并使用 traefik.ingress.kubernetes.io/router.pathmatcher 注解，将默认路径匹配器改为 PathRegexp。

运行行为变更¶

Traefik RBAC 更新¶

v3 引入了 TCPServersTransport 支持。因此，使用 KubernetesCRD 提供者时，需要更新 RBAC 和 CRD（参阅要求）。

Content-Type 自动检测¶

在 v3 中，后端未设置 Content-Type 响应头时，不再自动检测该响应头的值。应使用 ContentType 中间件启用 Content-Type 响应头值自动检测。

可观测性¶

打开连接数指标¶

在 v3 中，打开连接数指标改为全局指标，因为之前它错误地放在 HTTP 层级，提供的信息可能造成误导。原先在入口点、路由器和服务层级生成的指标，现在由一个全局指标取代。原来的 traefik_entrypoint_open_connections、traefik_router_open_connections 和 traefik_service_open_connections，现在对应 traefik_open_connections。

配置重载失败指标¶

在 v3 中，由于无法实现，traefik_config_reloads_failure_total 和 traefik_config_last_reload_failure 指标已移除。

gRPC 指标¶

在 v3 中，gRPC 请求报告的状态码改为 Grpc-Status 响应头的值。

追踪¶

在 v3 中，追踪功能经过重新设计，现在完全基于 OpenTelemetry（OTel）。

重要

Traefik v3 不再支持 Instana、Jaeger、Zipkin、Haystack、Datadog 和 Elastic 等特定供应商的直接输出格式。它转而专注于纯 OpenTelemetry 实现，为可观测性提供统一、标准化的方法。

有两种可用的过渡策略：

OTLP 接收端点：

大多数供应商如今都提供 OpenTelemetry Protocol（OTLP）接收端点。可以将 Traefik v3 接入这些端点，继续使用追踪能力。
旧有技术栈兼容：

对于无法立即升级到支持 OTLP 接收的最新供应商代理的旧技术栈，可以使用 OpenTelemetry（OTel）收集器，并配置适当的导出器。这样能够继续兼容现有基础设施。

更多信息请参阅 OpenTelemetry 追踪提供者文档。

内部资源可观测性¶

在 v3 中，内部路由器或服务（例如 ping@internal）的可观测性默认关闭。如需启用，使用 AccessLogs、Metrics 或 Tracing 新增的 addInternals 选项。更多信息请参阅可观测性文档：

访问日志¶

在 v3 中，ServiceURL 字段不再是对象，而是字符串形式。如果对访问日志建立索引，可能需要相应更新。

路由配置变更¶

路由器规则匹配器¶

在 v3 中，HTTP 和 TCP 路由器引入了新的规则匹配器语法。默认规则匹配器语法现为 v3，但为保持向后兼容，可以配置为其他语法。 v2 规则匹配器语法已弃用，并将在下一个主要版本移除。因此，我们建议迁移到新语法。

安装选项 defaultRuleSyntax 默认自动设为 v3，即使用新规则语法。

V3 新语法的主要变更¶

Headers 和 HeadersRegexp 匹配器分别重命名为 Header 和 HeaderRegexp。

PathPrefix 不再使用正则表达式匹配路径前缀。

Path 和 PathPrefix 不再支持路径参数占位符，例如 {id}、{name}。使用 Path(`/route/{id}`) 这类占位符的路由，在 v3 语法下不会匹配。动态路径片段应改用 PathRegexp。

新增 QueryRegexp，通过正则表达式匹配查询值。

HeaderRegexp、HostRegexp、PathRegexp、QueryRegexp 和 HostSNIRegexp 匹配器现在使用 Go 正则表达式语法。

所有匹配器现在只接受一个值，只有 Header、HeaderRegexp、Query 和 QueryRegexp 接受两个值。要复现之前的行为，应通过逻辑运算符显式组合匹配器。

Query 可以接受一个值，用于匹配没有值的查询参数，例如 /search?mobile。

HostHeader 已移除，请改用 Host。

处理方法¶

在安装配置中设置默认语法¶

默认规则匹配器语法适用于所有未主动覆盖此默认值的路由器。可以在安装配置中设置它。

默认规则匹配器语法配置示例

文件 (YAML)

# install configuration
core:
  defaultRuleSyntax: v2

文件 (TOML)

# install configuration
[core]
    defaultRuleSyntax="v2"

CLI

# install configuration
--core.defaultRuleSyntax=v2

按路由器配置语法¶

规则语法也可以为每个路由器单独配置，因此可以让不同路由器使用不同配置，便于迁移。

路由器语法配置示例

Docker 与 Swarm

labels:
  - "traefik.http.routers.test.ruleSyntax=v2"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test.route
  namespace: default

spec:
  routes:
    - match: PathPrefix(`/foo`, `/bar`)
      syntax: v2
      kind: Rule

Consul Catalog

- "traefik.http.routers.test.ruleSyntax=v2"

文件 (YAML)

http:
  routers:
    test:
      ruleSyntax: v2

文件 (TOML)

[http.routers]
  [http.routers.test]
    ruleSyntax = "v2"

将路径占位符迁移到 PathRegexp¶

在 v2 中，Path 和 PathPrefix 支持 {id} 等路径参数占位符，以匹配动态路径片段。在 v3 中，这已不受支持，应改用 PathRegexp。

迁移包含路径占位符的路由

v2 语法（在 v3 中不再生效）：

match: Host(`example.com`) && Path(`/products/{id}`)

使用 PathRegexp 的 v3 语法：

match: Host(`example.com`) && PathRegexp(`^/products/[^/]+$`)

对于包含多个占位符的复杂模式：

v2 语法：

match: Host(`example.com`) && Path(`/users/{userId}/orders/{orderId}`)

v3 语法：

match: Host(`example.com`) && PathRegexp(`^/users/[^/]+/orders/[^/]+$`) ## matches any non-slash characters
match: Host(`example.com`) && PathRegexp(`^/users/[a-zA-Z0-9_-]+/orders/[a-zA-Z0-9_-]+$`) ## restricts to alphanumeric, hyphens, and underscores

IPWhiteList¶

在 v3 中，IPWhiteList 中间件重命名为 IPAllowList，配置保持不变。

移除已弃用选项¶

tracing.datadog.globaltag 选项已移除。
ForwardAuth 中间件，以及 HTTP、Consul、Etcd、Redis、ZooKeeper、Consul Catalog 和 Docker 提供者中的 tls.caOptional 选项已移除。
Headers 中间件的 sslRedirect、sslTemporaryRedirect、sslHost、sslForceHost 和 featurePolicy 选项已移除。
StripPrefix 中间件的 forceSlash 选项已移除。
preferServerCipherSuites 选项已移除。

TCP LoadBalancer 的 `terminationDelay` 选项¶

TCP LoadBalancer 的 terminationDelay 选项已弃用。现在可以直接在 TCPServersTransport 层级配置，参见相关文档。

Kubernetes CRD API 组 `traefik.containo.us`¶

在 v3 中，Kubernetes CRD API 组 traefik.containo.us 已移除。请改用 API 组 traefik.io。

Kubernetes Ingress API 组 `networking.k8s.io/v1beta1`¶

在 v3 中，对 Kubernetes Ingress API 组 networking.k8s.io/v1beta1 的支持已移除；该 API 自 Kubernetes v1.22 起已移除。

请改用 API 组 networking.k8s.io/v1。

Traefik CRD API 版本 `apiextensions.k8s.io/v1beta1`¶

在 v3 中，对 Traefik CRD API 版本 apiextensions.k8s.io/v1beta1 的支持已移除；该 API 自 Kubernetes v1.22 起已移除。

请改用 API 版本为 apiextensions.k8s.io/v1 的 CRD 定义。

从 Traefik v2 迁移到 v3 的配置详情¶

安装配置变更¶

SwarmMode¶

处理方法¶

TLS.CAOptional¶

处理方法¶

Kubernetes Gateway API¶

实验通道资源（TLSRoute 和 TCPRoute）¶

处理方法¶

实验配置¶

HTTP3¶

处理方法¶

Consul 提供者¶

namespace¶

处理方法¶

TLS.CAOptional¶

处理方法¶

ConsulCatalog 提供者¶

namespace¶

处理方法¶

Endpoint.TLS.CAOptional¶

处理方法¶

Nomad 提供者¶

namespace¶

处理方法¶

Endpoint.TLS.CAOptional¶

处理方法¶

Rancher v1 提供者¶

处理方法¶

Marathon 提供者¶

处理方法¶

HTTP 提供者¶

TLS.CAOptional¶

处理方法¶

ETCD 提供者¶

TLS.CAOptional¶

处理方法¶

Redis 提供者¶

TLS.CAOptional¶

处理方法¶

InfluxDB v1¶

处理方法¶

Pilot¶

处理方法¶

Kubernetes Ingress 路径匹配¶

处理方法¶

运行行为变更¶

Traefik RBAC 更新¶

Content-Type 自动检测¶

可观测性¶

打开连接数指标¶

配置重载失败指标¶

gRPC 指标¶

追踪¶

内部资源可观测性¶

访问日志¶

路由配置变更¶

路由器规则匹配器¶

V3 新语法的主要变更¶

处理方法¶

在安装配置中设置默认语法¶

按路由器配置语法¶

将路径占位符迁移到 PathRegexp¶

IPWhiteList¶

移除已弃用选项¶

TCP LoadBalancer 的 terminationDelay 选项¶

Kubernetes CRD API 组 traefik.containo.us¶

Kubernetes Ingress API 组 networking.k8s.io/v1beta1¶

Traefik CRD API 版本 apiextensions.k8s.io/v1beta1¶

TCP LoadBalancer 的 `terminationDelay` 选项¶

Kubernetes CRD API 组 `traefik.containo.us`¶

Kubernetes Ingress API 组 `networking.k8s.io/v1beta1`¶

Traefik CRD API 版本 `apiextensions.k8s.io/v1beta1`¶