迁移指南：从 v2 到 v3¶

如何从 Traefik v2 迁移到 Traefik v3。

Traefik v3 为从 v2 升级提供了更简洁的过渡流程。安装配置中只有少数特定选项发生不兼容变更，路由配置则保持对 v2 语法的向后兼容。因此可以逐步采用 v3 语法，将 Kubernetes Ingress 资源、Docker 标签等逐项迁移到新格式。

迁移概览¶

迁移由三个渐进步骤组成，旨在降低风险、平稳过渡：

步骤 1：准备配置并测试 v3¶

配置更新¶

检查并更新安装配置

检查 Traefik v3 带来的安装配置与运行行为变更，并相应调整配置。

启用 v2 兼容模式

加入以下配置，保持 v2 语法兼容：

# install configuration
core:
  defaultRuleSyntax: v2

测试阶段¶

启动测试环境

1. 使用更新后的配置启动 Traefik v3。
2. 检查启动日志中是否有错误。
3. 测试到应用的路由。

验证清单

• ✅ Traefik 启动时没有错误日志。
• ✅ 全部路由正常工作。
• ✅ 可以通过 Traefik 访问应用。

测试实例能够正常启动并将请求路由到应用后，进入下一步。

步骤 2：将生产实例迁移到 Traefik v3¶

迁移策略¶

渐进部署

强烈建议使用渐进迁移策略，将生产实例迁移到 v3，例如 Kubernetes 滚动更新机制。

必要准备

执行迁移¶

迁移期间：

1. 持续监控： 观察入口流量，检查错误或异常。
2. 准备回滚： 保持回滚流程随时可立即执行。
3. 使用调试日志： 利用调试日志和访问日志了解出现的问题。

验证步骤：

• 监控响应时间和错误率。
• 确认所有关键应用路径正常。
• 检查 SSL/TLS 终止是否正常。
• 验证中间件行为。

步骤 3：逐步迁移路由配置¶

迁移过程¶

检查路由配置变更

检查路由配置的变更，了解需要更新的内容。

逐步迁移路由器

1. 选择一个路由器先迁移，从非关键服务开始。
2. 为该路由器切换到 v3 语法。
3. 充分测试，确保入口流量不受影响。
4. 部署并验证更新后的资源。
5. 验证完成后，移除旧 v2 资源。
6. 对每个其余路由器重复执行。

迁移最佳实践¶

最终配置清理¶

所有 Ingress 资源迁移到 v3 语法后，移除兼容配置：

# Remove this from install configuration
core:
  defaultRuleSyntax: v2  # ← Delete this entire section

迁移后验证¶

最终清单：

• ✅ 所有路由器使用 v3 语法。
• ✅ 已关闭 v2 兼容模式。
• ✅ 日志中没有弃用警告。
• ✅ 所有应用正常工作。
• ✅ 性能指标稳定。