traefik

Traefik Agent 技能

全面介绍如何部署、配置和维护 Traefik v3，将其用作反向代理和负载均衡器。本技能涵盖 Traefik Proxy OSS 的所有主要功能，并提供可用于生产环境的 YAML 配置示例。

快速开始 — 最小化 Docker 部署

可使用 templates/docker-compose.yml 中的 Docker Compose 模板进行生产环境部署。快速测试：

一行健康检查

bash scripts/traefik-healthcheck.sh           # Text output
bash scripts/traefik-healthcheck.sh --json    # JSON output for agents

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.7
    command:
      # Static configuration via CLI args
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--api.dashboard=true"
      - "--api.insecure=false"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    labels:
      # Dashboard router
      - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=auth"
      - "traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$10$$..."

核心概念

Traefik 有两个配置层：

• 静态配置 — 通过 YAML 文件、CLI 参数或环境变量在启动时设置。定义 entryPoints、providers、API、指标和 TLS 解析器。
• 动态（路由）配置 — 在运行时更改。由 providers 定义（Docker 标签、File provider YAML、Kubernetes CRD）。

请求流程：EntryPoint → Router → (Middlewares) → Service → Backend

参考文件

主题	适用场景	文件
静态配置	首次设置 Traefik、添加 entryPoints、providers 或全局设置时	references/static-configuration.md
Docker Provider	为容器添加路由标签、配置多个网络、检测端口时	references/docker-provider.md
HTTP 路由	编写 Host/Path 匹配器、了解优先级和规则语法时	references/http-routing.md
中间件目录	添加身份验证、速率限制、标头操作、路径重写和错误页面时	references/middleware-catalog.md
TLS 和 ACME	配置 Let's Encrypt、通配符证书、DNS-01/HTTP-01 挑战和 mTLS 时	references/tls-acme.md
TCP 和 UDP 路由	路由非 HTTP 流量、进行 SNI 匹配和 TCP TLS 终止时	references/tcp-routing.md
API 和仪表板	保护仪表板、使用 API 端点和调试路由时	references/api-dashboard.md
可观测性	使用 Prometheus/OTel 指标、访问日志、追踪和健康检查时	references/observability.md
v2→v3 迁移	处理重大变更、规则语法更新和已弃用选项时	references/migration-v2-to-v3.md
生产环境模式	使用 Docker Compose 模板、强化安全、实现高可用性和监控时	references/production-deployment.md
服务器传输	配置后端连接、与后端建立 mTLS、连接池和 SPIFFE 时	references/servers-transport.md
Kubernetes Providers	在 K8s 中部署 Traefik — Ingress、CRD（IngressRoute）、Gateway API	references/kubernetes-providers.md
其他 Providers	使用 ECS、Nomad、Consul Catalog、KV 存储、File、HTTP 和 REST providers 时	references/other-providers.md
社区实践	了解生产环境经验 — 中间件排序、性能调优、CDN 真实 IP、CrowdSec、Authelia 和故障排查	references/community-patterns.md
运维审计	进行全栈审计 — 面向面清单、配置审查、运行时状态、日志分析和分类框架	references/operational-audit.md
CSP / SPA 调试	入口点标头覆盖会悄然破坏跨域 SPA — 诊断流程、修复方案、CORS 预检拦截	references/csp-spa-debugging.md
插件和扩展	使用 Yaegi 和 WASM 插件、配置插件、使用 FastProxy 时	references/plugins-extend.md

常见问题**

• Traefik 连接到错误端口： 默认使用第一个暴露的端口。务必设置 traefik.http.services.<name>.loadbalancer.server.port=XXXX
• 标签不区分大小写，但资源名称应在同一个 compose 文件中保持一致
• 路由器、服务或中间件名称中不允许使用 @ 字符
• 仪表板未显示路由： 确认已启用 API（api.dashboard: true），并且使用的是 service=api@internal
• 未生成 ACME 证书： 检查 ACME 挑战所用的 entryPoint 是否可从互联网访问（HTTP-01 使用端口 80，TLS-ALPN-01 使用端口 443）
• Docker 网络： 如果容器连接到多个网络，请设置 traefik.docker.network=<name> 以选择正确的网络
• exposedByDefault=false 表示任何容器都不会获得路由，除非其带有 traefik.enable=true 标签
• 中间件顺序很重要： middlewares 列表中的顺序就是执行顺序
• 文件提供程序路径： 使用 providers.file.directory 时，Traefik 会监视 .yml/.yaml/.toml 文件，并按字母顺序合并
• 日志级别： 仅在排查问题时使用 DEBUG——在生产环境中它会生成极其详细的日志
• 规则中不接受单引号——请使用反引号 或转义后的双引号"`
• traefik healthcheck 需要配置 ping entryPoint： 如果静态配置中未配置 ping entryPoint，traefik healthcheck CLI 命令（以及 docker exec traefik traefik healthcheck）会返回“please enable ping to use health check”。若要在不启用 ping 的情况下验证配置语法，YAML 文件可使用 python3 -c "import yaml; yaml.safe_load(open('config.yml'))"，也可通过运行时 API http://localhost:8080/api/rawdata（如果已启用不安全 API）检查实时配置状态。
• 命名 Docker 卷需要使用 docker cp： 当 Traefik 的配置位于命名 Docker 卷中（而非绑定挂载）时，无法直接在主机上编辑文件。使用 docker cp <src> traefik:/etc/traefik/<dest> 将文件推送到容器中，并使用 docker cp traefik:/etc/traefik/<src> <dest> 拉取文件。静态配置更改（traefik.yml）需要重启容器；动态配置更改（dynamic/*.yml）则会通过文件提供程序监视器实时加载。
• entryPoint 级中间件 + 路由器级声明 = 执行两次： 当 entryPoint 应用中间件（例如 http.middlewares: [default@file]），而路由器也声明了相同的中间件时，该中间件会执行两次。表现为：速率限制计数翻倍、重复压缩浪费 CPU、调试日志令人困惑。诊断： 查询运行时 API（/api/rawdata），并检查路由器的 middlewares 数组是否存在重复项。修复： 从路由器级声明中移除该中间件——entryPoint 已经覆盖了它。只需要 entryPoint 中间件且不需要添加其他中间件的服务，可以完全省略 middlewares 字段。
• YAML 解析错误会导致整个文件提供程序失效： 当 providers.file.directory 中的某个文件出现 YAML 解析错误时，Traefik 会丢弃该提供程序的全部配置——该目录中所有文件的每个中间件、路由器和服务都会消失。明显迹象是：所有路由器都在同一时间出现大量 "middleware X does not exist" 错误。Python 的 yaml.safe_load() 并非充分的验证手段——Traefik 的解析器可能会拒绝 Python 解析器可以通过的文件（例如细微的缩进差异、尾随空格或类似模板变量的字符串）。恢复： 立即从备份还原最近一次可正常使用的文件（docker cp /tmp/backup.yml traefik:/etc/traefik/dynamic/config.yml）。预防： 编辑前务必备份配置，逐步部署动态配置更改（每次进行一项逻辑更改 → 通过冒烟测试验证 → 再进行下一项更改），并保留所有已编辑文件的备份。
• 速率限制会导致 SPA 页面加载失败（429 Too Many Requests）： 现代 SPA 在初次加载页面时会发起 50–100+ 个 JS 分块请求。400 req/s 的速率限制会让这些请求收到 429，从而导致浏览器窗口一片黑屏。诊断： docker logs traefik | grep "429" | grep "/assets/"——如果你在同一秒内看到大量针对 JS/CSS 资源的 429 响应，说明速率限制过低。修复： 提高限制。对于带有繁重 Web UI 的 homelab 部署，1000 avg / 1500 burst（速率限制）和 100 concurrent（inFlightReq）是合理的设置。请注意，应用于 entryPoint 的中间件无法按服务覆盖——如果不同服务需要不同限制，你必须提高全局限制，或者将中间件从 entryPoint 移至各个路由器。
• entryPoint 级 headers 中间件会覆盖路由器级 CSP（导致 SPA 悄无声息地故障）： entryPoint 中间件会在响应路径的最后阶段运行，并且 headers 中间件会覆盖名称相同的现有标头（文档）。当 entryPoint 链设置了 contentSecurityPolicy 时，它会覆盖任何路由器级 CSP——无法通过路由器进行覆盖。如果该 CSP 是通用配置（default-src 'self'，且没有 connect-src），浏览器就会阻止 SPA 发起的所有跨源 fetch/XHR 请求。明显迹象： SPA 页面和资源均已加载（200），但登录/API 调用没有反应，且后端日志中显示该客户端的请求数为 零。诊断： curl -D- -o /dev/null https://your-spa/ | grep content-security-policy——如果 SPA 页面带有严格的 CSP，请检查其来源是否为 entryPoint 中间件。修复： 从 entryPoint 默认链中移除 contentSecurityPolicy；让每个服务发送各自定制的 CSP。对于任何与其他源通信的 SPA，代理级的 default-src 'self' 都会造成实际危害。完整的诊断流程和 CORS 预检拦截模式请参阅 references/csp-spa-debugging.md。

不应使用此技能的情况

• 对于 Traefik Hub、Traefik Enterprise 或 Traefik Mesh——这些是具有不同 API 的独立产品
• 对于开发 Traefik 插件（Yaegi 或 WASM）——此技能涵盖的是使用已配置的插件，而非编写插件。有关插件开发，请参阅 https://plugins.traefik.io/create