集成指南

最近更新: June 23, 2025
所有文档

如果您是托管服务提供商或正在大型网站中集成 Let’s Encrypt,或者您正在为 Let’s Encrypt 编写客户端软件,则本文档包含了一些对您有用的建议。

做好更改准备

Let’s Encrypt 和 Web PKI 都将随着时间的推移而不断发展。您应该确保能够轻松更新所有使用 Let’s Encrypt 的服务。如果您还要部署依赖于 Let’s Encrypt 证书的客户端,请特别确保这些客户端定期收到更新。

将来,这些事情可能会发生变化:

我们将始终尽可能提前通知此类更改,但如果在某些组件中发现严重的安全漏洞,我们可能需要在短期内或立即进行更改。特别是对于中间证书改变,你不应该硬编码中间证书,而应该使用 ACME 协议中的 Link: rel="up"标头,因为中间证书很可能会改变。

类似地,服务条款 (ToS) 变更时,其网址也很有可能发生变化。请避免硬编码 ToS 链接,而是使用 Link:rel =“terms-of-service” 标头确定要使用的 ToS 链接。

要接收有关上述重要更改的小批量更新,请订阅我们的 API 公告分类。这对客户端开发人员和托管提供商都很有用。

获取更新

要接收有关上述重要更改的小批量更新,请订阅我们的 [API 公告](https://community.letsencrypt.org/t/about-the-api-announcements-category/23836)分类。这对客户端开发人员和托管提供商都很有用。

有关维护和停机的更高容量更新,请访问我们的[状态页面](https://letsencrypt.status.io/)并点击右上方的"订阅"按钮。这对托管服务提供商最为有用。

谁是用户

正如我们的 CP/CPS 和用户协议所述,用户指的是私钥的持有者。因此,对于托管服务提供商而言,用户是提供商自身,而非其客户。如果您正在编写允许人们自行部署的软件,那用户就是部署软件的人。

这意味着如果您是托管服务提供商,无需要求客户同意我们的用户协议,只需为您持有的域名申请证书并使用即可。

使用一个还是多个账户?

在 ACME 中,可以创建一个帐户并将其用于所有授权和颁发,或者为每个客户创建一个帐户。这种灵活性可能很有价值。例如,一些主机提供商可能希望每个客户使用一个帐户,并将帐户密钥存储在不同的地方中,这样即使帐户密钥泄露也不会允许攻击者给所有用户颁发证书。

但是,对于大多数大型托管服务提供商,我们建议使用单个帐户并保护相应的帐户密钥。从而明确证书归属,且便于按需调整速率限制。如果您使用许多不同的帐户,我们将无法有效调整速率限制。

多域名 (SAN) 证书

我们每份证书最多支持 100 个域名,具体取决于您所选的证书配置。您可以为每个域名都申请一份证书,也可以只用几份证书覆盖大量域名。

每个域名使用单独的证书可以简化域名增删的流程,同时减小证书体积,从而在带宽较低的网络上缩短建立 HTTPS 连接所需的时间。您可以查看速率限制了解可申请的证书数量。

另一方面,一份证书也可以包含大量域名,从而减少需要管理的证书数量。如果您需要兼容 Windows XP 等不支持 TLS 服务器名称指示 (SNI) 的早期客户端,则每份证书都必须由不同的 IP 地址提供服务,因此每份证书包含的域名越多,您所需要的 IP 地址就越少。

绝大多数情况下,这两种证书管理方式都是安全的。

存储和重用证书和密钥

Let’s Encrypt 的主要价值在于我们允许在创建新网站时自动颁发证书。但是,如果您的基础架构可能会为同一网站重复创建新的前端服务器,那么这些前端应该首先尝试使用来自持久性存储的证书和私钥,并且只在没有可用的证书或者所有现有的证书都已过期的情况下颁发新证书。

对于 Let’s Encrypt,这有助于我们为尽可能多的人高效地提供服务。对您而言,这可以确保您能够随时随地部署您的网站,无论 Let’s Encrypt 的状态如何。

例如,许多站点正在开始使用 Docker 按需配置新的前端实例。如果您将 Docker 容器设置为在启动时颁发证书,并且您没有持久性地存储证书和密钥,那么您如果一次启动太多实例,就可能会达到速率限制。在最坏情况下,如果您一次性销毁并重新创建所有实例,就有可能导致所有实例都无法获取证书,您的网站可能会停摆数天,直至速率限制解除。而且不仅仅是速率限制会导致这类问题。如果在需要启动前端时 Let’s Encrypt 出于任何原因不可用,您就会遇到同样的问题。

请注意,某些部署原则指出加密密钥永远不能离开生成它们的物理机器。只要您确保机器及其数据可以长期使用,并且您仔细管理速率限制,此模型就可以正常使用 Let’s Encrypt。

选择验证方式

您如果正在使用 http-01 ACME 进行验证,则需要先向每个前端提供验证用的回复,然后才能通知 Let’s Encrypt 您已准备好进行验证。如果您有很多前端服务器,这么做可能非常困难。在这种情况下,使用 dns-01 进行验证可能会更容易。当然,您如果有许多地理位置分散的 DNS 响应服务器,则必须确保每个响应服务器上都有验证所需的 TXT 记录。

此外,在使用 dns-01 进行验证时,请务必清理旧的 TXT 记录,以确保对 Let’s Encrypt 的查询的回复不会太大。

如果您想无论如何都要使用 http-01 进行验证,您也许可以利用 HTTP 重定向。例如,对于任意的 XYZ 字符串,您可以让所有前端的 /.well-known/acme-challenge/XYZ 路径都跳转至 validation-server.example.com/XYZ。此时 validation-server 也承担了申请证书的部分职责,故该服务器的安全同样需要妥善保护。

中央验证服务器

与上述两点相关,您如果有很多前端服务器,可能需要使用较小的服务器子集来管理证书颁发。这样可以更轻松地使用重定向进行 http-01 验证,并提供长期存储证书和密钥的位置。

防火墙配置

为了正常使用 Let’s Encrypt,您需要允许运行 ACME 客户端的设备向外与 443 端口建立连接。我们的 ACME 服务的 IP 地址范围不对外公开,并且随时可能变动,恕不另行告知。

如果您 “http-01” ACME 验证方法,您需要允许 80 端口上的入站通信。我们发起测试所使用的 IP 地址范围同样不公开,且随时可能变动,恕不另行告知。

注意:我们建议您的网页服务器始终允许无加密的明文 HTTP 连接,并重定向至 HTTPS。相比直接拒绝对 80 端口的连接,这种方式能够提升用户体验,并且不会影响安全性。

对于所有的验证方式,您的权威 DNS 服务器都必须能够在 53 端口(包括 TCP 和 UDP)上接收流量。

支持的密钥算法

Let’s Encrypt 接受 2048、3072 或 4096 位的 RSA 密钥以及 P-256 或 P-384 曲线的 ECDSA 密钥。对于帐户密钥和证书密钥来说都是如此。您不能将帐户密钥重用为证书密钥。

我们建议托管服务提供商自动颁发证书并为其控制的所有主机名配置 HTTPS,并且允许用户选择是否将 HTTP 链接重定向到等效的 HTTPS 链接。我们建议为现有帐户在默认情况下禁用该设置,但为新帐户在默认情况下启用该设置。

默认使用 HTTPS

对于网站托管服务商,我们建议为您所控制的所有域名自动申请证书并配置 HTTPS,同时允许用户选择是否将 HTTP 网址重定向至对应的 HTTPS 路径。对于现有的账户,我们建议默认关闭这一选项,但新账户则建议默认开启。

上述建议的理由在于,现有的网站可能包含部分未加密的 HTTP 资源(如脚本、样式表和图片),如果贸然重定向至 HTTPS,浏览器可能会因为协议混用而屏蔽这些资源,从而影响网站的功能。但新建网站的用户发现重定向至 HTTPS 后会自然地使用 HTTPS 资源,因为一旦使用未加密的 HTTP 资源就会注意到问题所在。

我们建议允许客户配置 HTTP 的 Strict-Transport-Security (HSTS) 标头,并将默认的 max-age 设为 60 天。然而,此类设置也应当附有警告,如果客户将来切换至不支持 HTTPS 的托管服务商,那么访客浏览器所缓存的 HSTS 设置将导致网站无法正常访问。此外,客户与服务商均应注意,HSTS 标头会导致所有证书错误都演变为硬性故障。例如在通常情况下,即使证书已过期或名称不匹配,用户也可以在浏览器中点击忽略错误,但 HSTS 生效后浏览器就不会再允许此类操作。

续期时间

我们建议每天至少查询 ACME 更新信息 (ARI) 两次, ARI 接口会给出推荐的续期时间。

若不使用 ARI,我们建议在证书有效期剩余三分之一时自动续期。对于有效期不足十天的证书,我们建议在有效期剩余一半时续期。也就是说,对于 Let’s Encrypt 当前颁发的有效期 90 天的证书,建议在到期前第 30 天续期。

另外,如果您需要为超过 10000 个域名申请证书,我们建议分批依次执行续期,而非大规模集中完成。这是为了降低风险:即使 Let’s Encrypt 在您需要续期时服务中断,或者您的证书续期系统暂时故障,也只有一部分证书会受影响。另一方面,这样做也便于我们预测服务负载。

首次获取证书时您可以一次性为所有域名完成申请,然后将第一次续期时间错开,例如部分证书提前一天续期、另一部分证书提前两天续期等等。

如果您开发的客户端软件会自动创建定时任务,请务必随机设置其执行的时间点,而非统一设为某个固定时刻。这可以防止 Let’s Encrypt 在每小时或每分钟的第一秒遭遇流量突增。由于 Let’s Encrypt 需要根据峰值负载规划服务器资源分配,避免流量突增可以帮助我们降低成本。

验证失败后重试

续期失败不应被视为无法解决的错误,您应当采用指数退避的方式实现平滑的重试逻辑,使频率最终收敛至每份证书每天重试一次。例如,一种合理的重试方式为:第一次重试前等待 1 分钟,第二次重试前等待 10 分钟,第三次重试前等待 100 分钟,第四次及后续重试前均等待一天。当然,您也应当允许系统管理员提前对部分或所有域名发起重试。

采用退避机制意味着您的软件不仅需要记录成功的操作,还需要记录失败的操作,从而决定能否发起新的证书申请。每小时尝试申请上百次是没有意义的,因为重复的失败往往会不断持续。

另外,所有的错误信息均应发送给相应的系统管理员,以便解决可能存在的问题。