跳转至

Let's Encrypt

自动 HTTPS

你可以将 Traefik 配置为使用 ACME 提供程序(类似于 Let's Encrypt)来自动生成证书。

Let's Encrypt 和速率限制

注意 Let's Encrypt API 是有 速率限制

配置示例

开启 ACME
[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  email = "your-email@your-domain.org"
  storage = "acme.json"
  # 在验证期间使用
  [certificatesResolvers.sample.acme.httpChallenge]
    entryPoint = "web"
entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      email: your-email@your-domain.org
      storage: acme.json
      # 在验证期间使用
      httpChallenge: 
        entryPoint: web
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.email="your-email@your-domain.org"
--certificatesResolvers.sample.acme.storage="acme.json"
# 在验证期间使用
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

Important

定义一个证书解析器(resolver)不会导致所有路由都自动使用它,每个应该使用解析器的路由都必须 引用 它。

配置引用

ACME 有许多可用选项。 快速浏览一下可能的情况,查看下面的配置文档:

# Enable ACME (Let's Encrypt): automatic SSL.
[certificatesResolvers.sample.acme]

  # Email address used for registration.
  #
  # Required
  #
  email = "test@traefik.io"

  # File or key used for certificates storage.
  #
  # Required
  #
  storage = "acme.json"

  # CA server to use.
  # Uncomment the line to use Let's Encrypt's staging server,
  # leave commented to go to prod.
  #
  # Optional
  # Default: "https://acme-v02.api.letsencrypt.org/directory"
  #
  # caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"

  # KeyType to use.
  #
  # Optional
  # Default: "RSA4096"
  #
  # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
  #
  # keyType = "RSA4096"

  # Use a TLS-ALPN-01 ACME challenge.
  #
  # Optional (but recommended)
  #
  [certificatesResolvers.sample.acme.tlsChallenge]

  # Use a HTTP-01 ACME challenge.
  #
  # Optional
  #
  # [certificatesResolvers.sample.acme.httpChallenge]

    # EntryPoint to use for the HTTP-01 challenges.
    #
    # Required
    #
    # entryPoint = "web"

  # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
  # Note: mandatory for wildcard certificate generation.
  #
  # Optional
  #
  # [certificatesResolvers.sample.acme.dnsChallenge]

    # DNS provider used.
    #
    # Required
    #
    # provider = "digitalocean"

    # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
    # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
    # Useful if internal networks block external DNS queries.
    #
    # Optional
    # Default: 0
    #
    # delayBeforeCheck = 0

    # Use following DNS servers to resolve the FQDN authority.
    #
    # Optional
    # Default: empty
    #
    # resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

    # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
    #
    # NOT RECOMMENDED:
    # Increase the risk of reaching Let's Encrypt's rate limits.
    #
    # Optional
    # Default: false
    #
    # disablePropagationCheck = true
certificatesResolvers:
  sample:
    # Enable ACME (Let's Encrypt): automatic SSL.
    acme:

      # Email address used for registration.
      #
      # Required
      #
      email: "test@traefik.io"

      # File or key used for certificates storage.
      #
      # Required
      #
      storage: "acme.json"

      # CA server to use.
      # Uncomment the line to use Let's Encrypt's staging server,
      # leave commented to go to prod.
      #
      # Optional
      # Default: "https://acme-v02.api.letsencrypt.org/directory"
      #
      # caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"

      # KeyType to use.
      #
      # Optional
      # Default: "RSA4096"
      #
      # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
      #
      # keyType: RSA4096

      # Use a TLS-ALPN-01 ACME challenge.
      #
      # Optional (but recommended)
      #
      tlsChallenge:

      # Use a HTTP-01 ACME challenge.
      #
      # Optional
      #
      # httpChallenge:

        # EntryPoint to use for the HTTP-01 challenges.
        #
        # Required
        #
        # entryPoint: web

      # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
      # Note: mandatory for wildcard certificate generation.
      #
      # Optional
      #
      # dnsChallenge:

        # DNS provider used.
        #
        # Required
        #
        # provider: digitalocean

        # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
        # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
        # Useful if internal networks block external DNS queries.
        #
        # Optional
        # Default: 0
        #
        # delayBeforeCheck: 0

        # Use following DNS servers to resolve the FQDN authority.
        #
        # Optional
        # Default: empty
        #
        # resolvers
        # - "1.1.1.1:53"
        # - "8.8.8.8:53"

        # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
        #
        # NOT RECOMMENDED:
        # Increase the risk of reaching Let's Encrypt's rate limits.
        #
        # Optional
        # Default: false
        #
        # disablePropagationCheck: true
# Enable ACME (Let's Encrypt): automatic SSL.

# Email address used for registration.
#
# Required
#
--certificatesResolvers.sample.acme.email="test@traefik.io"

# File or key used for certificates storage.
#
# Required
#
--certificatesResolvers.sample.acme.storage="acme.json"

# CA server to use.
# Uncomment the line to use Let's Encrypt's staging server,
# leave commented to go to prod.
#
# Optional
# Default: "https://acme-v02.api.letsencrypt.org/directory"
#
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"

# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
--certificatesResolvers.sample.acme.keyType=RSA4096

# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
--certificatesResolvers.sample.acme.tlsChallenge=true

# Use a HTTP-01 ACME challenge.
#
# Optional
#
--certificatesResolvers.sample.acme.httpChallenge=true

# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
--certificatesResolvers.sample.acme.dnsChallenge=true

# DNS provider used.
#
# Required
#
--certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean

# By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
# If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
# Useful if internal networks block external DNS queries.
#
# Optional
# Default: 0
#
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0

# Use following DNS servers to resolve the FQDN authority.
#
# Optional
# Default: empty
#
--certificatesResolvers.sample.acme.dnsChallenge.resolvers="1.1.1.1:53,8.8.8.8:53"

# Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
#
# NOT RECOMMENDED:
# Increase the risk of reaching Let's Encrypt's rate limits.
#
# Optional
# Default: false
#
--certificatesResolvers.sample.acme.dnsChallenge.disablePropagationCheck=true

自动续订

Traefik 会自动跟踪其生成的 ACME 证书的到期日期。如果证书过期之前还不到 30 天了,Traefik 会尝试进行自动续订。

不再使用的证书可能人仍会续签,因为 Traefik 当前不会在续签前检查是否正在使用该证书。

各种 ACME 验证方式

Important

定义证书解析器(resolver)不会导致所有路由都自动使用它,每个应该使用解析器的路由都必须 引用 它。

tlsChallenge

使用 TLS-ALPN-01 验证通过设置 TLS 证书来生成和更新 ACME 证书。

如 Let's Encrypt 社区 中所描述的,当使用 TLS-ALPN-01 验证时,Let's Encrypt 到 Traefik 443 端口必须是可达的。

配置 tlsChallenge
[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.tlsChallenge]
certificatesResolvers:
  sample:
    acme:
      # ...
      tlsChallenge: {}
# ...
--certificatesResolvers.sample.acme.tlsChallenge=true

httpChallenge

通过在 well-known URI 下面配置 HTTP 资源,使用 HTTP-01 验证方式来生成和更新 ACME 证书。

如 Let's Encrypt 社区 中所描述的,当使用 HTTP-01 challenge 时,Let's Encrypt 到 Traefik 80 端口必须是可达的。

使用称为 http 的入口点作为 httpChallenge
[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.httpChallenge]
    entryPoint = "web"
entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      # ...
      httpChallenge:
        entryPoint: web
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

重定向与 HTTP-01 验证方式是完全兼容的。

dnsChallenge

通过设置 DNS 记录,使用 DNS-01 验证方式来生成和更新 ACME 证书。

用 DigitalOcean Provider 来配置一个 dnsChallenge
[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...
certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...
# ...
--certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
# ...

Important

provider 是必须配置的。

providers

这儿有一个支持的 [providers] 列表,能够自动进行 DNS 校验,以及所需的环境变量和 通配符和根域支持

每个 lego 环境变量都可以由其各自的 _FILE 对应变量覆盖,后者应具有指向包含 secret 值的文件的路径。 例如,CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email 可以用来提供 Cloudflare API 电子邮件地址,作为名为 traefik_cf-api-email 的 Docker Secret 。

Provider 名称 Provider 码值 环境变量
ACME DNS acme-dns ACME_DNS_API_BASE, ACME_DNS_STORAGE_PATH 额外配置
Alibaba Cloud alidns ALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY, ALICLOUD_REGION_ID 额外配置
Auroradns auroradns AURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINT 额外配置
Azure azure AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP, [AZURE_METADATA_ENDPOINT] 额外配置
Bindman bindman BINDMAN_MANAGER_ADDRESS 额外配置
Blue Cat bluecat BLUECAT_SERVER_URL, BLUECAT_USER_NAME, BLUECAT_PASSWORD, BLUECAT_CONFIG_NAME, BLUECAT_DNS_VIEW 额外配置
ClouDNS cloudns CLOUDNS_AUTH_ID, CLOUDNS_AUTH_PASSWORD 额外配置
Cloudflare cloudflare CF_API_EMAIL, CF_API_KEY or CF_DNS_API_TOKEN, [CF_ZONE_API_TOKEN] 5 额外配置
CloudXNS cloudxns CLOUDXNS_API_KEY, CLOUDXNS_SECRET_KEY 额外配置
ConoHa conoha CONOHA_TENANT_ID, CONOHA_API_USERNAME, CONOHA_API_PASSWORD 额外配置
DigitalOcean digitalocean DO_AUTH_TOKEN 额外配置
DNSimple dnsimple DNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URL 额外配置
DNS Made Easy dnsmadeeasy DNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOX 额外配置
DNSPod dnspod DNSPOD_API_KEY 额外配置
Domain Offensive (do.de) dode DODE_TOKEN 额外配置
DreamHost dreamhost DREAMHOST_API_KEY 额外配置
Duck DNS duckdns DUCKDNS_TOKEN 额外配置
Dyn dyn DYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORD 额外配置
EasyDNS easydns EASYDNS_TOKEN, EASYDNS_KEY 额外配置
External Program exec EXEC_PATH 额外配置
Exoscale exoscale EXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINT 额外配置
Fast DNS fastdns AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKEN 额外配置
Gandi gandi GANDI_API_KEY 额外配置
Gandi v5 gandiv5 GANDIV5_API_KEY 额外配置
Glesys glesys GLESYS_API_USER, GLESYS_API_KEY, GLESYS_DOMAIN 额外配置
GoDaddy godaddy GODADDY_API_KEY, GODADDY_API_SECRET 额外配置
Google Cloud DNS gcloud GCE_PROJECT, Application Default Credentials 2 3, [GCE_SERVICE_ACCOUNT_FILE] 额外配置
hosting.de hostingde HOSTINGDE_API_KEY, HOSTINGDE_ZONE_NAME 额外配置
HTTP request httpreq HTTPREQ_ENDPOINT, HTTPREQ_MODE, HTTPREQ_USERNAME, HTTPREQ_PASSWORD 1 额外配置
IIJ iij IIJ_API_ACCESS_KEY, IIJ_API_SECRET_KEY, IIJ_DO_SERVICE_CODE 额外配置
INWX inwx INWX_USERNAME, INWX_PASSWORD 额外配置
Joker.com joker JOKER_API_KEY or JOKER_USERNAME, JOKER_PASSWORD 额外配置
Lightsail lightsail AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DNS_ZONE 额外配置
Linode linode LINODE_API_KEY 额外配置
Linode v4 linodev4 LINODE_TOKEN 额外配置
Liquid Web liquidweb LIQUID_WEB_PASSWORD, LIQUID_WEB_USERNAME, LIQUID_WEB_ZONE 额外配置
manual - none, but you need to run Traefik interactively 4, turn on debug log to see instructions and press Enter.
MyDNS.jp mydnsjp MYDNSJP_MASTER_ID, MYDNSJP_PASSWORD 额外配置
Namecheap namecheap NAMECHEAP_API_USER, NAMECHEAP_API_KEY 额外配置
name.com namedotcom NAMECOM_USERNAME, NAMECOM_API_TOKEN, NAMECOM_SERVER 额外配置
Namesilo namesilo NAMESILO_API_KEY 额外配置
Netcup netcup NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORD 额外配置
NIFCloud nifcloud NIFCLOUD_ACCESS_KEY_ID, NIFCLOUD_SECRET_ACCESS_KEY 额外配置
Ns1 ns1 NS1_API_KEY 额外配置
Open Telekom Cloud otc OTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINT 额外配置
OVH ovh OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY 额外配置
Openstack Designate designate OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, OS_REGION_NAME 额外配置
Oracle Cloud oraclecloud OCI_COMPARTMENT_OCID, OCI_PRIVKEY_FILE, OCI_PRIVKEY_PASS, OCI_PUBKEY_FINGERPRINT, OCI_REGION, OCI_TENANCY_OCID, OCI_USER_OCID 额外配置
PowerDNS pdns PDNS_API_KEY, PDNS_API_URL 额外配置
Rackspace rackspace RACKSPACE_USER, RACKSPACE_API_KEY 额外配置
RFC2136 rfc2136 RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVER 额外配置
Route 53 route53 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, [AWS_REGION], [AWS_HOSTED_ZONE_ID] or a configured user/instance IAM profile. 额外配置
Sakura Cloud sakuracloud SAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRET 额外配置
Selectel selectel SELECTEL_API_TOKEN 额外配置
Stackpath stackpath STACKPATH_CLIENT_ID, STACKPATH_CLIENT_SECRET, STACKPATH_STACK_ID 额外配置
TransIP transip TRANSIP_ACCOUNT_NAME, TRANSIP_PRIVATE_KEY_PATH 额外配置
VegaDNS vegadns SECRET_VEGADNS_KEY, SECRET_VEGADNS_SECRET, VEGADNS_URL 额外配置
Versio versio VERSIO_USERNAME, VERSIO_PASSWORD 额外配置
Vscale vscale VSCALE_API_TOKEN 额外配置
VULTR vultr VULTR_API_KEY 额外配置
Zone.ee zoneee ZONEEE_API_USER, ZONEEE_API_KEY 额外配置

delayBeforeCheck

默认情况下,provider 会先验证 TXT 记录,然后再让 ACME 进行验证。你可以通过使用 delayBeforeCheck(值必须大于0)来指定延迟(以秒为单位)来延迟该操作。 当内部网络阻止外部 DNS 查询时,该选项很有用。

resolvers

使用自定义的 DNS 服务器来解析 FQDN。

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    # ...
    resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        # ...
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"
# ...
--certificatesResolvers.sample.acme.dnsChallenge.resolvers:="1.1.1.1:53,8.8.8.8:53"

通配符域名

ACME V2 支持通配符证书。

如在 Let's Encrypt 的文章 中描述的,通配符证书只能通过 DNS-01 challenge 生成。

caServer

使用 Let's Encrypt 测试环境
[certificatesResolvers.sample.acme]
  # ...
  caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  # ...
certificatesResolvers:
  sample:
    acme:
      # ...
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
      # ...
# ...
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
# ...

storage

storage 选项设置保存 ACME 证书的位置。

[certificatesResolvers.sample.acme]
  # ...
  storage = "acme.json"
  # ...
certificatesResolvers:
  sample:
    acme:
      # ...
      storage: acme.json
      # ...
# ...
--certificatesResolvers.sample.acme.storage=acme.json
# ...

该值可以指定某些类型的存储:

  • 一个 JSON 文件

在一个文件中

ACME 证书可以存储在一个需要 600 文件权限的 JSON 文件中。

在 Docker 中,你可以挂载 JSON 文件或者包含它的文件夹:

docker run -v "/my/host/acme.json:/acme.json" traefik
docker run -v "/my/host/acme:/etc/traefik/acme" traefik

Warning

由于并发的原因,无法在 Traefik 的多个实例之间共享该文件,请使用 key value 存储来代替。

降级

如果 Let's Encrypt 不可达,则将应用以下证书:

  1. 之前生成的 ACME 证书(停机之前)
  2. 过期的 ACME 证书
  3. 自动提供的证书

Important

对于需要 Let's Encrypt 认证的新(子)域,将使用默认的 Traefik 证书,直到重新启动 Traefik。


  1. 更多关于 HTTP 消息格式的信息 here 

  2. providing_credentials_to_your_application 

  3. google/default.go 

  4. docker stack remark: there is no way to support terminal attached to container when deploying with docker stack, so you might need to run container with docker run -it to generate certificates using manual provider. 

  5. The Global API Key needs to be used, not the Origin CA Key