全局选项

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>
	metrics {
		per_host
	}

	# 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> ...
	dns <provider> ...
	ech <public_names...> {
		dns <provider> ...
	}
	on_demand_tls {
		ask        <endpoint>
		permission <module>
	}
	key_type ed25519|p256|p384|rsa2048|rsa4096
	cert_issuer <name> ...
	renew_interval <duration>
	cert_lifetime  <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>
		}
		keepalive_interval <duration>
		trusted_proxies <module> ...
		client_ip_headers <headers...>
		trace
		max_header_size <size>
		enable_full_duplex
		log_credentials
		protocols [h1|h2|h2c|h3]
		strict_sni_host [on|insecure_off]
	}

	# File Systems
	filesystem <name> <module> {
		<options...>
	}

	# 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 未经验证）并且 admin API 暴露于公共互联网时，这最有用。它启用 CORS 预检检查，并确保 Origin 标头根据 origins 列表进行验证。仅当您在开发机器上运行 Caddy 并且需要从 Web 浏览器访问 admin API 时才使用此选项。

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

{
	admin :2020
}

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

{
	admin off
}

要为 admin API 使用 unix 套接字，允许通过文件权限进行访问控制

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

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

{
	admin :2019 {
		origins localhost
		enforce_origin
	}
}

persist_config

控制是否应将当前 JSON 配置持久化到配置目录，以避免丢失通过 admin 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
}

email

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

{
	email admin@example.com
}

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 事务的 ACME DNS 质询提供程序。

需要使用 DNS 提供程序的插件自定义构建 Caddy。

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

{
	acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

dns

当在相关上下文中未在本地指定其他 DNS 提供程序时，配置要使用的默认 DNS 提供程序。例如，如果启用了 ACME DNS 质询，但未配置 DNS 提供程序，则将使用此全局默认值。它也适用于发布加密客户端问候语 (ECH) 配置。

您的 Caddy 二进制文件必须使用指定的 DNS 提供程序模块进行编译才能正常工作。

示例，使用来自环境变量的凭据

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

（需要 Caddy 2.10 beta 1 或更高版本。）

ech

通过在 TLS 握手中使用指定的公共域名作为明文服务器名称 (SNI)，启用加密客户端问候语 (ECH)。在正确的情况下，ECH 可以帮助保护连接期间线路上的站点域名。Caddy 将为每个指定的公共名称生成和发布一个 ECH 配置。发布是兼容客户端（例如正确配置的现代浏览器）如何知道使用 ECH 访问您的站点。

为了正常工作，必须以客户端期望的方式发布 ECH 配置。大多数浏览器（启用 DNS-over-HTTPS 或 DNS-over-TLS）希望将 ECH 配置发布到 HTTPS 类型 DNS 记录。Caddy 会自动执行此类发布，但您必须使用 dns 子选项或全局使用 dns 全局选项指定 DNS 提供程序，并且您的 Caddy 二进制文件必须使用指定的 DNS 提供程序模块构建。（自定义构建可在我们的 下载页面上找到。）

隐私声明

• 通常建议最大化您的匿名集的大小。因此，我们通常建议大多数用户仅配置一个公共域名来保护所有站点。
• 您的服务器应该是您指定的公共域名的权威（即它们应该指向您的服务器），因为 Caddy 将为其获取证书。这些证书对于帮助符合规范的客户端在某些情况下可靠且安全地与 ECH 连接至关重要。它们仅用于促进正确的 ECH 握手，而不是用于应用程序数据（您的站点——除非您定义一个与您的公共域名相同的站点）。
• 每种情况都可能不同。如果风险很高，我们建议咨询专家来审查您的威胁模型，因为 ECH 不是一刀切的解决方案。

示例，使用来自环境变量的凭据发布到停放在 Cloudflare 的名称服务器

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	ech ech.example.net
}

这应该导致兼容的客户端使用 ech.example.net 加载您的所有站点，而不是以明文形式公开的各个站点名称。

成功发布需要将您站点的域名停放在配置的 DNS 提供程序处，并且可以使用给定的凭据/提供程序配置修改记录。

（需要 Caddy 2.10 beta 1 或更高版本。）

on_demand_tls

配置启用按需 TLS 的位置，但不启用它（要启用它，请使用 tls 指令的 on_demand 子指令）。在生产环境中使用是必需的，以防止滥用。

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

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

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

• permission 允许使用自定义模块来确定是否应为特定名称颁发证书。该模块必须实现 caddytls.OnDemandPermission 接口。包含一个 http 权限模块，这是 ask 选项使用的模块，并且作为向后兼容性的快捷方式保留。

• ⚠️ interval 和 burst 速率限制选项可用，但不建议使用。如果您仍然拥有它们，请从您的配置中删除它们。

{
	on_demand_tls {
		ask http://localhost: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
}

cert_lifetime

要求 CA 颁发证书的有效期。

此值用于计算 ACME 订单的 notAfter 字段；因此系统必须具有合理同步的时钟。注意：并非所有 CA 都支持此功能。请查阅您的 CA 的 ACME 文档以查看是否允许这样做以及可以使用哪些值。

默认值：0（CA 选择有效期，通常为 90 天）

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

{
	cert_lifetime 30d
}

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 握手之前时才应使用它。

http_redirect

http_redirect 为 TLS 端口上作为 HTTP 请求的连接提供 HTTP->HTTPS 重定向，方法是使用前几个字节检测到它不是 TLS 握手，而是 HTTP 请求。当在非标准端口（443 以外）上提供 HTTPS 时，这最有用，因为除非指定了方案，否则浏览器将尝试 HTTP。它必须放置在 tls 侦听器包装器之前。这是一个例子

{
	servers {
		listener_wrappers {
			http_redirect
			tls
		}
	}
}

proxy_protocol

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

proxy_protocol {
	timeout <duration>
	allow <cidrs...>
	deny <cidrs...>
	fallback_policy <policy>
}

• timeout 指定等待 PROXY 标头的最长持续时间。默认为 5s。

• allow 是受信任来源的 CIDR 范围列表，用于接收 PROXY 标头。Unix 套接字默认受信任，不属于此选项。

• deny 是受信任来源的 CIDR 范围列表，用于拒绝来自它们的 PROXY 标头。

• fallback_policy 是当 PROXY 标头来自不在 allow/deny 列表中的地址时要采取的操作。默认的回退策略是 ignore。fallback_policy 的接受值为

  • ignore：来自 PROXY 标头的地址，但接受连接
  • use：来自 PROXY 标头的地址
  • reject：当发送 PROXY 标头时拒绝连接
  • require：连接必须发送 PROXY 标头，如果未提供则拒绝连接
  • skip：接受连接，无需 PROXY 标头。

例如，对于一个 HTTPS 服务器（需要 tls 监听器封装器），它接受来自特定 IP 地址范围的 PROXY 标头，并拒绝来自不同范围的 PROXY 标头，超时时间为 2 秒

{
	servers {
		listener_wrappers {
			proxy_protocol {
				timeout 2s
				allow 192.168.86.1/24 192.168.86.1/24
				deny 10.0.0.0/8
				fallback_policy reject
			}
			tls
		}
	}
}

超时

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

• read_header 是一个 持续时间值，用于设置允许从客户端请求标头读取数据的时间长度。默认情况下，没有超时。

• write 是一个 持续时间值，用于设置允许向客户端写入数据的时间长度。请注意，当服务大型文件时，将其设置为较小的值可能会对合法的慢速客户端产生负面影响。默认情况下，没有超时。

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

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

keepalive_interval

TCP keepalive 数据包发送的间隔，用于在没有其他数据传输时在 TCP 层保持连接活动。默认为 15s。

{
	servers {
		keepalive_interval 30s
	}
}

trusted_proxies

允许配置代理服务器的 IP 范围 (CIDR)，从中收到的请求应被信任。默认情况下，不信任任何代理。

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

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

目前，标准 Caddy 发行版仅包含 static IP 源模块，但可以通过插件进行扩展，以维护 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
	}
}

trusted_proxies_strict

当启用 trusted_proxies 时，标头（由 client_ip_headers 配置）中的 IP 地址默认从左到右解析。找到的第一个不受信任的 IP 地址将成为真实的客户端地址。自 v2.8 起，您可以选择使用 trusted_proxies_strict 从右到左解析这些标头。默认情况下，为了向后兼容性，此选项处于禁用状态。

上游代理（如 HAProxy、CloudFlare、AWS ALB、CloudFront 等）会将每个新的连接远程地址附加到 X-Forwarded-For 的右侧。当使用这些代理时，建议启用 trusted_proxies_strict，因为最左侧的 IP 地址可能被客户端欺骗。

{
	servers {
		trusted_proxies static private_ranges
		trusted_proxies_strict
	}
}

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 指标收集；在抓取指标之前是必要的。请注意，指标会降低非常繁忙的服务器的性能。（我们的社区正在努力改进这一点。请参与进来！）

{
	metrics
}

您可以添加 per_host 选项，以使用指标的主机名标记指标。

{
	metrics {
		per_host
	}
}

trace

记录调用的每个单独的处理程序。要求日志以 DEBUG 级别发出（您可以使用 debug 全局选项这样做）。

注意：这可能会记录您的 HTTP 处理程序模块的配置；当配置中存在敏感数据时，请勿在不安全的环境中启用此功能。

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

{
	servers {
		trace
	}
}

max_header_size

从客户端 HTTP 请求标头解析的最大大小。如果超过限制，服务器将以 HTTP 状态 431 Request Header Fields Too Large 响应。它接受 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

默认情况下，包含可能敏感信息的标头的访问日志（使用 log 指令启用）（Cookie、Set-Cookie、Authorization 和 Proxy-Authorization）将被记录为 REDACTED。

如果您希望不对这些标头进行编辑，您可以启用 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
	}
}

文件系统

filesystem 全局选项允许声明一个或多个可用于文件 I/O 的文件系统。

这可以让您连接到云中运行的远程文件系统，或者具有类文件接口的数据库，甚至可以从 Caddy 二进制文件中嵌入的文件中读取。

文件系统以名称声明以标识它们。这意味着如果您需要，您可以连接到多个相同类型的文件系统。

默认情况下，Caddy 没有文件系统模块，因此您需要使用您想要使用的文件系统的插件来构建 Caddy。

示例

使用一个假想的 custom 文件系统模块，您可以声明两个文件系统

{
	filesystem foo custom {
		...
	}

	filesystem bar custom {
		...
	}
}

foo.example.com {
	fs foo
	file_server
}

foo.example.com {
	fs bar
	file_server
}

PKI 选项

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

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

name

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

默认值：Caddy 本地机构

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

root_cn

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

默认值：{pki.ca.name} - {time.now.year} ECC 根证书

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

intermediate_cn

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

默认值：{pki.ca.name} - ECC 中间证书

{
	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 事件

插件也可能发出事件，因此请查看其文档以获取详细信息。