文档
一个 项目

tls

为站点配置 TLS。

Caddy 的默认 TLS 设置是安全的。只有在有充分理由且理解其影响的情况下才更改这些设置。 此指令最常见的用途是指定 ACME 帐户电子邮件地址、更改 ACME CA 端点或提供您自己的证书。

兼容性说明：由于 TLS 协议的敏感性，在新的次要或补丁版本中可能会对 TLS 默认值进行有意调整。旧版或损坏的 TLS 版本、密码、功能等可能会随时被移除。如果您的部署对更改极其敏感，您应该明确指定必须保持不变的值，并注意升级。在几乎所有情况下，我们建议使用默认设置。

语法

tls [internal|<email>] | [<cert_file> <key_file>] {
	protocols <min> [<max>]
	ciphers   <cipher_suites...>
	curves    <curves...>
	alpn      <values...>
	load      <paths...>
	ca        <ca_dir_url>
	ca_root   <pem_file>
	key_type  ed25519|p256|p384|rsa2048|rsa4096
	dns       <provider_name> [<params...>]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	eab       <key_id> <mac_key>
	on_demand
	client_auth {
		mode                   [request|require|verify_if_given|require_and_verify]
		trusted_ca_cert        <base64_der>
		trusted_ca_cert_file   <filename>
		trusted_leaf_cert      <base64_der>
		trusted_leaf_cert_file <filename>
	}
	issuer          <issuer_name>  [<params...>]
	get_certificate <manager_name> [<params...>]
	insecure_secrets_log <log_file>
}

  • internal 表示使用 Caddy 的内部、本地信任的 CA 为该站点生成证书。要进一步配置 internal 发行者，请使用 issuer 子指令。

  • <email> 是用于管理站点证书的 ACME 帐户的电子邮件地址。您可能更喜欢使用 email 全局选项，以便为所有站点一次性配置此选项。

  • <cert_file> 和 <key_file> 是证书和私钥 PEM 文件的路径。仅指定一个是不合法的。

  • protocols 指定最小和最大协议版本。除非您知道自己在做什么，否则不要更改这些设置。配置此选项很少需要，因为 Caddy 将始终使用现代默认值。

    默认最小值：tls1.2，默认最大值：tls1.3

  • ciphers 指定密码套件名称列表，按优先级降序排列。除非您知道自己在做什么，否则不要更改这些设置。请注意，密码套件对于 TLS 1.3 不可自定义；并且并非所有 TLS 1.2 密码默认情况下都已启用。支持的名称为（按 Go 标准库的优先级排序）：

    • TLS_AES_128_GCM_SHA256
    • TLS_CHACHA20_POLY1305_SHA256
    • TLS_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

  • curves 指定要支持的 EC 曲线列表。建议不要更改这些设置。支持的值为：

    • x25519
    • secp256r1
    • secp384r1
    • secp521r1

  • alpn 是在 TLS 握手 ALPN 扩展 中要通告的值列表。

  • load 指定要从中加载证书+密钥捆绑包的 PEM 文件的文件夹列表。

  • ca 更改 ACME CA 端点。这最常用于设置 Let's Encrypt 的暂存端点 （在测试时）或内部 ACME 服务器。（要更改整个 Caddyfile 的此值，请使用 acme_ca 全局选项。）

  • ca_root 指定包含 ACME CA 端点的受信任根证书的 PEM 文件（如果不在系统信任存储中）。

  • key_type 是在生成 CSR 时要使用的密钥类型。只有在您有特定要求时才设置此选项。

  • dns 使用指定的提供程序插件启用 DNS 挑战，该插件必须从 caddy-dns 存储库之一中插入。每个提供程序插件可能在其名称之后有自己的语法；有关详细信息，请参阅其文档。维护对每个 DNS 提供程序的支持是一项社区工作。 从我们的维基了解如何为您的提供程序启用 DNS 挑战。

  • propagation_timeout 是一个 持续时间值，用于设置使用 DNS 挑战时等待 DNS TXT 记录出现的最长时间。设置为 -1 以禁用传播检查。默认 2 分钟。

  • propagation_delay 是一个 持续时间值，用于设置使用 DNS 挑战时在开始 DNS TXT 记录传播检查之前要等待的时间。默认 0（不等待）。

  • dns_ttl 是一个 持续时间值，用于设置用于 DNS 挑战的 TXT 记录的 TTL。很少需要。

  • dns_challenge_override_domain 覆盖用于 DNS 挑战的域。这是为了将挑战委派给另一个域。

    如果您主要域的 DNS 提供程序没有可用的 DNS 插件 ，您可能需要使用此选项。您可以改为添加一个 CNAME 记录，其子域 _acme-challenge 指向您确实有插件的辅助域。此选项不需要插件的特殊支持。

    当 ACME 发行者尝试解决您主要域的 DNS 挑战时，他们将遵循 CNAME 到您的辅助域以查找 TXT 记录。

    注意：在此处使用来自 CNAME 记录的完整规范名称 - _acme-challenge 子域不会自动添加。

  • resolvers 自定义在执行 DNS 挑战时使用的 DNS 解析器；这些解析器优先于系统解析器或任何默认解析器。如果在此处设置，解析器将传播到所有配置的证书发行者。

    这通常是 IP 地址列表。例如，要使用 Google 公共 DNS 

    resolvers 8.8.8.8 8.8.4.4

  • eab 使用您的 CA 提供的密钥 ID 和 MAC 密钥为该站点配置 ACME 外部帐户绑定 (EAB)。

  • on_demand 为站点块的地址（es）中给出的主机名启用 按需 TLS。安全警告：在生产环境中这样做是不安全的，除非您还配置了 on_demand_tls 全局选项 以减轻滥用。

  • client_auth 启用并配置 TLS 客户端身份验证：

    • mode 是用于对客户端进行身份验证的模式。允许的值为：

      模式 描述
      request 向客户端请求证书，但即使没有证书也允许；不验证它
      require 要求客户端出示证书，但不验证它
      verify_if_given 向客户端请求证书；即使没有证书也允许，但如果有证书则验证它
      require_and_verify 要求客户端出示经过验证的有效证书

      默认值：如果提供了任何 trusted_ca_cert 或 trusted_leaf_cert，则为 require_and_verify；否则为 require。

    • trusted_ca_cert 是一个 base64 DER 编码的 CA 证书，用于验证客户端证书。

    • trusted_ca_cert_file 是一个指向 PEM CA 证书文件的路径，用于验证客户端证书。

    • trusted_leaf_cert 是一个 base64 DER 编码的客户端叶证书，用于接受。

    • trusted_leaf_cert_file 是一个指向 PEM CA 证书文件的路径，用于验证客户端证书。

      可以使用多个 trusted_* 指令来指定多个 CA 或叶证书。根据 mode，未列为叶证书之一或未由任何指定 CA 签名的客户端证书将被拒绝。

  • issuer 配置自定义证书发行者或获取证书的来源。

    使用哪个发行者以及此段中后续的选项取决于可用的 发行者模块。一些其他子指令（例如 ca 和 dns）实际上是配置 acme 发行者的快捷方式（此子指令是在后来添加的），因此指定此指令和一些其他指令会造成混淆，因此被禁止。

    此子指令可以多次指定，以配置多个冗余发行者；如果一个发行者无法颁发证书，则将尝试下一个发行者。

  • get_certificate 启用在握手时从 管理器模块 获取证书。

  • insecure_secrets_log 启用将 TLS 机密信息记录到文件。这也称为 SSLKEYLOGFILE。使用 NSS 密钥日志格式，然后可以由 Wireshark 或其他工具解析。⚠️ 安全警告：这很不安全，因为它允许其他程序或工具解密 TLS 连接，从而完全破坏安全性。但是，此功能对于调试和故障排除很有用。

发行者

这些发行者随 tls 指令一起提供

acme

使用 ACME 协议获取证书。请注意，acme 是一个默认发行者（使用 Let's Encrypt），因此通常不需要显式配置它。

... acme [<directory_url>] {
	dir      <directory_url>
	test_dir <test_directory_url>
	email    <email>
	timeout  <duration>
	disable_http_challenge
	disable_tlsalpn_challenge
	alt_http_port    <port>
	alt_tlsalpn_port <port>
	eab <key_id> <mac_key>
	trusted_roots <pem_files...>
	dns <provider_name> [<options>]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}
}

  • dir 是 ACME CA 的目录的 URL。

    默认值：https://acme-v02.api.letsencrypt.org/directory

  • test_dir 是一个可选的备用目录，用于在重试挑战时使用；如果所有挑战都失败，则此端点将在重试期间使用；如果 CA 有一个暂存端点，您希望避免其生产端点的速率限制，这将很有用。

    默认值：https://acme-staging-v02.api.letsencrypt.org/directory

  • email 是 ACME 帐户的联系电子邮件地址。

  • timeout 是一个 持续时间值，用于设置在 ACME 操作超时之前要等待的时间。

  • disable_http_challenge 将禁用 HTTP 挑战。

  • disable_tlsalpn_challenge 将禁用 TLS-ALPN 挑战。

  • alt_http_port 是用于提供 HTTP 挑战的备用端口；它必须在端口 80 上发生，因此您必须将数据包转发到此备用端口。

  • alt_tlsalpn_port 是用于提供 TLS-ALPN 挑战的备用端口；它必须在端口 443 上进行，因此您必须将数据包转发到此备用端口。

  • eab 指定外部帐户绑定，某些 ACME CA 可能需要此绑定。

  • trusted_roots 是一个或多个根证书（作为 PEM 文件名），在连接到 ACME CA 服务器时需要信任这些证书。

  • dns 配置 DNS 挑战。

  • propagation_timeout 是一个 持续时间值，用于设置使用 DNS 挑战时等待 DNS TXT 记录出现的最长时间。设置为 -1 以禁用传播检查。默认 2 分钟。

  • propagation_delay 是一个 持续时间值，用于设置在使用 DNS 挑战时，在开始 DNS TXT 记录传播检查之前等待的时间。默认值为 0（不等待）。

  • dns_ttl 是一个 持续时间值，用于设置用于 DNS 挑战的 TXT 记录的 TTL。很少需要。

  • dns_challenge_override_domain 覆盖用于 DNS 挑战的域。这是为了将挑战委派给另一个域。

    如果您主要域的 DNS 提供程序没有可用的 DNS 插件 ，您可能需要使用此选项。您可以改为添加一个 CNAME 记录，其子域 _acme-challenge 指向您确实有插件的辅助域。此选项不需要插件的特殊支持。

    当 ACME 发行者尝试解决您主要域的 DNS 挑战时，他们将遵循 CNAME 到您的辅助域以查找 TXT 记录。

    注意：在此处使用来自 CNAME 记录的完整规范名称 - _acme-challenge 子域不会自动添加。

  • resolvers 自定义在执行 DNS 挑战时使用的 DNS 解析器；这些解析器优先于系统解析器或任何默认解析器。如果在此处设置，解析器将传播到所有配置的证书发行者。

    这通常是 IP 地址列表。例如，要使用 Google 公共 DNS 

    resolvers 8.8.8.8 8.8.4.4

  • preferred_chains 指定 Caddy 应该优先使用的证书链；如果您的 CA 提供多个链，这将很有用。使用以下选项之一：

    • smallest 将告诉 Caddy 优先使用字节数最少的链。

    • root_common_name 是一个或多个通用名称的列表；Caddy 将选择第一个与至少一个指定通用名称匹配的根的链。

    • any_common_name 是一个或多个通用名称的列表；Caddy 将选择第一个与至少一个指定通用名称匹配的发行者的链。

zerossl

使用 ACME 协议（特别是 ZeroSSL）获取证书。请注意，zerossl 是默认发行者，因此通常不需要显式配置它。

... zerossl [<api_key>] {
	...
}

zerossl 的语法与 acme 完全相同，只是它的名称是 zerossl，并且可以选择使用您的 ZeroSSL API 密钥。

它的功能也相同，只是它默认情况下将使用 ZeroSSL 的目录，并且可以自动协商 EAB 凭据（而使用 acme 发行者，您必须手动提供 EAB 凭据并设置目录端点）。

在显式配置 zerossl 时，需要配置 email，以便您的证书可以显示在您的 ZeroSSL 仪表板中。

internal

从内部证书颁发机构获取证书。

... internal {
	ca       <name>
	lifetime <duration>
	sign_with_root
}

  • ca 是要使用的内部 CA 的名称。默认值：local。请参阅 PKI 应用程序全局选项 以配置 local CA 或创建备用 CA。

    默认情况下，根 CA 证书的有效期为 3600d（10 年），中间证书的有效期为 7d（7 天）。

    Caddy 将尝试将根 CA 证书安装到系统信任存储中，但这可能会在 Caddy 作为非特权用户运行或在 Docker 容器中运行时失败。在这种情况下，需要手动安装根 CA 证书，可以使用 caddy trust 命令或 从容器中复制出来。

  • lifetime 是一个 持续时间值，用于设置内部颁发的叶子证书的有效期。默认值：12h。不建议更改此值，除非绝对必要。它必须短于中间证书的有效期。

  • sign_with_root 强制使用根作为发行者而不是中间证书。不建议这样做，并且仅应在设备/客户端无法正确验证证书链（非常罕见）时使用。

证书管理器

证书管理器模块与发行者模块不同，使用管理器模块意味着外部工具或服务正在维护证书的续订，而发行者模块意味着 Caddy 本身正在管理证书。（发行者模块以证书签名请求 (CSR) 作为输入，而证书管理器模块以 TLS 客户端问候作为输入。）

这些管理器模块是 tls 指令的标准配置。

tailscale

从本地运行的 Tailscale 实例获取证书。您的 Tailscale 帐户（或您的开源 Headscale 服务器 ）必须 启用 HTTPS；并且 Caddy 进程必须以 root 身份运行，或者您必须配置 tailscaled 以授予您的 Caddy 用户 获取证书的权限。

注意：这通常是不必要的！ Caddy 自动为所有 *.ts.net 域使用 Tailscale，无需任何额外配置。

get_certificate tailscale  # often unnecessary!

http

通过发出 HTTP(S) 请求获取证书。响应必须具有 200 状态代码，并且主体必须包含一个 PEM 链，其中包括完整的证书（包含中间证书）以及私钥。

get_certificate http <url>

  • url 是要发出请求的完全限定 URL。强烈建议此 URL 为本地端点，以提高性能。URL 将使用以下查询字符串参数进行扩展：

    • server_name：SNI 值
    • signature_schemes：签名算法的十六进制 ID 的逗号分隔列表
    • cipher_suites：密码套件的十六进制 ID 的逗号分隔列表

示例

使用自定义证书和密钥。证书应具有与站点地址匹配的 SAN。

example.com {
	tls cert.pem key.pem
}

对当前站点块上的所有主机使用 本地信任 证书，而不是通过 ACME/Let's Encrypt 使用公共证书（在开发环境中很有用）。

example.com {
	tls internal
}

使用本地信任证书，但管理 按需 而不是在后台。这允许您将任何域指向您的 Caddy 实例，并让它自动为您配置证书。如果您的 Caddy 实例是公开可访问的，则不应使用此方法，因为攻击者可以使用它来耗尽服务器的资源。

https:// {
	tls internal {
		on_demand
	}
}

对内部 CA 使用自定义选项（无法使用 tls internal 快捷方式）。

example.com {
	tls {
		issuer internal {
			ca foo
		}
	}
}

为您的 ACME 帐户指定电子邮件地址（但如果所有站点只使用一个电子邮件地址，我们建议使用 email 全局选项）。

example.com {
	tls [email protected]
}

为在 Cloudflare 上管理的域启用 DNS 挑战，并在环境变量中使用帐户凭据。这将解锁通配符证书支持，这需要 DNS 验证。

*.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
}

通过 HTTP 获取证书链，而不是让 Caddy 管理它。请注意，get_certificate 意味着 on_demand 已启用，使用模块获取证书而不是触发 ACME 发行。

https:// {
	tls {
		get_certificate http https://127.0.0.1:9007/certs
	}
}

启用 TLS 客户端身份验证，并要求客户端出示经过 trusted_ca_cert_file 中提供的所有 CA 验证的有效证书。

example.com {
	tls {
		client_auth {
			mode                 require_and_verify
			trusted_ca_cert_file ../caddy.ca.cer
			trusted_ca_cert_file ../root.ca.cer
		}
	}
}