Let's Encrypt¶

自动 HTTPS

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

Let's Encrypt 和速率限制

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

配置示例¶

开启 ACME

File (TOML)

[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"

File (YAML)

entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      email: your-email@your-domain.org
      storage: acme.json
      # 在验证期间使用
      httpChallenge: 
        entryPoint: web

CLI

--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 有许多可用选项。快速浏览一下可能的情况，查看下面的配置文档：

File (TOML)

# 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

File (YAML)

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

CLI

# 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

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.tlsChallenge]

File (YAML)

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

CLI

# ...
--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

File (TOML)

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

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

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

File (YAML)

entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

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

CLI

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

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

`dnsChallenge`¶

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

用 DigitalOcean Provider 来配置一个 dnsChallenge

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...

CLI

# ...
--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]` ⁵	额外配置
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 ² ³, [`GCE_SERVICE_ACCOUNT_FILE`]	额外配置
hosting.de	`hostingde`	`HOSTINGDE_API_KEY`, `HOSTINGDE_ZONE_NAME`	额外配置
HTTP request	`httpreq`	`HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` ¹	额外配置
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 ⁴, 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。

File (TOML)

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

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        # ...
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"

CLI

# ...
--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 测试环境

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  # ...

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
      # ...

CLI

# ...
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
# ...

`storage`¶

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

File (TOML)

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

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      storage: acme.json
      # ...

CLI

# ...
--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 不可达，则将应用以下证书：

之前生成的 ACME 证书（停机之前）
过期的 ACME 证书
自动提供的证书

Important

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

更多关于 HTTP 消息格式的信息 here ↩
providing_credentials_to_your_application ↩
google/default.go ↩
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. ↩
The Global API Key needs to be used, not the Origin CA Key. ↩

Let's Encrypt¶

配置示例¶

自动续订¶

各种 ACME 验证方式¶

tlsChallenge¶

httpChallenge¶

dnsChallenge¶

providers¶

resolvers¶

通配符域名¶

caServer¶

storage¶

在一个文件中¶

降级¶

`tlsChallenge`¶

`httpChallenge`¶

`dnsChallenge`¶

`providers`¶

`resolvers`¶

`caServer`¶

`storage`¶