1. 从一次容器端口打架说起Traefik 到底解决什么问题如果你在单机上跑过三四个 Docker 服务大概率遇到过这种局面每个容器都想对外暴露端口80 被占了、8080 被占了最后变成 30001、30002 这种自己都记不住的映射表。更麻烦的是服务一扩容端口映射就得重排前端调用方还得跟着改地址。Traefik 就是冲着这个痛点来的——它是一款用 Go 编写的反向代理天生盯着容器生态做服务发现容器起来它自动加路由容器挂掉它自动摘路由不需要你手动 reload 配置。这篇聚焦的是 Traefik 在 Docker 容器场景下的入门配置核心围绕config.toml骨架展开。我会把静态配置和动态配置拆开讲清楚再演示 Docker provider 怎么自动发现容器、路由怎么绑定到入口点最后用 curl 把整条链路验证一遍。适合已经会写docker-compose.yml、但还没系统用过 Traefik 的同学。整套流程跑通大概二十分钟命令和配置都能直接复制。需要说明的是Traefik 本身是开源代理组件和模型服务没有强绑定关系。但如果你后续要把本地跑的模型对话、编码 Agent 这类服务也挂到统一入口上用 Traefik 做流量层会比手写 Nginx 配置省心不少。下面进入正题。2. 前置准备TaoToken 侧要拿的东西与网络规划在动手写 Traefik 配置之前先把两件事定下来一是容器网络二是如果你要把模型相关服务也接进来需要提前准备好访问凭证。先说网络。Traefik 要和被代理的容器处在同一个 Docker 网络里才能通过容器名或服务名发现它们。我习惯单独建一个网络不跟默认 bridge 混在一起docker network create traefik-net这条命令执行完会返回一串网络 ID说明网络建好了。后面所有容器都通过--network traefik-net或 compose 里的networks字段接进来。再说凭证。如果你打算把模型对话、编码 Agent 这类服务也纳入统一入口需要先在 TaoToken 控制台生成 API Key。入口在这里控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenttraefik_configAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenttraefik_config生成后把 Key 存到环境变量或.env文件里别硬编码进 compose。API 的基础地址是https://taotoken.net/api这个地址在配置上游服务时会用到。如果你只是想先验证 Traefik 的转发能力用官方的 whoami 测试容器就够了不必急着接真实业务。注意API Key 属于敏感信息写进docker-compose.yml后如果提交到 Git记得用.gitignore排除.env文件。3. config.toml 骨架静态配置与动态配置分离Traefik 的配置分两层这是它和 Nginx 最大的思维差异。静态配置决定 Traefik 进程本身怎么启动——监听哪些端口、开哪些 provider、日志级别动态配置决定流量怎么走——路由规则、服务后端、中间件。静态配置改了要重启进程动态配置改了热生效。用config.toml承载静态配置结构大致是这样# config.toml —— 静态配置骨架 [global] checkNewVersion false sendAnonymousUsage false [entryPoints] [entryPoints.web] address :80 [entryPoints.websecure] address :443 [api] dashboard true insecure false [providers] [providers.docker] endpoint unix:///var/run/docker.sock exposedByDefault false network traefik-net [providers.file] directory /etc/traefik/dynamic watch true [log] level INFO [accessLog] filePath /var/log/traefik/access.log逐段解释一下关键项。entryPoints定义入口点web监听 80websecure监听 443后面路由要绑定到具体入口点。providers.docker里exposedByDefault false很重要——它意味着容器默认不被暴露必须显式打traefik.enabletrue标签才会被代理避免误暴露数据库之类的容器。network traefik-net指定 Traefik 从哪个网络里发现容器地址。providers.file指向/etc/traefik/dynamic目录用来放动态配置文件配合watch true实现热加载。这样静态和动态就彻底分开了config.toml管进程dynamic/目录管路由。动态配置可以写成 YAML比如dynamic/routers.yml# dynamic/routers.yml —— 动态配置示例 http: routers: whoami: rule: Host(whoami.local) entryPoints: - web service: whoami-svc services: whoami-svc: loadBalancer: servers: - url: http://whoami:80这份动态配置定义了一个路由whoami规则是 Host 匹配whoami.local绑定到web入口点后端指向whoami容器的 80 端口。注意这里的whoami是容器名Traefik 会通过 Docker 网络解析它。4. 可复制配置Docker provider 自动发现容器静态配置写好后用 compose 把 Traefik 跑起来。目录结构建议这样组织traefik-demo/ ├── docker-compose.yml ├── config.toml └── dynamic/ └── routers.ymldocker-compose.yml内容如下version: 3.8 services: traefik: image: traefik:v3.0 container_name: traefik restart: always ports: - 80:80 - 8080:8080 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./config.toml:/etc/traefik/traefik.toml:ro - ./dynamic:/etc/traefik/dynamic:ro networks: - traefik-net whoami: image: traefik/whoami container_name: whoami labels: - traefik.enabletrue - traefik.http.routers.whoami.ruleHost(whoami.local) - traefik.http.routers.whoami.entrypointsweb - traefik.http.services.whoami.loadbalancer.server.port80 networks: - traefik-net networks: traefik-net: external: true几个关键点。/var/run/docker.sock挂载进去且设为只读让 Traefik 能订阅 Docker 事件容器起停它立刻感知。config.toml挂到/etc/traefik/traefik.toml这是 Traefik 默认读取的静态配置路径。dynamic目录挂进去对应前面providers.file.directory的设置。whoami 容器的 labels 是重点。traefik.enabletrue显式开启代理traefik.http.routers.whoami.rule定义路由规则entrypointsweb绑定到 80 入口点loadbalancer.server.port80告诉 Traefik 容器内部监听的是 80 端口。这套标签就是声明式路由改完docker compose up -d就生效不用碰 Traefik 主配置。启动命令docker compose up -d执行后docker compose ps应该看到两个容器都是 Up 状态。Traefik 的 dashboard 在 8080 端口浏览器打开http://127.0.0.1:8080能看到路由和服务列表。5. 验证请求curl 打通容器流量转发配置跑起来后用 curl 验证转发是否真的通了。因为用的是whoami.local这种本地域名先改 hostsecho 127.0.0.1 whoami.local | sudo tee -a /etc/hosts然后发请求curl -H Host: whoami.local http://127.0.0.1预期返回类似Hostname: whoami IP: 172.20.0.3 RemoteAddr: 172.20.0.2:54321 GET / HTTP/1.1 Host: whoami.local看到Hostname: whoami就说明 Traefik 把请求转发到了 whoami 容器。RemoteAddr显示的是 Traefik 容器的地址证明流量确实经过了代理层。接着验证负载均衡。把 whoami 扩容到两个实例docker compose up -d --scale whoami2再连续请求几次for i in 1 2 3 4; do curl -s -H Host: whoami.local http://127.0.0.1 | grep Hostname; done如果返回的 Hostname 在whoami和whoami-1之间交替说明 Traefik 已经自动发现新实例并做了轮询。整个过程没有改任何 Traefik 配置这就是 Docker provider 自动发现的价值。如果你要把模型对话服务也挂进来可以在 compose 里加一个服务labels 里把rule换成对应域名loadbalancer.server.port指向服务实际端口。上游地址填https://taotoken.net/apiKey 通过环境变量注入。这样模型服务就和 whoami 一样被统一入口管理。6. 本篇常见错排查404 page not found最常见的原因是容器没打traefik.enabletrue或者exposedByDefault没设成 false 导致规则冲突。先看 dashboard 的 Routers 列表里有没有你的路由没有就是标签没生效。另外检查rule里的域名和 curl 的 Host 头是否完全一致大小写敏感。502 Bad GatewayTraefik 找到了路由但连不上后端。多半是loadbalancer.server.port填错了或者容器不在traefik-net网络里。用docker inspect 容器名看它的网络配置确认和 Traefik 在同一网络。还有一种情况是容器启动慢Traefik 先探到但后端还没就绪等几秒重试即可。dashboard 打不开检查 8080 端口有没有映射出来以及config.toml里api.dashboard true是否开启。如果设了insecure falsedashboard 需要通过路由暴露不能直接访问 8080。入门阶段建议先insecure true跑通再收紧。配置改了不生效静态配置改动必须重启 Traefik 容器docker compose restart traefik。动态配置如果放在providers.file.directory下且watch true保存后几秒内自动加载不用重启。分不清改的是哪层就看这个配置是决定进程行为还是决定路由行为。容器名解析失败Traefik 通过 Docker 网络内的 DNS 解析容器名。如果 compose 里服务名和容器名不一致以服务名为准。另外network字段在providers.docker里指定后Traefik 只会从该网络取容器 IP跨网络的容器发现不了。7. 把入口层固定下来后续接入更省事Traefik 这套配置跑通后你手里就有了一个能自动感知容器变化的入口层。新服务上线只需要加几行 labels不用改代理主配置也不用记端口映射表。对于经常在本地起多个模型服务、编码 Agent 的场景这种声明式路由比手写 Nginx upstream 要轻快得多。如果你准备把模型对话或编码 Agent 也接到这个入口后面建议先把访问凭证配好。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenttraefik_config 长期跑编码任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenttraefik_config 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenttraefik_config 里面有各语言 SDK 的调用示例配合 Traefik 的路由规则可以直接把服务挂到统一域名下。最后留一个实操建议把config.toml和dynamic/目录一起纳入版本管理但.env和 API Key 单独排除。每次调整路由前先docker compose config校验一遍 compose 语法能省掉不少低级报错。