Traefik v2 到 v3 迁移完全指南:逐项解析 Install、Operations 与 Routing 配置变更
本文基于 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.swarmMode、providers.docker.tls.caOptionalproviders.consul.namespace、providers.consulCatalog.namespace、providers.nomad.namespace- 各 provider 的
tls.caOptional(Consul、ConsulCatalog、Nomad、ETCD、Redis、HTTP) providers.marathon、providers.rancherexperimental.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.go 中 Providers 结构体同时持有 Docker 与 Swarm 两个字段,而 docker.SwarmName("swarm")与 docker.DockerName("docker")分别定义在 pswarm.go 与 pdocker.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/tls 的 ClientAuthType),放在"连接远端的客户端"一侧的配置中语义上是错误的。弃用检查器对每一处都有对应的报错分支,例如 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)只保留了 insecureSkipVerify、rootCAs 与 spiffe 字段,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 资源(如 TCPRoute、TLSRoute)。需要显式开启 experimentalChannel 选项。源码中该字段定义为 gateway/kubernetes.go:ExperimentalChannel bool,描述为 "Toggles Experimental Channel resources support (TCPRoute, TLSRoute...)",并在初始化 client 时(client.experimentalChannel = p.ExperimentalChannel,L302)与监听器支持的路由 Kind 判定(supportedRouteKinds,L490)中生效。
# 开启实验通道资源支持
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 字段,现存的只有 plugins、localPlugins、fastProxy、otlplogs、knative 等。
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)不再支持正则。两条修复路径,可按需选用:
- 按 v2 语法解释默认路径匹配器:可全局在 install 配置中设置默认规则语法(见下文 Router Rule Matchers),也可对单个 Ingress 使用
traefik.ingress.kubernetes.io/router.rulesyntax注解(见 Ingress 注解文档); - 改造正则:将路径正则改写为 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.yml 与 kubernetes-crd-definition-v1.yml(后者已使用 apiextensions.k8s.io/v1)。
Content-Type 不再自动探测
v3 中,若后端未设置 Content-Type 请求头,Traefik 不再自动探测其值。如需恢复该行为,应显式使用 ContentType 中间件,参数说明见 ContentType 中间件文档。
Observability 变更
Open connections 指标改为全局指标。v2 中 traefik_entrypoint_open_connections、traefik_router_open_connections、traefik_service_open_connections 三个指标实际上错误地位于 HTTP 层级、信息有误导性;v3 将其统一替换为单个全局指标 traefik_open_connections。如果你有基于旧指标名的看板或告警规则(如 contrib/grafana/traefik.json、contrib/grafana/traefik-kubernetes.json 一类的 Grafana 面板),需要相应更新。
配置重载失败指标被移除。traefik_config_reloads_failure_total 与 traefik_config_last_reload_failure 两个指标在 v3 中被取消,因为它们无法被正确实现。
gRPC 指标状态码。v3 中 gRPC 请求上报的状态码改为取 Grpc-Status 头的值,监控中按 gRPC 状态码聚合的规则需要注意这一变化。
Tracing 全面转向 OpenTelemetry。v3 的 tracing 功能完全重构,仅由 OpenTelemetry(OTel)驱动,不再支持 Instana、Jaeger、Zipkin、Haystack、Datadog、Elastic 等厂商直出格式。这与源码一致:Tracing 结构体 中只保留 serviceName、resourceAttributes、capturedRequestHeaders、capturedResponseHeaders、safeQueryParams、sampleRate、addInternals 与 otlp 字段,而弃用检查器会为任何残留的 tracing.jaeger/tracing.zipkin/tracing.datadog/tracing.instana/tracing.haystack/tracing.elastic 配置报错并阻止启动(tracing.deprecationNotice)。两条迁移策略:
- OTLP 摄取端点:大多数厂商已提供 OTLP 摄取端点,可将 Traefik 的 OTLP 导出直接指向它们;
- OTel Collector 兼容旧栈:无法立即升级到支持 OTLP 的旧版 agent 时,可部署 OpenTelemetry Collector 并配置相应 exporter,向既有基础设施继续导出。
完整参数说明参考 Tracing 文档。
内部资源可观测性默认关闭。v3 中针对内部 router / service(例如 ping@internal)的 observability 默认禁用,如需开启,应在 AccessLog、Metrics 或 Tracing 配置中使用新增的 addInternals 选项(Tracing 侧字段见 static_config.go)。文档参考:AccessLogs、Metrics、Tracing。
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.go,SetDefaults 将其默认置为 "v3";ValidateConfiguration 只接受 v3 与 v2 两个取值(其它值直接报错),且在设为 v2 时输出 "v2 rules syntax is now deprecated" 警告。此外,该默认值还会传导给 Kubernetes Ingress provider:SetEffectiveConfiguration 中 c.Providers.KubernetesIngress.DefaultRuleSyntax = c.Core.DefaultRuleSyntax。
v3 新语法的重点变化:
Headers与HeadersRegexp分别改名为Header与HeaderRegexp;PathPrefix不再使用正则来匹配路径前缀;Path与PathPrefix不再支持路径参数占位符(如{id}、{name}),形如Path(/route/{id})的写在 v3 语法下不会匹配,动态路径段请改用PathRegexp;- 新增
QueryRegexp,可用正则匹配 query 值; HeaderRegexp、HostRegexp、PathRegexp、QueryRegexp、HostSNIRegexp统一采用 Go regexp 语法;- 所有匹配器只接受单个值(
Header、HeaderRegexp、Query、QueryRegexp除外,它们接受两个值),需要显式用逻辑运算符组合来模拟旧行为; Query可以只取一个值,匹配"存在但无值"的 query(如/search?mobile);HostHeader已移除,改用Host。
按 Router 配置语法
默认语法适用于所有未显式选择退出的 router。也可以在单个 router 上配置 ruleSyntax,实现异构共存、渐进迁移。动态配置结构中的 RuleSyntax 字段见 http_config.go 与 tcp_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.go 与 tcp/ipallowlist/ip_allowlist.go,参数说明见 IPAllowList 文档。
废弃选项移除清单
以下废弃选项在 v3 中被移除,需从动态路由配置中清理:
tracing.datadog.globaltag;tls.caOptional:从 ForwardAuth 中间件,以及 HTTP、Consul、Etcd、Redis、ZooKeeper、Consul Catalog、Docker provider 中移除;- Headers 中间件的
sslRedirect、sslTemporaryRedirect、sslHost、sslForceHost、featurePolicy(应使用stsIncludeSubdomains、stsPreload、stsSeconds及crossOrigin*等新选项,见 Headers 中间件文档); - StripPrefix 中间件的
forceSlash。
TCP LoadBalancer terminationDelay 迁移
TCP LoadBalancer 上的 terminationDelay 选项被废弃,改为直接配置在 TCPServersTransport 层级。v3 中该字段位于 TCPServersTransport 结构体:单位为毫秒,默认 100,负值表示无限延迟(即永不关闭读能力)。参数说明见 TCPServersTransport 文档。
Kubernetes:API Group 与 CRD 版本升级
三项与 Kubernetes 相关的兼容性移除,均指向使用新 API 版本:
- CRD API Group
traefik.containo.us已移除,请使用traefik.io(仓库内 CRD 样例 traefik.io_ingressroutes.yaml 均为新 group)。已有的traefik.containo.us资源需要重新 apply 为traefik.io版本; - Kubernetes Ingress API Group
networking.k8s.io/v1beta1支持已移除(该版本自 Kubernetes v1.22 起已被 K8s 官方删除),请使用networking.k8s.io/v1; - 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.io、networking.k8s.io/v1、apiextensions.k8s.io/v1,并更新 RBAC/CRD |
迁移完成后可删除临时兼容项 core.defaultRuleSyntax: v2,并以"启动无错误日志、路由全部生效、无废弃警告"作为验收标准。由于 v3 的弃用检查器会在启动时精确指出每一处不兼容配置(deprecation.go),逐条修复错误日志中的提示是最稳妥的实操路径。
atomcodeClaude Code 的开源替代方案。连接任意大模型,编辑代码,运行命令,自动验证 — 全自动执行。用 Rust 构建,极致性能。 | An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0622
Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家(MoE)旗舰模型。模型总参数量 770B,每个 token 激活 49B,主干共包含78层,第一层采用标准 FFN,其余 77 层均为 MoE 结构,每层包含 256 个路由专家与 1 个共享专家,每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP(总参数量 10B,激活 0.7B)以支持投机解码。Python00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比,它在复杂编程和长程任务上的表现显著提升。Jinja00
GLM-5.3-FlashGLM-5.3-Flash (320B-A18B),是GLM-5系列的首个原生多模态模型。320B总参数,能力超过GLM-5.2Jinja00
Spark-X2.5-4BSpark-X2.5-4B 旨在让强大的 AI 更实用、更高效、更易获得。在广泛日常任务中表现强劲,涵盖对话、写作、翻译、推理、编码、工具调用以及智能体工作流,并在同等规模的开源模型中取得领先成绩。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合,并支持 200 多种语言。Python00
Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色,涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流,并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合,并支持 200 多种语言。Python00