使用 Docker 部署 Traefik 反向代理
在 Debian 或 Ubuntu 上使用 Docker Compose 部署 Traefik:通过 Let's Encrypt 自动启用 HTTPS,以标签发布应用,保护仪表板,并完成更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何将 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:
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.yamlservices:
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 -dTraefik 会自动检测到该容器,无需重启。标签 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 -datesHTTP 请求应返回指向 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 将仪表板限定在私有网络中。
常用设置
响应多个域名
- "traefik.http.routers.whoami.rule=Host(`app.您的域名.com`) || Host(`www.您的域名.com`)"每个域名都必须指向该服务器,才能签发证书。
用相同规则保护应用
在 Traefik 容器上声明的中间件可供其他容器复用,只需加上后缀 @docker:
- "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-proxyport 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 traefikFailed 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 的测试环境(其证书不被浏览器信任):
- "--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