Traefik 与 ACME 证书解析器

ACME（Let's Encrypt）

ACME 是 Traefik 用来自动从 Let's Encrypt（或其他支持 ACME 协议的 CA）获取和续订 TLS 证书的协议。

配置示例

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

YAML 格式：

entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      email: [email protected]
      storage: acme.json
      httpChallenge:
        # 用于 challenge 期间
        entryPoint: web

TOML 格式：

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

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "[email protected]"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # 用于 challenge 期间
    entryPoint = "web"

CLI 格式：

--entrypoints.web.address=:80
--entrypoints.websecure.address=:443
--certificatesresolvers.myresolver.acme.email=[email protected]
--certificatesresolvers.myresolver.acme.storage=acme.json
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web

Challenge 类型

HTTP-01 Challenge

通过 80 端口响应 HTTP challenge。需要在 80 端口的 web 入口点可被 Let's Encrypt 访问。

certificatesResolvers:
  myresolver:
    acme:
      httpChallenge:
        entryPoint: web

TLS-ALPN-01 Challenge

通过 443 端口的 TLS ALPN 响应 challenge。需要在 443 端口的 websecure 入口点可被 Let's Encrypt 访问。

certificatesResolvers:
  myresolver:
    acme:
      tlsChallenge: {}

DNS-01 Challenge

通过 DNS 记录响应 challenge。需要 DNS 提供商 API 凭证。支持通配符证书。

certificatesResolvers:
  myresolver:
    acme:
      dnsChallenge:
        provider: cloudflare
        # 使用环境变量 CLOUDFLARE_API_KEY
        delayBeforeCheck: 0

配置选项

字段	描述	默认值
email	ACME 账户的邮箱（必填）。	-
storage	证书和账户存储路径。	-
server	ACME 服务器 URL。	https://acme-v02.api.letsencrypt.org/directory
httpChallenge	HTTP-01 challenge 配置。	-
httpChallenge.entryPoint	用于 HTTP-01 challenge 的入口点。	-
tlsChallenge	TLS-ALPN-01 challenge 配置。	-
dnsChallenge	DNS-01 challenge 配置。	-
dnsChallenge.provider	DNS provider 名称。	-
dnsChallenge.delayBeforeCheck	等待 DNS 传播的时间。	0
dnsChallenge.resolvers	自定义 DNS 解析器。	-
prefersChain	首选证书链。	-
keyType	密钥类型（RSA2048、RSA4096、RSA8192、EC256、EC384）。	RSA2048
disableGlobalCheck	禁用全局 challenge 检查。	false
caCertificates	额外 CA 证书。	-
eab	外部账户绑定（EAB）。	-
eab.kid	EAB 密钥 ID。	-
eab.hmacEncoded	EAB HMAC（Base64 编码）。	-

适用场景

• 生产 HTTPS：为生产环境自动获取 Let's Encrypt 证书
• 通配符证书：使用 DNS-01 challenge 获取 *.example.com 通配符证书
• 内网环境：使用自签名 ACME 服务器（如 step-ca）
• 多域名：一张证书覆盖多个域名

最佳实践

1. 使用 staging 服务器测试：先用 https://acme-staging-v02.api.letsencrypt.org/directory 测试
2. 持久化存储：挂载 acme.json 到持久卷，避免重启后重新颁发证书
3. DNS-01 用于内网：内网环境必须使用 DNS-01 challenge
4. 使用通配符：为所有子域使用通配符证书，简化管理
5. 监控证书过期：监控证书到期时间，配置提醒

---

在生产环境使用 Traefik OSS？

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

• 观看我们的 API 网关演示视频
• 申请 24/7/365 OSS 支持