跳到正文
Træfɪk

Docker

本指南详细介绍如何使用官方 Traefik Docker 镜像与 Docker Compose，在 Docker 容器内安装和配置 Traefik Proxy。指南涵盖以下内容：

  • 启用 Docker 提供者
  • 暴露 web（HTTP :80）和 websecure（HTTPS :443）入口点
  • 将所有 HTTP 流量重定向到 HTTPS
  • 使用 basic-auth 保护 Traefik 仪表盘
  • 使用适用于 *.docker.localhost 的自签名证书终止 TLS
  • 部署 whoami 演示服务
  • 启用访问日志和 Prometheus 指标

前提条件

  • Docker Desktop / Engine
  • Docker Compose
  • openssl
  • htpasswd（由 apache2-utils 提供）

创建自签名证书

Traefik 需要证书才能在本地提供 HTTPS。在生产环境中应使用可信 CA 签发的证书，但对于单机应用栈，快速生成的自签名证书就足够了。可以运行以下命令，通过 openssl 创建证书：

mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/local.key -out certs/local.crt \
  -subj "/CN=*.docker.localhost"

现在，certs 文件夹中包含 local.crt 和 local.key，它们将以只读方式挂载到 Traefik 中。

创建 Traefik 仪表盘凭证

在生产环境中，建议为 Traefik 仪表盘配置某种形式的身份验证或安全保护。可以通过 basic-auth 中间件保护 Traefik。为此，生成一组带哈希的用户名与密码凭证，供 Traefik 中间件验证：

htpasswd -nb admin "P@ssw0rd" | sed -e 's/\$/\$\$/g'

复制完整输出（例如 admin:$$apr1$$…），稍后配置中间件时需要使用。

创建 docker-compose.yaml

现在，在 Compose 文件中定义整个应用栈。此文件声明 Traefik、挂载证书、设置专用网络，后面还将包含 whoami 演示服务。

说明

您也可以选择通过 Docker CLI 和配置文件运行 Traefik，但本教程使用 Docker Compose。

首先，创建名为 dynamic 的文件夹，并创建用于动态配置的 tls.yaml 文件。将 TLS 证书配置粘贴到文件中：

tls:
  certificates:
    - certFile: /certs/local.crt
      keyFile:  /certs/local.key

在项目根文件夹（dynamic/tls.yaml 文件的父级目录）中创建 docker-compose.yaml，并填入以下内容：

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

    networks:
     # Connect to the 'traefik_proxy' overlay network for inter-container communication across nodes
      - proxy

    ports:
      - "80:80"
      - "443:443"

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs:ro
      - ./dynamic:/dynamic:ro

    command:
      # EntryPoints
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"

      # Attach the static configuration tls.yaml file that contains the tls configuration settings
      - "--providers.file.filename=/dynamic/tls.yaml"

      # Providers 
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"

      # API & Dashboard 
      - "--api.dashboard=true"
      - "--api.insecure=false"

      # Observability 
      - "--log.level=INFO"
      - "--accesslog=true"
      - "--metrics.prometheus=true"

  # Traefik Dynamic configuration via Docker labels
    labels:
      # Enable self‑routing
      - "traefik.enable=true"

      # Dashboard router
      - "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.tls=true"

      # Basic‑auth middleware
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=<PASTE_HASH_HERE>"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"

# Whoami application
  whoami:
    image: traefik/whoami
    container_name: whoami
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"

networks:
  proxy:
    name: proxy

提示

  • 记得将 <PASTE_HASH_HERE> 替换为之前生成的哈希。
  • --api.insecure=false 标志用于保护 API，避免在 8080 端口暴露仪表盘。之所以这样配置，是因为我们通过 HTTPS 路由器暴露仪表盘。

启动应用栈

准备好 Compose 文件和配套资源后，启动容器，由 Docker 在后台连接网络：

docker compose up -d

Traefik 启动后，会从 command 参数读取静态配置，连接 Docker 套接字，通过自身的标签发现动态配置（仪表盘路由和身份验证），并开始监听 80 和 443 端口。HTTP 请求将被重定向到 HTTPS。

访问仪表盘

Traefik 部署完成后，您可以通过 https://dashboard.docker.localhost 访问仪表盘，它应会提示输入您配置的基本身份验证凭证：

Traefik 仪表盘

测试 whoami 应用

您可以使用 curl 测试应用：

curl -k https://whoami.docker.localhost/
Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1

向 HTTP 入口点发出相同请求，会返回以下结果：

curl -k http://whoami.docker.localhost

Moved Permanently

上述结果确认发生了重定向，说明部署运行正常。

您也可以在浏览器中访问 https://whoami.docker.localhost，查看服务输出的 JSON 数据：

Whoami 服务

提示

您还可以通过 https://dashboard.docker.localhost 进入 Traefik 仪表盘，确认路由已创建。

其他关键配置领域

除了这一初始部署，Traefik 还提供丰富的配置能力。下面使用 Docker Compose 的 command 参数或 labels 给出简要介绍和最小示例。完整信息请参阅所链接的主文档。

TLS 证书管理（Let's Encrypt）

要让 websecure 入口点自动提供有效的 HTTPS 证书，请启用 Let's Encrypt（ACME）。

command 新增配置示例：

command:
  # ... other command arguments ...
  - "[email protected]"
  - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json" # Path inside container volume
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"

  # - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Needs provider setup

  # Optionally make 'le' the default resolver for TLS-enabled routers
  - "--entrypoints.websecure.http.tls.certresolver=le"

这会定义名为 le 的解析器，设置必需的电子邮件和存储路径（位于挂载的 /letsencrypt 卷内），并启用 HTTP 质询。质询和 DNS 提供商配置的详细信息，请参阅 HTTPS/TLS 文档和 Let's Encrypt 文档。

指标（Prometheus）

您可以暴露 Traefik 的内部指标，供 Prometheus 监控。此前的配置中已经启用了 Prometheus，但还可以进一步配置。 command 新增配置示例：

command:
  # If using a dedicated metrics entry point, define it:
  - "--entrypoints.metrics.address=:8082"

  # ... other command arguments ...
  - "--metrics.prometheus=true"

  # Optionally change the entry point metrics are exposed on (defaults to 'traefik')
  - "--metrics.prometheus.entrypoint=metrics"

  # Add labels to metrics for routers/services (can increase cardinality)
  - "--metrics.prometheus.addrouterslabels=true"
  - "--metrics.prometheus.addserviceslabels=true"

这会启用 /metrics 端点（通常通过内部 API 端口访问；未保护时默认常为 8080，也可通过专用入口点访问）。可用选项请参阅指标文档。

追踪（OTel）：

您可以启用分布式追踪，跟踪请求经过 Traefik 的过程。 command 新增配置示例：

command:
  # ... other command arguments ...
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector:4317" # Adjust endpoint as needed
  - "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed

说明

此选项需要一个正在运行且可由 Traefik 访问的 OTEL 收集器。请参阅追踪文档。

访问日志

您可以配置 Traefik 记录传入请求，用于调试和分析。 command 新增配置示例：

command:
  # ... other command arguments ...
  - "--accesslog=true" # Enable access logs to stdout

  # Optionally change format or output file (requires volume)
  - "--accesslog.format=json"
  - "--accesslog.filepath=/path/to/access.log"

  # Optionally filter logs
  - "--accesslog.filters.statuscodes=400-599"

这会将访问日志输出到容器的标准输出（可通过 docker compose logs <traefik-container-id> 查看）。请参阅访问日志文档。

结语

现在，您已在 Docker 中完成 Traefik 的基本部署，具备安全的仪表盘访问和 HTTP 到 HTTPS 重定向。

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。

查看官方原文源码

版权所有 © 头文件软件工作室

文档由 HeadFile Studio 翻译。

Traefik v3.7 中文快照 · 原文版权归 Traefik Labs 及贡献者所有 · MIT 许可证