自动 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 Local Authority”（除非您配置了不同的名称）。如果您愿意，可以随时卸载它（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 查找，然后通过端口 80 使用 HTTP 请求临时加密资源。如果 CA 看到预期的资源，则颁发证书。

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

默认情况下启用此挑战，并且不需要显式配置。

TLS-ALPN 挑战

TLS-ALPN 挑战对候选主机名的 A/AAAA 记录执行权威 DNS 查找，然后通过端口 443 使用包含特殊 ServerName 和 ALPN 值的 TLS 握手请求临时加密资源。如果 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 提供商支持是一项社区工作。在我们的 wiki 上了解如何为您的提供商启用 DNS 挑战。

按需 TLS

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

许多企业依靠此独特功能来扩展其 TLS 部署，从而降低成本，并避免在服务数万个站点时出现操作难题。

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

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

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

使用按需 TLS

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

如果使用 JSON 配置，则在 TLS 自动化策略 中启用按需 TLS，如果使用 Caddyfile，则在 带有 tls 指令的站点块 中启用按需 TLS。

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

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

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

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

错误

如果证书管理出现错误，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 挑战 来获取通配符证书。