Traefik 暴露 API 实战：跨 Docker、Swarm、Kubernetes、Consul 与 File 六类 Provider 配置 api@internal 路由

Traefik 通过内建的服务 api@internal 对外提供 API 与 Dashboard，但除 api.insecure 模式外，它不会自动生成路由，必须手动编写指向该内部服务的 Router 并挂载认证中间件。本文围绕官方文档提供的多 Provider 配置示例展开，完整给出 Docker、Swarm、Kubernetes CRD、Consul Catalog、File（YAML/TOML）六类动态配置写法，并结合源码解析 api@internal 的注册与分发机制，帮助读者安全地暴露并保护 Traefik 的 API 端点。

1. 核心目标：把请求路由到 api@internal 服务

Traefik 的 API 与 Dashboard 数据全部由 API 端点提供，而这两者都运行在 Traefik 内部。从源码结构看，内部服务的注册发生在 internal.go 的 apiConfiguration 函数中：只要静态配置启用了 api，Traefik 就会向动态配置中注册一个名为 api 的 HTTP 服务（cfg.HTTP.Services["api"]）；若同时启用 Dashboard，还会注册 dashboard 服务。

关键在于该函数的分支逻辑：

• 当 api.insecure = true 时，Traefik 自动在名为 traefik 的内部 Entrypoint 上创建 api、dashboard（以及可选的 debug）三个 Router，规则分别是 PathPrefix(\/api`)、PathPrefix(`/`)、PathPrefix(`/debug`)`，无需用户额外配置；
• 当未启用 insecure 模式时，apiConfiguration 只注册服务本身，不创建任何 Router——这时就需要用户自己编写 Router，把外部流量指向 api@internal 服务。这正是本文档示例集要解决的问题。

请求到达后，由 internalhandler.go 根据服务名进行分发，case "api@internal": 分支会把请求交给 API 的 HTTP handler 处理。因此“路由到 api@internal”本质上就是让某个 Router 的 service 字段等于这个内部服务名。

配套的静态配置只需开启 API（各格式的完整选项说明见 API 与 Dashboard 静态配置文档）：

api: {}

[api]

--api=true

下面的示例全部假设静态配置已启用 api，且未启用 api.insecure，统一采用“仅按 Host 匹配”的规则 Host(\traefik.example.com`)，并在路由上挂载名为 auth` 的 basicAuth 中间件。

2. 六类 Provider 的完整动态配置示例

以下六个配置块与文档完全一致，分别对应六种常见的 Provider 场景，可按部署环境直接选用。

2.1 Docker 与 Swarm（Compose 风格标签）

在 Docker Compose 服务上通过 labels 声明动态配置：

# Dynamic Configuration
labels:
  - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
  - "traefik.http.routers.api.service=api@internal"
  - "traefik.http.routers.api.middlewares=auth"
  - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

要点说明：

• traefik.http.routers.api.*：创建一个名为 api 的 HTTP Router，规则为 Host(\traefik.example.com`)，服务指向 api@internal`；
• traefik.http.middlewares.auth.basicauth.users：定义 basicAuth 中间件的凭据列表，格式为 用户名:哈希，多个用户以英文逗号分隔；
• $ 必须写成 $$：在 Docker Compose / Swarm 的标签中，$ 是变量插值符号，因此 MD5-crypt 哈希里的 $apr1$... 必须转义为 $$apr1$$...，这与下文 File 配置中直接使用单 $ 的写法形成对照。

2.2 Docker (Swarm)：deploy.labels 与虚拟端口

Swarm 模式下的标签放在 deploy.labels 下，且需要额外声明一个虚拟服务端口：

# Dynamic Configuration
deploy:
  labels:
    - "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
    - "traefik.http.routers.api.service=api@internal"
    - "traefik.http.routers.api.middlewares=auth"
    - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
    # Dummy service for Swarm port detection. The port can be any valid integer value.
    - "traefik.http.services.dummy-svc.loadbalancer.server.port=9999"

末尾的 dummy-svc 是文档明确注释的要点：Swarm 中 Traefik 依赖端口探测来识别服务，指向 api@internal 的路由没有真实后端端口，因此需要声明一个仅用于端口探测的虚拟服务（Dummy service），其 server.port 可以是任意合法整数值，这里取 9999。

2.3 Kubernetes CRD：IngressRoute + Middleware + Secret

Kubernetes 环境下使用 CRD 资源，basicAuth 凭据存放在独立的 Kubernetes Secret 中，而不是直接写在中间件里：

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard
spec:
  routes:
  - match: Host(`traefik.example.com`)
    kind: Rule
    services:
    - name: api@internal
      kind: TraefikService
    middlewares:
      - name: auth
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: auth
spec:
  basicAuth:
    secret: secretName # Kubernetes secret named "secretName"

要点说明：

• 服务必须声明 kind: TraefikService，这是 TraefikService 类型，用于引用 api@internal 这类跨 Provider 的内部服务；
• basicAuth.secret 引用一个名为 secretName 的 Secret（生产环境请自行创建，通常类型为 kubernetes.io/basic-auth），实现上将凭据与路由配置解耦，比在标签里明文写哈希更符合集群的安全实践。

2.4 Consul Catalog：KV 键值对形式

在 Consul 体系中，动态配置以“键=值”的键值对形式表达，前缀到最后一个 . 为止的部分是键，等号后是值：

# Dynamic Configuration
- "traefik.http.routers.api.rule=Host(`traefik.example.com`)"
- "traefik.http.routers.api.service=api@internal"
- "traefik.http.routers.api.middlewares=auth"
- "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

其语义与 Docker 标签完全一致：一条规则、一个内部服务、一个中间件引用、一组 basicAuth 用户。

2.5 File (YAML)

使用 File Provider 的 YAML 动态配置文件时，凭据以结构化的 users 列表书写，$ 无需转义：

# Dynamic Configuration
http:
  routers:
    api:
      rule: Host(`traefik.example.com`)
      service: api@internal
      middlewares:
        - auth
  middlewares:
    auth:
      basicAuth:
        users:
          - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
          - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

2.6 File (TOML)

TOML 写法的字段含义与 YAML 一一对应，路由名在 TOML 示例中取为 my-api（路由名可任意，与其他示例中的 api 不同但功能等价）：

# Dynamic Configuration
[http.routers.my-api]
  rule = "Host(`traefik.example.com`)"
  service = "api@internal"
  middlewares = ["auth"]

[http.middlewares.auth.basicAuth]
  users = [
    "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
    "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  ]

3. 配置要素逐项解析

六个示例虽然 Provider 不同，但表达的都是同一套路由模型，可拆解为四个要素：

要素	字段（以 File/YAML 为例）	取值	作用
路由名	http.routers.api	任意标识符	Router 的命名空间标识
匹配规则	rule	Host(\traefik.example.com`)`	仅匹配指定域名的请求；文档采用纯 Host 规则，意味着该域名下的 /api/...、/dashboard/ 等路径都进入 Traefik 内部处理
目标服务	service	api@internal	指向 Traefik 内建的 API 服务，@internal 后缀表明它来自内部 Provider 而非业务后端
认证中间件	middlewares + basicAuth.users	test:$apr1$...	以 HTTP Basic 认证拦截请求，凭据为 用户名:$apr1$盐$哈希 的 MD5-crypt 格式

关于 basicAuth 中间件更完整的字段说明（含 secret、removeHeader 等），参见 basicauth.md。

规则写法上，Host(\traefik.example.com`)与 Dashboard 文档中推荐的Host(...) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))` 组合规则是两种常见选择：纯 Host 规则更简洁，适合把整个管理域名专门留给 Traefik 管理界面；组合规则则适合在共享域名上按路径前缀精确圈定 API 与 Dashboard 的访问面。本示例集统一采用前者，读者可按需调整，规则语法细节可参考 路由规则文档 与 API Dashboard 文档中的 “Dashboard Router Rule” 一节。

4. 源码纵深：api@internal 是如何被注册和分发的

示例中的 api@internal 并非普通后端服务，其生命周期完全由源码决定：

1. 服务注册：internal.go 末尾无条件执行 cfg.HTTP.Services["api"] = &dynamic.Service{}（Dashboard 启用时再注册 dashboard 服务），这使得无论路由由哪个 Provider 提供，api@internal 服务都始终存在；
2. insecure 模式的自动路由：同文件 L291-L333 中，api.insecure 会在内部 traefik Entrypoint 上创建高优先级（math.MaxInt - 1）的 api Router，并附带 dashboard_redirect@internal、dashboard_stripprefix@internal 两个内建中间件实现 / 到 /dashboard/ 的跳转与前缀剥离——这也解释了为什么 insecure 模式下不需要本文第二节的任何配置，而开启 api.basePath 定制后二者互斥；
3. 请求分发：internalhandler.go 以服务名 api@internal 作为 case 分支，将命中该内部服务的请求转交 API handler，返回 /api/overview、/api/http/routers 等端点数据（完整端点列表见 api-dashboard.md 的 Endpoints 章节）；
4. 行为验证：集成测试中的 simple_secure_api.toml 等 fixture 正是按照“静态开启 API + 动态路由加认证”的同一模式组织用例，可结合 simple_test.go 查看端到端断言方式；CRD 侧则有 simple_to_api_internal.yml 演示 Gateway API 场景下引用 api@internal 的写法。

5. 安全注意事项

官方 API 与 Dashboard 文档 的 Security 章节给出了明确约束，本文所有示例均应在此前提下使用：

• 生产环境不建议直接公开 API 与 Dashboard，它们会暴露全部路由、服务、中间件等配置信息，访问应仅限管理员；
• 必须至少配置认证与授权——本文示例中的 basicAuth 即为最小认证手段，生产环境还应考虑 forwardAuth 对接 OIDC/WAF，或 IP 白名单等更强方案（参见 安全访问文档）；
• 不要公开暴露 API 端口，遵循最小权限原则将其限制在内部网络；
• 示例中的 test/test2 凭据仅用于演示，落地时必须替换为自行生成的强口令哈希，Kubernetes 场景还应将 Secret 纳入密钥管理流程。

6. 小结与延伸阅读

本文完整继承了 include-api-examples.md 的六类 Provider 配置示例，并补齐了上下文：api@internal 由 internal.go 在静态 api 启用时注册，由 internalhandler.go 完成请求分发；非 insecure 模式下 Router 必须自建，核心即“Host 规则 + api@internal 服务 + basicAuth 中间件”三要素，Docker/Swarm 标签中注意 $ 转义，Swarm 需附加虚拟服务端口，Kubernetes 则用 Secret 承载凭据。后续可结合 setup/docker.md 与 setup/kubernetes.md 完成整体验证。