Traefik 快速上手：在 Docker 与 Kubernetes 中部署云原生应用代理

本篇指南基于 Traefik 官方入门文档（getting-started 索引 及其关联的 Docker 指南、Kubernetes 指南）编写，完整覆盖两种主流部署环境下从零安装 Traefik 的实操流程：安装与启动、暴露 Dashboard 控制台、部署 whoami 示例应用、配置基础路由规则（Docker Label 路由、IngressRoute CRD 与 Gateway API）。读完你可以独立完成 Traefik 的首次部署与验证，并理解其 Dashboard 路由、Provider 发现机制背后的源码实现。

一、选择部署环境与前置准备

Traefik 支持多种部署环境，官方入门文档将快速上手分为两条主线：

• Docker 快速上手：使用 Docker（可选 Docker Compose）直接运行 Traefik 容器；
• Kubernetes 快速上手：使用 Helm 在 Kubernetes 集群中部署 Traefik。

每条指南都会帮助你完成四件事：安装 Traefik、暴露 Dashboard、部署一个示例应用、配置基础路由。

开始之前，请确认所选环境的前置条件：

环境	前置条件
Kubernetes	一个可用的 Kubernetes 集群、Helm 3、kubectl，本地实验可加 k3d
Docker	Docker，可选 Docker Compose

从源码结构看，Traefik 对 Docker 和 Kubernetes 都是"一等公民"：仓库中 pkg/provider/docker/ 与 pkg/provider/kubernetes/ 分别实现了两种环境的 Provider，负责监听容器/资源事件并转换成 Traefik 动态配置。入门文档示例使用 traefik:v3.7 镜像，以下内容均以该版本为适用前提。

二、Docker 环境快速上手

Docker 是 Traefik 的一等公民，原生支持 Docker 容器与服务发现。无论是 Docker Compose 还是直接运行容器，Traefik 都能无缝管理你的 Docker 流量。

2.1 使用 Docker Compose 安装

创建如下 Compose 文件：

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.7
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

这份配置做了四件事：

• 暴露 80 与 8080 端口：80 用于业务流量，8080 用于 Dashboard；
• 启用 Docker Provider（--providers.docker=true），让 Traefik 通过 Docker API 发现容器；
• --entrypoints.web.address=:80 定义名为 web 的 Entrypoint，监听 80 端口；
• 挂载 Docker socket /var/run/docker.sock，这是容器发现的必要条件。

启动命令：

docker-compose up -d

2.2 使用 Docker CLI 安装

也可以直接以 CLI 方式运行。先创建静态配置文件：

# traefik.yml
api:
  insecure: true
entryPoints:
  web:
    address: ":80"
providers:
  docker: {}

然后启动容器：

docker run -d \
  -p 80:80 \
  -p 8080:8080 \
  -v $PWD/traefik.yml:/etc/traefik/traefik.yml \
  -v /var/run/docker.sock:/var/run/docker.sock \
  traefik:v3.7

该命令与 Compose 版本配置等价：暴露 80/8080 端口、挂载配置文件与 Docker socket。

关于 api.insecure 的源码原理：在静态配置定义中，Insecure 字段描述为 "Activate API directly on the entryPoint named traefik"（见 pkg/config/static/static_config.go）。开启后，内部 Provider 会动态注入两条路由——api 路由（规则 PathPrefix("/api")，优先级极高）与 dashboard 路由（规则 PathPrefix("/")，并挂载 dashboard_redirect/dashboard_stripprefix 中间件把根路径 301 到 /dashboard/），实现见 pkg/provider/traefik/internal.go。因此 Dashboard 无需认证即可通过 8080 端口的 /dashboard/ 访问。注意：insecure 模式仅限开发环境使用，生产环境不要开启，生产环境应改用受保护的 API 配置（参见 Dashboard 参考文档）。

访问地址：http://localhost:8080/dashboard/

2.3 部署示例应用 whoami

使用 Traefik 官方的 whoami 镜像（回显请求信息），并通过 Docker Label 声明路由规则：

# whoami.yml
services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"

docker-compose -f whoami.yml up -d

Label 中 traefik.http.routers.whoami 命名了一个 HTTP Router，rule 使用 Host() 匹配 whoami.localhost 域名。Docker Provider 会自动把该容器发现为 Service，与 Router 绑定。

2.4 验证部署

curl http://whoami.localhost

预期输出（请求会附带 X-Forwarded-* 系列头部，说明请求确实经过了 Traefik 反代）：

Hostname: 068c0a29a8b7
IP: 127.0.0.1
IP: ::1
IP: 192.168.147.3
RemoteAddr: 192.168.147.2:56006
GET / HTTP/1.1
Host: whoami.localhost
User-Agent: curl/8.7.1
X-Forwarded-For: 192.168.147.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: 9232cdd4fd6c
X-Real-Ip: 192.168.147.1

在 Dashboard 的 HTTP Routers 页面中，可以看到 whoami.localhost 路由标注为由 Docker Provider 管理。至此，Docker 环境的 Traefik 部署与路由配置完成。

三、Kubernetes 环境快速上手

Kubernetes 同样是 Traefik 的一等公民，原生支持 IngressRoute CRD、Ingress 以及 Kubernetes Gateway API 三种标准的流量接入方式（分别参见 IngressRoute CRD、Ingress、Gateway API）。

3.1 使用 k3d 创建本地集群

k3d cluster create traefik \
  --port 80:80@loadbalancer \
  --port 443:443@loadbalancer \
  --port 8000:8000@loadbalancer \
  --k3s-arg "--disable=traefik@server:0"

该命令：创建名为 "traefik" 的 k3d 集群；将 80、443、8000 端口映射到 loadbalancer；并通过 --disable=traefik@server:0 禁用 k3s 内置的 Traefik 入口控制器，避免与我们要部署的 Traefik 冲突。

配置 kubectl：

kubectl cluster-info --context k3d-traefik

3.2 使用 Helm 安装 Traefik

添加 Traefik Helm 仓库：

helm repo add traefik https://traefik.github.io/charts
helm repo update

创建 values 文件：

# values.yaml
ingressRoute:
  dashboard:
    enabled: true
    matchRule: Host(`dashboard.localhost`)
    entryPoints:
      - web
providers:
  kubernetesGateway:
    enabled: true
gateway:
  listeners:
    web:
      namespacePolicy:
        from: All

各配置项含义：

• ingressRoute.dashboard：由 Helm Chart 内置的 IngressRoute 资源暴露 Dashboard，匹配 dashboard.localhost 主机名，绑定 web Entrypoint；
• providers.kubernetesGateway.enabled：启用 Kubernetes Gateway API Provider；
• gateway.listeners.web.namespacePolicy.from: All：允许 Gateway 接收来自所有命名空间的 HTTPRoute。

提示：使用 Helm Chart 安装时，KubernetesCRD Provider 默认开启，因此 values 文件中无需显式配置。

执行安装：

helm install traefik traefik/traefik -f values.yaml --wait

也可以完全用 CLI 参数安装（等价配置，额外映射 30000/30001 端口到 web/websecure）：

helm install traefik traefik/traefik --wait \
  --set ingressRoute.dashboard.enabled=true \
  --set ingressRoute.dashboard.matchRule='Host(`dashboard.localhost`)' \
  --set ingressRoute.dashboard.entryPoints={web} \
  --set providers.kubernetesGateway.enabled=true \
  --set gateway.listeners.web.namespacePolicy.from=All

安装启用 Gateway API Provider 后，Traefik 会自动创建名为 traefik 的默认 GatewayClass：

kubectl describe GatewayClass traefik

3.3 暴露 Dashboard

Dashboard 由 Helm Chart 提供的 IngressRoute 暴露（对应上面 values 中的 ingressRoute.dashboard 配置）。访问：

http://dashboard.localhost/dashboard/

（本地调试需在 hosts 文件中将 dashboard.localhost 指向 127.0.0.1。）

3.4 部署示例应用

创建 Deployment（2 副本，使用 traefik/whoami 镜像）：

# whoami.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80

创建 Service：

# whoami-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: whoami
spec:
  ports:
    - port: 80
  selector:
    app: whoami

kubectl apply -f whoami.yaml
kubectl apply -f whoami-service.yaml

3.5 方式一：使用 IngressRoute（CRD）暴露应用

# whoami-ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`whoami.localhost`)
      kind: Rule
      services:
        - name: whoami
          port: 80

kubectl apply -f whoami-ingressroute.yaml

验证：

curl http://whoami.localhost

Hostname: whoami-76c9859cfc-6v8hh
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.11
IP: fe80::20ad:eeff:fe44:a63
RemoteAddr: 10.42.0.9:38280
GET / HTTP/1.1
Host: whoami.localhost
User-Agent: curl/8.7.1
Accept-Encoding: gzip
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: whoami.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: traefik-598946cd7-zds59
X-Real-Ip: 127.0.0.1

也可以直接在浏览器打开 http://whoami.localhost 验证。

3.6 方式二：使用 Gateway API 暴露应用

Traefik 支持 Kubernetes Gateway API 规范，这是配置入口流量更加标准化的方式。由于安装时已启用 Gateway API Provider，可在 Dashboard 的 Providers 部分确认。

先在集群中安装 Gateway API CRDs（入门文档以 v1.5.1 为准）：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

创建 HTTPRoute，该配置：创建名为 "whoami" 的 HTTPRoute；将其挂载到 Traefik 安装时自动创建的默认 Gateway（traefik-gateway）；为 whoami-gatewayapi.localhost 主机名配置路由；将所有流量转发到 whoami Service 的 80 端口：

# httproute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
spec:
  parentRefs:
    - name: traefik-gateway
  hostnames:
    - "whoami-gatewayapi.localhost"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: whoami
          port: 80

kubectl apply -f httproute.yaml

验证：

curl http://whoami-gatewayapi.localhost

输出与 IngressRoute 方式一致（含 X-Forwarded-* 头部）。在 Dashboard 的 HTTP Routes 页面中，可以看到该路由由 Traefik Kubernetes Gateway API Provider 管理。

仓库中的 integration/fixtures/k8s/03-gateway.yml、integration/fixtures/k8s/03-ingressroute.yml 等集成测试夹具，以及 integration/gateway-api-conformance-reports/ 下的 Gateway API 一致性测试报告，可以佐证 Traefik 对上述资源类型的完整支持。

四、核心机制小结与下一步

核心机制回顾（结合源码）：

1. 静态配置 + 动态配置分离：Entrypoint、Provider 开关属于静态配置（pkg/config/static/static_config.go），Router/Service/Middleware 属于动态配置，由 Provider 实时生成；
2. Provider 驱动发现：Docker Provider 监听 socket 上的容器事件、解析 traefik.http.* Label；Kubernetes Provider 监听 CRD/Ingress/Gateway 资源，统一转换为动态配置；
3. 内部路由注入：Dashboard 与 API 路由由内部 Provider（pkg/provider/traefik/internal.go）按需注入，insecure 模式会直接暴露且不做认证，务必只在开发环境使用。

下一步学习路径（与入门文档保持一致）：

• 配置 TLS
• 配置 Middlewares（中间件）
• 启用 Metrics
• Docker Provider 参考
• Kubernetes CRD Provider 参考
• Kubernetes Gateway API Provider 参考
• Entrypoints 参考、API 与 Dashboard 参考

至此，你已在 Docker 与 Kubernetes 两种环境中完成了 Traefik 的安装、Dashboard 暴露与基础路由配置，后续可在此基础上叠加 TLS、中间件与可观测性能力。