Traefik Dashboard 对外暴露实战：api@internal 全 Provider 配置示例与内部服务路由原理

本文围绕 Traefik 官方文档中的 Dashboard 对外暴露示例片段（include-dashboard-examples.md）展开，完整覆盖 Docker、Swarm、Kubernetes CRD、Consul Catalog、File 等所有 Provider 的动态配置写法，并结合仓库源码深入解释 api@internal 内部服务是如何被注册、路由和保护的。读完之后，你将能够在任意部署形态下安全地把 Traefik API 与 Dashboard 暴露到外网域名，并理解 PathPrefix(/api) || PathPrefix(/dashboard) 路由规则背后的实现机制。

核心思路：为内部服务 api@internal 建一条受保护的路由

Traefik 的 Dashboard 本身不是一个独立进程，它的数据来自 Traefik 内置的 API。要让用户从外部访问 Dashboard，做法是：在动态配置中定义一个 HTTP Router，把它指向内置服务 api@internal，并挂上 BasicAuth 等中间件做鉴权。官方主文档 api-dashboard.md 在 “Dashboard” 一节明确说明：需要定义一个挂接在 api@internal 服务上的 router，用于实现认证（basicAuth、digestAuth、forwardAuth）或 IP 白名单（ipAllowList）等安全特性。

关键的路由规则必须同时匹配 /api 与 /dashboard 两个路径前缀，官方给出的规则模板为：

rule = "Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))"

原因是 Dashboard 前端页面加载后，会持续向 /api/... 端点（routers、services、middlewares、overview 等）发起 GET 请求拉取数据；如果规则只匹配 /dashboard，页面能打开但图表区域会因 API 请求 404 而无法工作。这正是示例片段中所有 Provider 变体共用的那条 rule。

此外官方还提醒：/dashboard/ 的尾部斜杠是必需的，可通过 RedirectRegex 中间件规避；虽然存在从 / 到 /dashboard/ 的重定向，但不应依赖该行为（它会随版本变化并干扰路由规则）。

各 Provider 的动态配置示例

以下内容完整继承自文档片段 include-dashboard-examples.md，按 Provider 分类。所有示例使用同一组演示账号（test / test2，MD5 格式的 htpasswd 凭据），生产环境请务必替换为自己的密码。

Docker & Swarm（普通 Docker 网络）

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

注意 Docker 标签中密码使用 $$apr1$$ 双美元符写法：$ 在 Docker 标签里是转义字符，$$ 表示字面量 $，最终 Traefik 收到的是标准的 user:$apr1$salt$hash htpasswd 格式。

Docker (Swarm) 服务

# Dynamic Configuration
deploy:
  labels:
    - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))"
    - "traefik.http.routers.dashboard.service=api@internal"
    - "traefik.http.routers.dashboard.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"

Swarm 形态下多一条特殊标签：traefik.http.services.dummy-svc.loadbalancer.server.port=9999。这是因为 Swarm Provider 需要端口信息来判定服务是否存在，而 api@internal 这类内置服务并没有真实的后端端口，所以用一个任意整数值的“哑服务”标签满足检测，Dashboard 流量的真实去向仍由 router 指定的 api@internal 决定。

Kubernetes CRD（IngressRoute + Middleware）

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard
spec:
  routes:
  - match: Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
    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"

Kubernetes 场景有两点差异值得注意：

• 服务引用通过 kind: TraefikService + name: api@internal 完成。源码中 Gateway API 与 CRD Provider 均显式支持跨 Provider 引用内部服务，例如 pkg/provider/kubernetes/gateway/httproute.go 中的注释 “Support for cross-provider references (e.g: api@internal)”。
• 凭据不落明文：basicAuth.secret 指向一个名为 secretName 的 Kubernetes Secret（标准 htpasswd 内容），而不是像标签方式那样直接写在配置里。

Consul Catalog

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

File (YAML)

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

File (TOML)

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

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

File 与 KV 类 Provider 中凭据是单 $ 的标准 htpasswd 格式；而 Docker/Swarm/Consul 标签场景需要 $$ 转义，这是跨 Provider 复用示例时最容易踩的坑。

源码视角：api@internal 是如何被接管的

从源码结构看，api@internal 并不是某个外部后端，而是 Traefik 内部注册的一组 HTTP Handler。核心实现位于 pkg/server/service/internalhandler.go：

case "api@internal":
    if m.api == nil {
        return nil, errors.New("api is not enabled")
    }
    return m.api, nil

case "dashboard@internal":
    if m.dashboard == nil {
        return nil, errors.New("dashboard is not enabled")
    }
    return m.dashboard, nil

InternalHandlers.BuildHTTP 只对以 @internal 结尾的服务名生效，并在静态配置未开启 API 时直接返回 “api is not enabled” 错误——也就是说，必须先有静态配置 api: {}（或 CLI --api=true），上述动态路由才有意义。

内置服务的注册发生在内置的 traefik Provider 中。pkg/provider/traefik/internal.go 的 apiConfiguration 负责在启用 api.insecure 时向内部入口点（端口 8080）注册高优先级路由：PathPrefix(/api) 指向 api@internal（优先级 math.MaxInt - 1），同时注册 dashboard_redirect（把 / 永久重定向到 /dashboard/）与 dashboard_stripprefix（剥离 /dashboard/ 前缀）两个内部中间件。这正是官方文档“/ 会重定向到 /dashboard/ 但不建议依赖”这一说明的代码出处。

而本片段讲解的“通过外网域名访问 Dashboard”方案，则是绕开 insecure 内部端口、走正常入口点 + 用户自定义 router 的路径，因此更安全：流量先经过你的 BasicAuth/allowlist 中间件，再由 InternalHandlers 把请求交给内部 API/Dashboard Handler。API 具体端点（/api/http/routers、/api/entrypoints、/api/overview、/api/version 等）可查阅 api-dashboard.md 的 “Endpoints” 表格。

安全建议与适用前提

结合 api-dashboard.md 的 “Security” 章节，生产环境使用这些示例时应遵循：

1. 不要裸奔暴露：API 会暴露全部路由/服务/中间件配置乃至敏感数据，应至少启用认证与授权，API 端口建议只保留在内网（最小权限原则）。
2. 凭据自行生成：示例中的 test/test2 哈希仅为演示，应使用 htpasswd 等工具生成你自己的 MD5/SHA256 哈希；Kubernetes 场景通过 Secret 管理凭据，避免明文进入 IngressRoute。
3. 规则二选一：文档同时推荐了 Host 规则（Host(traefik.example.com)，匹配该域名下所有请求）与 双 PathPrefix 组合规则（示例片段采用后者），按域名的独占程度选择即可；示例统一使用组合规则以便同一域名上还有其他业务。
4. 规则语法前提：以上 rule 均为 Traefik v3 默认规则语法（RuleSyntax: "default"，见 internal.go 中的注释），与仓库当前版本一致。

延伸阅读

• 静态配置项（api、api.basePath、api.insecure、api.debug 等）与全部 API 端点清单：api-dashboard.md
• 自定义路径场景（PathPrefix(/traefik) 变体）的示例片段：include-dashboard-custom-path-examples.md
• 仅暴露 /api 而不含 /dashboard 的变体：include-api-examples.md
• 内部服务注册实现：pkg/provider/traefik/internal.go；服务名到 Handler 的映射：pkg/server/service/internalhandler.go
• 集成测试可验证 api@internal 在 rawdata 端点中的行为，参见 integration/https_test.go