ACME

配置示例¶

以下是 Traefik 中 ACME 的基本配置示例。

entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      email: [email protected]
      storage: acme.json
      httpChallenge:
        # used during the challenge
        entryPoint: web

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "[email protected]"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.acme.email=your-email@example.com
--certificatesresolvers.myresolver.acme.storage=acme.json
# used during the challenge
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web

# Traefik entryPoints configuration for HTTP and HTTPS.
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      email: "[email protected]"
      storage: "/data/acme.json"       # Path to store the certificate information.
      httpChallenge:
        # Entry point to use during the ACME HTTP-01 challenge.
        entryPoint: "web"

配置选项¶

ACME 证书解析器提供以下配置选项：

自动续期证书¶

Traefik 会自动跟踪它所生成证书的到期时间。不再使用的证书仍可能被续期，因为 Traefik 目前在续期前不会检查证书是否仍在使用。

默认情况下，Traefik 管理有效期为 90 天的证书，并在到期前 30 天开始续期。 如果使用的证书解析器签发的是自定义有效期的证书，可以通过 certificatesDuration 选项配置证书有效期。

不同的 ACME 质询¶

dnsChallenge¶

DNS-01 质询通过配置 DNS 记录来生成和续期 ACME 证书。

Traefik 内部依赖 Lego 实现 ACME。 你可以在其文档中找到所有受支持的 DNS 提供者列表， 以及需要设置哪些环境变量的说明。

LEGO_DISABLE_CNAME_SUPPORT=true

tlsChallenge¶

使用 TLS-ALPN-01 质询，通过配置 TLS 证书来生成和续期 ACME 证书。

如 Let's Encrypt 社区论坛所述， 使用 TLS-ALPN-01 质询时，Let's Encrypt 必须能够通过端口 443 访问 Traefik。

certificatesResolvers:
  myresolver:
    acme:
      # ...
      tlsChallenge: {}

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.tlsChallenge]

# ...
--certificatesresolvers.myresolver.acme.tlschallenge=true

httpChallenge¶

使用 HTTP-01 质询，通过在约定的 URI 下提供 HTTP 资源来生成和续期 ACME 证书。

如 Let's Encrypt 社区论坛所述， 使用 HTTP-01 质询时，Let's Encrypt 必须能够通过端口 80 访问 certificatesresolvers.myresolver.acme.httpchallenge.entrypoint。

entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      # ...
      httpChallenge:
        entryPoint: web

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.httpChallenge]
    entryPoint = "web"

--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web

域名定义¶

证书解析器根据以下规则，从路由器推导出一组域名，并为其请求证书：

• 如果 IngressRoute 设置了 tls.domains 选项， 证书解析器就会从 tls.domains 的 main 选项推导出此路由器的域名。

• 否则，证书解析器会从 IngressRoute 规则中的任意 Host() 或 HostSNI() 匹配器 推导出域名。

可以为每个主域名设置 SAN（备用域名）。 每个域名都必须有指向 Traefik 的 A/AAAA 记录。 每个域名和 SAN 都会触发一次证书请求。

ACME v2 支持通配符证书。 如 Let's Encrypt 的文章所述，通配符证书只能通过 DNS-01 质询生成。 无法为域名申请双重通配符证书（例如 *.*.local.com）。

通常也需要为根域名签发证书，因此必须将其指定为 SAN，此时会发起 2 次 DNS-01 质询。 在这种情况下，为两个域名生成的 DNS TXT 记录是相同的。 尽管这种行为符合 DNS RFC， 但仍可能引发问题：所有 DNS 提供者都会将 DNS 记录缓存一段时间（TTL），而这个 TTL 可能长于质询超时时间，导致 DNS-01 质询失败。

Traefik 使用的 ACME 客户端库 lego 为部分 DNS 提供者提供了解决此问题的支持，但并非全部。 受支持的 provider 表会注明是否允许为通配符域名及其根域名生成证书。

通配符域名¶

ACME V2 支持通配符证书。 如 Let's Encrypt 的文章所述，通配符证书只能通过 DNS-01 质询生成。

外部账户绑定¶

• kid：外部 CA 提供的密钥标识符
• hmacEncoded：外部 CA 提供的 HMAC 密钥，应采用不带填充的 Base64 URL 编码格式

certificatesResolvers:
  myresolver:
    acme:
      # ...
      eab:
        kid: abc-keyID-xyz
        hmacEncoded: abc-hmac-xyz

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.eab]
    kid = "abc-keyID-xyz"
    hmacEncoded = "abc-hmac-xyz"

# ...
--certificatesresolvers.myresolver.acme.eab.kid=abc-keyID-xyz
--certificatesresolvers.myresolver.acme.eab.hmacencoded=abc-hmac-xyz

在 Kubernetes 中使用 LetsEncrypt¶

在 kubernetes 中使用 LetsEncrypt 时，Ingress 和 CRD 提供者都有一些已知的注意事项。

Ingress 提供者对 LetsEncrypt 的支持¶

Traefik 被设计为无状态应用， 这意味着它仅从运行环境中推导配置， 不需要额外配置。 因此，用户可以同时运行多个 Traefik 实例， 实现高可用（HA），这也是 kubernetes 生态系统中的常见模式。

在单个 Traefik Proxy 实例中使用 Let's Encrypt 时， 通常不会遇到问题，但这可能成为单点故障。 遗憾的是，无法同时运行多个启用了 Let's Encrypt 的 Traefik 2.0 实例， 因为无法确保正确的 Traefik 实例收到质询请求 及后续响应。 早期版本（v1.x）的 Traefik 曾尝试通过 KV 存储 实现这一点，但该功能性能不佳， 因此在 2.0 中被移除。

如果需要在 Kubernetes 环境中以高可用方式使用 Let's Encrypt， 建议使用 Traefik Enterprise， 它将分布式 Let's Encrypt 作为受支持的功能提供。

如果希望继续使用 Traefik Proxy， 可以通过 Cert-Manager 等证书控制器实现 LetsEncrypt 高可用。 使用 Cert-Manager 管理证书时， 它会在你的命名空间中创建 Secret，这些 Secret 可以在 Ingress 对象 中作为 TLS Secret 引用。

回退¶

如果无法访问 Let's Encrypt，将按以下顺序使用证书：

1. 先前生成的 ACME 证书（故障发生前）
2. 已过期的 ACME 证书
3. 提供的证书