在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

caddyserver/caddy

菜单

自动 HTTPS

相关源文件

自动 HTTPS 是 Caddy 的一项旗舰功能，它能够以零配置实现安全网站。本文档解释了 Caddy 如何自动提供 TLS 证书、配置安全的 TLS 设置以及创建 HTTP 到 HTTPS 的重定向，而无需任何手动设置。

概述

Caddy 的自动 HTTPS 默认应用这些功能

  1. TLS 证书提供：自动为所有符合条件的域名从基于 ACME 的 CA（Let's Encrypt、ZeroSSL）获取和续订证书
  2. HTTP 到 HTTPS 重定向：自动将 HTTP 请求重定向到其 HTTPS 等效项
  3. 安全的 TLS 配置：为安全通信设置强大的 TLS 默认值

来源：modules/caddyhttp/autohttps.go1-70 modules/caddyhttp/app.go41-49 modules/caddytls/tls.go49-68

自动 HTTPS 如何工作

Caddy 在服务器配置过程中通过一个两阶段过程来实现自动 HTTPS

第一阶段：域名发现和重定向设置

在由 automaticHTTPSPhase1() 处理的初始阶段

  1. Caddy 扫描所有服务器配置中的域名
  2. 它识别出符合证书管理条件的域名
  3. 它为这些域名创建 HTTP 到 HTTPS 的重定向
  4. 它确保 HTTPS 服务器启用 TLS

来源：modules/caddyhttp/autohttps.go82-599

第二阶段：证书管理

在第二阶段，即 TLS 应用启动时

  1. 证书将根据第一阶段发现的域名进行加载或获取
  2. 安排证书续订
  3. 配置用于域名验证的 ACME 挑战

来源：modules/caddytls/tls.go384-421 modules/caddytls/automation.go178-349

证书发现和域名合格

Caddy 通过检查您的配置自动发现需要证书的域名。该过程如下所示

  1. Caddy 扫描服务器中定义的所有路由中的所有主机匹配器
  2. 对于找到的每个域名（例如 example.com），Caddy 会检查它是否符合证书管理条件
  3. 符合条件的域名将被添加到将由 Caddy 管理证书的域名列表中

如果满足以下条件，域名就有资格进行自动证书管理

  • 它是有效的域名（而不是 IP 地址）
  • 它不在 AutoHTTPS 配置的 Skip 或 SkipCerts 列表中
  • certmagic.SubjectQualifiesForPublicCert() 返回 true（检查有效的公共域名）
  • 默认情况下，Caddy 不会管理已加载证书的域名的证书（除非将 IgnoreLoadedCerts 设置为 true）

来源：modules/caddyhttp/autohttps.go145-198 modules/caddyhttp/autohttps.go220-246

HTTP 到 HTTPS 重定向

Caddy 自动配置从 HTTP 到 HTTPS 的重定向，除非禁用

  1. 对于监听非仅 HTTP（端口 80）以外端口的每个服务器
  2. Caddy 会创建或使用现有的仅 HTTP 服务器
  3. 此服务器将所有符合条件的域名重定向到其 HTTPS 等效项
  4. 重定向会保留路径和查询字符串

例如，请求 http://example.com/page?query=value 将被重定向到 https://example.com/page?query=value。

HTTP 到 HTTPS 的重定向是通过一个特殊的重定向路由实现的，该路由会插入到 HTTP 服务器路由列表中的一个精心选择的位置。该位置通过检查现有的主机匹配器来确定，以确保重定向能够适当优先。

来源：modules/caddyhttp/autohttps.go255-441 modules/caddyhttp/app.go437-509

证书管理

Caddy 使用多个组件来管理证书

  1. 自动化策略：定义不同域名的证书应如何管理
  2. 证书颁发者：用于获取证书的模块（ACME、ZeroSSL、内部）
  3. 证书存储：证书和元数据的持久化存储

来源：modules/caddytls/tls.go50-140 modules/caddytls/automation.go36-176 modules/caddytls/acmeissuer.go44-118 modules/caddytls/automation.go236-242

证书颁发者

Caddy 为不同场景提供了多种证书颁发者

颁发者描述默认用途
ACME使用 ACME 协议（Let's Encrypt）颁发公共证书公共域名的默认选项
ZeroSSL使用 ZeroSSL 的 ACME 颁发公共证书公共域名的替代选项
内部信息为本地开发颁发自签名证书非公共域名的默认选项

对于每个域名，Caddy 根据域名类型和配置的自动化策略选择合适的颁发者。

来源：modules/caddytls/acmeissuer.go44-118 modules/caddytls/automation.go236-242

配置自动 HTTPS

禁用自动 HTTPS

您可以完全禁用自动 HTTPS 或其特定方面

要仅禁用重定向或仅禁用证书管理

来源：modules/caddyhttp/autohttps.go31-43

跳过域名

您可以豁免特定域名不使用自动 HTTPS

skip 列表会从证书管理和 HTTP 到 HTTPS 重定向中排除域名，而 skip_certificates 只从证书管理中排除。

来源：modules/caddyhttp/autohttps.go50-59

高级选项

  • ignore_loaded_certificates: 强制 Caddy 管理证书，即使它们已经加载
  • prefer_wildcard: 如果通配符和特定域名都可用，则优先使用通配符

来源：modules/caddyhttp/autohttps.go60-73

按需 TLS

按需 TLS 允许 Caddy 在 TLS 握手期间而非启动时获取证书。这在以下情况很有用

  • 域名集合是预先不知道的
  • 您托管了许多域名，并且不想一次性获取所有证书
  • 您想通过按需获取证书来最大限度地减少资源使用

来源：modules/caddytls/automation.go38-54 modules/caddytls/automation.go139-142

实现细节

自动 HTTPS 阶段

Caddy 在以下阶段实现自动 HTTPS

  1. 第一阶段（automaticHTTPSPhase1）：在配置开始时发生

    • 提供路由匹配器
    • 确定哪些域名符合自动 HTTPS 条件
    • 设置 HTTP 到 HTTPS 的重定向
    • 需要尽早进行，因为它可能会添加需要配置的路由和服务器

  2. 证书加载：在 TLS 应用启动时发生

    • 首先加载手动配置的证书
    • 然后管理自动发现的域名的证书

来源： modules/caddyhttp/autohttps.go82-87 modules/caddytls/tls.go384-402

默认自动化策略

当未定义特定的自动化策略时，Caddy 会创建默认策略

  • 对于公共域名（符合公共证书条件的域名）：使用 ACME/ZeroSSL
  • 对于内部域名：使用内部、自签名证书颁发者

这确保所有域名都能获得适当的证书管理，无需任何配置。

来源： modules/caddytls/automation.go280-301

自动 HTTPS 故障排除

常见问题与解决方案

  1. 未颁发证书

    • 检查域名是否符合公共证书条件（必须是公共域名）
    • 验证 DNS 记录是否已正确配置（域名必须解析到服务器）
    • 确保 ACME 挑战可以完成（HTTP、TLS-ALPN 或 DNS）

  2. HTTP 到 HTTPS 重定向不起作用

    • 检查服务器是否同时监听 HTTP 和 HTTPS 端口
    • 验证重定向未被禁用（disable_redirects: true）
    • 检查是否有冲突的路由可能先处理请求

  3. 证书续订失败

    • 检查与 ACME 服务器的连接性
    • 验证证书存储的存储权限
    • 查看 Caddy 日志中与续订相关的错误

来源： modules/caddyhttp/autohttps.gomodules/caddyhttp/autohttps.go389-402

调试技巧

  • 使用 caddy validate 命令检查您的配置
  • 使用更高的详细程度检查日志： caddy run --config config.json --debug
  • 对于与 ACME 相关的​​问题，请检查与 ACME 端点的连接性

有关 TLS 配置的更多信息，请参阅

  • TLS 系统概述 4
  • 证书管理 4.2
  • 连接策略 4.3