企业官网建设流程全解析

第一次真正被老式反向代理的配置规则逼到崩溃，是手底下一批容器开始频繁上下线的那阵子。我原来习惯一个端口对应一个 upstream，容器重启后 IP 一变，就得手工改配置、reload、再验证，一天重复十多次，人和机器都麻了。后来把目光转向 Traefik，最直接的吸引力只有两个字：服务发现。这篇内容不绕弯子，从它解决什么问题、核心概念怎么理解，到安装配置和实际接入服务的完整操作，再补上我踩过的几个典型坑。适合已经会一点 Docker、正在为容器环境找一套顺手网关工具的读者，也能当一篇 Traefik 上手指南来用。

1. 为什么偏偏是 Traefik：服务发现带来的选择差异

1.1 传统反向代理在动态环境里的笨拙

Nginx 这类工具本身非常优秀，绝大多数静态路由场景里，我至今仍然会选它。问题集中出现在"后端地址反复变化"的场景下。你新起一个容器，要写一条 location，再补一个 upstream，还要记着 reload；容器销毁重建后 IP 变了，又要回去改。听起来只是多敲几行命令的事，但容器一多，维护成本会指数上升。更麻烦的是，你很难让这些配置跟上编排平台的真实状态，总有那么几次，页面 502 了才发现 upstream 早就指向一个不存在的 IP。

有人会用脚本去定时抓 Docker 的 IP，再重新生成 Nginx 配置。这条路能跑通，但它本质上是在给静态配置打补丁，你要额外维护一套生成逻辑、处理并发、处理 reload 失败的回滚。我在一个小项目里这么干过，配置模板越来越复杂，最后自己都懒得维护了。

1.2 Traefik 的逆向思路：让容器自己"报备"路由

Traefik 处理问题的角度完全不一样。它不做"静态配置 + 手工刷新"这件事，而是作为一个边缘路由器，直接接入你已有的编排生态。以 Docker 场景为例，Traefik 通过挂载的 docker.sock 感知容器的新增、停止、销毁事件，然后根据容器上的标签自动生成路由规则。

你可以把这种机制理解成：老式网关是一本通讯录，每次联系人变了，你得手动换页；Traefik 则是系统里自动同步的通讯录，新服务上线时，只要带上自己的标签，网关立刻知道该把哪个域名、哪个路径的流量送到它那里。这个"报备"不是靠写配置文件，而是通过容器 label 声明的，例如声明这个容器对应哪个 Host、哪个 PathPrefix，以及它自己监听什么端口。容器只要声明清楚，Traefik 就会把流量送过去，全程不需要重启网关进程。

1.3 和 Nginx、Caddy 放到一起看

工具没有绝对的好坏，只有合不合适。我整理过一个三者对比，直接贴在这里：

我这里不是说 Nginx 不中用。如果你的环境是固定的几台虚拟机，后端地址常年不变，Nginx 永远是可靠的答案。但你要管理的是一批动态创建、随时可能销毁的容器，Traefik 的"配置跟随容器状态自动收敛"能力，就是实打实的生产效率。

2. 先把几个核心抽象吃透，配置才有底气

2.1 一条请求的完整旅程：EntryPoints、Routers、Services

Traefik 的配置体系建立在几个固定概念上，理解它们比背参数重要得多。

EntryPoint 是流量的入口，通常直接对应一个端口。最常见的两个入口是 web（80）和 websecure（443）。Router 负责规则匹配，它监听来自 EntryPoint 的请求，通过 Host、PathPrefix、Header 等规则判断这个请求应该交给谁。匹配通过之后，Router 再转发给一个或多个 Service。Service 是后端实例的抽象，可以是一个地址，也可以是负载均衡后面的多个实例。

一个请求的完整路径大致是：用户在浏览器输入app.example.com访问 80 或 443 端口，Traefik 在对应 EntryPoint 上收到请求，Router 发现 Host 满足app.example.com，于是把它转给名为 app 的 Service；Service 的负载均衡器再把请求交给某个具体容器。整个过程发生在网关内部，对用户完全透明。

我一开始学的时候总把 Router 和 Service 混在一起，后来用一句话提醒自己：Router 管"这个请求该不该接"，Service 管"接到了该往哪送"。

2.2 Middlewares：插在转发之前的处理环节

中间件是 Traefik 比较出彩的设计。它允许你在 Router 匹配完成之后、请求真正被转发到 Service 之前，插入一串处理逻辑。比如最常见的：把所有 HTTP 请求重定向到 HTTPS；给某个路由加上 BasicAuth；对某个接口做限流；往请求头里注入自定义字段；在转发前去掉路径前缀。

中间件的声明和 Router 是分开的，一个中间件可以被多个 Router 引用。这个解耦方式非常实用，你不需要在新服务接入时重新写认证逻辑，只要在标签里引用一个已经存在的中间件名称就行。我把它理解成请求要经过的安检通道，每个通道负责一个独立的策略，数量、顺序都可以按需编排。

2.3 Providers：路由表的数据来源

Provider 是 Traefik 能够"动态"的根本。简单说，Provider 决定路由信息从哪里来。Docker Provider 会监听 Docker 事件，从容器标签里读取路由规则；Kubernetes Provider 则从 Ingress、IngressRoute 等资源里读取配置；File Provider 允许你直接写 yaml 文件，Traefik 监控这些文件的变化并热加载。

理解 Provider 的意义在于：你不再需要把所有路由写进一个庞大的主配置里。哪些服务归 Docker 标签管，哪些服务归文件配置管，可以在 Traefik 启动时就划分清楚。我在实际项目里通常同时启用 Docker Provider 和 File Provider：容器服务全部走标签，而一些不跑在容器里的固定服务，比如宿主机上的内部接口，则用 File Provider 单独维护。两种来源会被 Traefik 自动合并，互不干扰。

2.4 静态配置与动态配置：两个世界的边界

Traefik 的配置文件分成两个层次，这个区别很多人一开始会忽略。

静态配置（traefik.yml）决定 Traefik 自身怎么运行，比如监听哪些 EntryPoint、内置 Dashboard 是否开启、访问日志是否记录、ACME 证书存储在哪里。静态配置的改动通常需要重启 Traefik 进程才能生效。

动态配置则来自 Provider，决定流量怎么转发，比如某个 Host 对应哪个 Service、某个路由是否启用认证。动态配置支持热更新，容器标签一改、文件一存，Traefik 会在几秒内自动应用新规则，不需要重启。

我建议从一开始就把这两种配置分开维护。想改入口端口、换证书存储路径，去动静态配置；想加服务、调路由，去动标签或动态文件。这样既能发挥热更新的优势，也避免把 Traefik 自身配置和业务路由混成一锅粥。

3. 安装：用 Docker Compose 把 Traefik 跑起来

3.1 准备目录和权限

这套配置我通常在宿主机上固定放在一个目录里，方便备份。目录结构大致如下：

/opt/traefik/ ├── traefik.yml # 静态配置 ├── docker-compose.yml # 编排文件 ├── acme.json # 证书存储，生产环境需要 └── dynamic/ # 动态文件 └── services.yml

先创建目录和证书存储文件：

mkdir -p /opt/traefik/dynamic touch /opt/traefik/acme.json chmod 600 /opt/traefik/acme.json

acme.json 的权限非常重要，必须是 600。我第一次配置 HTTPS 时，就是因为它权限太宽松，证书一直签发失败，后面踩坑部分会详细说。

3.2 静态配置文件逐段说明

下面是一份可以落地的 traefik.yml，我用 v2.10 版本为例：

api: dashboard: true insecure: true # 开发环境方便起见，生产环境必须关闭 entryPoints: web: address: ":80" websecure: address: ":443" providers: docker: endpoint: "unix:///var/run/docker.sock" exposedByDefault: false network: traefik file: directory: /etc/traefik/dynamic watch: true certificatesResolvers: letsencrypt: acme: email: "admin@example.com" storage: "/etc/traefik/acme.json" httpChallenge: entryPoint: web accessLog: {}

逐段解释一下：

• api.dashboard决定是否启用内置控制面板；insecure: true表示开发时可以直接通过 8080 端口访问面板，生产环境务必关闭。
• entryPoints定义两个入口，80 给普通 HTTP，443 给 HTTPS。
• Docker Provider 里exposedByDefault: false是我强烈建议的写法。它表示：只有显式打了traefik.enable=true标签的容器才会被接入网关，避免有些镜像自带标签导致意外暴露。
• File Provider 的watch: true让 Traefik 自动监控 dynamic 目录的 yaml 变化，改完文件无需重启。
• certificatesResolvers 这段是给 HTTPS 自动签证书用的，先放着，后续章节会用到。

3.3 编排文件：网络和 docker.sock 是关键

docker-compose.yml 内容如下：

services: traefik: image: traefik:v2.10 container_name: traefik restart: unless-stopped ports: - "80:80" - "443:443" - "8080:8080" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./traefik.yml:/etc/traefik/traefik.yml:ro - ./acme.json:/etc/traefik/acme.json - ./dynamic:/etc/traefik/dynamic:ro networks: - traefik networks: traefik: name: traefik

这里最核心的就是挂载/var/run/docker.sock。Traefik 要感知容器事件、读取容器标签，全靠这个 socket。我用的是只读挂载，Traefik 只要读取能力就够了，没必要给它写宿主 Docker 的权限。

另外，所有需要被 Traefik 路由的后端容器，都必须加入同一个traefik网络。如果后端服务和 Traefik 不在同一个网络里，就算标签写对了，流量也找不到目标。这个细节容易忽略，排查时还比较隐蔽。

3.4 启动并验证 Dashboard

执行docker compose up -d后，先看一下日志：

docker logs -f traefik

看到没有报错、出现新 Provider 的监听日志后，直接访问http://<服务器IP>:8080。开发模式下api.insecure: true已经生效，你应该能看到 Dashboard 的图形页面，里面会列出已接入的路由、服务、中间件。刚启动时列表是空的，因为还没有任何服务打上标签，这很正常。

4. 接入第一个业务服务：标签路由与文件路由

4.1 用 Docker 标签声明一个服务

我习惯用一个最简单的 whoami 服务来验证链路是否打通。它专门用来回显请求信息，非常适合做路由连通性测试。下面是它的 compose 片段：

services: whoami: image: traefik/whoami:v1.5 labels: - "traefik.enable=true" - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)" - "traefik.http.routers.whoami.entrypoints=web,websecure" - "traefik.http.services.whoami.loadbalancer.server.port=80" networks: - traefik

标签的格式很好理解：traefik.http.routers.whoami这部分是命名空间，whoami是这个路由的名称。Traefik 允许同一前缀对应多个路由，所以名字要保证唯一。rule里的Host(\whoami.example.com`)表示只有当请求的域名是这个地址时才命中。loadbalancer.server.port=80` 告诉 Traefik，这个容器对外提供服务的端口是 80。

启动这个服务后，在服务器本机测试：

curl -H "Host: whoami.example.com" http://127.0.0.1

如果返回了一段服务信息，说明 Traefik 已经把请求按标签路由到了 whoami 容器。整个过程不需要 reload、不需要重启 Traefik，容器一上线，路由就出现。

4.2 用 File Provider 管理固定服务

容器化服务走标签很舒服，但总有一些后端不在 Docker 里，比如宿主机上一套老服务、内网某台物理机的接口。这种场景我用 File Provider 来接。

先在 dynamic 目录下新建一个services.yml：

http: routers: legacy-api: rule: "Host(`legacy.example.com`) && PathPrefix(`/api`)" service: legacy-api entryPoints: - websecure services: legacy-api: loadBalancer: servers: - url: "http://192.168.1.20:3000"

Traefik 监控到文件变化后会自动加载。这里我特意演示了PathPrefix的用法，路由规则可以组合。文件配置对于管理"不主动报备"的老服务非常方便，而且和 Docker 标签产生的路由能同时存在，互不冲突。

4.3 用一个中间件实现 HTTP 自动跳转 HTTPS

新服务接入后，很多人习惯在浏览器里直接敲域名，80 端口如果能访问，就不会主动输 https。但生产环境要求强制跳转。用一个重定向中间件就能解决。

在 whoami 的标签里补上：

- "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https" - "traefik.http.routers.whoami-http.rule=Host(`whoami.example.com`)" - "traefik.http.routers.whoami-http.entrypoints=web" - "traefik.http.routers.whoami-http.middlewares=redirect-to-https"

注意这里我新增了一个名为whoami-http的路由，只监听 web 入口，并且把redierct-to-https中间件挂上去。原来的whoami路由继续监听 websecure 入口。这样访问 http 地址时会先被 302 到 https，再由 https 路由正常处理。

4.4 路由规则升级组合：多域名、子路径、多副本

一个 Traefik 实例完全可以同时管理大量服务。举例来说：

- "traefik.http.routers.frontend.rule=Host(`www.example.com`)" - "traefik.http.routers.api.rule=Host(`api.example.com`) && PathPrefix(`/v1`)" - "traefik.http.routers.api.rule=Host(`api.example.com`) && PathPrefix(`/v2`)"

如果同一个服务跑着多个副本，Traefik 默认的负载均衡器会自动在多个后端之间分发流量。你只需要给每个容器打相同的traefik.http.services.<name>.loadbalancer.server.port标签，Traefik 会发现多个实例并归入同一个 Service，自动做负载均衡。这一点在 Docker Swarm 或 Compose 多副本场景下特别省心。

再往后还可以利用中间件做灰度发布，比如给不同权重设置多个 Service 后端，这在生产发布时是个很实用的能力。

5. 生产环境必须补齐的几块拼图

5.1 配置 HTTPS 自动签发证书

第四章的配置还没有真正启用 HTTPS。要让 Traefik 自动申请和续期证书，使用我之前在静态配置里预留的 certificatesResolvers。

首先确保 traefik.yml 里 acme 配置正确：

certificatesResolvers: letsencrypt: acme: email: "admin@example.com" storage: "/etc/traefik/acme.json" httpChallenge: entryPoint: web

然后在需要 HTTPS 的路由标签里加上certresolver：

- "traefik.http.routers.whoami.tls.certresolver=letsencrypt"

Traefik 会通过 HTTP-01 方式向公共 CA 验证域名所有权。整个流程自动完成：收到 HTTPS 请求时发现没有对应证书，就自动申请；证书到期前会自动续期。你唯一需要确保的是 80 端口能从公网被访问到，因为验证请求会通过这个端口进来。

我建议生产环境先使用临时域名验证一遍，确认证书确实能签发，再正式切换域名，避免因为 DNS 未解析导致验证失败。

5.2 让 Dashboard 不再裸奔

前文提到api.insecure: true只适合开发环境。生产环境要关闭它，改为通过安全路由访问 Dashboard。

首先把静态配置里的insecure: true改成false，然后新增一个指向api@internal的路由。我通常会给 Dashboard 绑一个独立子域名，并挂上 BasicAuth 中间件。动态文件里可以这样写：

http: routers: dashboard: rule: "Host(`traefik.example.com`)" service: "api@internal" entryPoints: - websecure middlewares: - dashboard-auth tls: certResolver: letsencrypt middlewares: dashboard-auth: basicAuth: users: - "admin:$apr1$Hj7u8Pqd$abc123..."

BasicAuth 的用户名密码可以用htpasswd工具生成。这里有个小细节：如果走 Docker Compose，标签字符串里的$会被 Compose 做变量插值，建议把$写成$$转义，或者把中间件定义放在 File Provider 的 yaml 里，避开插值问题。我把这段配置放在动态文件里，就是为了少踩这个坑。

5.3 健康检查：让流量始终打到健康实例

Traefik 的负载均衡器支持主动健康检查。你可以为每个 Service 配置一个探测路径，Traefik 会定时发起请求，一旦某个实例连续失败，就会把它从负载均衡池中临时摘除。这样即使某个容器的进程还活着、但业务已经不可用时，前端也不会把流量送过去。

在动态文件或容器标签里配置：

http: services: backend: loadBalancer: healthCheck: path: /health interval: 10s timeout: 3s servers: - url: "http://192.168.1.20:8080"

路径务必选一个真正反映业务可用性的接口，比如能检查数据库连接的接口。如果只配/，它只能告诉你 HTTP 服务有没有在监听，意义有限。

5.4 日志与指标：问题有迹可循

Traefik 默认日志信息量有限。我建议至少在静态配置里开启访问日志：

accessLog: filePath: /var/log/traefik/access.log

这样每次请求的来源 IP、目标 Host、路由名称、后端耗时、状态码都会被记录，排查问题时能清楚地看到请求被哪个 Router 承接、有没有转发失败。

如果后续想接监控告警，可以再开启 Prometheus 指标：

metrics: prometheus: {}

Traefik 会暴露标准的/metrics端点，后续接一个采集任务就能看到各路由的请求量、错误率、延迟分布。这一步不属于最基础的使用必需项，但只要服务数量上了两位数，早点接上会让你省力很多。

6. 踩坑复盘：这几类问题我几乎都遇到过

6.1 Dashboard 打开却空白或 404

这种情况最常见的原因是静态配置没开全。我遇到过一次，api.dashboard写了 true，但忘了写api.insecure，或者生产环境关了 insecure 却没有配api@internal路由，结果打开 8080 端口只看到空白。

解决办法很简单：要么开发模式下确认insecure: true，要么生产模式下给 Dashboard 写一条指向service: "api@internal"的 Router。没有这条内部服务路由，Dashboard 就没有对外入口。

6.2 标签看起来写对了，路由就是不出现在 Dashboard

这个问题我排查过很多次，原因通常就三类。

第一类是容器和 Traefik 不在同一个网络。Docker Provider 虽然能看到容器事件，但如果它们不在同一个自定义网络，Traefik 就无法把流量送到容器 IP。用docker network inspect traefik确认后端容器是否在里面。

第二类是exposedByDefault的配置。如果你和我一样把它设成false，就必须显式写traefik.enable=true。漏掉这句，整个标签组都会被忽略。

第三类是标签里的语法问题。rule里的反引号、路径的大小写、路由名称的重复命名，任何一个小错都可能导致这条路由没有生成。特别是路由名重复时，后定义的可能会覆盖前面定义的同名路由，看起来就像"规则没生效"。

6.3 HTTPS 证书一直签不下来

证书相关的坑，我印象最深的几个：

一个是 acme.json 的权限不对。这个文件需要 Traefik 进程可写，但权限又不能太宽松，必须是 600。我用chmod 600 acme.json之后，很多诡异问题都消失了。

另一个是 80 端口没有真正暴露到公网。HTTP-01 校验需要 CA 从公网访问你的 80 端口，如果前面还有一层防火墙或云安全组没放行，申请流程会一直卡住。建议先用浏览器从外网访问一下http://你的域名，能通再检查 Traefik 日志。

还有一点是不要忽略 CA 的限流策略。申请失败几次后，同一个域名会被暂时限制，短时间内反复试只会延长等待时间。需要先在临时域名或测试环境调通完整流程，再切换正式域名。

6.4 分清哪些改动需要重启

热更新是 Traefik 的卖点，但不是所有配置都能热更新。

动态配置，比如新增路由、修改中间件、调整服务地址，改动后几秒内自动生效，不需要重启。静态配置，比如把insecure: true改成false、修改 EntryPoint 端口、调整 certificatesResolvers 的存储路径，这些改动必须重启 Traefik 进程。

我自己的操作习惯是：业务路由全部走动态配置，能热更新就热更新；Traefik 自身运行参数固定之后基本不动，偶尔要改也是先备份配置文件，再执行docker compose restart，启动后拿着日志确认没有配置错误。这样既享受了动态能力，又不会让"不知道改了什么才需要重启"这个问题困扰自己。

最后再说一个建议：我手边所有配置最终都要放进 Git 管理。docker-compose.yml、traefik.yml、dynamic 目录里的服务配置，全部版本化。容器标签里的路由规则虽然没法直接入库，但对应的 compose 文件本身就是标签的载体，一样能提交。这样每次改动都有历史，出问题可以快速 diff，回滚也只是执行一次旧版本 compose 的事。这套体系跑顺之后，Traefik 基本就变成我接手新服务的标准配置，省下的时间远比最初学习成本要多。