GeekIt

Traefik命令速查

启动与静态配置、EntryPoints、Provider 发现、Docker 标签、动态中间件、K8s CRD、TLS 证书、Dashboard API 与报错排查等 144 条命令

共 144 条命令 · 12 类场景 · 点击右侧图标可复制

命令 / 配置说明复制
traefik version查看 Traefik 版本,v2 与 v3 的 CRD 与中间件名有差异
traefik --help查看全部静态配置参数
traefik --configFile=/etc/traefik/traefik.yml指定静态配置文件启动
traefik --providers.docker --entryPoints.web.address=:80纯命令行启动,快速验证环境
traefik --providers.file.directory=/etc/traefik/dynamic --providers.file.watch=true文件动态配置 + 热加载,最易调试的组合
traefik healthcheck --ping健康检查(需开启 ping),容器编排探针常用
systemctl start traefiksystemd 部署方式启动
systemctl status traefik查看服务状态与启动失败原因
docker compose up -d traefik容器方式启动
ss -lntp | grep -E "80|443|8080"确认入口与 Dashboard 端口监听
tail -f /var/log/traefik/traefik.log主日志,配置加载失败与证书问题先看这里
配置优先级:命令行 > 环境变量 > 配置文件排查"改了没生效"时先看是否被更高优先级覆盖
命令 / 配置说明复制
entryPoints: web: address: ":80" websecure: address: ":443"定义入口点,所有流量都从 entryPoints 进入
providers: docker: {} file: directory: /etc/traefik/dynamic watch: true声明配置来源,可同时启用多个 Provider
api: dashboard: true insecure: false开启 Dashboard,生产不要用 insecure 暴露 8080
log: level: INFO filePath: /var/log/traefik/traefik.log日志级别与输出路径,排查时临时调 DEBUG
accessLog: filePath: /var/log/traefik/access.log format: json访问日志 JSON 格式,便于采集分析
--log.level=DEBUG命令行开启调试日志,观察配置构建过程
TRAEFIK_LOG_LEVEL=DEBUG环境变量方式覆盖配置,容器部署常用
traefik --configFile=traefik.yml --log.level=DEBUG命令行覆盖文件配置,快速排障
ping: entryPoint: traefik开启 /ping 健康检查入口
serversTransport: insecureSkipVerify: true跳过后端证书校验(仅测试环境)
静态配置改动必须重启进程watch 只对动态配置生效,traefik.yml 不会热加载
命令 / 配置说明复制
entryPoints: web: address: ":80"HTTP 入口点
entryPoints: websecure: address: ":443"HTTPS 入口点
entryPoints: web: asDefault: true设为默认入口点,未指定 entryPoints 的路由自动挂载
entryPoints: web: http: redirections: entryPoint: to: websecure scheme: httpsHTTP 全量跳转 HTTPS,最常见的入口配置
entryPoints: websecure: http: tls: {}入口点统一启用 TLS
entryPoints: web: http: middlewares: [security-headers@file]入口点级中间件,对所有路由生效
entryPoints: web: transport: respondingTimeouts: readTimeout: 60s调整读写超时,大文件上传下载场景必改
entryPoints: metrics: address: ":8082"单独开指标入口,避免暴露在业务入口
entryPoints: web: forwardedHeaders: insecure: true信任上游代理的 X-Forwarded-* 头,需确认边界
入口点不存在时路由不生效路由引用了未定义的 entryPoint 会被直接丢弃
命令 / 配置说明复制
providers: docker: endpoint: "unix:///var/run/docker.sock" exposedByDefault: falseDocker Provider:只暴露显式开启的容器
providers: docker: watch: true swarmMode: false监听容器变化自动更新路由
providers: docker: constraints: "Label(`env`, `prod`)"只发现带指定标签的容器,避免误暴露
providers: docker: defaultRule: "Host(`{{ normalize .Name }}.example.com`)"默认路由规则,减少逐个写标签
providers: kubernetesCRD: allowCrossNamespace: trueKubernetes CRD Provider,IngressRoute 方式
providers: kubernetesIngress: {}兼容原生 Ingress 注解方式
providers: file: filename: /etc/traefik/dynamic.yml单文件动态配置,适合手工维护少量路由
providers: consulCatalog: endpoint: { address: "10.0.0.20:8500" }从 Consul 服务目录自动发现后端
curl --unix-socket /var/run/docker.sock http://localhost/containers/json确认 Traefik 能访问 Docker socket
Docker socket 权限不足是容器部署最常见的故障检查 socket 挂载与容器用户权限
Provider 配置错误只体现在日志里Dashboard 看不到路由时先看 traefik.log 的 provider 报错
命令 / 配置说明复制
traefik.enable=true开启该容器的路由发现(exposedByDefault=false 时必需)
traefik.http.routers.app.rule=Host(`app.example.com`)路由匹配规则,支持 Host/Path/Headers/Method 组合
traefik.http.routers.app.rule=Host(`app.example.com`) && PathPrefix(`/api`)多条件组合,&& 表示同时满足
traefik.http.routers.app.entrypoints=websecure指定入口点,多个用逗号分隔
traefik.http.routers.app.tls.certresolver=le为该路由启用 ACME 自动证书
traefik.http.services.app.loadbalancer.server.port=8080后端端口,容器多端口时必须显式指定
traefik.http.routers.app.middlewares=auth@file,compress@file绑定中间件,带 @file/@docker 指定来源
traefik.http.routers.app.priority=100提升匹配优先级,解决规则冲突
traefik.http.routers.app.service=app-svc指定服务名,多路由共享同一后端
traefik.http.services.app.loadbalancer.healthcheck.path=/health主动健康检查路径
traefik.docker.network=traefik-net多网络时指定 Traefik 使用哪个网络访问容器
traefik.http.routers.app.rule=PathPrefix(`/`)路径兜底路由,注意优先级要低于具体规则
命令 / 配置说明复制
http: routers: app: rule: "Host(`app.example.com`)" service: app middlewares: [auth]file Provider 动态路由定义
http: services: app: loadBalancer: servers: - url: "http://10.0.0.21:8080"定义后端服务与服务器列表
http: middlewares: strip: stripPrefix: prefixes: ["/api"]剥离路径前缀,后端无需感知网关前缀
http: middlewares: add: addPrefix: prefix: "/v1"转发时补前缀
http: middlewares: redirect: redirectScheme: scheme: https permanent: true强制跳 HTTPS
http: middlewares: auth: basicAuth: usersFile: /etc/traefik/usersBasic Auth,用户文件由 htpasswd 生成
http: middlewares: fa: forwardAuth: address: "http://auth:9000/verify"转发鉴权到外部服务,统一登录常用
http: middlewares: headers: headers: stsSeconds: 31536000 contentTypeNosniff: true安全响应头统一注入
http: middlewares: rl: rateLimit: average: 100 burst: 50限流:平均速率与突发桶
http: middlewares: ip: ipAllowList: sourceRange: ["10.0.0.0/8"]IP 白名单(v3 用 ipAllowList)
http: middlewares: retry: retry: attempts: 3 initialInterval: 100ms失败重试,注意幂等性
http: middlewares: comp: compress: {}响应压缩
http: middlewares: chain: chain: middlewares: [headers, comp, retry]中间件链,复用一组组合
http: middlewares: err: errors: status: ["500-599"] service: errorpage自定义错误页,后端异常时兜底
动态文件保存即生效(watch=true)语法错误会导致整份配置被拒绝,日志有明确行号
命令 / 配置说明复制
apiVersion: traefik.io/v1alpha1 kind: IngressRoutev3 CRD 组为 traefik.io,v2 是 traefik.containo.us
kubectl apply -f ingressroute.yaml创建路由
kubectl get ingressroute -A查看所有 IngressRoute
kubectl describe ingressroute app -n prod查看状态与事件,路由不生效先看这里
kubectl get middleware -A查看 Middleware 资源
kubectl get tlsoption -A查看 TLS 选项(协议版本、加密套件)
kubectl get serversstransport -A查看后端传输参数
kubectl get traefikservice -A查看加权/镜像服务定义
traefik.ingress.kubernetes.io/router.entrypoints: websecure原生 Ingress 注解方式指定入口点
traefik.ingress.kubernetes.io/router.tls.certresolver: leIngress 注解启用自动证书
kubectl logs -l app.kubernetes.io/name=traefik -f查看 Traefik 日志,CRD 解析错误在这里
跨命名空间引用需 allowCrossNamespace: true否则 IngressRoute 引用其他 ns 的服务会失败
命令 / 配置说明复制
certificatesResolvers: le: acme: email: ops@example.com storage: /letsencrypt/acme.json httpChallenge: entryPoint: webACME HTTP-01 自动签发,需要 80 端口可达
certificatesResolvers: le: acme: dnsChallenge: provider: alidnsDNS-01 签发,泛域名必须用这种方式
certificatesResolvers: le: acme: tlsChallenge: {}TLS-ALPN-01 校验,只用 443 端口时可选
traefik.http.routers.app.tls.certresolver=le路由启用该解析器签发证书
tls: stores: default: defaultCertificate: certFile: /certs/tls.crt keyFile: /certs/tls.key配置默认自签证书,未匹配域名时兜底
tls: options: modern: minVersion: VersionTLS13强制 TLS 1.3,安全加固常用
tls: certificates: - certFile: /certs/app.crt keyFile: /certs/app.key手工加载证书(file Provider)
tls: stores: default: defaultGeneratedCert: resolver: le domain: { main: example.com }生成默认证书,避免无 SNI 请求报错
acme.json 权限必须是 600权限不对 Traefik 会拒绝写入,导致证书反复申请
openssl s_client -connect app.example.com:443 -servername app.example.com验证实际下发的证书与 SNI
证书申请失败看日志中的 ACME challenge 记录常见原因是 80 端口不可达或 DNS 解析未生效
命令 / 配置说明复制
api: dashboard: true开启 Dashboard,通过 api@internal 路由访问
traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) traefik.http.routers.dashboard.service=api@internal用标签暴露 Dashboard,务必加认证中间件
curl http://127.0.0.1:8080/api/overview查看全局概览:入口点、Provider、特性开关
curl http://127.0.0.1:8080/api/version查看版本与启动参数
curl http://127.0.0.1:8080/api/http/routers查看所有 HTTP 路由与状态
curl http://127.0.0.1:8080/api/http/services查看所有服务与后端服务器
curl http://127.0.0.1:8080/api/http/middlewares查看中间件定义
curl http://127.0.0.1:8080/api/rawdata导出全部动态配置,排障时最好用
curl http://127.0.0.1:8080/api/http/routers/app@docker按 名称@provider 精确查询单个对象
curl http://127.0.0.1:8080/ping健康检查(需开启 ping 配置)
api.insecure=true 只用于本地调试会无鉴权暴露全部配置,生产禁用
Dashboard 显示 router 为 disabled 时看错误提示通常是引用了不存在的中间件或服务
命令 / 配置说明复制
accessLog: filePath: /var/log/traefik/access.log format: json fields: headers: defaultMode: drop访问日志 JSON 化,控制敏感头输出
log: level: DEBUG调试日志,能看到路由匹配与配置构建细节
metrics: prometheus: entryPoint: metrics addServicesLabels: truePrometheus 指标,需指定专用入口点
curl http://127.0.0.1:8082/metrics | grep traefik_router抓取路由级请求与错误指标
metrics: prometheus: addEntryPointsLabels: true开启入口点维度标签
tracing: otlp: http: endpoint: http://otel-collector:4318v3 的 OpenTelemetry 追踪配置
tracing: serviceName: traefik-gateway设置服务名,便于链路检索
tail -f /var/log/traefik/access.log | jq '.RequestPath', '.DownstreamStatus'快速查看请求路径与状态码
grep " 502 " /var/log/traefik/access.log | tail筛出 502 请求定位后端问题
指标入口点要单独开放给 Prometheus不要挂在业务入口,避免被公网抓取
DEBUG 日志只临时开启高 QPS 下会显著增加磁盘与 CPU 开销
命令 / 配置说明复制
http: services: weighted: weighted: services: - name: app-v1 weight: 90 - name: app-v2 weight: 10加权服务:按比例把流量切到新版本
http: services: mirror: mirroring: service: app-v1 mirrorService: app-v2 mirrorBody: true流量镜像,把请求复制到新版本验证
http: services: fo: failover: service: app-primary fallback: app-backup故障转移服务,主服务不可用时切备用
http: services: app: loadBalancer: healthCheck: path: /health intervalSeconds: 10主动健康检查,自动剔除故障后端
traefik.http.services.app.loadbalancer.sticky.cookie.name=srv_id会话保持,粘性 Cookie
rateLimit 按来源 IP 限流average 与 burst 配合使用,避免误伤正常突发
inFlightReq 限制并发请求数保护后端不被瞬时并发打垮
circuitBreaker 表达式熔断按错误比例或网络错误触发,恢复后自动闭合
redirectRegex 做域名或路径迁移跳转迁移期兼容旧地址,注意避免循环跳转
多实例部署要共享 ACME 存储acme.json 不能多节点并发写,建议用分布式存储或独立签发
灰度先看指标再放量结合 5xx 比例与延迟决定是否继续扩大权重
命令 / 配置说明复制
404 page not found没有匹配的路由:检查 rule、entryPoints 与 host 是否一致
502 Bad Gateway后端不可达:容器端口写错、服务未起或网络不通
504 Gateway Timeout后端处理超时:调整 respondingTimeouts 或优化后端
too many redirects重定向循环:入口点与中间件重复配置了跳转
unable to obtain ACME certificate证书申请失败:80 端口不可达、DNS 未解析或速率限制
middleware "xxx@file" does not exist中间件名或 Provider 后缀写错,先查 /api/http/middlewares
router uses a non-existent entryPoint引用了未定义的入口点,路由被丢弃
error while building configuration动态配置文件语法错误,日志会给出行号
provider connection refused(docker.sock)socket 未挂载或权限不足
x509: certificate signed by unknown authority后端自签证书,配置 serversTransport 或安装 CA
TLS handshake error / no certificatesSNI 未匹配、证书未加载或 acme.json 权限错误
路由在 Dashboard 中显示 error看其错误信息,多为服务或中间件引用失败
修改 traefik.yml 不生效静态配置需重启进程,只有动态配置能热加载
容器已启动但没被 Traefik 发现检查 traefik.enable、exposedByDefault 与 constraints
多网络下 502指定 traefik.docker.network,确保与后端在同一网络
访问慢但后端正常查日志中的中间件耗时与 DNS 解析,必要时调 serversTransport

运维常用组合

本地调试traefik --configFile=traefik.yml --log.level=DEBUG → curl :8080/api/rawdata → 确认路由与中间件已加载
Docker 接入开启 exposedByDefault=false → 容器加 traefik.enable=true → 写 rule 与 server.port → Dashboard 确认 → curl 验证
HTTPS 上线certificatesResolvers 配置 ACME → 路由加 tls.certresolver → entryPoint 80 跳 443 → openssl 验证证书
灰度发布新建 v2 服务 → weighted 权重 10 → 观察 5xx 与延迟 → 逐步加到 100 → 下线 v1
安全加固headers 中间件 → ipAllowList 保护管理面 → rateLimit 限流 → 关闭 api.insecure → 收紧 accessLog 敏感头
故障排查Dashboard 看 router 状态 → /api/rawdata 核对配置 → access.log 查 5xx → traefik.log 看 provider/证书错误

常见问题排查

1. 先分清静态与动态

traefik.yml 属于静态配置,改动必须重启;路由、服务、中间件属于动态配置,可热加载

2. 404 先查路由匹配

rule 是否命中、entryPoints 是否正确、Dashboard 里 router 状态是否为 enabled

3. 502 先查后端端口

容器多端口时必须显式指定 loadbalancer.server.port,否则打到错误端口

4. 证书三要素

certresolver 名称一致、acme.json 权限 600、80 或 DNS 校验通道可达

5. 中间件要带 Provider 后缀

引用时写 auth@file、compress@docker,不加后缀会找不到

6. 多实例注意状态共享

ACME 存储与 Dashboard 鉴权要做统一,避免各实例证书与配置不一致

共 144 条 Traefik 命令 · 示例中的域名、容器名与路径请替换为实际环境

关于Traefik命令速查

在线 Traefik 命令速查手册,按安装与启动、静态配置 traefik.yml、EntryPoints 入口点、Provider 服务发现、Docker 标签路由、动态配置与中间件、Kubernetes CRD、TLS 与证书、Dashboard 与 API、日志指标与追踪、灰度限流与高可用、常见报错与排查等 12 类场景整理 150+ 条常用命令与配置,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 traefik version/--help/--configFile/healthcheck --ping 与命令行参数、systemd 与 docker compose 启动、80/443/8080 端口与 traefik.log/access.log、traefik.yml 的 entryPoints/web/websecure/asDefault/http.redirections/tls/middlewares/transport.respondingTimeouts/forwardedHeaders、providers 的 docker.endpoint/exposedByDefault/watch/constraints/defaultRule 与 kubernetesCRD/kubernetesIngress/file.watch/consulCatalog、日志 log.level/DEBUG/TRAEFIK_LOG_LEVEL/accessLog JSON、Docker 标签 traefik.enable/rule 的 Host 与 PathPrefix 组合/entrypoints/tls.certresolver/middlewares/priority/service/loadbalancer.server.port/healthcheck.path/docker.network、动态配置 http.routers/services/middlewares 的 stripPrefix/addPrefix/redirectScheme/basicAuth/forwardAuth/headers/rateLimit/ipAllowList/retry/compress/chain/errors、Kubernetes 的 IngressRoute/Middleware/TLSOption/ServersTransport/TraefikService 与 traefik.io/v1alpha1 与 Ingress 注解、certificatesResolvers 的 ACME httpChallenge/dnsChallenge/tlsChallenge 与 acme.json 权限 600 与 tls.stores 默认证书与 minVersion、Dashboard 与 /api/overview/version/rawdata/http routers services middlewares 与 /ping、metrics.prometheus 的 entryPoint/addServicesLabels 与 /metrics、tracing.otlp、weighted 加权灰度与 mirroring 镜像与 failover 与 healthCheck 与 sticky cookie、inFlightReq/circuitBreaker/redirectRegex,以及 404 page not found、502 Bad Gateway、504 Gateway Timeout、too many redirects、unable to obtain ACME certificate、middleware does not exist、non-existent entryPoint、error while building configuration、provider connection refused、x509 unknown authority、TLS handshake error 等报错排查。适用于 Traefik 云原生网关日常运维、Docker 与 Kubernetes 服务暴露、动态路由与中间件配置、ACME 自动证书与 mTLS、灰度发布与流量镜像、Dashboard 与 Prometheus 可观测性、静态与动态配置边界排查,以及网关运维与面试复习。

核心能力

  • 涵盖 traefik version/--help/--configFile/healthcheck --ping 与命令行参数、systemd 与 docker compose 启动、80/443/8080 端口与 traefik.log/access.log、traefik.yml 的 entryPoints/web/websecure/asDefault/http.redirections/tls/middlewares/transport.respondingTimeouts/forwardedHeaders、providers 的 docker.endpoint/exposedByDefault/watch/constraints/defaultRule 与 kubernetesCRD/kubernetesIngress/file.watch/consulCatalog、日志 log.level/DEBUG/TRAEFIK_LOG_LEVEL/accessLog JSON、Docker 标签 traefik.enable/rule 的 Host 与 PathPrefix 组合/entrypoints/tls.certresolver/middlewares/priority/service/loadbalancer.server.port/healthcheck.path/docker.network、动态配置 http.routers/services/middlewares 的 stripPrefix/addPrefix/redirectScheme/basicAuth/forwardAuth/headers/rateLimit/ipAllowList/retry/compress/chain/errors、Kubernetes 的 IngressRoute/Middleware/TLSOption/ServersTransport/TraefikService 与 traefik.io/v1alpha1 与 Ingress 注解、certificatesResolvers 的 ACME httpChallenge/dnsChallenge/tlsChallenge 与 acme.json 权限 600 与 tls.stores 默认证书与 minVersion、Dashboard 与 /api/overview/version/rawdata/http routers services middlewares 与 /ping、metrics.prometheus 的 entryPoint/addServicesLabels 与 /metrics、tracing.otlp、weighted 加权灰度与 mirroring 镜像与 failover 与 healthCheck 与 sticky cookie、inFlightReq/circuitBreaker/redirectRegex,以及 404 page not found、502 Bad Gateway、504 Gateway Timeout、too many redirects、unable to obtain ACME certificate、middleware does not exist、non-existent entryPoint、error while building configuration、provider connection refused、x509 unknown authority、TLS handshake error 等报错排查

适用场景

适用于 Traefik 云原生网关日常运维、Docker 与 Kubernetes 服务暴露、动态路由与中间件配置、ACME 自动证书与 mTLS、灰度发布与流量镜像、Dashboard 与 Prometheus 可观测性、静态与动态配置边界排查,以及网关运维与面试复习。Traefik命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Traefik命令速查是免费的吗?需要注册或安装吗?
Traefik命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Traefik命令速查支持哪些功能?
涵盖 traefik version/--help/--configFile/healthcheck --ping 与命令行参数、systemd 与 docker compose 启动、80/443/8080 端口与 traefik.log/access.log、traefik.yml 的 entryPoints/web/websecure/asDefault/http.redirections/tls/middlewares/transport.respondingTimeouts/forwardedHeaders、providers 的 docker.endpoint/exposedByDefault/watch/constraints/defaultRule 与 kubernetesCRD/kubernetesIngress/file.watch/consulCatalog、日志 log.level/DEBUG/TRAEFIK_LOG_LEVEL/accessLog JSON、Docker 标签 traefik.enable/rule 的 Host 与 PathPrefix 组合/entrypoints/tls.certresolver/middlewares/priority/service/loadbalancer.server.port/healthcheck.path/docker.network、动态配置 http.routers/services/middlewares 的 stripPrefix/addPrefix/redirectScheme/basicAuth/forwardAuth/headers/rateLimit/ipAllowList/retry/compress/chain/errors、Kubernetes 的 IngressRoute/Middleware/TLSOption/ServersTransport/TraefikService 与 traefik.io/v1alpha1 与 Ingress 注解、certificatesResolvers 的 ACME httpChallenge/dnsChallenge/tlsChallenge 与 acme.json 权限 600 与 tls.stores 默认证书与 minVersion、Dashboard 与 /api/overview/version/rawdata/http routers services middlewares 与 /ping、metrics.prometheus 的 entryPoint/addServicesLabels 与 /metrics、tracing.otlp、weighted 加权灰度与 mirroring 镜像与 failover 与 healthCheck 与 sticky cookie、inFlightReq/circuitBreaker/redirectRegex,以及 404 page not found、502 Bad Gateway、504 Gateway Timeout、too many redirects、unable to obtain ACME certificate、middleware does not exist、non-existent entryPoint、error while building configuration、provider connection refused、x509 unknown authority、TLS handshake error 等报错排查。
Traefik命令速查适合哪些场景使用?
适用于 Traefik 云原生网关日常运维、Docker 与 Kubernetes 服务暴露、动态路由与中间件配置、ACME 自动证书与 mTLS、灰度发布与流量镜像、Dashboard 与 Prometheus 可观测性、静态与动态配置边界排查,以及网关运维与面试复习。