Traefik v3 版本迁移实战破坏性变更、配置迁移与源码级解析【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefikTraefik 自 v3 起在匹配器语义、Kubernetes Provider、安全默认值等方面经历了多次行为变更。本篇以仓库中 迁移指南 为主体完整梳理 v3.0 至 v3.8 各版本升级所需的迁移步骤并结合 Traefik 源码印证每一项变更的底层实现帮助你在升级任何两个 v3 小版本之间准确识别破坏性变更、补齐 RBAC/CRD并规避潜在的路径与头部安全风险。一、迁移指南的定位与覆盖范围migrate/v3.md 是 Traefik 官方的 v3 版本间迁移手册按版本号倒序组织每一节覆盖破坏性变更Breaking changes匹配器语义、默认值翻转等弃用Deprecations被标记 Deprecated 的配置项及其替代项配置迁移要求Kubernetes CRD/RBAC 更新命令、选项改名对照表。升级前建议先定位你当前版本与目标版本之间的所有小节逐项核对静态配置、动态配置与 Kubernetes 清单。下文按文档原始版本顺序完整展开并补充源码证据。二、v3.8.0peerCertURI弃用迁移到peerCertSANs从v3.8.0起ServersTransport与ServersTransportTCP中的peerCertURI选项被弃用将在下一个大版本移除。替代选项peerCertSANs支持多个SAN 匹配类型为URI或DNSName。在源码中可以直接看到弃用标记与替代字段ServersTransport 定义// Deprecated: PeerCertURI is deprecated, please use the PeerCertSANs option instead. PeerCertURI string ... json:peerCertURI,omitempty ... PeerCertSANs []traefiktls.SAN ... json:peerCertSANs,omitempty ...详细参数说明见 ServersTransport 与 ServersTransportTCP 文档。Kubernetes CRD Provider 迁移步骤若通过 CRD 使用peerCertSANs需要更新集群中的 CRD 定义kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.8/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml三、v3.7.7Host(*)通配符语义变为全匹配从v3.7.7起Host匹配器将裸*视为捕获一切catch-all与 TCP 的HostSNI(*)保持一致现在Host(*)匹配任意请求包括完全没有 Host 的请求此前*只当作单个通配标签Host(*)仅匹配单段主机名如localhost不匹配example.com。如果你的路由规则中曾依赖Host(*)只匹配单段主机名的旧语义升级后需显式改写规则。更多细节见 HTTP 路由规则。四、v3.7.6 / v3.6.22underscoreHeadersStrategy下划线头部处理策略从v3.6.20主干与v3.6.22维护线起新增入口点级选项underscoreHeadersStrategy定义路由前如何处理名称含下划线的请求头静态配置定义取值行为keep默认含下划线的请求头原样转发delete名称含下划线的请求头被静默删除reject携带此类请求头的请求直接以400 Bad Request拒绝默认值为keep保持既有行为不变。为什么需要该选项头伪装Header Smuggling风险下划线是合法的 HTTP 头名字符但 Go 只对连字符做头名规范化。因此管理连字符形式头部的中间件例如 ForwardAuth 的authResponseHeaders设置的X-Auth-User看不到下划线变体X_Auth_User也就无法覆盖或删除它。而很多后端CGI、WSGI、PHP、NGINX 等把两种形式映射到同一个变量。面对这类后端客户端可以把下划线变体混过只管理连字符形式的中间件让后端读到伪造值从而绕过中间件本应提供的保护。安全警告当入口点后面是“把下划线与连字符视为同一头部”的后端时不建议保留默认的keep策略应将该入口点设为delete或reject。参数文档见入口点 underscoreHeadersStrategy。五、v3.7.3 / v3.6.19Gateway 限流调优、BasicAuth 与 StripPrefix 行为收紧1. Kubernetes Gateway API ProviderQPS/Burst 提升v3.7.3主干与v3.6.19维护线起Gateway API provider 所用 Kubernetes client 的 QPS/Burst 提升到50/100Kubernetes client 默认值的 10 倍。原因是该 provider 为符合 Gateway API 规范会密集回写 status避免 API 限流拖慢新路由配置的构建。可通过kubernetesGateway.qps与kubernetesGateway.burst选项覆盖见 Kubernetes Gateway Provider 文档。2. BasicAuth 中间件要求非空 users从v3.7.3/v3.6.19起BasicAuth 中间件必须配置非空 users 才能构建成功。此前空配置时中间件构建成功但对任何请求恒返回401现在构建报错使用它的 router 会被卸载同样请求将得到404。源码印证BasicAuth 构建逻辑users, err : getUsers(authConfig.UsersFile, authConfig.Users, basicUserParser) ... if len(users) 0 { return nil, fmt.Errorf(no users found in %s, authConfig.UsersFile) }3. StripPrefix / StripPrefixRegex 拒绝未规范化路径同一版本起当剥离前缀后得到的路径与其规范化形式不一致含会被规范化折叠的.或..段时中间件直接返回400 Bad Request防止剥离后的路径被上游解释为另一资源参见 StripPrefix 中间件实现 与 StripPrefixRegex。以前缀/api为例请求路径剥离后规范化后结果/api/foo/foo/foo200转发/api///200转发/api./foo/./foo/foo400/api../foo/../foo/foo400六、v3.7.1 / v3.6.17crossProviderNamespaces限制跨 provider 引用v3.7.1主干与v3.6.17维护线为 Kubernetes CRD、Ingress、Gateway 三个 provider 新增crossProviderNamespaces选项。背景Traefik 允许跨 provider 引用资源如myservicekubernetescrd但在 Kubernetes 场景下这类引用可以跨越命名空间边界甚至暴露本应只有 operator 才能暴露的internal服务。新选项用于限制哪些命名空间中的资源允许声明跨 provider 引用取值行为未设置所有 Kubernetes 资源都可以声明跨 provider 引用[]任何声明跨 provider 引用的 Kubernetes 资源都被拒绝[ns-a]仅列出的命名空间中的资源可以声明跨 provider 引用该选项在三个 provider 中的落地实现可分别在 CRD provider、Ingress provider、Gateway provider 中查看。参数文档见 Kubernetes CRD、Kubernetes Ingress、Kubernetes Gateway。七、v3.7.0Ingress NGINX 自定义头、Gateway API v1.5.1 与通配符增强1. Ingress NGINX Provider 支持custom-headersv3.7.0起Ingress NGINX provider 支持nginx.ingress.kubernetes.io/custom-headers注解向转发给客户端的响应添加自定义头。因此其 RBAC见 KubernetesIngressNGINX provider RBAC中新增了configmaps权限... - apiGroups: - resources: - configmaps verbs: - list - watch ...2. Kubernetes Gateway API Provider 升级到 v1.5.1v3.7.0起Gateway API provider 支持规范 v1.5.1需要更新集群中的 Gateway API CRDkubectl 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关键变化TLSRoute已晋升 Standard 通道不再需要experimentalChannel选项现在只有TCPRoute需要experimentalChannel。3. Kubernetes CRD Provider 更新要使用retry中间件的新选项或新的ingressClassName字段需更新 CRDkubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml4. 通配符Host/HostSNI与 TLSOptions自v3.7.0起Host与HostSNI匹配器支持单层通配符子域名匹配如*.example.com*.example.com匹配foo.example.com但不匹配foo.bar.example.com也不匹配example.com本身。该能力仅在 v3 规则语法默认下可用。TLSOptions 现在可以关联到使用通配符Host/HostSNI匹配器的 router。此前 TLSOptions 选择仅限精确Host匹配使用HostRegexp或通配符时会回退到默认 TLS options 并产生类似No domain found in rule HostRegexp(...) the TLS option foo cannot be applied的警告。注意HostRegexp匹配器的 TLSOptions 仍不支持请改用通配符Host。八、v3.6.x 各维护版本变更要点v3.6.16Docker provider 最低 API 版本自v3.6.16起Docker provider 要求 Docker API v1.40 及以上对应 Docker Engine v19.03。运行更老已 EOLDocker Engine 的用户应升级 Engine或用DOCKER_API_VERSION环境变量覆盖 Traefik 使用的 API 版本。v3.6.15Errors 中间件errorRequestHeaders新增errorRequestHeaders选项。默认行为不变原始请求头全部转发给错误页服务若错误页服务处于不同信任域建议用它限制可转发的头。详见 Error Pages 文档。v3.6.14Chain 中间件遵循allowCrossNamespacetrustForwardHeader弃用Chain中间件现在遵循 Kubernetes CRD provider 的allowCrossNamespace若其为false默认而Chain引用了其他命名空间的中间件整个Chain被拒绝并记录错误日志。ForwardAuth 的trustForwardHeader被弃用下个大版本移除。应改为在入口点级用forwardedHeaders.trustedIPs配置可信 IP并显式将中间件的trustForwardHeader设为true。未显式设置时 Traefik 会记录警告——因为其旧行为不一致部分X-Forwarded-*头如X-Forwarded-For、X-Forwarded-Proto被移除而另一部分如X-Forwarded-Prefix原样转发。参数详见 ForwardAuth 文档。v3.6.9ForwardAuthmaxResponseBodySize新增maxResponseBodySize选项默认-1不限。强烈建议设置为合理值避免 DoS 与内存耗尽等性能/安全问题。CRD 用户需同步更新 CRD 才能使用kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml详见 ForwardAuth 文档。v3.6.8健康检查路径必须为相对 URL自v3.6.8起健康检查请求配置的 path 会被校验必须为相对 URL否则健康检查失败。v3.6.7 与 v3.6.4编码字符默认行为的两段演进v3.6.4起Traefik 默认拒绝请求路径中含特定编码字符的请求返回400 Bad Request编码字符字符允许该字符的配置项%2f/%2F/斜杠entryPoints.name.http.encodedCharacters.allowEncodedSlash%5c/%5C\反斜杠entryPoints.name.http.encodedCharacters.allowEncodedBackSlash%00NULLentryPoints.name.http.encodedCharacters.allowEncodedNullCharacter%3b/%3B;分号entryPoints.name.http.encodedCharacters.allowEncodedSemicolon%25%百分号entryPoints.name.http.encodedCharacters.allowEncodedPercent%3f/%3F?问号entryPoints.name.http.encodedCharacters.allowEncodedQuestionMark%23#井号entryPoints.name.http.encodedCharacters.allowEncodedHashv3.6.7起上述选项的默认值全部翻转为true即默认不再拒绝安全加固改为用户自行配置设为false才能禁用对应字符编码字符字符配置项默认值%2f/%2F/allowEncodedSlashtrue%5c/%5C\allowEncodedBackSlashtrue%00NULLallowEncodedNullCharactertrue%3b/%3B;allowEncodedSemicolontrue%25%allowEncodedPercenttrue%3f/%3F?allowEncodedQuestionMarktrue%23#allowEncodedHashtrue注意该校验只作用于按 RFC 3986 第 3 节定义的路径部分不检查查询参数。相关实现见 encodedCharacters 中间件参数文档见入口点 encodedCharacters。v3.6.2Ingress NGINX Provider 毕业KubernetesIngressNGINX provider 自 v3.6.2 起不再是实验特性无需experimental.kubernetesIngressNGINX选项。迁移步骤从实验段中删除kubernetesIngressNGINX选项按 kubernetesIngressNGINX Provider 文档 直接配置 provider。被弃用的旧配置形如# YAML experimental: kubernetesIngressNGINX: true# TOML [experimental] kubernetesIngressNGINXtrue# CLI --experimental.kubernetesIngressNGINXtrue九、v3.6.0Gateway API v1.4.0 与 leasttime 负载均衡Gateway API provider 仅支持规范 v1.4.0需更新 Gateway API CRDkubectl 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要在 CRD provider 中使用新的leasttime负载均衡算法需更新 CRDkubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml十、v3.5.x可观测性与协议变更v3.5.4OpenTelemetry 证书指标改名traefik_tls_certs_not_after_milliseconds改名为traefik_tls_certs_not_after_seconds使指标名与真实精度单位秒一致。v3.5.2TCP LoadBalancerproxyProtocol选项弃用该选项改为在TCPServersTransport级别配置详见 TCPServersTransport 文档。CRD 用户需更新 CRDkubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.5/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.ymlv3.5.0traceVerbosity与 K8s 资源属性入口点与 router 新增traceVerbosity选项控制 tracing span 粒度router 可覆盖入口点继承值minimal每个请求只产生一个 server span 和一个 client spandetailed为每个执行的中间件额外创建 span。影响依赖 tracing 的用户应显式设置期望的 verbosity既有配置默认落到minimalspan 数量会比以前少。文档见入口点与动态路由。启用 OTel tracing/logs/metrics 时自动注入 semconv 属性k8s.pod.name与k8s.pod.uid到 OTel 资源属性。需要为 Traefik 的 Kubernetes RBAC 增加 pods 的get权限... - apiGroups: - resources: - pods verbs: - get ...十一、v3.4.xMPTCP 移除与请求路径规范化v3.4.5MultiPath TCP 支持被移除v3.4.2引入的 MPTCP 支持在v3.4.5被移除因为在部分平台上启用 MPTCP 会导致 Traefik 停止并报错set tcp X.X.X.X:X-X.X.X.X:X: setsockopt: operation not supported如需重新启用可通过 Go 的GODEBUG环境变量设置multipathtcp变量见 Go 官方 GODEBUG 文档。v3.4.1请求路径规范化与保留字符处理自v3.4.1起请求路径按 RFC 3986 规范化非保留字符解码如%2E.解码为字面形式大小写规范化百分号编码字符统一大写%2e→%2E。处理顺序先路径规范化不可禁用后路径净化若启用。同时保留字符RFC 3986 2.2 节在路由匹配期间保持编码状态避免解码改变路径语义造成路由歧义。行为对照请求路径Router 规则Traefik v3.4.0Traefik v3.4.1说明/foo%2FbarPathPrefix(/foo/bar)匹配不匹配%2F/保持编码防止误匹配/foo/../barPathPrefix(/foo)不匹配不匹配路径穿越被净化掉/foo/../barPathPrefix(/bar)匹配匹配净化后解析为/bar/foo/%2E%2E/barPathPrefix(/foo)匹配不匹配编码点号先规范化再净化/foo/%2E%2E/barPathPrefix(/bar)不匹配匹配规范化 净化后解析为/bar十二、v3.3 → v3.4CRD 负载均衡策略、rootCAs 与规则语法弃用负载均衡策略更新v3.4 起 HTTP 服务定义支持新的负载均衡策略需更新 CRDkubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml新增策略值wrr加权轮询、p2cPower of Two Choices。弃用警告RoundRobin策略已弃用但仍受支持等价于wrr将在下一个大版本移除。详见 HTTP 服务负载均衡文档。rootCAs取代rootCAsSecretsServersTransport与ServersTransportTCPCRD 新增rootCAs选项同时支持 ConfigMap 与 Secret 存放 CA 证书替代旧的rootCAsSecrets# 更新 CRD kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.4/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml # 更新 RBAC 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-secretrootCAsSecrets仅 Secret仍受支持但已弃用将在下个大版本移除。规则语法选项弃用以下用于 v2→v3 语法过渡的选项将在下一个大版本移除core.defaultRuleSyntax静态配置ruleSyntaxrouter 选项。请确保所有 router 规则改用 v3 语法。十三、v3.3.x路径净化、压缩与指标v3.3.6请求路径净化sanitizePath自v3.3.6起请求路径在处理前自动净化折叠以下路径段/../父目录引用、/.//当前目录引用、重复斜杠//。可通过入口点 HTTP 配置关闭不推荐# EntryPoint HTTP 配置 entryPoints: web: address: :80 http: sanitizePath: false # 不推荐危险警告sanitizePath: false并不安全仅建议用于不能正确 URL 编码的遗留客户端正确做法是保证请求被正确 URL 编码。风险示例含/的 Base64 数据在禁用净化且未 URL 编码时可能导致不安全的路由。v3.3.5Compress 默认编码顺序默认压缩算法重排为gzip, br, zstd优先 gzip。影响未指定Accept-Encoding偏好、或偏好中无顺序的请求以兼容不支持新算法的旧客户端。v3.3.4OpenTelemetry 请求时长指标单位traefik_(entrypoint|router|service)_request_duration_seconds指标单位从毫秒统一为秒与其他 provider 及命名规范一致。十四、v3.2.x 与 v3.2 → v3.3v3.2 → v3.3ACME DNS 与 tracing 选项改名ACME DNS 挑战选项重组弃用选项新选项acme.dnsChallenge.delaybeforecheckacme.dnsChallenge.propagation.delayBeforeChecksacme.dnsChallenge.disablepropagationcheckacme.dnsChallenge.propagation.disableCheckstracing 配置改名tracing.globalAttributes→tracing.resourceAttributes旧名有误导——它实际是给 collector 添加资源属性而非全局 span 属性。v3.2.2Swarm provider 标签更新弃用标签新标签traefik.docker.networktraefik.swarm.networktraefik.docker.lbswarmtraefik.swarm.lbswarmv3.2.1X-Forwarded-Prefix头处理收紧自v3.2.1起X-Forwarded-Prefix与其他X-Forwarded-*头一致来自非可信来源时会被 Traefik 移除防止头伪装。配置见转发头文档。十五、v3.1 → v3.2CRD 新字段与 Gateway 通道演进CRD 新增可选字段向后兼容kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.3/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml涉及资源TraefikServicemirrorBodyPR #11032RateLimit 与 InFlightReq 中间件的sourceCriterion.ipStrategy.ipv6SubnetPR #9747Compress 中间件的encodingsPR #10943。Gateway Provider Standard 通道GRPCRoutev3.2 起 Gateway provider 支持GRPCRoute资源。需在对应 RBAC见 KubernetesGateway Provider 要求中补充grpcroutes与grpcroutes/status权限... - apiGroups: - gateway.networking.k8s.io resources: - grpcroutes verbs: - get - list - watch - apiGroups: - gateway.networking.k8s.io resources: - grpcroutes/status verbs: - update ...Gateway Provider Experimental 通道BackendTLSPolicyGateway API v1.2.0-rc1 有破坏性变更v3.3 仅在启用实验特性时支持 Gateway v1.2.x。新增BackendTLSPolicy支持RBAC 需补充configmaps、backendtlspolicies与backendtlspolicies/status权限... - 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.1disableIngressClassLookup弃用disableIngressClassLookup被弃用下个大版本移除替换为disableClusterScopeResources——后者对集群级资源发现提供更广的控制同时覆盖 IngressClass 与 Nodes 资源。十七、v3.0 → v3.1EndpointSlices、NodePort 与 Gateway 毕业Kubernetes Provider RBAC 变更自 v3.1 起所有 Kubernetes Provider 使用 EndpointSlices API要求 Kubernetes v1.21发现服务端点并引入 NodePort 负载均衡能力。RBAC 需更新# 移除这段 # - apiGroups: [] # resources: [endpoints] # verbs: [get, list, watch] # 替换为 - apiGroups: - discovery.k8s.io resources: - endpointslices verbs: - list - watch并新增 nodes 权限以支持 NodePort- apiGroups: - resources: - nodes verbs: - get - list - watch受影响 providerKubernetesIngress、KubernetesCRD、KubernetesGateway。KubernetesGateway Provider 毕业v3.1 起不再是实验特性移除experimental.kubernetesgateway选项后按 KubernetesGateway Provider 文档 配置即可。被弃用的旧配置# YAML experimental: kubernetesgateway: true# TOML [experimental] kubernetesgatewaytrue# CLI --experimental.kubernetesgatewaytrue十八、升级检查清单对齐版本区间确认当前与目标版本之间的所有小节如 3.4 → 3.8 需覆盖 v3.4.1、v3.4.5、v3.5.x、v3.6.x、v3.7.x、v3.8.0 全部条目。Kubernetes 环境先应用对应版本的 CRD 与 RBAC 清单每节均已给出kubectl apply -f命令再滚动升级核对 EndpointSlices、nodes、configmaps、grpcroutes、backendtlspolicies 等权限是否齐全。路由规则检查Host(*)语义变化v3.7.7、通配符与 TLSOptions 关联v3.7.0、路径规范化/净化行为v3.4.1、v3.3.6。中间件BasicAuth 非空 usersv3.6.19/v3.7.3、StripPrefix 的 400 行为同上、ForwardAuth 的trustForwardHeader与maxResponseBodySize。安全默认值按后端类型评估underscoreHeadersStrategyv3.6.22/v3.7.6与encodedCharactersv3.6.4/v3.6.7的加固设置。可观测性更新 Grafana/告警中依赖改名指标..._not_after_seconds、..._request_duration_seconds的查询并确认traceVerbosity级别。完成以上核对后即可在任意两个 v3 版本之间平滑升级。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
