首页
/ Traefik v2 到 v3 迁移完全指南:逐项解析 Install、Operations 与 Routing 配置变更

Traefik v2 到 v3 迁移完全指南:逐项解析 Install、Operations 与 Routing 配置变更

2026-09-04 09:36:09作者:温玫谨Lighthearted

本文基于 Traefik 官方迁移细节文档(v2-to-v3-details.md),系统梳理从 Traefik v2 升级到 v3 时所有会导致启动失败或行为变化的配置项:包括 install 配置中被移除的 provider 选项(swarmMode、tls.CAOptional、namespace、Pilot、Marathon、Rancher v1、InfluxDB v1)、observability 层的指标与 Tracing 重构,以及 routing 配置中规则匹配器语法的迁移方案,并结合仓库源码说明这些约束在代码中的真实落地位置,帮助你安全完成 v2 → v3 迁移。

迁移机制总览:v3 如何"强制"你改配置

理解所有变更之前,先理解 v3 的执行机制:被移除的选项不是静默忽略,而是会让 Traefik 拒绝启动。仓库中有一个专门的弃用检查加载器 DeprecationLoader,它在启动时依次扫描命令行参数、配置文件和环境变量,把配置展平为 label 形式后,与一份"已移除/已废弃选项清单"结构体做匹配;一旦命中不兼容项,即输出错误日志并返回 incompatible deprecated install configuration option found,阻止进程继续启动(见 logDeprecations)。

这份清单覆盖的移除项(见 deprecationNotice 实现)与本文后续各节一一对应:

  • pilot.*(Pilot 已于 2022-10-04 下线)
  • providers.docker.swarmModeproviders.docker.tls.caOptional
  • providers.consul.namespaceproviders.consulCatalog.namespaceproviders.nomad.namespace
  • 各 provider 的 tls.caOptional(Consul、ConsulCatalog、Nomad、ETCD、Redis、HTTP)
  • providers.marathonproviders.rancher
  • experimental.http3(v3 中 HTTP/3 已正式化,实验开关被移除)
  • Tracing 的各厂商后端 jaeger/zipkin/datadog/instana/haystack/elastic(v3 仅支持 OpenTelemetry)
  • tracing.spanNameLimit

因此在迁移第一步,建议直接用 v3 版本启动一次现有配置,利用该加载器的错误日志快速定位所有必须修改的项。

Install 配置变更(Install Configuration Changes)

Docker Swarm:swarmMode 被拆分出独立 Swarm Provider

v2 中 Docker provider 通过 swarmMode 开关同时承担普通容器与 Swarm 服务两种角色。v3 中将其拆分为两个独立 provider:Docker provider(不含 Swarm 支持)Swarm provider(仅支持 Swarm)swarmMode 选项被彻底移除。仓库源码可印证这一拆分:pkg/config/static/static_config.goProviders 结构体同时持有 DockerSwarm 两个字段,而 docker.SwarmName"swarm")与 docker.DockerName"docker")分别定义在 pswarm.gopdocker.go

v2 中的旧写法(v3 中不再支持,会导致启动失败):

# 文件(YAML)
providers:
  docker:
    swarmMode: true
# 文件(TOML)
[providers.docker]
    swarmMode=true
# CLI
--providers.docker.swarmMode=true

修复方式:移除 swarmMode,改用独立的 Swarm provider,并指定 Swarm endpoint。

# 文件(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

Swarm provider 的其余参数说明可参考 Swarm provider 文档

各 Provider 的 tls.CAOptional 统一移除

v2 中 Docker、Consul、ConsulCatalog、Nomad、ETCD、Redis、HTTP 等多个 provider 都提供 tls.caOptional 选项。v3 中全部移除,原因在于:TLS 客户端认证本质上是服务端选项(对应 Go 标准库 crypto/tlsClientAuthType),放在"连接远端的客户端"一侧的配置中语义上是错误的。弃用检查器对每一处都有对应的报错分支,例如 Docker provider 的 caOptional 检查

各 provider 的 v2 旧写法与修复方式一致——直接从 install 配置中删除该字段

# v2 旧写法(以 Docker provider 为例,v3 中已移除)
providers:
  docker:
    tls:
      caOptional: true
[providers.docker.tls]
    caOptional=true
--providers.docker.tls.caOptional=true

同样的处理适用于:

  • Consul:providers.consul.tls.caOptional(旧 CLI --providers.consul.tls.caOptional=true
  • ConsulCatalog:providers.consulCatalog.endpoint.tls.caOptional(旧 CLI --providers.consulCatalog.endpoint.tls.caOptional=true
  • Nomad:providers.nomad.endpoint.tls.caOptional(旧 CLI --providers.nomad.endpoint.tls.caOptional=true
  • ETCD:providers.etcd.tls.caOptional(旧 CLI --providers.etcd.tls.caOptional=true
  • Redis:providers.redis.tls.caOptional(旧 CLI --providers.redis.tls.caOptional=true
  • HTTP provider:providers.http.tls.caOptional(旧 CLI --providers.http.tls.caOptional=true

修复方式相同:从对应 provider 的 install 配置中删除 tls.caOptional(或 endpoint.tls.caOptional)字段即可。源码层面,当前的 TLSClientConfig 结构(static_config.go)只保留了 insecureSkipVerifyrootCAsspiffe 字段,CAOptional 已无对应字段可映射。

Consul / ConsulCatalog / Nomad:namespace 改为 namespaces 列表

三个 provider 的单数 namespace 选项在 v2 已被标记废弃,v3 中正式移除。v3 的 namespaces 是一个字符串列表,支持同时发现多个命名空间。以 Consul KV provider 为例,其 ProviderBuilder 源码(consul.go)持有 Namespaces []string 字段,并在 BuildProviders 中为每个 namespace 构建一个独立的 provider 实例,provider 名形如 consul-<namespace>;同时显式拒绝通配符 namespace(* 不支持)。

v2 旧写法(v3 中不再支持,会阻止启动):

consul:
  namespace: foobar
[consul]
    namespace=foobar
--consul.namespace=foobar

修复方式:使用 namespaces 列表选项。

consul:
  namespaces:
    - foobar
[consul]
    namespaces=["foobar"]
--consul.namespaces=foobar

ConsulCatalog 与 Nomad provider 做完全相同的替换:

# ConsulCatalog
consulCatalog:
  namespaces:
    - foobar
--consulCatalog.namespaces=foobar
# Nomad
nomad:
  namespaces:
    - foobar
--nomad.namespaces=foobar

对应的 TOML 写法分别为 namespaces=["foobar"]

Kubernetes Gateway API:实验通道资源默认关闭

v3 中 Kubernetes Gateway API provider 默认不再启用实验通道(experimental channel)的 API 资源(如 TCPRouteTLSRoute)。需要显式开启 experimentalChannel 选项。源码中该字段定义为 gateway/kubernetes.goExperimentalChannel bool,描述为 "Toggles Experimental Channel resources support (TCPRoute, TLSRoute...)",并在初始化 client 时(client.experimentalChannel = p.ExperimentalChannelL302)与监听器支持的路由 Kind 判定(supportedRouteKindsL490)中生效。

# 开启实验通道资源支持
providers:
  kubernetesGateway:
    experimentalChannel: true
[providers.kubernetesGateway]
    experimentalChannel = true
      # ...
--providers.kubernetesgateway.experimentalchannel=true

实验配置:experimental.http3 移除

v3 中 HTTP/3 不再是实验特性:可以直接在 entrypoint 上启用,不再需要(也不再允许)experimental.http3 开关。该开关在 v3 中已移除,继续配置会阻止 Traefik 启动——弃用检查器中有专门的报错分支(experimental.deprecationNotice),提示 "HTTP3 is not an experimental feature in v3 and the associated enablement has been removed"。源码层面,Experimental 结构体(experimental.go)中已无任何 http3 字段,现存的只有 pluginslocalPluginsfastProxyotlplogsknative 等。

v2 旧写法(v3 中不再支持):

experimental:
  http3: true
[experimental]
    http3=true
--experimental.http3=true

修复方式:删除 experimental.http3,改为在对应 entrypoint 下配置 http3 字段。entrypoint 的 HTTP3 字段见 entrypoints.go,具体参数说明参考 entrypoint 文档的 HTTP/3 一节

Rancher v1 Provider 移除

v3 移除了 Rancher v1 provider,原因是 Rancher v1 已停止积极维护;Rancher v2 基于 Kubernetes,可直接用 Kubernetes provider 支持。v2 中的如下写法在 v3 中会导致启动失败:

providers:
  rancher: {}
[providers.rancher]
--providers.rancher=true

修复方式:Rancher 2.x 自身没有可供 Traefik 查询的 metadata endpoint,应直接使用 Kubernetes CRD provider,并删除所有 Rancher 相关配置。这也与 v3 的 provider 白名单一致——providerNames 列表中不存在 rancher,且 ValidateConfiguration 会对 precedence 中出现的未知 provider 名直接报错。

Marathon Provider 移除

Marathon 已于 2021-10-31 结束维护,v3 中移除其 provider。以下 v2 写法不再支持,需从 install 配置中全部删除:

providers:
  marathon: {}
[providers.marathon]
--providers.marathon=true

InfluxDB v1 指标移除

InfluxDB v1.x 维护已于 2021 年结束,v3 移除 InfluxDB v1 metrics 后端。以下 v2 写法不再支持:

metrics:
  influxDB: {}
[metrics.influxDB]
--metrics.influxDB=true

修复方式:删除所有 InfluxDB v1 相关 metrics 配置,可迁移到 Prometheus 或 OTLP 指标导出等 v3 支持的方案(见 metrics 文档)。

Pilot 移除

Traefik Pilot 自 2022-10-04 起不再提供服务,v2 中其配置已是废弃且无效状态,v3 中正式移除。以下配置会阻止启动:

pilot:
  token: foobar
[pilot]
    token=foobar
--pilot.token=foobar

修复方式:删除所有 Pilot 相关配置。

Kubernetes Ingress 路径匹配不再支持正则

v3 中 Kubernetes Ingress 的默认路径匹配(PathPrefix不再支持正则。两条修复路径,可按需选用:

  1. 按 v2 语法解释默认路径匹配器:可全局在 install 配置中设置默认规则语法(见下文 Router Rule Matchers),也可对单个 Ingress 使用 traefik.ingress.kubernetes.io/router.rulesyntax 注解(见 Ingress 注解文档);
  2. 改造正则:将路径正则改写为 Go 正则语法,并把默认路径匹配器改为 PathRegexp,通过 traefik.ingress.kubernetes.io/router.pathmatcher 注解指定。

Operations 变更(Operations Changes)

Traefik RBAC 与 CRD 更新

v3 引入了 TCPServersTransport 支持。使用 Kubernetes CRD provider 时,必须同步更新 RBAC 与 CRD 定义,具体要求见 Kubernetes CRD 文档的 Requirements 一节。仓库内可直接查看到新版 RBAC 与 CRD 样例:kubernetes-crd-rbac.ymlkubernetes-crd-definition-v1.yml(后者已使用 apiextensions.k8s.io/v1)。

Content-Type 不再自动探测

v3 中,若后端未设置 Content-Type 请求头,Traefik 不再自动探测其值。如需恢复该行为,应显式使用 ContentType 中间件,参数说明见 ContentType 中间件文档

Observability 变更

Open connections 指标改为全局指标。v2 中 traefik_entrypoint_open_connectionstraefik_router_open_connectionstraefik_service_open_connections 三个指标实际上错误地位于 HTTP 层级、信息有误导性;v3 将其统一替换为单个全局指标 traefik_open_connections。如果你有基于旧指标名的看板或告警规则(如 contrib/grafana/traefik.jsoncontrib/grafana/traefik-kubernetes.json 一类的 Grafana 面板),需要相应更新。

配置重载失败指标被移除traefik_config_reloads_failure_totaltraefik_config_last_reload_failure 两个指标在 v3 中被取消,因为它们无法被正确实现。

gRPC 指标状态码。v3 中 gRPC 请求上报的状态码改为取 Grpc-Status 头的值,监控中按 gRPC 状态码聚合的规则需要注意这一变化。

Tracing 全面转向 OpenTelemetry。v3 的 tracing 功能完全重构,仅由 OpenTelemetry(OTel)驱动,不再支持 Instana、Jaeger、Zipkin、Haystack、Datadog、Elastic 等厂商直出格式。这与源码一致:Tracing 结构体 中只保留 serviceNameresourceAttributescapturedRequestHeaderscapturedResponseHeaderssafeQueryParamssampleRateaddInternalsotlp 字段,而弃用检查器会为任何残留的 tracing.jaeger/tracing.zipkin/tracing.datadog/tracing.instana/tracing.haystack/tracing.elastic 配置报错并阻止启动(tracing.deprecationNotice)。两条迁移策略:

  1. OTLP 摄取端点:大多数厂商已提供 OTLP 摄取端点,可将 Traefik 的 OTLP 导出直接指向它们;
  2. OTel Collector 兼容旧栈:无法立即升级到支持 OTLP 的旧版 agent 时,可部署 OpenTelemetry Collector 并配置相应 exporter,向既有基础设施继续导出。

完整参数说明参考 Tracing 文档

内部资源可观测性默认关闭。v3 中针对内部 router / service(例如 ping@internal)的 observability 默认禁用,如需开启,应在 AccessLog、Metrics 或 Tracing 配置中使用新增的 addInternals 选项(Tracing 侧字段见 static_config.go)。文档参考:AccessLogsMetricsTracing

Access log 的 ServiceURL 字段结构变化。v3 中 access log 的 ServiceURL 字段不再是对象,而是字符串表示。如果你的日志索引/采集流程依赖旧的对象结构,需要更新解析规则。

Routing 配置变更(Routing Configuration Changes)

Router Rule Matchers:v3 新匹配器语法

v3 为 HTTP 与 TCP router 引入了新的规则匹配器语法,默认语法为 v3;v2 语法仍受支持但已废弃,并将在下一个大版本移除。默认值可在 install 配置中调整:

# install 配置
core:
  defaultRuleSyntax: v2
# install 配置
[core]
    defaultRuleSyntax="v2"
# install 配置
--core.defaultRuleSyntax=v2

源码印证:Core 结构体的 DefaultRuleSyntax 字段定义在 static_config.goSetDefaults 将其默认置为 "v3"ValidateConfiguration 只接受 v3v2 两个取值(其它值直接报错),且在设为 v2 时输出 "v2 rules syntax is now deprecated" 警告。此外,该默认值还会传导给 Kubernetes Ingress provider:SetEffectiveConfigurationc.Providers.KubernetesIngress.DefaultRuleSyntax = c.Core.DefaultRuleSyntax

v3 新语法的重点变化

  • HeadersHeadersRegexp 分别改名为 HeaderHeaderRegexp
  • PathPrefix 不再使用正则来匹配路径前缀;
  • PathPathPrefix 不再支持路径参数占位符(如 {id}{name}),形如 Path(/route/{id}) 的写在 v3 语法下不会匹配,动态路径段请改用 PathRegexp
  • 新增 QueryRegexp,可用正则匹配 query 值;
  • HeaderRegexpHostRegexpPathRegexpQueryRegexpHostSNIRegexp 统一采用 Go regexp 语法;
  • 所有匹配器只接受单个值(HeaderHeaderRegexpQueryQueryRegexp 除外,它们接受两个值),需要显式用逻辑运算符组合来模拟旧行为;
  • Query 可以只取一个值,匹配"存在但无值"的 query(如 /search?mobile);
  • HostHeader 已移除,改用 Host

按 Router 配置语法

默认语法适用于所有未显式选择退出的 router。也可以在单个 router 上配置 ruleSyntax,实现异构共存、渐进迁移。动态配置结构中的 RuleSyntax 字段见 http_config.gotcp_config.go

# Docker & Swarm(label)
labels:
  - "traefik.http.routers.test.ruleSyntax=v2"
# Kubernetes(CRD)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test.route
  namespace: default

spec:
  routes:
    - match: PathPrefix(`/foo`, `/bar`)
      syntax: v2
      kind: Rule
# Consul Catalog(key 值)
- "traefik.http.routers.test.ruleSyntax=v2"
# 文件 provider(YAML)
http:
  routers:
    test:
      ruleSyntax: v2
# 文件 provider(TOML)
[http.routers]
  [http.routers.test]
    ruleSyntax = "v2"

路径占位符迁移到 PathRegexp

v2 中 Path/PathPrefix 支持 {id} 这类占位符匹配动态段,v3 不再支持,需要改为 PathRegexp

v2 语法(v3 中不再工作):

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

v3 语法(使用 PathRegexp):

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

多个占位符的更复杂场景:

v2 语法:

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

v3 语法:

match: Host(`example.com`) && PathRegexp(`^/users/[^/]+/orders/[^/]+$`) ## 匹配任意非斜杠字符
match: Host(`example.com`) && PathRegexp(`^/users/[a-zA-Z0-9_-]+/orders/[a-zA-Z0-9_-]+$`) ## 限制为字母、数字、连字符、下划线

IPWhiteList 中间件改名为 IPAllowList

v3 将 IPWhiteList 中间件改名为 IPAllowList配置项本身没有任何变化。仓库中 HTTP 与 TCP 两侧的新中间件分别位于 ipallowlist/ip_allowlist.gotcp/ipallowlist/ip_allowlist.go,参数说明见 IPAllowList 文档

废弃选项移除清单

以下废弃选项在 v3 中被移除,需从动态路由配置中清理:

  • tracing.datadog.globaltag
  • tls.caOptional:从 ForwardAuth 中间件,以及 HTTP、Consul、Etcd、Redis、ZooKeeper、Consul Catalog、Docker provider 中移除;
  • Headers 中间件的 sslRedirectsslTemporaryRedirectsslHostsslForceHostfeaturePolicy(应使用 stsIncludeSubdomainsstsPreloadstsSecondscrossOrigin* 等新选项,见 Headers 中间件文档);
  • StripPrefix 中间件的 forceSlash

TCP LoadBalancer terminationDelay 迁移

TCP LoadBalancer 上的 terminationDelay 选项被废弃,改为直接配置在 TCPServersTransport 层级。v3 中该字段位于 TCPServersTransport 结构体:单位为毫秒,默认 100,负值表示无限延迟(即永不关闭读能力)。参数说明见 TCPServersTransport 文档

Kubernetes:API Group 与 CRD 版本升级

三项与 Kubernetes 相关的兼容性移除,均指向使用新 API 版本:

  1. CRD API Group traefik.containo.us 已移除,请使用 traefik.io(仓库内 CRD 样例 traefik.io_ingressroutes.yaml 均为新 group)。已有的 traefik.containo.us 资源需要重新 apply 为 traefik.io 版本;
  2. Kubernetes Ingress API Group networking.k8s.io/v1beta1 支持已移除(该版本自 Kubernetes v1.22 起已被 K8s 官方删除),请使用 networking.k8s.io/v1
  3. Traefik CRD 的 apiextensions.k8s.io/v1beta1 支持已移除(同样自 Kubernetes v1.22 起被 K8s 移除),CRD 定义必须使用 apiextensions.k8s.io/v1 版本。

迁移核查清单

结合官方三步迁移流程(准备与测试 → 生产实例升级 → 渐进迁移路由配置,见 迁移总览文档),在动手前可用本清单逐项核查:

检查项 变更 修复动作
providers.docker.swarmMode 移除,Docker/Swarm provider 拆分 改用 providers.swarm.endpoint
各 provider tls.caOptional 移除(Docker/Consul/ConsulCatalog/Nomad/ETCD/Redis/HTTP) 删除该字段
Consul/ConsulCatalog/Nomad namespace 移除 改用 namespaces 列表
Gateway API 实验通道 默认关闭 显式设 experimentalChannel: true
experimental.http3 移除,HTTP/3 正式化 在 entrypoint 配置 http3
Rancher v1 / Marathon provider 整体移除 删除配置;Rancher 2.x 用 K8s CRD provider
InfluxDB v1 metrics / Pilot 移除 删除相关配置
tracing.<vendor> 各厂商后端 移除,仅留 OTel 走 OTLP 端点或 OTel Collector
open connections 指标 三个层级指标合并为全局 traefik_open_connections 更新看板/告警
access log ServiceURL 对象变字符串 更新日志索引解析
规则匹配器 v3 语法为默认 全局 core.defaultRuleSyntax 或逐 router ruleSyntax
路径占位符 {id} v3 语法下不匹配 改写为 PathRegexp
IPWhiteList 改名 改用 IPAllowList(配置不变)
Headers/StripPrefix 等废弃选项 移除 按上文清单清理
TCP LB terminationDelay 上移至 transport 层 配到 TCPServersTransport
K8s traefik.containo.us / Ingress v1beta1 / CRD v1beta1 移除 使用 traefik.ionetworking.k8s.io/v1apiextensions.k8s.io/v1,并更新 RBAC/CRD

迁移完成后可删除临时兼容项 core.defaultRuleSyntax: v2,并以"启动无错误日志、路由全部生效、无废弃警告"作为验收标准。由于 v3 的弃用检查器会在启动时精确指出每一处不兼容配置(deprecation.go),逐条修复错误日志中的提示是最稳妥的实操路径。

登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库,实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库,实现网络在NPU上加速计算。
C++
904
1.82 K
docsdocs
暂无描述
Markdown
889
5.78 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件,TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件,使 PyTorch 框架能够直接调用昇腾 NPU,为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
kernelkernel
openEuler内核是openEuler操作系统的核心,既是系统性能与稳定性的基石,也是连接处理器、设备与服务的桥梁。
C
527
590
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent,它能够将大语言模型的强大能力,通过你日常使用的各类通讯应用,直接延伸至你的指尖。
Python
3.52 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库,实现网络在NPU上加速计算。
C++
1.33 K
1.45 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR(Multi-Level Intermediate Representation)构建的,面向昇腾亲和算子编译时使用的中间表示,提供昇腾完备表达能力,通过编译优化提升昇腾AI处理器计算效率,支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384
flutter_flutterflutter_flutter
本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本,由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用,3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。
Dart
1.17 K
341