Traefik v3 配置参数详解

目标：详解 Traefik v3.7.14 的配置体系与常用参数。Traefik 采用「静态配置 + 动态配置」两级体系，本文档给出各配置段参数说明、真实默认值与生产配置模板，全部对照 Ubuntu 22.04 真实环境配置文件与 traefik --help 实测输出。

环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Traefik 版本：v3.7.14（Codename langres）
• 静态配置文件：/etc/traefik/traefik.yml
• 动态配置目录：/etc/traefik/dynamic
• 管理端口：:8080（API / Dashboard），入口 :80（web）、:443（websecure）
• 参考来源：traefik --help 完整输出（/tmp/traefik-exp/fullhelp.txt 实测）

前置条件

• 已按《Ubuntu 22.04 安装 Traefik 指南》完成安装
• 掌握 Traefik 两级配置概念：静态配置（启动加载）与动态配置（routing，provider 发现）

参数查看与修改方式

• 查看全部静态配置 flag 与默认值：

  traefik --help
  # 或对某子段精细查看
  traefik --help | grep -A3 "--providers.redis.endpoints"
  

• 查看当前运行状态（动态配置）：

  curl http://127.0.0.1:8080/api/rawdata
  curl http://127.0.0.1:8080/api/overview
  curl http://127.0.0.1:8080/api/version
  

• 查看静态配置加载日志（DEBUG 级别）：

  Static configuration loaded [json] staticConfiguration={"api":{...},"entryPoints":{...},"log":{...},"providers":{...}}
  

• 修改方式：编辑静态配置 /etc/traefik/traefik.yml 后重启 Traefik（系统重启或 systemctl restart traefik）；修改动态配置 /etc/traefik/dynamic/ 后自动热加载（需 providers.file.watch: true）。

参数总览

Traefik 配置分两级：

静态配置核心段：

一、entryPoints（流量入口）

每类入口决定 Traefik 监听哪些端口、走 HTTP/TCP/UDP。

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entrypoint:
          to: websecure
          scheme: https
          permanent: true
  websecure:
    address: ":443"
  traefik:
    address: ":8080"

💡 说明：named entryPoint 常用 web(80)、websecure(443)、traefik(8080)。traefik 这个内置名默认承载 API 与 ping。

二、providers（动态配置来源）

Provider 是 Traefik 发现路由/服务的来源。以下为常见 file 与 KV 类 provider 的真实默认值（traefik --help 实测）。

2.1 file provider

providers:
  file:
    directory: /etc/traefik/dynamic
    watch: true
    # 或 filename: /etc/traefik/dynamic.yml（单文件模式，与 directory 二选一）

2.2 redis / consul / etcd KV provider（集群共享配置）

💡 说明：KV provider 让多个 Traefik 实例共享同一份动态配置（详见《Traefik v3 Docker Compose 部署指南》集群模式）。多实例共享 Redis/Consul/etcd 即实现路由配置一致与互备。

2.3 docker provider

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false

三、api 与 Dashboard

api:
  dashboard: true
  insecure: true
  debug: false
  basepath: "/"

💡 说明：api.insecure: true 仅建议内网/调试使用；生产建议关闭 insecure 或以带 TLS 的独立域名暴露 Dashboard。

四、log 与 accesslog

4.1 运行日志 log

log:
  level: INFO
  filePath: ""
  # format: json

4.2 访问日志 accesslog

accesslog:
  filepath: ""
  format: common
  # 可按需过滤
  filters:
    statuscodes: "200-299"

五、ping（健康检查）

ping: true

💡 说明：开启后 GET /ping 返回 200 OK，供负载均衡/编排系统探活；也可用 traefik healthcheck 子命令调用。

六、metrics（指标采集）

metrics:
  prometheus:
    addEntryPointsLabels: true
    addServicesLabels: true

💡 说明：开启后 GET /metrics 输出 traefik_entrypoint_requests_total、traefik_service_requests_total、traefik_config_reloads_total、traefik_build_info、traefik_open_connections 等指标，可直接被 Prometheus 抓取。

七、certificatesresolvers（ACME 证书）

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      caserver: https://acme-staging-v02.api.letsencrypt.org/directory
      tlschallenge: true
      # 或 httpchallenge:
      #   entryPoint: web

💡 说明：caserver 默认是正式环境；实验/联调时改 acme-staging-v02 避免证书限额。无公网域名时 ACME 无法真正签发（日志显示 The ACME resolve is skipped）；按真实服务器配置公网域名 + 80/443 放通后即可自动签发。

八、global（全局能力）

生产配置模板

适用场景：16GB 内存、公网域名、反向代理 + 自动 HTTPS + 指标采集 + 集群共享配置。

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entrypoint:
          to: websecure
          scheme: https
          permanent: true
  websecure:
    address: ":443"

api:
  dashboard: true
  insecure: false     # 生产关闭 insecure，以证书保护

providers:
  file:
    directory: /etc/traefik/dynamic
    watch: true

log:
  level: INFO
  filePath: /var/log/traefik/traefik.log
  format: json

accesslog:
  filepath: /var/log/traefik/access.log

ping: true

metrics:
  prometheus:
    addEntryPointsLabels: true
    addServicesLabels: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /etc/traefik/acme.json
      tlschallenge: true

💡 说明：本模板面向「16GB 内存、SSD 磁盘、对外公网网关」场景：web 强制跳 HTTPS、Dashboard 关闭 insecure、日志落盘并走 json、开启 ping 探活与 Prometheus 指标、配 Let's Encrypt 自动证书。若为多实例高可用，将 providers.file 更换为共享 providers.redis/consul/etcd 即可（见部署篇集群模式）。

常见问题

Q1：API/Dashboard 无法访问 A：确认 api.insecure: true 且监听 :8080（api.basepath 默认 /）。生产关闭 insecure 后访问带 TLS 的域名需要额外路由。

Q2：动态配置不生效 A：确认 providers.file.watch: true 且文件放入 directory 指向目录；配 YAML 后可用 curl /api/rawdata 核对 routers/services 是否出现。

Q3：metrics 拿不到数据 A：确认 metrics.prometheus: true 且 GET /metrics 从 traefik 入口访问；addRoutersLabels 默认 false，需要时显式开启。

Q4：ACME 签发失败 A：确认公网域名已解析且 80/443 放通；caserver 指向正式环境；可用 staging caserver 联调，成功后再切正式。

参考链接

• 静态配置参考：https://doc.traefik.io/traefik/reference/static-configuration/file/
• 路由与动态配置：https://doc.traefik.io/traefik/routing/overview/
• ACME 证书：https://doc.traefik.io/traefik/https/acme/
• CLI 帮助：traefik --help（本机实测）