1. 本地 Docker 里跑 Traefik请求到底走了哪条路如果你刚开始接触 Traefik大概率会被它的配置文件绕晕静态配置里写 entryPoints动态配置里又冒出 routers、services、middlewares改完一个地方不生效日志里还看不出问题出在哪。我试过在本地 Docker 环境里把整条链路拆开跑一遍才发现这四个概念其实是一条流水线上的四个工位各管一段谁也不能越权。Traefik 是一个云原生反向代理和负载均衡器它能直接对接 Docker、Kubernetes 等服务发现后端自动感知容器上下线。它适合谁适合正在做容器化改造、需要统一南北向流量入口的后端和运维同学也适合想搞明白「请求从进门到落地」完整链路的开发者。本文不讲抽象架构图而是用本地 Docker 起一套最小可跑环境把 Entrypoints、Routers、Services、Middlewares 四个核心概念串成一条可验证的请求链路最后用 curl 亲眼看到路由和中间件生效。整条链路是这样的请求先打到 Entrypoints 监听的端口Traefik 拿到请求后交给 Routers 按规则匹配匹配成功再依次穿过 Middlewares 做加工最后由 Services 决定转发到哪个后端容器。四个环节各司其职配置也分两层Entrypoints 属于静态配置启动时就要确定Routers、Services、Middlewares 属于动态配置可以热加载。理解这个分层是后面少踩坑的关键。2. 前置准备TaoToken 与本地环境在动手之前先把两件事准备好一个是本地 Docker 环境另一个是后续做模型调用验证时用到的 API 凭证。Traefik 本身不依赖任何模型服务但我们在验证环节会用一个后端服务来模拟真实流量如果你想让后端服务对接大模型能力可以提前在 TaoToken 上把 Key 准备好。TaoToken 是一个面向开发者的模型调用平台提供统一的 API 入口兼容常见的对话与编码模型调用方式。它的控制台可以管理 API Keys接入文档里有各语言的调用示例。对于本文的场景你只需要拿到一个 Key后面在验证 Services 转发时可以把它注入到后端容器的环境变量里让后端服务真正去调用模型从而验证整条链路是通的。具体操作路径先访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解平台能力然后进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完成后在 API Keys 页面复制你的 Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你对调用方式不熟悉接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的请求示例。这里要提醒一句Key 属于敏感凭证不要硬编码进镜像或提交到 Git用环境变量或 Docker secrets 注入。本文后续的配置里我会用占位符YOUR_TAOTOKEN_KEY表示你替换成自己的即可。3. 可复制配置静态骨架与动态规则Traefik 的配置分静态和动态两层。静态配置在启动时加载决定 Entrypoints、日志级别、Provider 等动态配置可以在运行时热更新承载 Routers、Services、Middlewares。下面给出可直接复制的最小骨架。3.1 静态配置 traefik.yml# traefik.yml entryPoints: web: address: :80 websecure: address: :443 api: dashboard: true insecure: true providers: file: filename: /etc/traefik/dynamic.yml watch: true log: level: INFO accessLog: {}这里定义了两个 Entrypointsweb监听 80websecure监听 443。api.insecure: true打开 Dashboard方便本地调试生产环境务必关掉并加认证。providers.file指向动态配置文件watch: true表示文件改动后自动热加载省去重启。3.2 动态配置 dynamic.yml# dynamic.yml http: routers: api-router: rule: Host(api.local) PathPrefix(/v1) service: api-service middlewares: - strip-v1 - add-header entryPoints: - web middlewares: strip-v1: stripPrefix: prefixes: - /v1 add-header: headers: customRequestHeaders: X-Gateway: traefik services: api-service: loadBalancer: servers: - url: http://backend:8080 healthCheck: path: /health interval: 10s timeout: 3s这段配置里api-router的规则是同时匹配 Host 为api.local且路径以/v1开头。匹配后先过strip-v1中间件把/v1前缀去掉再过add-header给请求加一个X-Gateway: traefik头最后转发给api-service。api-service是一个负载均衡器指向后端容器backend:8080并配置了健康检查。3.3 docker-compose.yml 把环境串起来# docker-compose.yml version: 3.8 services: traefik: image: traefik:v3.0 ports: - 80:80 - 8080:8080 volumes: - ./traefik.yml:/etc/traefik/traefik.yml:ro - ./dynamic.yml:/etc/traefik/dynamic.yml:ro networks: - traefik-net backend: image: hashicorp/http-echo:0.2.3 command: - -listen:8080 - -texthello from backend environment: - TAOTOKEN_KEYYOUR_TAOTOKEN_KEY networks: - traefik-net networks: traefik-net: driver: bridge这里用hashicorp/http-echo模拟后端服务它会监听 8080 并返回一段文本。Traefik 和 backend 在同一个自定义网络traefik-net里所以 Traefik 可以直接用服务名backend访问它。注意api.insecure打开的 Dashboard 在 8080 端口和 Traefik 的 web 入口 80 不冲突。启动命令docker compose up -d启动后先确认两个容器都在运行docker compose ps你应该看到 traefik 和 backend 都是 Up 状态。如果 traefik 反复重启多半是配置文件路径或语法问题用docker compose logs traefik看日志。4. 验证请求curl 看路由与中间件是否生效配置跑起来只是第一步真正要确认的是请求有没有按预期走完整条链路。下面用 curl 分步验证。4.1 验证 Entrypoints 监听先确认 80 端口有响应。因为我们的路由规则要求 Host 是api.local所以直接访问 IP 不会命中路由Traefik 会返回 404。这恰好能证明 Entrypoints 在工作——请求进来了只是没匹配到路由。curl -i http://localhost/预期返回404 Not Found响应头里能看到Server: traefik。如果连不上说明 Entrypoints 没监听成功检查端口映射和 traefik.yml 里的 address。4.2 验证 Routers 匹配用 Host 头命中路由。因为本地没有 DNS 解析api.local我们用 curl 的--resolve或-H手动指定 Host。curl -i -H Host: api.local http://localhost/v1/hello预期返回200 OK响应体是hello from backend。这说明 Routers 成功匹配了 Host 和 PathPrefix并把请求交给了 Services。4.3 验证 Middlewares 生效中间件是否生效要看两个地方一是strip-v1有没有把/v1去掉二是add-header有没有加上自定义头。后端http-echo会把收到的路径回显吗默认不会但我们可以通过 Traefik 的访问日志或后端日志来确认。更直接的办法是临时把后端换成一个能回显请求头的服务或者看 Traefik 的 access log。先看 Traefik 日志里这条请求的记录docker compose logs traefik | grep api.local你会看到类似GET /v1/hello HTTP/1.1 200的访问日志。要确认strip-v1生效可以观察后端实际收到的路径。http-echo不支持回显路径我们换一个更直观的验证方式用curl直接请求后端容器对比路径。docker compose exec backend wget -qO- http://localhost:8080/hello如果后端收到的是/hello而不是/v1/hello说明stripPrefix生效了。至于add-header可以临时把后端换成mendhak/http-https-echo这类会回显请求头的镜像然后curl -s -H Host: api.local http://localhost/v1/hello | grep -i x-gateway预期能看到X-Gateway: traefik。这一步验证了 Middlewares 确实在请求转发前做了加工。4.4 验证 Services 负载均衡与健康检查Services 的负载均衡需要多个后端才能看出效果。把 docker-compose 里的 backend 扩成两个实例docker compose up -d --scale backend2然后连续请求几次观察返回是否来自不同实例。因为http-echo返回的文本一样我们可以给两个实例设置不同的 text或者看 Traefik 日志里转发的目标地址。更简单的办法是看 Dashboard访问http://localhost:8080在 HTTP Services 里能看到api-service下面挂了两个 server健康检查状态是绿色。如果健康检查失败server 会被自动摘除。你可以手动停掉一个 backend 容器等 10 秒后再看 Dashboard会发现只剩一个健康的 server。5. 本篇常见错排查配置 Traefik 时报错往往不直观。下面列几个我踩过的坑和对应的排查动作。404 但日志里没有路由匹配记录。先确认 Host 和 PathPrefix 是否同时满足。Traefik 的规则是关系少一个条件都不匹配。用curl -H Host: api.local http://localhost/v1/hello逐字对照规则里的反引号和括号YAML 里规则字符串必须用反引号包裹 Host 和 Path。502 Bad Gateway。说明 Routers 匹配成功了但 Services 转发失败。检查servers里的 url 是否可达。在 Docker 网络里服务名就是主机名http://backend:8080里的backend必须和 docker-compose 里的服务名一致。如果后端容器没起来或者端口写错就会 502。中间件不生效。先确认 router 的middlewares列表里引用的名字和http.middlewares下定义的名字完全一致大小写敏感。其次确认动态配置有没有被加载看 Traefik 启动日志里有没有Configuration loaded from file之类的记录。如果用了watch: true改完文件等一两秒再试。Dashboard 打不开。api.insecure: true时 Dashboard 在 8080 端口但如果你把 Traefik 的 8080 映射到了宿主机其他端口就要用对应端口访问。生产环境不要用 insecure 模式应该通过 router 暴露 Dashboard 并加 basicAuth 中间件。健康检查一直失败。检查healthCheck.path是否返回 200。http-echo默认对所有路径都返回 200但真实后端可能只对/health返回 200。另外interval和timeout的单位是秒写10s和10在 Traefik 里含义不同建议显式带单位。6. 把链路跑通之后下一步做什么四个概念跑通之后你会发现 Traefik 的配置其实是在描述一条数据流Entrypoints 是门Routers 是分拣员Middlewares 是加工台Services 是出货口。本地验证时用 file provider 手写动态配置最直观但真实容器环境里更常用 Docker provider让 Traefik 自动读取容器 label 生成路由省去手写 dynamic.yml。如果你后续要让后端服务真正对接模型能力比如在 Services 指向的容器里调用对话或编码模型可以先把 Key 和调用方式准备好。模型对话的入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 适合快速验证模型是否可用如果你要做长期的编码或 Agent 类任务Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 可以按需选用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。把这些凭证通过环境变量注入后端容器整条从 Entrypoints 到 Services 的链路就能承载真实的模型调用流量了。