SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场traefik

traefik

部署与运维

查看项目

更新于 10-16 09:25

技能介绍

用途

Traefik Agent Skill 是一份用于部署、配置和维护 Traefik v3 反向代理与负载均衡器的综合参考。它面向 Traefik Proxy OSS，提供生产可用的 YAML 配置示例，帮助使用者理解并操作 Traefik 的各类核心功能。

主要能力

技能覆盖 Traefik 的主要功能领域，并按主题组织为参考文件：

  • 静态配置：首次设置 Traefik、添加 entryPoints、providers 或全局设置。
  • Docker Provider：为容器打标签进行路由、配置多网络、端口检测。
  • HTTP 路由：编写 Host/Path 匹配器、理解优先级、规则语法。
  • 中间件目录：添加认证、限流、请求头操作、路径重写、错误页面。
  • TLS 与 ACME：配置 Let's Encrypt、通配符证书、DNS-01/HTTP-01 挑战、mTLS。
  • TCP 与 UDP 路由：路由非 HTTP 流量、SNI 匹配、TCP 的 TLS 终止。
  • API 与仪表盘：保护仪表盘、API 端点、调试路由。
  • 可观测性：Prometheus/OTel 指标、访问日志、追踪、健康检查。
  • v2→v3 迁移：破坏性变更、规则语法更新、弃用选项。
  • 生产模式：Docker Compose 模板、安全加固、高可用、监控。
  • Servers Transport：后端连接配置、到后端的 mTLS、连接池、SPIFFE。
  • Kubernetes Providers：在 K8s 中部署 Traefik——Ingress、CRD（IngressRoute）、Gateway API。
  • 其他 Providers：ECS、Nomad、Consul Catalog、KV 存储、File、HTTP、REST providers。
  • 社区模式：生产经验——中间件顺序、性能调优、CDN 真实 IP、CrowdSec、Authelia、故障排查。
  • 运维审计：全栈审计方法——表面清单、配置审查、运行时状态、日志分析、分类框架。
  • CSP / SPA 调试：入口点请求头覆盖会静默破坏跨域 SPA——诊断流程、修复、CORS 预检拦截。
  • 插件与扩展：Yaegi 和 WASM 插件、插件配置、FastProxy。

使用方式

技能提供快速开始模板与脚本：

  • 生产可用的 Docker Compose 模板位于 templates/docker-compose.yml。
  • 一行健康检查命令：
    • bash scripts/traefik-healthcheck.sh（文本输出）
    • bash scripts/traefik-healthcheck.sh --json（供 agent 使用的 JSON 输出）

示例 docker-compose.yml 展示了通过 CLI 参数进行静态配置、端口映射、挂载 Docker socket，以及使用标签定义仪表盘路由、服务和 basic auth 中间件。

核心概念方面，Traefik 有两层配置：

  • 静态配置：启动时通过 YAML 文件、CLI 参数或环境变量设置，定义 entryPoints、providers、API、metrics、TLS resolvers。
  • 动态（路由）配置：运行时变化，通过 providers（Docker 标签、File provider YAML、Kubernetes CRD）定义。

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

适用场景

适用于使用 Traefik Proxy OSS 进行反向代理与负载均衡的部署、配置、迁移和故障排查，包括 Docker、Kubernetes 及其他 provider 环境下的路由、TLS、中间件和可观测性配置。

限制

技能明确说明不适用于以下情况：

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

常见陷阱（技能中列出）

  • 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 列表中的顺序即执行顺序。
  • File provider 路径：使用 providers.file.directory 时，Traefik 监视 .yml/.yaml/.toml 文件并按字母顺序合并。
  • 日志级别：仅排查问题时使用 DEBUG，生产环境极其冗长。
  • 规则中不接受单引号——使用反引号或转义双引号。

此外还包含若干深入陷阱说明：

  • traefik healthcheck 需要 ping entryPoint：除非静态配置中配置了 ping entryPoint，否则 traefik healthcheck CLI 命令返回“please enable ping to use health check”。不使用 ping 验证配置语法时，可用 python3 -c "import yaml; yaml.safe_load(open('config.yml'))" 检查 YAML 文件，或查看运行时 API http://localhost:8080/api/rawdata（若启用了不安全 API）。
  • 命名 Docker 卷需要 docker cp：配置位于命名卷而非绑定挂载时，无法直接在宿主机编辑文件，需用 docker cp 推送/拉取。静态配置变更需重启容器；动态配置变更由 file provider 监视器实时拾取。
  • 入口级中间件 + 路由级声明 = 双重执行：entryPoint 应用中间件且路由器也声明同一中间件时，中间件执行两次。症状包括限流计数翻倍、重复压缩浪费 CPU、调试日志混乱。诊断：查询运行时 API 检查路由器 middlewares 数组是否有重复。修复：从路由级声明中移除该中间件。
  • YAML 解析错误会丢弃整个 file provider：providers.file.directory 中单个文件有 YAML 解析错误时，Traefik 丢弃整个 provider 的配置。恢复：立即从备份恢复最后已知良好文件。预防：编辑前快照配置，增量部署动态配置变更，保留每个触碰文件的备份。
  • 限流破坏 SPA 页面加载（429 Too Many Requests）：现代 SPA 初始加载会发出 50–100+ JS chunk 请求，400 req/s 的限流会导致 429，产生黑屏。诊断：docker logs traefik | grep "429" | grep "/assets/"。修复：提高限制，例如 1000 avg / 1500 burst 和 100 concurrent。注意入口级应用的中间件无法按服务覆盖。
  • 入口级 headers 中间件覆盖路由级 CSP（静默破坏 SPA）：入口中间件在响应路径最后运行，headers 中间件会覆盖同名现有请求头。若入口链设置 contentSecurityPolicy，会覆盖任何路由级 CSP。诊断：curl -D- -o /dev/null https://your-spa/ | grep content-security-policy。修复：从入口默认链中移除 contentSecurityPolicy，让每个服务发出自己的 CSP。详见 references/csp-spa-debugging.md。