中文

应用程序

使用 Docker 部署 Traefik 反向代理

在 Debian 或 Ubuntu 上使用 Docker Compose 部署 Traefik:通过 Let's Encrypt 自动启用 HTTPS,以标签发布应用,保护仪表板,并完成更新与备份。

阅读约 10 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何将 Traefik 部署在 Docker 容器的前端。Traefik 在 80 和 443 端口接收访客请求,获取并续期 Let’s Encrypt 证书,再根据标签将每个请求转发给相应的容器。

完成本指南后,一个测试应用将通过 https://app.您的域名.com 响应。Traefik 的仪表板位于 https://traefik.您的域名.com,仅允许从您的 IP 地址访问,并需要密码。您也将掌握如何更新和备份这套安装。

文中标注的版本是撰写时(2026 年 11 月)的最新稳定版本:Traefik v3.7.19 和 whoami v1.12.0。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

  • 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
  • 使用具有 sudo 权限且属于 docker 组的用户进行 SSH 访问
  • 已按照指南安装 Docker Engine 和 Docker Compose安装 Docker Engine 和 Docker Compose
  • 一个由您管理 DNS 区域的域名
  • 没有其他软件占用 80 和 443 端口,例如 Nginx、Apache、Caddy 或 Nginx Proxy Manager
  • 您电脑上的固定 IP 地址用于访问仪表板,或使用 VPN

使用的端口

端口 方向 作用 是否需要开放
80/tcp 入站 HTTP-01 验证以及重定向到 HTTPS 是
443/tcp 入站 HTTPS 站点和仪表板 是
8080/tcp 无 Traefik 的非安全 API,此处已禁用 否
2375/tcp Docker 内部网络 Docker socket 代理,绝不在服务器上发布 否

步骤 1:将域名指向服务器

创建两条指向 您的服务器IP 的 A 记录:app.您的域名.com 和 traefik.您的域名.com。如果您的域名由 HostMyServers 管理,请参阅指南创建 A 记录。

然后在服务器上检查结果:

终端
sudo apt update
sudo apt install -y bind9-dnsutils
dig +short A app.您的域名.com
dig +short A traefik.您的域名.com
dig +short AAAA traefik.您的域名.com

前两条命令应返回您服务器的地址。最后一条命令的结果必须为空:仪表板按 IPv4 地址进行过滤,通过 IPv6 发起的连接会被拒绝。

步骤 2:准备文件夹和网络

创建项目文件夹以及用于存放证书的文件。如果除所有者之外的其他用户可以读取该文件,Traefik 会拒绝使用它。

终端
sudo install -d -o "$USER" -g "$USER" /opt/traefik /opt/traefik/letsencrypt
cd /opt/traefik
touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json

接着创建 Traefik 与待发布应用共用的 Docker 网络:

终端
docker network create proxy

步骤 3:创建仪表板密码

安装 htpasswd,然后为 admin 账户生成哈希值。该命令会要求您输入两次密码:

终端
sudo apt install -y apache2-utils
htpasswd -nB admin > /opt/traefik/dashboard.htpasswd
chmod 600 /opt/traefik/dashboard.htpasswd

该文件保存的是 bcrypt 哈希值,而不是明文密码。将其放在文件中,可以避免在 Docker Compose 标签里将 $ 字符写成双倍。

步骤 4:编写 Compose 文件

创建文件:

终端
nano /opt/traefik/compose.yaml

粘贴以下内容,并替换域名、邮箱地址和 您的IP:

YAML
services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:3.4
    container_name: traefik-socket-proxy
    restart: unless-stopped
    environment:
      CONTAINERS: "1"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket

  traefik:
    image: traefik:v3.7.19
    container_name: traefik
    restart: unless-stopped
    depends_on:
      - socket-proxy
    security_opt:
      - no-new-privileges:true
    ports:
      - "80:80"
      - "443:443"
    command:
      - "--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"
      - "--entrypoints.websecure.http.tls.certresolver=le"
      - "--providers.docker=true"
      - "--providers.docker.endpoint=tcp://socket-proxy:2375"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--api.dashboard=true"
      - "--api.insecure=false"
      - "--certificatesresolvers.le.acme.email=admin@您的域名.com"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--log.level=INFO"
      - "--accesslog=true"
    volumes:
      - ./letsencrypt:/letsencrypt
      - ./dashboard.htpasswd:/etc/traefik/dashboard.htpasswd:ro
    networks:
      - proxy
      - socket
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.您的域名.com`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-ip,dashboard-auth"
      - "traefik.http.middlewares.dashboard-ip.ipallowlist.sourcerange=您的IP/32"
      - "traefik.http.middlewares.dashboard-auth.basicauth.usersfile=/etc/traefik/dashboard.htpasswd"

networks:
  proxy:
    external: true
  socket:
    internal: true
元素 作用
socket-proxy 过滤对 Docker API 的访问:Traefik 可以读取容器,但不能创建或修改容器
CONTAINERS: "1" 允许读取容器,写入请求默认仍被阻止
socket 内部网络,无法访问互联网,仅供 Traefik 和该代理使用
exposedbydefault=false 只有带有 traefik.enable=true 的容器才会被发布
network=proxy Traefik 通过该网络连接各个应用
httpchallenge Let’s Encrypt 通过 80 端口验证每个域名
certresolver=le HTTPS 入口点下的所有站点都会获得证书
api@internal 提供仪表板的内部服务
dashboard-ip 然后 dashboard-auth 先过滤 IP 地址,再要求输入密码

Traefik 不会直接挂载 Docker socket:即使暴露在互联网上的容器被入侵,攻击者也无法获得对 Docker 的控制权。这是 Traefik 文档推荐的防护措施之一。

步骤 5:启动 Traefik

验证文件,然后启动容器:

终端
cd /opt/traefik
docker compose config --quiet
docker compose up -d
docker compose ps

两个服务都应处于 running 状态。请在日志中查看启动过程,然后按 Ctrl+C 退出:

终端
docker compose logs -f traefik

步骤 6:检查防火墙

Docker 使用自己的规则发布 80 和 443 端口,这些规则先于 UFW 的规则生效。因此,即使没有执行 ufw allow,这两个端口也可以被访问,UFW 无法对其进行限制。指南配置 UFW 防火墙详细介绍了这一机制。

由此得出两条规则:

  • 不要发布您应用的端口:它们保留在 proxy 网络中,不要写 ports 部分。
  • 如果您使用实例自带的防火墙,请同时在客户中心允许 80 和 443 端口。

步骤 7:发布应用

在单独的文件夹中创建一个测试应用:

终端
sudo install -d -o "$USER" -g "$USER" /opt/whoami
nano /opt/whoami/compose.yaml
YAML
services:
  whoami:
    image: traefik/whoami:v1.12.0
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`app.您的域名.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

启动它:

终端
cd /opt/whoami
docker compose up -d

Traefik 会自动检测到该容器,无需重启。标签 loadbalancer.server.port 指定的是容器内部的监听端口。对于您自己的应用,请沿用这四个标签,只需修改路由器名称、域名和端口。

验证结果

测试两种协议,然后检查证书:

终端
curl -I http://app.您的域名.com
curl -I https://app.您的域名.com
echo | openssl s_client -connect app.您的域名.com:443 -servername app.您的域名.com 2>/dev/null | openssl x509 -noout -issuer -dates

HTTP 请求应返回指向 HTTPS 的 308 重定向,HTTPS 请求应返回 200 状态码。证书的颁发者应为 Let’s Encrypt。获取第一张证书可能需要片刻时间。

接着检查 socket 代理是否确实阻止了未授权的请求:

终端
cd /opt/traefik
docker compose exec traefik wget -S -O- http://socket-proxy:2375/images/json

预期响应为 403 Forbidden。

在您的电脑上测试仪表板。第一次调用应返回 401,第二次返回 Traefik 的版本,第三次不应有响应:

终端
curl -I https://traefik.您的域名.com/dashboard/
curl -u admin https://traefik.您的域名.com/api/version
curl -m 5 http://您的服务器IP:8080

最后,在浏览器中打开 https://traefik.您的域名.com/dashboard/。末尾的斜杠不可省略。从其他 IP 地址访问同一页面时,应返回 403。

管理仪表板访问

要更改密码,请重新生成文件,然后重启 Traefik:

终端
cd /opt/traefik
htpasswd -nB admin > dashboard.htpasswd
docker compose restart traefik

如果您的 IP 地址发生变化,请修改 compose.yaml 中的标签 dashboard-ip,然后执行 docker compose up -d。如果 IP 地址经常变化,建议改为通过 WireGuard 或 Tailscale 将仪表板限定在私有网络中。

常用设置

响应多个域名

YAML
- "traefik.http.routers.whoami.rule=Host(`app.您的域名.com`) || Host(`www.您的域名.com`)"

每个域名都必须指向该服务器,才能签发证书。

用相同规则保护应用

在 Traefik 容器上声明的中间件可供其他容器复用,只需加上后缀 @docker:

YAML
- "traefik.http.routers.whoami.middlewares=dashboard-ip@docker,dashboard-auth@docker"

更新

请先查看版本说明;如果是次版本或主版本的变更,还请查看迁移指南。然后备份安装,修改 compose.yaml 中的标签 traefik:v3.7.19,再执行:

终端
cd /opt/traefik
docker compose pull
docker compose up -d
docker compose exec traefik traefik version
docker compose logs --tail 50 traefik

镜像 tecnativa/docker-socket-proxy:3.4 保持在 HAProxy 3.4 分支上,其发布方每周都会重新构建:docker compose pull 会获取这些更新。请以同样的方式处理 /opt/whoami 以及您各个应用的文件夹。

备份与恢复

文件夹 /opt/traefik 包含所有需要保留的内容:

路径 内容
compose.yaml Traefik 和 socket 代理的配置
dashboard.htpasswd 仪表板密码的哈希值
letsencrypt/acme.json 证书、私钥和 ACME 账户
终端
sudo tar -czf /root/traefik-$(date +%F).tar.gz -C /opt traefik
sudo chmod 600 /root/traefik-$(date +%F).tar.gz

该归档包含私钥:请将其复制到服务器之外的加密位置。同时也请备份您应用的 Compose 文件和数据。

要恢复归档,请将 YYYY-MM-DD 替换为归档的日期,如果该服务器上尚不存在 proxy 网络,请先创建它:

终端
cd /opt/traefik 2>/dev/null && docker compose down
sudo tar -xzf /root/traefik-YYYY-MM-DD.tar.gz -C /opt
docker network create proxy
cd /opt/traefik
docker compose up -d

故障排除

请先查看日志:

终端
cd /opt/traefik
docker compose logs --tail 100 traefik
docker compose logs --tail 50 socket-proxy

port is already allocated 或 address already in use

另一个服务占用了 80 或 443 端口:

终端
sudo ss -ltnp | grep -E ':(80|443) '
docker ps --format '{{.Names}} {{.Ports}}'

如果不再需要该服务,请将其停止,例如使用 sudo systemctl disable --now nginx。

permissions 644 for /letsencrypt/acme.json are too open, please use 600

修正权限,然后重启 Traefik:

终端
chmod 600 /opt/traefik/letsencrypt/acme.json
cd /opt/traefik
docker compose restart traefik

Failed to retrieve information of the docker client and server host

Traefik 无法连接到 socket 代理。请检查 socket-proxy 是否正在运行,以及两个服务是否共用 socket 网络。根据其日志中指明的原因:

  • 如果服务器没有 IPv6 且代理无法启动,请在其环境变量中添加 DISABLE_IPV6: "1"。
  • 如果缺少 CONTAINERS,Traefik 在列出容器时会收到 403 Forbidden。
  • 如果代理无权打开 socket,其发布方指出,在某些 SELinux 或 AppArmor 配置下可能需要 privileged: true。仅在万不得已时才添加此选项。

404 page not found

没有任何路由器与该请求匹配。请检查容器是否已启动、是否带有 traefik.enable=true、Host() 中的域名是否准确,以及它是否已连接到 proxy 网络:

终端
docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'

Bad Gateway 或 Gateway Timeout

Traefik 找到了路由器,但无法连接到应用。请检查 loadbalancer.server.port 中指定的端口,然后从 Traefik 内部进行测试:

终端
cd /opt/traefik
docker compose exec traefik wget -qO- http://whoami:80

应用必须在其容器内监听 0.0.0.0。如果它只监听 127.0.0.1,Traefik 将无法访问它。

浏览器显示 TRAEFIK DEFAULT CERT

Traefik 尚未获得该域名的有效证书,因此展示了它的默认证书。请在日志中查找原因:

终端
cd /opt/traefik
docker compose logs traefik | grep -iE 'acme|certificate'

Unable to obtain ACME certificate for domains

消息中包含被拒绝的原因:

  • urn:ietf:params:acme:error:dns:该域名在 DNS 中尚不存在,或传播尚未完成。
  • urn:ietf:params:acme:error:unauthorized 或 connection:Let’s Encrypt 无法连接到 80 端口。请检查 A 和 AAAA 记录,然后检查实例的防火墙。如果一切正常,请通过客户中心联系支持团队。
  • urn:ietf:params:acme:error:caa:某条 CAA 记录禁止了 Let’s Encrypt。
  • urn:ietf:params:acme:error:rateLimited:发送的请求过多。请等待消息中指明的时间段结束。

测试时,请临时加入 Let’s Encrypt 的测试环境(其证书不被浏览器信任):

YAML
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

在切换回生产环境之前,请删除这一行,并使用 truncate -s 0 /opt/traefik/letsencrypt/acme.json 清空 acme.json,且不要修改其权限。然后执行 docker compose up -d。

仪表板出现 403 Forbidden

您的 IP 地址与标签 dashboard-ip 中的地址不一致。访问日志的行首显示了 Traefik 看到的地址:

终端
cd /opt/traefik
docker compose logs --no-log-prefix traefik | grep 'dashboard@docker' | tail -n 5

如果该地址是 Docker 网关的地址,说明连接很可能是通过 IPv6 到达的:请删除该域名的 AAAA 记录。

dashboard.htpasswd 出现 is a directory

首次启动时该文件不存在,Docker 便创建了一个同名文件夹。请删除该文件夹,重新创建文件,然后重启容器:

终端
cd /opt/traefik
docker compose down
sudo rmdir dashboard.htpasswd
htpasswd -nB admin > dashboard.htpasswd
chmod 600 dashboard.htpasswd
docker compose up -d

参考资料