全局选项

Caddyfile 提供了一种方法，用于指定全局适用的选项。某些选项充当默认值；其他选项自定义 HTTP 服务器，不适用于任何特定站点；而另一些选项自定义 Caddyfile 适配器 的行为。

Caddyfile 的最顶部可以是全局选项块。这是一个没有键的块

{
	...
}

最多只能有一个，并且它必须是 Caddyfile 的第一个块。

可能的选项是（单击每个选项以跳转到其文档）

{
	# General Options
	debug
	http_port    <port>
	https_port   <port>
	default_bind <hosts...>
	order <dir1> first|last|[before|after <dir2>]
	storage <module_name> {
		<options...>
	}
	storage_clean_interval <duration>
	admin   off|<addr> {
		origins <origins...>
		enforce_origin
	}
	persist_config off
	log [name] {
		output  <writer_module> ...
		format  <encoder_module> ...
		level   <level>
		include <namespaces...>
		exclude <namespaces...>
	}
	grace_period   <duration>
	shutdown_delay <duration>

	# TLS Options
	auto_https off|disable_redirects|ignore_loaded_certs|disable_certs
	email <yours>
	default_sni <name>
	fallback_sni <name>
	local_certs
	skip_install_trust
	acme_ca <directory_url>
	acme_ca_root <pem_file>
	acme_eab {
		key_id <key_id>
		mac_key <mac_key>
	}
	acme_dns <provider> ...
	on_demand_tls {
		ask      <endpoint>
		interval <duration>
		burst    <n>
	}
	key_type ed25519|p256|p384|rsa2048|rsa4096
	cert_issuer <name> ...
	renew_interval <duration>
	ocsp_interval  <duration>
	ocsp_stapling off
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}

	# Server Options
	servers [<listener_address>] {
		name <name>
		listener_wrappers {
			<listener_wrappers...>
		}
		timeouts {
			read_body   <duration>
			read_header <duration>
			write       <duration>
			idle        <duration>
		}
		trusted_proxies <module> ...
		client_ip_headers <headers...>
		metrics
		max_header_size <size>
		enable_full_duplex
		log_credentials
		protocols [h1|h2|h2c|h3]
		strict_sni_host [on|insecure_off]
	}

	# PKI Options
	pki {
		ca [<id>] {
			name                  <name>
			root_cn               <name>
			intermediate_cn       <name>
			intermediate_lifetime <duration>
			root {
				format <format>
				cert   <path>
				key    <path>
			}
			intermediate {
				format <format>
				cert   <path>
				key    <path>
			}
		}
	}

	# Event options
	events {
		on <event> <handler...>
	}
}

常规选项

debug

启用调试模式，该模式将 默认记录器 的日志级别设置为 DEBUG。这会显示更多详细信息，在进行故障排除时很有用（并且在生产中非常详细）。我们要求你在 社区论坛 上寻求帮助之前启用此功能。例如，在你的 Caddyfile 的顶部，如果没有其他全局选项

{
	debug
}

http_port

服务器用于 HTTP 的端口。

仅供内部使用；不会更改客户端的 HTTP 端口。通常在以下情况下使用此功能：如果在内部网络中，你需要将 80 端口转发到另一个端口（例如 8080），然后才能到达 Caddy，以便进行路由。

默认值：80

https_port

服务器用于 HTTPS 的端口。

仅限内部使用；不会更改客户端的 HTTPS 端口。这通常在以下情况下使用：在内部网络中，需要将 443 端口转发到另一个端口（例如 8443），然后才能到达 Caddy，以便进行路由。

默认值：443

default_bind

如果网站中未使用 bind 指令，则用于所有网站的默认绑定地址。默认值：空，绑定到所有接口。

{
	default_bind 10.0.0.1
}

order

为 HTTP 处理程序指令分配一个顺序。由于 HTTP 处理程序按顺序链执行，因此必须按正确的顺序执行处理程序。标准指令具有 预定义的顺序，但如果使用第三方 HTTP 处理程序模块，则需要通过使用此选项或将指令放在 route 块 中来明确定义顺序。排序可以绝对描述（first 或 last），也可以相对描述（before 或 after）另一个指令。

例如，要使用 replace-response 插件，则需要确保其指令在 encode 之后排序，以便它可以在响应被编码之前执行替换（因为响应向上流动处理程序链，而不是向下流动）

{
	order replace after encode
}

storage

配置 Caddy 的存储机制。默认值为 file_system。还有许多其他可用 存储模块 作为插件提供。

例如，要更改文件系统的存储位置

{
	storage file_system /path/to/custom/location
}

通常在跨多个 Caddy 实例同步 Caddy 的存储时需要自定义存储模块，以确保它们都使用相同的证书和密钥。有关更多详细信息，请参阅 存储的自动 HTTPS 部分。

storage_clean_interval

扫描存储单元以查找旧资产或过期资产并将其删除的频率。这些扫描对存储模块执行大量读取（和列出操作），因此为大型部署选择更长的间隔。接受 持续时间值。

存储将在进程首次启动时始终被清理。然后，如果上一次清理在不到此间隔时间的一半时间内完成，则在此间隔时间后，将启动一次新的清理（否则将跳过下一次启动）。

默认值：24h

{
	storage_clean_interval 7d
}

admin

自定义 admin API 端点。接受占位符。采用 网络地址。

默认值：localhost:2019，除非设置了 CADDY_ADMIN 环境变量。

如果设置为 off，则 admin 端点将被禁用。禁用后，配置更改将无法完成，除非停止并启动服务器，因为 caddy reload 命令 使用 admin API 将新配置推送到正在运行的服务器。

请记住，如果正在运行的服务器的地址已从默认值更改，请使用 --address CLI 标志与兼容的 命令 一起使用，以指定当前 admin 端点。

还支持以下子选项

• origins 配置允许连接到端点的来源列表。

  默认值经过智能选择

  • 如果侦听地址是环回地址（例如 localhost 或环回 IP 或 Unix 套接字），则允许的来源是 localhost、::1 和 127.0.0.1，并与侦听地址端口连接（因此 localhost:2019 是一个有效的来源）。
  • 如果侦听地址不是环回地址，则允许的来源与侦听地址相同。

  如果侦听地址主机不是通配符接口（通配符包括：空字符串或 0.0.0.0 或 [::]），则执行 Host 头部强制。实际上，这意味着默认情况下，Host 头部经过验证，以确保位于 origins 中，因为接口是 localhost。但是，对于具有通配符接口的地址（如 :2020），不执行 Host 头部验证。

• enforce_origin 启用对 Origin 请求头部的强制执行。

  当监听地址为通配符接口（因为 Host 未经验证）且管理员 API 暴露给公共互联网时，此项非常有用。它启用 CORS 预检检查并确保 Origin 标头针对 origins 列表进行验证。仅当您在开发机器上运行 Caddy 且需要从 Web 浏览器访问管理员 API 时才使用此项。

例如，要在所有接口上以不同端口公开管理员 API — ⚠️ 此端口不应公开，否则任何人都可以控制您的服务器；如果您需要公开，请考虑启用来源强制

{
	admin :2020
}

要关闭管理员 API — ⚠️ 这使得重新加载配置变得不可能，除非停止并启动服务器

{
	admin off
}

对管理员 API 使用 Unix 套接字，允许通过文件权限进行访问控制

{
	admin unix//run/caddy-admin.sock
}

仅允许具有匹配 Origin 标头的请求

{
	admin :2019 {
		origins localhost
		enforce_origin
	}
}

persist_config

控制是否应将当前 JSON 配置持久保存到 配置目录，以避免丢失通过管理员 API 执行的配置更改。目前，仅支持 off 选项。默认情况下，配置是持久的。

{
	persist_config off
}

log

配置命名记录器。

可以传递名称以指示要自定义行为的特定记录器。如果未指定名称，则修改 default 记录器的行为。您可以阅读有关 default 记录器的更多信息，以及有关 Caddy 中日志记录的工作原理 的说明。

可以通过多次使用 log 来配置具有不同名称的多个记录器。

这不同于 log 指令，它仅配置 HTTP 请求日志记录（也称为访问日志）。log 全局选项与其配置结构与该指令共享（include 和 exclude 除外），可以在该指令的页面上找到完整文档。

• output 配置写入日志的位置。

  有关完整文档，请参见 log 指令。

• format 描述如何对日志进行编码或格式化。

  有关完整文档，请参见 log 指令。

• level 是要记录的最低条目级别。

  默认值：INFO。

  可能的值：DEBUG、INFO、WARN、ERROR，以及极少见的 PANIC、FATAL。

• include 指定要包含在此记录器中的日志名称。

  默认情况下，此列表为空（即包含所有日志）。

  例如，要仅包含由 admin API 发出的日志，则应包含 admin.api。

• exclude 指定要从该记录器中排除的日志名称。

  默认情况下，此列表为空（即不排除任何日志）。

  例如，要仅排除 HTTP 访问日志，则应排除 http.log.access。

include 和 exclude 接受的记录器名称取决于所使用的模块，最简单的方法是从之前的日志中发现它们。

以下是一个将所有 http 访问日志和 admin 日志作为 json 记录到 stdout 的示例：

{
	log default {
		output stdout
		format json
		include http.log.access admin.api
	}
}

grace_period

定义关闭 HTTP 服务器的宽限期（即在配置更改期间或 Caddy 停止时）。

在宽限期内，不接受新连接，关闭空闲连接，并且不耐烦地等待活动连接完成其请求。如果客户端在宽限期内未完成其请求，则服务器将被强制终止，以允许重新加载完成并释放资源。接受 持续时间值。

默认情况下，宽限期是永久的，这意味着永远不会强制关闭连接。

{
	grace_period 10s
}

shutdown_delay

定义一个 持续时间，在 宽限期之前，即将停止的服务器继续正常运行，但 {http.shutting_down} 占位符评估为 true，并且 {http.time_until_shutdown} 给出宽限期开始之前的时间。

如果任何服务器作为配置更改的一部分被关闭，这会导致延迟，并有效地将更改安排在稍后的时间。它对于向此服务器的运行状况检查器宣布其即将发生的灾难并为负载平衡器腾出时间将其移出轮换很有用；例如

{
	shutdown_delay 30s
}

example.com {
	handle /health-check {
		@goingDown vars {http.shutting_down} true
		respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
		respond 200
	}
	handle {
		respond "Hello, world!"
	}
}

TLS 选项

auto_https

配置 自动 HTTPS，这是使 Caddy 能够为您的网站自动执行证书管理和 HTTP 到 HTTPS 重定向的功能。

有几种模式可供选择

• off：禁用证书自动化和 HTTP 到 HTTPS 重定向。

• disable_redirects：仅禁用 HTTP 到 HTTPS 重定向。

• disable_certs：仅禁用证书自动化。

• ignore_loaded_certs：即使对于出现在手动加载的证书上的名称，也自动执行证书。如果您使用 tls 指令 指定了包含您希望自动管理的名称（或通配符）的证书，则很有用。

{
	auto_https disable_redirects
}

电子邮件

你的电子邮件地址。主要在使用你的 CA 创建 ACME 帐户时使用，并且在你的证书出现问题时强烈建议使用。

{
	email [email protected]
}

default_sni

当客户端在其 ClientHello 中不使用 SNI 时，设置默认 TLS ServerName。

{
	default_sni example.com
}

fallback_sni

⚠️ 实验性

如果配置，如果原始 ServerName 与缓存中的任何证书不匹配，则该回退将成为 ClientHello 中的 TLS ServerName。

它的用途非常小众；通常，如果客户端是 CDN 并通过下游握手的 ServerName，但可以接受具有原始主机名的证书，那么你可以将其设置为原始主机名。请注意，Caddy 必须为该名称管理证书。

{
	fallback_sni example.com
}

local_certs

导致所有证书默认由内部颁发，而不是通过（公共）ACME CA（例如 Let's Encrypt）。这在开发环境中作为快速切换很有用。

{
	local_certs
}

skip_install_trust

跳过将本地 CA 的根安装到系统信任存储以及 Java 和 Mozilla Firefox 信任存储中的尝试。

{
	skip_install_trust
}

acme_ca

指定到 ACME CA 目录的 URL。强烈建议将其设置为 Let's Encrypt 的暂存端点 ，用于测试或开发。默认：ZeroSSL 和 Let's Encrypt 的生产端点。

请注意，全局配置的 ACME CA 可能不适用于所有网站；请参阅主机名要求以使用默认 ACME 颁发者。

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

acme_ca_root

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

{
	acme_ca_root /path/to/ca/root.pem
}

acme_eab

指定一个外部帐户绑定，用于所有 ACME 交易。

例如，使用模拟的 ZeroSSL 凭据

{
	acme_eab {
		key_id GD-VvWydSVFuss_GhBwYQQ
		mac_key MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA
	}
}

acme_dns

配置 ACME DNS 质询 提供程序，用于所有 ACME 交易。

需要使用带有 DNS 提供程序插件的 Caddy 自定义版本。

提供程序名称后面的令牌设置提供程序的方式与在 tls 指令的 acme 发行方 中指定的方式相同。

{
	acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

on_demand_tls

配置 按需 TLS，在按需 TLS 已启用但未启用它的情况下（要启用它，请使用 tls 指令的 on_demand 子指令）。在生产环境中使用时需要此配置，以防止滥用。

• ask 将导致 Caddy 向给定的 URL 发出 HTTP 请求，询问是否允许颁发某个域名的证书。

  该请求的查询字符串为 ?domain=，其中包含域名值。

  如果端点返回 2xx 状态代码，则 Caddy 将被授权获取该名称的证书。任何其他状态代码都将导致取消颁发证书并使 TLS 握手出错。

• interval 和 burst 允许在 <duration> 间隔内执行 <n> 个证书操作。

{
	on_demand_tls {
		ask https://127.0.0.1:9123/ask
	}
}

https:// {
	tls {
		on_demand
	}
}

key_type

指定为 TLS 证书生成的密钥类型；仅在你需要自定义密钥类型时才更改此设置。

可能的值有：ed25519、p256、p384、rsa2048、rsa4096。

{
	key_type ed25519
}

cert_issuer

定义 TLS 证书的发行方（或来源）。

这允许全局配置发行方，而不是像使用 tls 指令的 issuer 子指令 那样按站点配置。

如果您希望配置多个要尝试的发行机构，可以重复。它们将按定义的顺序进行尝试。

{
	cert_issuer acme {
		...
	}
	cert_issuer zerossl {
		...
	}
}

renew_interval

扫描所有已加载的受管理证书的过期时间并触发续订（如果已过期）的频率。

默认值：10m

{
	renew_interval 30m
}

ocsp_interval

检查 OCSP 订书钉 是否需要更新的频率。

默认值：1h

{
	ocsp_interval 2h
}

ocsp_stapling

可以设置为 off 以禁用 OCSP 订书钉。在由于防火墙而无法访问响应者的环境中很有用。

{
	ocsp_stapling off
}

preferred_chains

如果您的 CA 提供多个证书链，您可以使用此选项指定 Caddy 应首选哪个链。设置以下选项之一

• smallest 将告诉 Caddy 首选字节数最少的链。

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

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

请注意，将 preferred_chains 指定为全局选项将影响所有发行机构，如果没有 覆盖发行机构级别配置。

{
	preferred_chains smallest
}

{
	preferred_chains {
		root_common_name "ISRG Root X2"
	}
}

服务器选项

使用可能跨越多个站点的设置自定义 HTTP 服务器，因此无法在站点块中正确配置。这些选项影响 HTTP 层之下的侦听器/套接字或其他设施。

可以指定多次，并使用不同的 listener_address 值为每个服务器配置不同的选项。例如，servers :443 将仅应用于绑定到侦听器地址 :443 的服务器。省略侦听器地址将把选项应用于任何剩余的服务器。

例如，要为端口 :80 和 :443 上的服务器配置不同的选项，您需要指定两个 servers 块

{
	servers :443 {
		listener_wrappers {
			http_redirect
			tls
		}
	}

	servers :80 {
		protocols h1 h2c
	}
}

使用 servers 时，它仅适用于在 Caddyfile 中实际出现的服务器（即由站点块生成）。请记住，自动 HTTPS 将创建一个侦听端口 80（或 http_port 选项）的服务器，以提供 HTTP->HTTPS 重定向并解决 ACME HTTP 挑战；这发生在运行时，即在 Caddyfile 适配器应用 servers 之后。换句话说，这意味着 servers 不会应用于 :80，除非您明确声明一个站点块，如 http:// 或 :80。

name

分配给此服务器的自定义名称。通常有助于通过日志和指标中的名称来识别服务器。如果没有设置，Caddy 将使用 srvX 模式动态定义它，其中 X 从 0 开始，并根据配置中的服务器数量递增。

请记住，只有配置中站点块生成的服务器才会应用设置。 自动 HTTPS 在运行时创建一个 :80 服务器（或 http_port），因此如果您想重命名它，您至少需要一个空的 http:// 站点块。

例如

{
	servers :443 {
		name https
	}
	
	servers :80 {
		name http
	}
}

example.com {
}

http:// {
}

listener_wrappers

允许配置 侦听器包装器，它可以修改套接字侦听器的行为。它们按给定的顺序应用。

有一个特殊的无操作 tls 侦听器包装器，作为标准模块提供，它标记了在侦听器包装器链中应该处理 TLS 的位置。仅当必须将另一个侦听器包装器放在 TLS 握手之前时才应使用它。这不会为服务器启用 TLS；例如，如果在 :80 HTTP 服务器上使用它，它仍将作为无操作。

包含的 http_redirect 侦听器包装器可以查看传入请求的前几个字节，以确定它是否可能是 HTTP（而不是 TLS），并在同一端口上触发 HTTP 到 HTTPS 的重定向，但使用 https:// 方案。当在非标准端口（而不是 443）上提供 HTTPS 时，这非常有用，因为除非指定方案，否则浏览器将尝试 HTTP。不要在 HTTP 服务器上使用此项。它必须放在 tls 侦听器包装器之前。例如

{
	servers {
		listener_wrappers {
			http_redirect
			tls
		}
	}
}

还包括 proxy_protocol 侦听器包装器（在 v2.7.0 之前，它只能通过插件获得），它启用 PROXY 协议 解析（由 HAProxy 推广）。这必须在 tls 侦听器包装器之前使用，因为它在连接开始时解析纯文本数据

{
	servers {
		listener_wrappers {
			proxy_protocol {
				timeout 2s
				allow 192.168.86.1/24 192.168.86.1/24
			}
			tls
		}
	}
}

超时

• read_body 是一个 持续时间值，用于设置允许从客户端上传读取的时间长度。将其设置为较短的非零值可以减轻 slowloris 攻击，但也可能影响合法缓慢的客户端。默认为无超时。

• read_header 是一个 持续时间值，用于设置允许从客户端请求头读取的时间长度。默认为无超时。

• write 是一个 持续时间值，用于设置允许向客户端写入的时间长度。请注意，在提供大型文件时将其设置为较小值可能会对合法缓慢的客户端产生负面影响。默认为无超时。

• idle 是一个 持续时间值，用于设置在启用保持活动时等待下一个请求的最大时间。默认为 5 分钟，以帮助避免资源耗尽。

{
	servers {
		timeouts {
			read_body   10s
			read_header 5s
			write       30s
			idle        10m
		}
	}
}

受信任的代理

允许配置代理服务器的 IP 范围（CIDR），从中应该信任请求。默认情况下，不信任任何代理。

启用此功能会导致受信任的请求从 HTTP 标头（默认情况下为 X-Forwarded-For；请参阅 client_ip_headers 以配置其他标头）中解析出真实客户端 IP。如果受信任，则客户端 IP 会添加到 访问日志 中，可用作 {client_ip} 占位符，并允许使用 client_ip 匹配器。如果请求不是来自受信任的代理，则客户端 IP 会设置为直接传入连接的远程 IP 地址。

某些匹配器或处理程序可能会使用请求的信任状态来做出决策。例如，如果受信任，则 reverse_proxy 处理程序将代理并增强敏感的 X-Forwarded-* 请求标头。

目前，只有 static IP 源模块 包含在 Caddy 的标准发行版中，但可以通过插件 扩展 此模块以维护 IP 范围的动态列表。

static

获取要信任的 IP 范围 (CIDR) 的静态（不变）列表。

作为一种快捷方式，private_ranges 可用于匹配所有私有 IPv4 和 IPv6 范围。它与指定所有这些范围相同：192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1。

语法如下

trusted_proxies static [private_ranges] <ranges...>

这是一个完整的示例，信任一个示例 IPv4 范围和一个 IPv6 范围

{
	servers {
		trusted_proxies static 12.34.56.0/24 1200:ab00::/32
	}
}

client_ip_headers

与 trusted_proxies 配对，允许配置用于确定客户端 IP 地址的标头。默认情况下，仅考虑 X-Forwarded-For。可以指定多个标头字段，在这种情况下，将使用第一个非空标头值。

{
	servers {
		trusted_proxies static private_ranges
		client_ip_headers X-Forwarded-For X-Real-IP
	}
}

metrics

启用 Prometheus 指标收集；在抓取指标之前需要启用。请注意，指标会降低非常繁忙的服务器的性能。（我们的社区正在努力改进这一点。请参与！）

{
	servers {
		metrics
	}
}

max_header_size

从客户端的 HTTP 请求标头中解析的最大大小。如果超出限制，服务器将响应 HTTP 状态431 请求标头字段太大。它接受 go-humanize 支持的所有格式。默认情况下，限制为 1MB。

{
	servers {
		max_header_size 5MB
	}
}

enable_full_duplex

为 HTTP/1 请求启用全双工通信。仅当 Caddy 使用 Go 1.21 或更高版本构建时才有效。

对于 HTTP/1 请求，Go HTTP 服务器在开始编写响应之前默认会使用请求正文的任何未读部分，从而防止处理程序同时从请求中读取并编写响应。启用此选项将禁用此行为，并允许处理程序在同时编写响应时继续从请求中读取。

对于 HTTP/2+ 请求，Go HTTP 服务器始终允许并发读取和响应，因此此选项无效。

使用您的 HTTP 客户端进行彻底测试，因为某些较旧的客户端可能不支持全双工 HTTP/1，这可能导致它们死锁。有关更多信息，请参阅 golang/go#57786。

⚠️ 这是一个实验性功能。可能会更改或删除。

{
	servers {
		enable_full_duplex
	}
}

log_credentials

自 Caddy v2.5 起，默认情况下，具有潜在敏感信息的标头（Cookie、Set-Cookie、Authorization 和 Proxy-Authorization）将在访问日志中以空值记录（请参阅 log 指令）。

如果您希望不编辑这些标头，则可以启用 log_credentials 选项。

{
	servers {
		log_credentials
	}
}

protocols

要支持的 HTTP 协议的空格分隔列表。

默认值：h1 h2 h3

可接受的值是

• h1 表示 HTTP/1.1
• h2 表示 HTTP/2
• h2c 表示明文上的 HTTP/2
• h3 表示 HTTP/3

目前，启用 HTTP/2（包括 H2C）必然意味着启用 HTTP/1.1，因为 Go 标准库不允许我们在使用其 HTTP 服务器时禁用 HTTP/1.1。但是，HTTP/1.1 或 HTTP/3 可以独立启用。

请注意，H2C（“明文 HTTP/2”或“TCP 上的 H2”）和 HTTP/3 并未由 Go 标准库实现，因此某些功能或特性可能会受到限制。除非您的应用程序绝对需要，否则我们建议您不要启用 H2C。

{
	servers :80 {
		protocols h1 h2c
	}
}

strict_sni_host

启用此功能需要请求的 Host 标头与客户端的 TLS ClientHello 发送的 ServerName 的值匹配，这是使用 TLS 客户端身份验证时必要的保护措施。如果出现不匹配，则向客户端写入 HTTP 状态 421 Misdirected Request 响应。

如果客户端身份验证已配置，此选项将自动打开。这将禁止 TLS 客户端身份验证绕过（域前端），否则在 TLS 握手期间发送未受保护的 SNI 值，然后在建立连接后将受保护的域放入 Host 头中，可能会利用此漏洞。此行为是安全的默认设置，但你可以使用 insecure_off 明确将其关闭；例如，在运行需要域前端的代理且访问不受主机名限制的情况下。

{
	servers {
		strict_sni_host on
	}
}

PKI 选项

PKI（公钥基础设施）应用程序是 Caddy 的本地 HTTPS和ACME 服务器功能的基础。该应用程序定义了能够签署证书的证书颁发机构 (CA)。

默认 CA ID 为 local。如果在配置 ca 时省略了 ID，则假定为 local。

name

证书颁发机构面向用户的名称。

默认值：Caddy Local Authority

{
	pki {
		ca local {
			name "My Local CA"
		}
	}
}

root_cn

要放入根证书的 CommonName 字段中的名称。

默认值：{pki.ca.name} - {time.now.year} ECC Root

{
	pki {
		ca local {
			root_cn "My Local CA - 2024 ECC Root"
		}
	}
}

intermediate_cn

要放入中间证书的 CommonName 字段中的名称。

默认值：{pki.ca.name} - ECC Intermediate

{
	pki {
		ca local {
			intermediate_cn "My Local CA - ECC Intermediate"
		}
	}
}

intermediate_lifetime

中间证书有效的持续时间。此值必须小于根证书的生存期（3600d 或 10 年）。

默认值：7d。不建议更改此值，除非绝对必要。

{
	pki {
		ca local {
			intermediate_lifetime 30d
		}
	}
}

root

用作 CA 根的密钥对（证书和私钥）。如果未指定，将自动生成并管理一个密钥对。

• format 是提供证书和私钥的格式。目前，仅支持 pem_file，这是默认值，因此此字段是可选的。
• cert 是证书。使用 pem_file 格式时，这应该是 PEM 文件的路径。
• key 是私钥。使用 pem_file 格式时，这应该是 PEM 文件的路径。

intermediate

用作 CA 中间的密钥对（证书和私钥）。如果未指定，将自动生成并管理一个密钥对。

• format 是提供证书和私钥的格式。目前，仅支持 pem_file，这是默认值，因此此字段是可选的。
• cert 是证书。使用 pem_file 格式时，这应该是 PEM 文件的路径。
• key 是私钥。使用 pem_file 格式时，这应该是 PEM 文件的路径。

{
	pki {
		ca local {
			root {
				format pem_file
				cert /path/to/root.pem
				key /path/to/root.key
			}
			intermediate {
				format pem_file
				cert /path/to/intermediate.pem
				key /path/to/intermediate.key
			}
		}
	}
}

事件选项

当发生（或即将发生）有趣的事情时，Caddy 模块会发出事件。

事件通常包括元数据有效负载。了解事件及其有效负载的最佳方式是查看每个模块的文档，但您还可以通过启用 debug 全局选项 并阅读日志来查看事件及其数据有效负载。

on

将事件处理程序绑定到指定事件。指定事件处理程序模块的名称，后跟其配置。

例如，要在获取证书后运行命令（第三方插件 必需），其中部分事件有效负载使用占位符传递给脚本

{
	events {
		on cert_obtained exec ./my-script.sh {event.data.certificate_path}
	}
}

事件

这些标准事件由 Caddy 发出

• tls 事件
• reverse_proxy 事件

插件还可以发出事件，因此请查看其文档了解详情。