文档
一个 项目

tls

配置站点的 TLS。

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

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

语法

tls [internal|<email>] | [<cert_file> <key_file>] {
	protocols <min> [<max>]
	ciphers   <cipher_suites...>
	curves    <groups...>
	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
	reuse_private_keys
	client_auth {
		mode                   [request|require|verify_if_given|require_and_verify]
		trust_pool             <module>
		verifier 			   <module>
	}
	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 组列表。建议不要更改默认值。支持的值有：

    • x25519mlkem768 (PQC)
    • x25519
    • secp256r1
    • secp384r1
    • secp521r1

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

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

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

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

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

  • dns 使用指定的提供者插件启用 DNS 质询，该插件必须从 caddy-dns 仓库中插入。每个提供者插件可能在其名称后有自己的语法；有关详细信息，请参阅其文档。维护对每个 DNS 提供者的支持是一项社区工作。在我们的 wiki 上了解如何为您的提供者启用 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 插件 ，您可能想要使用此选项。您可以改为向主域添加一个带有子域 _acme-challenge 的 CNAME 记录，指向您确实有插件的次要域。此选项不需要插件的特殊支持。

    当 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 为站点块的地址中给出的主机名启用按需 TLS。安全警告： 除非您还配置了 on_demand_tls 全局选项 以减轻滥用，否则在生产环境中这样做是不安全的。

  • reuse_private_keys 启用续订证书时重用私钥。默认情况下，每个新证书都会创建一个新密钥，以减轻固定并减少密钥泄露的范围。密钥固定违反行业最佳实践。除非您有特定理由使用此选项，否则不建议使用；这可能会在将来的版本中被移除。

  • client_auth 启用并配置 TLS 客户端认证：

    • mode 是认证客户端的模式。允许的值有：

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

      默认值：如果提供了 trust_pool 模块，则为 require_and_verify；否则为 require。

    • trust_pool 配置用于验证客户端证书的证书颁发机构（CA）的来源。

      提供受信任证书池的证书颁发机构和段内的配置取决于配置的信任池模块源。Caddy 中可用的标准模块如下所示。完整模块列表，包括第三方模块，列在 trust_pool JSON 文档 中。

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

    • verifier 启用自定义客户端证书验证器模块的使用。这些可以执行自定义客户端认证检查，例如确保证书未被撤销。

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

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

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

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

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

信任池提供者

这些是可以在 trust_pool 子指令中使用的标准信任池提供者：

inline

inline 模块直接以 base64 DER 编码格式解析 Caddyfile 中列出的受信任根证书。trust_der 指令可以重复多次。

trust_pool inline {
	trust_der      <base64_der>
}
  • trust_der 是用于验证客户端证书的 base64 DER 编码的 CA 证书。

file

file 模块从磁盘上的 PEM 文件读取受信任的根证书。pem_file 指令可以在同一行接受多个文件路径，并且可以重复多次。

... file [<pem_file>...] {
	pem_file <pem_file>...
}
  • pem_file 是用于验证客户端证书的 PEM CA 证书文件的路径。

pki_root

pki_root 模块从 PKI 应用 中定义的证书颁发机构获取 root 和信任证书。authority 指令可以同时接受多个颁发者，并且可以重复多次。

... pki_root [<ca_name>...] {
	authority <ca_name>...
}
  • authority 是在 PKI 应用中配置的证书颁发机构的名称。

pki_intermediate

pki_intermediate 模块从 PKI 应用 中定义的证书颁发机构获取 intermediate 和信任证书。authority 指令可以同时接受多个颁发者，并且可以重复多次。

... pki_intermediate [<ca_name>...] {
	authority <ca_name>...
}
  • authority 是在 PKI 应用中配置的证书颁发机构的名称。

storage

storage 模块从 Caddy 存储 中提取受信任的证书根。authority 指令可以同时接受多个颁发者，并且可以重复多次。

... storage [<storage_keys>...] {
	storage <storage_module>
	keys    <storage_keys>...
}

  • storage 是要使用的可选存储模块。如果未指定，将使用默认存储模块。如果指定，它只能指定一次。

  • keys 是存储证书的 PEM 文件的存储键列表。该指令可以在同一行接受多个值，并且可以多次指定。

http

http 模块从 HTTP 端点获取受信任的证书。endpoints 指令可以同时接受多个端点，并且可以重复多次。

... http [<endpoints...>] {
	endpoints   <endpoints...>
	tls         <tls_config>
}

  • endpoints 是要从中获取证书的 HTTP 端点列表。该指令可以在同一行接受多个值，并且可以多次指定。

  • tls 是连接到 HTTP 端点时要使用的可选 TLS 配置。段解析在以下部分中定义。

TLS
... {
	ca                    <ca_module>
	insecure_skip_verify
	handshake_timeout     <duration>
	server_name           <name>
	renegotiation         <never|once|freely>
}

  • ca 是可选指令，用于定义信任池提供者。配置行为与 trust_pool 相同。如果指定，它只能指定一次。

  • insecure_skip_verify 关闭 TLS 握手验证，使连接不安全且容易受到中间人攻击。不要在生产中使用。 验证是针对系统信任的证书颁发机构或 ca 指令确定的。

  • handshake_timeout 是等待 TLS 握手完成的最大持续时间。默认值：无超时。

  • server_name 设置在 TLS 握手期间使用的服务器名称，以验证接收到的证书。默认情况下，这将使用上游地址的主机部分。

  • renegotiation 设置 TLS 重新协商级别。TLS 重新协商是执行后续握手的过程。级别可以是以下之一：

    • never（默认）禁用重新协商。
    • once 允许远程服务器在每次连接时请求重新协商一次。
    • freely 允许远程服务器反复请求重新协商。

Issuers

这些颁发者是 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 是用于完成 ZeroSSL 的 HTTP 验证的备用端口，如果不是端口 80。

  • alt_tlsalpn_port 是用于完成 ZeroSSL 的 TLS-ALPN 验证的备用端口，必须发生在端口 443 上，因此您必须将数据包转发到此备用端口。

  • eab 指定外部账户绑定（EAB），可能需要与某些 ACME CAs 一起使用。

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

  • dns 配置 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 插件 ，您可能想要使用此选项。您可以改为向主域添加一个带有子域 _acme-challenge 的 CNAME 记录，指向您确实有插件的次要域。此选项不需要插件的特殊支持。

    当 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

使用 ZeroSSL 的专有证书颁发 API 获取证书。需要 API 密钥，并且可能需要根据您的计划支付。请注意，此问题与 ZeroSSL 的 ACME 端点 不同。要使用 ZeroSSL 的 ACME 端点，请使用上面配置的 acme 颁发者，配置 ZeroSSL 的 ACME 目录端点。

... zerossl <api_key> {
	validity_days <days>
	alt_http_port <port>
	dns <provider_name> ...
	propagation_delay <duration>
	propagation_timeout <duration>
	resolvers <list...>
	dns_ttl <duration>
}
  • validity_days 定义证书生命周期。仅接受某些值；请参阅 ZeroSSL 的文档 了解详细信息。
  • alt_http_port 是用于完成 ZeroSSL 的 HTTP 验证的端口，如果不是端口 80。
  • dns 启用 CNAME 验证方法，使用给定的配置自动记录提供程序，用于自动记录提供程序。DNS 提供程序插件必须从 caddy-dns 仓库中安装。每个提供程序插件可能在其名称后有自己的语法；有关详细信息，请参阅其文档。维护对每个 DNS 提供程序的支持是一项社区工作。
  • propagation_delay 是等待 CNAME 记录传播之前的时间。
  • propagation_timeout 是等待 CNAME 记录传播之前的时间。
  • resolvers 定义自定义 DNS 解析器，用于检查 CNAME 记录传播。
  • dns_ttl 配置 CNAME 记录创建作为验证过程的一部分的 TTL。

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 强制根成为发行者，而不是中间。不建议使用此选项，除非设备/客户端不正确地验证证书链（非常罕见）。

Certificate Managers

证书管理器模块与颁发者模块不同，因为使用管理器模块意味着外部工具或服务正在保持证书更新，而颁发者模块意味着 Caddy 本身正在管理证书。（颁发者模块接受证书签名请求（CSR）作为输入，但证书管理器模块接受 TLS ClientHello 作为输入。）

这些管理器模块是 tls 指令的标准：

tailscale

从本地运行的 Tailscale 实例获取证书。HTTPS 必须在您的 Tailscale 帐户中启用（或您的开源 Headscale 服务器 ); 并且 Caddy 进程必须作为根运行，或者您必须配置 tailscaled 以授予您的 Caddy 用户获取证书的权限。

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

get_certificate tailscale  # often unnecessary!

http

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

get_certificate http <url>

  • url 是要对其进行请求的完全限定的 URL。强烈建议此为本地端点，以获得性能原因。URL 将补充以下查询字符串参数：

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

示例

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

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 your@email.com
}

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

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

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

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

启用 TLS 客户端认证并要求客户端提供经过验证的有效证书，通过 trust_pool file 提供程序提供所有提供的 CA 的验证：

example.com {
	tls {
		client_auth {
			trust_pool file ../caddy.ca.cer ../root.ca.cer
		}
	}
}