自动 HTTPS

Caddy 是第一个也是唯一一个使用 HTTPS 自动化并且默认的 Web 服务器。

自动 HTTPS 为您的所有站点提供 TLS 证书，并保持其续订。它还会为您将 HTTP 重定向到 HTTPS！Caddy 使用安全且现代的默认设置 - 不需要停机、额外配置或单独的工具。

这是一个 28 秒的视频，展示了它的工作原理

菜单

• 概述
• 激活
• 效果
• 主机名要求
• 本地 HTTPS
• 测试
• ACME 挑战
• 按需 TLS
• 错误
• 存储
• 通配符证书

概述

默认情况下，Caddy 通过 HTTPS 提供所有站点。

• Caddy 使用自动信任的本地自签名证书通过 HTTPS 提供 IP 地址和本地/内部主机名（如果允许）。
  • 示例：localhost、127.0.0.1
• Caddy 使用来自公共 ACME CA（如 Let's Encrypt 或 ZeroSSL ）的证书通过 HTTPS 提供公共 DNS 名称。
  • 示例：example.com、sub.example.com、*.example.com

Caddy 会自动保持所有管理的证书续订，并将 HTTP（默认端口 80）重定向到 HTTPS（默认端口 443）。

对于本地 HTTPS

• Caddy 可能会提示您输入密码以将唯一的根证书安装到您的信任存储中。这每个根只发生一次；您可以随时删除它。
• 任何在没有信任 Caddy 根 CA 证书的情况下访问站点的客户端都会显示安全错误。

对于公共域名

• 如果您的域的 A/AAAA 记录指向您的服务器，
• 端口 80 和 443 在外部打开，
• Caddy 可以绑定到这些端口（或这些端口被转发到 Caddy），
• 您的 数据目录 可写且持久，
• 并且您的域名出现在配置中的相关位置，

那么站点将自动通过 HTTPS 提供服务。您无需再做任何其他操作。它可以正常工作！

由于 HTTPS 利用了共享的公共基础设施，因此您作为服务器管理员应该了解本页面的其余信息，以便您可以避免不必要的问题，在出现问题时进行故障排除，并正确配置高级部署。

激活

当 Caddy 知道它正在服务的域名（即主机名）或 IP 地址时，它会隐式激活自动 HTTPS。根据您运行或配置 Caddy 的方式，有多种方法可以告诉 Caddy 您的域名/IP

• 站点地址 在 Caddyfile 中
• 一个 主机匹配器 在 JSON 路由 中的顶层
• 命令行标志，如 --domain 或 --from
• 该 automate 证书加载器

以下任何一项都会阻止自动 HTTPS 被激活，无论是全部还是部分

• 显式禁用它 通过 JSON 或 通过 Caddyfile
• 在配置中不提供任何主机名或 IP 地址
• 仅在 HTTP 端口上监听
• 在 Caddyfile 中使用 http:// 前缀 站点地址
• 手动加载证书（除非设置了 ignore_loaded_certificates）

特殊情况

• 以 .ts.net 结尾的域名不会由 Caddy 管理。相反，Caddy 会自动尝试从本地运行的 Tailscale 实例中获取这些证书，并在握手时进行。这要求 在您的 Tailscale 帐户中启用 HTTPS ，并且 Caddy 进程必须以 root 身份运行，或者您必须配置 tailscaled 以授予您的 Caddy 用户 获取证书的权限。

效果

当自动 HTTPS 被激活时，会发生以下情况

• 为 所有符合条件的域名 获取并续订证书
• HTTP 重定向到 HTTPS（这使用 HTTP 端口 80）

自动 HTTPS 永远不会覆盖显式配置，它只会对其进行补充。

如果您已经有一个在 HTTP 端口上监听的 服务器，HTTP->HTTPS 重定向路由将插入到您的路由之后，使用主机匹配器，但在用户定义的 catch-all 路由之前。

您可以 自定义或禁用自动 HTTPS，如果需要；例如，您可以跳过某些域名或禁用重定向（对于 Caddyfile，使用 全局选项 这样做）。

主机名要求

如果所有主机名（域名）满足以下条件，则有资格获得完全管理的证书

• 非空
• 仅包含字母数字、连字符、点和通配符 (*)
• 不以点开头或结尾 (RFC 1034)

此外，如果主机名满足以下条件，则有资格获得公开信任的证书

• 不是 localhost（包括 .localhost、.local 和 .home.arpa TLD）
• 不是 IP 地址
• 只有一个通配符 * 作为最左边的标签

本地 HTTPS

Caddy 自动为所有指定了主机（域名、IP 或主机名）的站点使用 HTTPS，包括内部和本地主机。某些主机要么不是公共的（例如 127.0.0.1、localhost），要么通常没有资格获得公开信任的证书（例如 IP 地址 - 您可以为它们获取证书，但只能从某些 CA 获取）。这些仍然通过 HTTPS 提供服务，除非被禁用。

为了通过 HTTPS 提供非公共站点，Caddy 会生成自己的证书颁发机构 (CA) 并使用它来签署证书。信任链由根证书和中间证书组成。叶证书由中间证书签署。它们存储在 Caddy 的数据目录 中的 pki/authorities/local。

Caddy 的本地 CA 由 Smallstep 库 提供支持。

本地 HTTPS 不使用 ACME，也不执行任何 DNS 验证。它仅在本地机器上工作，并且仅在安装了 CA 的根证书的地方被信任。

CA 根

根的私钥使用密码学安全的伪随机源唯一生成，并以有限的权限持久保存到存储中。它仅在执行签名任务时加载到内存中，之后它会离开作用域以进行垃圾回收。

虽然 Caddy 可以配置为直接使用根进行签名（以支持不兼容的客户端），但这在默认情况下是被禁用的，并且根密钥仅用于签署中间证书。

第一次使用根密钥时，Caddy 会尝试将其安装到系统的本地信任存储中。如果它没有权限这样做，它会提示您输入密码。如果不需要，可以在配置中禁用此行为。如果由于以非特权用户身份运行而失败，您可以运行 caddy trust 以特权用户身份重试安装。

安装 Caddy 的根 CA 后，您将在本地信任存储中看到它，名为“Caddy 本地颁发机构”（除非您配置了不同的名称）。您可以随时卸载它（caddy untrust 命令使这变得容易）。

请注意，自动将证书安装到本地信任存储中仅是为了方便起见，并不保证能正常工作，尤其是在使用容器或以非特权系统服务身份运行 Caddy 时。最终，如果您依赖内部 PKI，则系统管理员有责任确保 Caddy 的根 CA 正确添加到必要的信任存储中（这超出了 Web 服务器的范围）。

CA 中间证书

还会生成中间证书和密钥，它们将用于签署叶（单个站点）证书。

与根证书不同，中间证书的有效期要短得多，并且会根据需要自动续订。

测试

要测试或试验您的 Caddy 配置，请确保您 将 ACME 端点更改为 暂存或开发 URL，否则您可能会遇到速率限制，这可能会阻止您访问 HTTPS，持续时间长达一周，具体取决于您遇到的速率限制。

Caddy 的默认 CA 之一是 Let's Encrypt ，它有一个 暂存端点 ，它不受相同的 速率限制 的影响

https://acme-staging-v02.api.letsencrypt.org/directory

ACME 挑战

获取公开信任的 TLS 证书需要来自公开信任的第三方机构的验证。如今，此验证过程已通过 ACME 协议 自动化，并且可以通过以下三种方式（“挑战类型”）之一执行，如下所述。

前两种挑战类型在默认情况下是启用的。如果启用了多个挑战，Caddy 会随机选择一个，以避免意外地依赖于特定挑战。随着时间的推移，它会了解哪种挑战类型最成功，并将开始优先选择它，但如果需要，会回退到其他可用的挑战类型。

HTTP 挑战

HTTP 挑战会对候选主机名的 A/AAAA 记录执行权威 DNS 查找，然后使用 HTTP 通过端口 80 请求临时加密资源。如果 CA 看到预期的资源，则会颁发证书。

此挑战要求端口 80 可外部访问。如果 Caddy 无法在端口 80 上监听，则来自端口 80 的数据包必须转发到 Caddy 的 HTTP 端口。

此挑战在默认情况下是启用的，不需要显式配置。

TLS-ALPN 挑战

TLS-ALPN 挑战会对候选主机名的 A/AAAA 记录执行权威 DNS 查找，然后使用包含特殊 ServerName 和 ALPN 值的 TLS 握手通过端口 443 请求临时加密资源。如果 CA 看到预期的资源，则会颁发证书。

此挑战要求端口 443 可外部访问。如果 Caddy 无法在端口 443 上监听，则来自端口 443 的数据包必须转发到 Caddy 的 HTTPS 端口。

此挑战在默认情况下是启用的，不需要显式配置。

DNS 挑战

DNS 挑战会对候选主机名的 TXT 记录执行权威 DNS 查询，并查找具有特定值的特殊 TXT 记录。如果 CA 看到预期值，则会颁发证书。

此挑战不需要任何开放端口，并且请求证书的服务器不需要对外可访问。但是，DNS 挑战需要配置。Caddy 需要知道访问您域名 DNS 提供商的凭据，以便它可以设置（和清除）特殊的 TXT 记录。如果启用了 DNS 挑战，则默认情况下会禁用其他挑战。

由于 ACME CA 在查找用于挑战验证的 TXT 记录时遵循 DNS 标准，因此您可以使用 CNAME 记录将挑战的回答委托给其他 DNS 区域。这可以用于将 _acme-challenge 子域委托给另一个区域。如果您 的 DNS 提供商没有提供 API 或不受 Caddy 的某个 DNS 插件支持，这将特别有用。

DNS 提供商支持是社区共同努力的结果。 在我们的维基页面上了解如何为您的提供商启用 DNS 挑战。

按需 TLS

Caddy 开创了一种我们称之为 **按需 TLS** 的新技术，它在第一次需要 TLS 证书的 TLS 握手期间动态获取新证书，而不是在配置加载时获取。至关重要的是，这 **不需要** 在您的配置中提前硬编码域名。

许多企业依靠此独特功能以更低的成本和更少的运营问题来扩展其 TLS 部署，即使是在为数万个网站提供服务时。

按需 TLS 在以下情况下很有用：

• 您在启动或重新加载服务器时不知道所有域名，
• 域名可能无法立即正确配置（DNS 记录尚未设置），
• 您无法控制域名（例如，它们是客户域名）。

启用按需 TLS 后，您无需在配置中指定域名即可获取其证书。相反，当接收到 Caddy 尚未拥有证书的服务器名称 (SNI) 的 TLS 握手时，握手将被保留，同时 Caddy 获取证书以完成握手。延迟通常只有几秒钟，并且只有初始握手速度慢。所有将来的握手都很快，因为证书会被缓存并重复使用，并且续订会在后台进行。将来的握手可能会触发证书的维护以保持其续订，但如果证书尚未过期，则此维护会在后台进行。

使用按需 TLS

按需 TLS 必须同时启用和限制以防止滥用。

启用按需 TLS 在 TLS 自动化策略 中进行（如果使用 JSON 配置），或在 使用 Caddyfile 的站点块中的 tls 指令 中进行。

为了防止滥用此功能，您必须配置限制。这在 JSON 配置的 automation 对象 或 Caddyfile 的 on_demand_tls 全局选项 中完成。限制是“全局的”，不能按站点或按域名进行配置。主要限制是“询问”端点，Caddy 将向其发送 HTTP 请求以询问它是否有权获取和管理握手中的域名的证书。这意味着您将需要一些内部后端，例如，可以查询数据库的帐户表并查看客户是否已使用该域名注册。

请注意您的 CA 颁发证书的速度。如果需要超过几秒钟，这将对用户体验产生负面影响（仅针对第一个客户端）。

由于其延迟性质以及防止滥用所需的额外配置，我们建议仅在您的实际用例如上所述时启用按需 TLS。

有关有效使用按需 TLS 的更多信息，请参阅我们的维基文章。

错误

如果证书管理出现错误，Caddy 会尽力继续运行。

默认情况下，证书管理在后台执行。这意味着它不会阻止启动或减慢您的网站速度。但是，这也意味着服务器将在所有证书可用之前就开始运行。在后台运行允许 Caddy 在很长一段时间内以指数退避的方式重试。

以下是获取或续订证书时出现错误的情况：

1. Caddy 在短暂暂停后重试一次，以防万一是偶然事件
2. Caddy 短暂暂停，然后切换到下一个启用的挑战类型
3. 在尝试完所有启用的挑战类型后，它会尝试下一个配置的发行机构
   • Let's Encrypt
   • ZeroSSL
4. 在尝试完所有发行机构后，它会以指数方式退避
   • 尝试之间最多间隔 1 天
   • 最多 30 天

在使用 Let's Encrypt 重试期间，Caddy 会切换到他们的 暂存环境 以避免速率限制问题。这不是一个完美的策略，但总的来说是有帮助的。

ACME 挑战至少需要几秒钟，内部速率限制有助于缓解意外滥用。Caddy 使用内部速率限制，除了您或 CA 配置的速率限制之外，这样您就可以将包含一百万个域名的托盘交给 Caddy，它会逐渐（但尽可能快地）为所有域名获取证书。Caddy 的内部速率限制目前是每个 ACME 帐户每 10 秒 10 次尝试。

为了避免泄漏资源，Caddy 会在更改配置时中止正在进行的任务（包括 ACME 事务）。虽然 Caddy 能够处理频繁的配置重新加载，但请注意此类操作考虑因素，并考虑将配置更改批处理以减少重新加载并让 Caddy 有机会实际完成在后台获取证书的过程。

发行机构回退

Caddy 是第一个（也是目前唯一一个）支持完全冗余的、自动故障转移到其他 CA 的服务器，以防它无法成功获取证书。

默认情况下，Caddy 会启用两个与 ACME 兼容的 CA：Let's Encrypt 和 ZeroSSL 。如果 Caddy 无法从 Let's Encrypt 获取证书，它会尝试使用 ZeroSSL；如果两者都失败，它会退避并稍后重试。在您的配置中，您可以自定义 Caddy 用于获取证书的发行机构，无论是全局的还是针对特定名称的。

存储

Caddy 会将其配置的存储设施（或未配置的默认存储设施 - 有关详细信息，请参阅链接）中存储公钥证书、私钥和其他资产。 配置的存储设施

使用默认配置，您需要知道的主要事项是 $HOME 文件夹必须是可写的并且是持久性的。为了帮助您进行故障排除，如果指定了 --environ 标志，Caddy 会在启动时打印其环境变量。

任何配置为使用相同存储的 Caddy 实例将自动共享这些资源并协调证书管理作为集群。

在尝试任何 ACME 事务之前，Caddy 会测试配置的存储以确保它是可写的并且具有足够的容量。这有助于减少不必要的锁争用。

通配符证书

当 Caddy 配置为为具有合格通配符名称的站点提供服务时，它可以获取和管理通配符证书。如果只有站点的最左侧域名标签是通配符，则站点名称有资格获得通配符。例如，*.example.com 有资格，但以下没有资格：sub.*.example.com、foo*.example.com、*bar.example.com 和 *.*.example.com。

如果使用 Caddyfile，Caddy 会在证书主体名称方面严格地对待站点名称。换句话说，定义为 sub.example.com 的站点将导致 Caddy 管理 sub.example.com 的证书，而定义为 *.example.com 的站点将导致 Caddy 管理 *.example.com 的通配符证书。您可以在我们的 常见 Caddyfile 模式 页面上看到此演示。如果您需要不同的行为，JSON 配置 为您提供了对证书主体和站点名称（“主机匹配器”）的更精确控制。

通配符证书代表着广泛的权限，只有在您拥有如此多的子域以至于管理它们的单个证书会给 PKI 带来压力或导致您达到 CA 强制实施的速率限制时才应使用它们。

注意： Let's Encrypt 需要 DNS 挑战 来获取通配符证书。