Traefik 最近终于发布了大版本升级后的第一个修正版本,或许是时候正式迁移程序到新版本了。

写在前面

Traefik 3 正式发布

最近 Traefik 发布了 3.1 版本。作为从 Traefik 1.x 开始使用的用户,Traefik 每个大版本升级都会出现一些配置不兼容的情况,这次 3.x 的正式升级也不例外。

虽然早在 Traefik 3.0 beta 的时候,我就写过尽可能兼容 3.x 版本的上手内容《Traefik v3.0 Docker 全面使用指南:基础篇》,上个季度正式发布 3.0 后,我们还是需要调整一些配置。

为了简化配置和上手的过程,我将我使用的基础配置开源在了 soulteary/traefik-v3-example,有需要可以自取。

下面,让我们来了解 Traefik 3 正式版的使用。

准备工作

为了上手简单,我们使用上面的开源项目代码为基础进行配置。

默认情况下,服务将运行在 80443 端口,所以,需要确保这两个端口没有其他程序占用。

获取基础配置代码

使用 git 将包含基础配置的项目下载到本地:

git clone https://github.com/soulteary/traefik-v3-example.git

然后进入代码目录:

cd traefik-v3-example

Docker 环境

关于 Docker 环境的准备,非常简单。

Docker, Develop faster, Run anywhere.

如果你使用的是图形化界面,尤其是 Windows 或者 macOS,可以访问 “Docker 官方网站”,从网页下载安装程序,“一路下一步”,完成环境准备。

当然,你也可以参考之前的一些文章:

准备 Traefik Docker 专用网络

在完成 Docker 的安装后,我们执行代码目录的脚本文件,就能够自动创建 Traefik 运行所需要的虚拟网络了:

bash scripts/prepare-network.sh

命令执行后,如果一切正常,我们能够看到类似下面的日志内容:

# bash scripts/prepare-network.sh

create docker network for traefik ok

让 Traefik 支持使用 HTTPS 证书

Traefik 支持两种方式来使用 HTTPS 证书:一种是使用我们准备好的证书文件,另一种是为我们拥有的域名自动申请“Let’s Encrypt”免费证书。去年这家非盈利证书机构已经为 3.63 亿网站提供了 TLS 证书。

关于第一种方式,我们可以在各种云服务商处购买或者申请免费的 HTTPS 证书,将 HTTPS 证书下载到本地,放在项目目录的 ssl 目录中即可。

当然,我们也可以贯彻免费到底,根据自己需求,自己生成一套证书来使用。

快速生成一套自己的签名证书

这里,推荐一个几年前写的开源证书生成小工具:soulteary/certs-maker。如果你对自签名证书的基础知识、如何快速部署到系统感兴趣,可以阅读之前的文章:《如何制作和使用自签名证书》。

如果你已经完成了 Docker 的安装,那么只需要使用下面的命令,就能够快速的完成自签名证书的生成了:

docker run --rm -it -v `pwd`/ssl:/ssl soulteary/certs-maker:v3.5.0 "--CERT_DNS=lab.com,*.lab.com,*.data.lab.com"

当命令执行后,就能够得到证书文件了。

[soulteary/certs-maker] v3.5.0

Flags:
  - CERT_COUNTRY= CN
  - CERT_STATE= BJ
  - CERT_LOCALITY= HD
  - CERT_ORGANIZATION= Lab
  - CERT_ORGANIZATIONAL_UNIT= Dev
  - CERT_COMMON_NAME= Hello World
  - CERT_DOMAINS= [lab.com *.lab.com *.data.lab.com]
  - APP_FOR_K8S= false
  - APP_FOR_FIREFOX= false
  - APP_OUTPUT_DIR= ./ssl

上面的命令中,我们指定了本地系统目录的 ssl 目录和容器内的 /ssl 目录打通,所以只需要查看本地的 ssl 目录,就能够验收证书了:

ls ssl    
lab.com.conf lab.com.crt  lab.com.key

不论是购买的证书还是自己生成的证书,我们只要放在 ssl 目录中就可以了,一会再用。

更新 Traefik 配置文件

根据你想 Traefik 使用 HTTPS 证书方式的不同,我们需要对示例代码的配置进行一些调整。

如果你选择自签名证书(参考上面的方法生成),或者云服务商处购买的域名,我们需要修改项目中的 .env 配置文件和 config/tls.toml 配置。

.env 配置文件中,我们需要将 Traefik 管理界面的域名地址修改为适配证书的域名:

# 服务域名
SERVICE_DOMAIN=traefik.example.com

并在 config/certs.toml 配置中,更新相关的域名:

[tls.stores.default.defaultCertificate]
certFile = "/data/ssl/example.com.crt"
keyFile = "/data/ssl/example.com.key"

[[tls.certificates]]
certFile = "/data/ssl/example.com.crt"
keyFile = "/data/ssl/example.com.key"

# others...
# [[tls.certificates]]
# certFile = "/data/ssl/lab.com.crt"
# keyFile = "/data/ssl/lab.com.key"

如果你拥有域名,希望使用免费申请的 HTTPS 证书,我们可以删除掉 config/certs.toml 配置文件,然后更新 .env 中的相关配置:

# 服务域名
SERVICE_DOMAIN=traefik.example.com

# 示例,使用 CloudFlare 来申请证书
ACME_PROVIDER=cloudflare
ACME_EMAIL=your-email@company.ltd

# CF DNS API Token
CF_DNS_API_TOKEN=your-cf-dns-api-token

# DNS Domain (main)
DNS_MAIN=example.com
# DNS Domain (list)
DNS_LIST=example.com,*.example.com

除了要和上面一样更新域名之外,我们还需要配置一些申请免费证书必须的配置,包括下面的内容(使用 CloudFlare DNS 申请证书为例):

  • ACME_PROVIDER:使用什么方式来申请免费证书。
  • ACME_EMAIL:申请证书要使用的邮箱。
  • CF_DNS_API_TOKEN:我使用 Cloudflare,这里需要配置 API Token 来操作 DNS 记录,完成域名所有权验证,进行证书申请。
  • DNS_MAINDNS_LIST 我们想要申请的域名证书列表,需要拥有域名所有权,比如,你不能够申请 www.google.com 或者 www.apple.com 这种不属于你的域名。

至于 Cloudflare 的 API Key,我们可以在登录后的“API 令牌”页面获得,配置方式参考下面的图片:

配置 CloudFlare API Key

快速上手

下面来分别介绍两种启动并使用 Traefik ,支持使用 HTTPS 证书的方法。

快速启动一个 Traefik 3 正式版程序

我们先来介绍配合购买或使用自签名的证书文件的使用方式。

想要使用这种方式,我们需要将目录中的 docker-compose.local-certs.yml 重命名为 docker-compose.yml,或者复制一份,将配置文件进行改名:

cp docker-compose.local-certs.yml docker-compose.yml

上面的准备工作结束后,在代码目录中,我们执行下面的命令,就能够自动启动 Traefik 来提供服务了。

docker compose down && docker compose up -d

命令执行后,我们将看到类似下面的日志内容:

# docker compose down && docker compose up -d

[+] Building 0.0s (0/0)                                                                                                                                               docker:desktop-linux
[+] Running 1/1
 ✔ Container traefik  Started

如果我们执行 docker compose ps,将能够看到 Traefik 健康运行:

NAME      IMAGE            COMMAND                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               SERVICE   CREATED         STATUS                   PORTS
traefik   traefik:v3.1.1   "/entrypoint.sh --global.sendanonymoususage=false --global.checknewversion=false --entrypoints.http.address=:80 --entrypoints.https.address=:443 --entryPoints.https.asDefault=true --entryPoints.https.http3 --entryPoints.https.http3.advertisedport=443 --serverstransport.insecureskipverify=true --entryPoints.http.forwardedHeaders.trustedIPs=127.0.0.1/32,172.18.0.1/24 --entryPoints.https.forwardedHeaders.trustedIPs=127.0.0.1/32,172.18.0.1/24 --api=true --api.dashboard=true --ping=true --log.level=INFO --log.maxsize=100 --log.format=common --accesslog=false --providers.docker=true --providers.docker.watch=true --providers.docker.exposedbydefault=false --providers.docker.endpoint=unix:///var/run/docker.sock --providers.docker.useBindPortIP=false --providers.docker.network=traefik --providers.file=true --providers.file.watch=true --providers.file.directory=/etc/traefik/config --providers.file.debugloggeneratedtemplate=true"   traefik   3 minutes ago   Up 3 minutes (healthy)   0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:443->443/udp

当服务出现问题的时候,Docker 将会自动恢复程序的运行。

在这个示例代码中,默认的自签名证书支持 example.com*.exmaple.com 相关的域名,而 Traefik 默认的管理界面域名是 traefik.example.com

我们可以通过修改系统的 /etc/hosts 或者局域网 DNS 指向,将 traefik.example.com 指向启动 traefik 容器的 IP 地址。比如,我启动的容器在本地:

127.0.0.1 traefik.example.com

使用浏览器访问 https://traefik.example.com ,我们就能够看到 Traefik 的管理界面了:

Traefik 的管理界面

如果你使用的是购买的证书,那么图中的小红锁默认应该就是绿色的。

信任自签名的 HTTPS 证书后,锁子就变绿了

如果你使用的是自签名证书,我们可以通过信任自签名证书,来解决浏览器中展示的“小红锁”,在不泄漏自签名证书的前提下,同样能够保证安全的访问,以及 HTTP2/3 请求特性。

启动 Traefik 并自动申请 HTTPS 证书

如果我们拥有某个域名,并且希望 Traefik 能够自动从网上申请免费的 HTTPS 证书,可以使用下面的方式。

我们需要将目录中的 docker-compose.acme.yml 重命名为 docker-compose.yml,或者复制一份,将配置文件进行改名:

cp docker-compose.acme.yml docker-compose.yml

本文中,我使用的是 CloudFlare 的方式来申请证书,所以我们需要确保配置文件 .env 中的变量 CF_DNS_API_TOKEN 配置在 docker-compose.yml 中:

environment:
  - CF_DNS_API_TOKEN=${CF_DNS_API_TOKEN}

和上文中一样,我们使用下面的命令,就能够创建干净的容器,来运行 Traefik 并自动申请证书了:

docker compose down && docker compose up -d

使用这种方式注册的证书,Traefik 会进行自动维护,在证书到期之前进行自动替换。不过,第一次注册的时候会比较漫长,如果我们打开 Traefik 可能看到它的申请或者证书续期的过程:

# docker compose logs -f

traefik  | 2024-08-04T19:23:17+08:00 INF Traefik version 3.1.1 built on 2024-07-30T13:55:22Z version=3.1.1
traefik  | 2024-08-04T19:23:17+08:00 INF 
traefik  | Stats collection is disabled.
traefik  | Help us improve Traefik by turning this feature on :)
traefik  | More details on: https://doc.traefik.io/traefik/contributing/data-collection/
traefik  | 
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider aggregator aggregator.ProviderAggregator
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider *file.Provider
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider *traefik.Provider
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider *docker.Provider
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider *acme.ChallengeTLSALPN
traefik  | 2024-08-04T19:23:17+08:00 INF Starting provider *acme.Provider
traefik  | 2024-08-04T19:23:17+08:00 INF Testing certificate renew... acmeCA=https://acme-v02.api.letsencrypt.org/directory providerName=le.acme
...

一般情况下,3~5 分钟证书就注册好了。

快速启动一个服务,注册到 Traefik 上

接下来,使用一个简单的例子,来说明如何将一个运行在某个具体端口上的程序,注册到 Traefik 网关中,并支持 HTTPS 访问。

还是以之前写过的一个简单的开源程序 flare 为例,下面的命令将下载 flare 并运行它,最终允许我们使用 5005 端口来访问它:

docker pull soulteary/flare:0.5.1
docker run --rm -it -p 5005:5005 soulteary/flare:0.5.1

运行在指定端口上的 Flare 程序

如果我们访问 http://localhost:5005 ,就能够看到上面的界面啦。

我们将上面的命令简化,去掉调试和自动清理容器的参数:

docker run -p 5005:5005 soulteary/flare:0.5.1

使用工具转换 Docker 命令为 Compose 配置

然后,我们将命令粘贴到在线转换 Docker 命令到 Compose 的工具里,可以得到最简单的 Docker Compose 配置文件:

name: flare
services:
  flare:
    ports:
      - 5005:5005
    image: soulteary/flare:0.5.1

我们可以对上面的配置进行一些修改,将上面的通过 5005 端口访问的程序,能够通过 flare.example.com 进行访问,并且支持自动将 HTTP 请求转换为 HTTPS 请求,并对访问内容自动进行 GZIP 压缩,提升访问加速:

name: flare
services:
  flare:
    image: soulteary/flare:0.5.1
    networks:
      - traefik
    labels:
      # 用于 Traefik 服务发现
      - "traefik.enable=true"
      - "traefik.docker.network=traefik"
      # HTTP 相关
      # 使用 HTTP 协议访问 Flare,将使用 `http`(80端口) 提供服务
      - "traefik.http.routers.flare-http.entrypoints=http"
      # 并自动跳转至 HTTPS 协议(443端口)
      - "traefik.http.routers.flare-http.middlewares=redir-https"
      # 默认服务域名为 flare.example.com
      - "traefik.http.routers.flare-http.rule=Host(`flare.example.com`)"
      # 服务名称为 noop@internal,表示不提供任何服务 (因为自动跳转,没必要请求服务)
      - "traefik.http.routers.flare-http.service=noop@internal"
      # HTTPS 相关
      # 使用 HTTPS 协议访问 Flare,将使用 `https`(443端口) 提供服务
      - "traefik.http.routers.flare-https.entrypoints=https"
      # 在这个端口上使用 TLS 协议
      - "traefik.http.routers.flare-https.tls=true"
      # 对响应内容启用 GZIP 压缩
      - "traefik.http.routers.flare-https.middlewares=gzip"
      # 默认服务域名为 flare.example.com
      - "traefik.http.routers.flare-https.rule=Host(`flare.example.com`)"
      # (可选)HTTPS 服务名称为 flare-backend,使用 5005 端口提供服务
      - "traefik.http.routers.flare-https.service=flare-backend"
      # 服务相关
      # 声明服务名称为 flare-backend,使用 5005 端口提供服务
      - "traefik.http.services.flare-backend.loadbalancer.server.scheme=http"
      - "traefik.http.services.flare-backend.loadbalancer.server.port=5005"

networks:
  traefik:
    external: true

我们将上面的内容保存为 docker-compose.flare.yml 后,使用 docker compose -f docker-compose.flare.yml up -d 启动容器后。使用浏览器访问 flare.example.com 就能够通过 HTTPS 的方式来访问到我们的程序啦。

使用域名来快速访问 Flare

其他的程序也是如此,尤其是基于 Docker 运行的程序,都可以使用这个方式来处理,是不是非常简单?

最后

通过上面的介绍,相信你应该已经能够快速的将 Traefik 运行起来,完成一个支持 HTTPS 的网关服务的部署了。

并且,也应该能够快速的将原本只支持使用 HTTP 或者具体端口访问的程序,通过 Traefik 来统一管理和提供服务,告别需要为每一个程序都配置和管理证书的日子了。

–EOF