API

Caddy 通过一个可以使用 REST API 访问的管理端点进行配置。您可以在 Caddy 配置中配置此端点。

默认地址：localhost:2019

默认地址可以通过设置 CADDY_ADMIN 环境变量来更改。某些安装方法可能会将其设置为不同的值。Caddy 配置中的地址始终优先于默认值。

最新配置将在任何更改后保存到磁盘（除非被禁用）。您可以使用 caddy run --resume 在重启后恢复最后一个工作配置，这可以保证在断电等情况下的配置持久性。

要开始使用 API，请尝试我们的 API 教程，或者如果您只有一分钟时间，请参阅我们的 API 快速入门指南。

• POST /load 设置或替换活动配置

• POST /stop 停止活动配置并退出进程

• GET /config/[path] 导出指定路径的配置

• POST /config/[path] 设置或替换对象；追加到数组

• PUT /config/[path] 创建新对象；插入到数组

• PATCH /config/[path] 替换现有对象或数组元素

• DELETE /config/[path] 删除指定路径的值

• 在 JSON 中使用 @id 轻松遍历配置结构

• 并发配置更改 避免在进行非同步配置更改时发生冲突

• POST /adapt 将配置适配为 JSON 而不运行它

• GET /pki/ca/<id> 返回特定 PKI 应用程序 CA 的信息

• GET /pki/ca/<id>/certificates 返回特定 PKI 应用程序 CA 的证书链

• GET /reverse_proxy/upstreams 返回已配置代理上游的当前状态

POST /load

设置 Caddy 的配置，覆盖任何先前的配置。它会阻塞直到重新加载完成或失败。配置更改是轻量级的、高效的，并且不会造成停机时间。如果新配置由于任何原因失败，旧配置将被回滚到位，不会出现停机时间。

此端点支持使用配置适配器的不同配置格式。请求的 Content-Type 标头指示请求主体中使用的配置格式。通常，这应该是 application/json，它代表 Caddy 的原生配置格式。对于其他配置格式，请指定适当的 Content-Type，使得斜杠 / 后的值是要使用的配置适配器的名称。例如，提交 Caddyfile 时，使用 text/caddyfile 这样的值；或者对于 JSON 5，使用 application/json5 这样的值；等等。

如果新配置与当前配置相同，则不会进行重新加载。要强制重新加载，请在请求标头中设置 Cache-Control: must-revalidate。

示例

设置新的活动配置：

curl "http://localhost:2019/load" \
	-H "Content-Type: application/json" \
	-d @caddy.json

注意：curl 的 -d 标志会删除换行符，所以如果您的配置格式对换行符敏感（例如 Caddyfile），请使用 --data-binary 代替：

curl "http://localhost:2019/load" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

POST /stop

优雅地关闭服务器并退出进程。要仅停止运行配置而不退出进程，请使用 DELETE /config/。

示例

停止进程：

curl -X POST "http://localhost:2019/stop"

GET /config/[path]

导出指定路径的 Caddy 当前配置。返回 JSON 主体。

示例

导出整个配置并美化打印：

curl "http://localhost:2019/config/" | jq
{
	"apps": {
		"http": {
			"servers": {
				"myserver": {
					"listen": [
						":443"
					],
					"routes": [
						{
							"match": [
								{
									"host": [
										"example.com"
									]
								}
							],
							"handle": [
								{
									"handler": "file_server"
								}
							]
						}
					]
				}
			}
		}
	}
}

仅导出监听器地址：

curl "http://localhost:2019/config/apps/http/servers/myserver/listen"
[":443"]

POST /config/[path]

将请求的 JSON 主体更改为指定路径的 Caddy 配置。如果目标值是数组，POST 会追加；如果是对象，则创建或替换。

作为特殊情况，如果满足以下条件，可以向数组添加多个项：

1. 路径以 /... 结尾
2. /... 之前的路径元素引用一个数组
3. 有效载荷是一个数组

在这种情况下，有效载荷数组中的元素将被展开，每个元素都将被追加到目标数组。用 Go 术语来说，这将产生与以下相同的效果：

baseSlice = append(baseSlice, newElems...)

示例

添加监听器地址：

curl \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen"

添加多个监听器地址：

curl \
	-H "Content-Type: application/json" \
	-d '[":8080", ":5133"]' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen/..."

PUT /config/[path]

将请求的 JSON 主体更改为指定路径的 Caddy 配置。如果目标值是数组中的位置（索引），PUT 会插入；如果是对象，则严格创建新值。

示例

在第一个位置添加监听器地址：

curl -X PUT \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen/0"

PATCH /config/[path]

将请求的 JSON 主体更改为指定路径的 Caddy 配置。PATCH 严格替换现有值或数组元素。

示例

替换监听器地址：

curl -X PATCH \
	-H "Content-Type: application/json" \
	-d '[":8081", ":8082"]' \
	"http://localhost:2019/config/apps/http/servers/myserver/listen"

DELETE /config/[path]

删除指定路径的 Caddy 配置。DELETE 删除目标值。

示例

要卸载整个当前配置但保持进程运行：

curl -X DELETE "http://localhost:2019/config/"

要只停止一个 HTTP 服务器：

curl -X DELETE "http://localhost:2019/config/apps/http/servers/myserver"

在 JSON 中使用 @id

您可以在 JSON 文档中嵌入 ID，以便更容易直接访问这些部分的 JSON。

只需向对象添加一个名为 "@id" 的字段，并为其指定一个唯一的名称。例如，如果您有一个想要频繁访问的反向代理处理器：

{
	"@id": "my_proxy",
	"handler": "reverse_proxy"
}

要使用它，只需以与相应的 /config/ 端点相同的方式向 /id/ API 端点发出请求，但不需要完整路径。ID 会直接将请求带入配置的那个范围。

例如，要在没有 ID 的情况下访问反向代理的上游，路径会是类似

/config/apps/http/servers/myserver/routes/1/handle/0/upstreams

但使用 ID 后，路径变为

/id/my_proxy/upstreams

这要容易记住和手动编写得多。

并发配置更改

Caddy 的配置 API 为单个请求提供 ACID 保证 ，但如果没有适当同步，涉及多个请求的更改可能会发生冲突或数据丢失。

例如，两个客户端可能同时 GET /config/foo，在该范围内（配置路径）进行编辑，然后同时调用 POST|PUT|PATCH|DELETE /config/foo/... 来应用它们的更改，导致冲突：要么一个会覆盖另一个，要么第二个可能会使配置处于意外状态，因为它是应用于与准备时不同版本的配置。这是因为这些更改彼此不知情。

Caddy 的 API 不支持跨多个请求的事务，并且 HTTP 是一个无状态协议。但是，您可以使用 Etag 和 If-Match 标头来检测和防止任何和所有更改的冲突，作为一种乐观并发控制。如果有任何可能您在没有同步的情况下并发使用 Caddy 的 /config/... 端点，这很有用。所有对 GET /config/... 请求的响应都有一个名为 Etag 的 HTTP 标头，其中包含该范围内的路径和内容的哈希值（例如 Etag: "/config/apps/http/servers 65760b8e"）。只需在变更请求上将 If-Match 标头设置为之前 GET 请求的 Etag 标头值即可。

基本算法如下：

1. 对配置中的任何范围 S 执行 GET 请求。保存响应的 Etag 标头。
2. 在返回的配置上进行所需的更改。
3. 在范围 S 内执行 POST|PUT|PATCH|DELETE 请求，将 If-Match 请求标头设置为存储的 Etag 值。
4. 如果响应是 HTTP 412（前提条件失败），从步骤 1 重复，或在尝试次数过多后放弃。

这个算法安全地允许对 Caddy 的配置进行多个重叠更改，而无需显式同步。它的设计使得对配置不同部分的同时更改不需要重试：只有重叠相同范围的配置的更改才可能导致冲突，因此需要重试。

POST /adapt

将配置适配为 Caddy JSON 而不加载或运行它。如果成功，则在响应主体中返回生成的 JSON 文档。

Content-Type 标头用于以与 /load 相同的方式指定配置格式。例如，要适配 Caddyfile，请设置 Content-Type: text/caddyfile。

只要相关的配置适配器插入到您的 Caddy 构建中，此端点就会适配任何配置格式。

示例

将 Caddyfile 适配为 JSON：

curl "http://localhost:2019/adapt" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

GET /pki/ca/<id>

通过其 ID 返回特定 PKI 应用程序 CA 的信息。如果请求的 CA ID 是默认值（local），则如果尚未配置，将配置该 CA。其他 CA ID 如果尚未配置，将返回错误。

curl "http://localhost:2019/pki/ca/local" | jq
{
	"id": "local",
	"name": "Caddy Local Authority",
	"root_common_name": "Caddy Local Authority - 2022 ECC Root",
	"intermediate_common_name": "Caddy Local Authority - ECC Intermediate",
	"root_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... gRw==\n-----END CERTIFICATE-----\n",
	"intermediate_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... FzQ==\n-----END CERTIFICATE-----\n"
}

GET /pki/ca/<id>/certificates

通过其 ID 返回特定 PKI 应用程序 CA 的证书链。如果请求的 CA ID 是默认值（local），则如果尚未配置，将配置该 CA。其他 CA ID 如果尚未配置，将返回错误。

此端点被 caddy trust 命令内部使用，以允许将 CA 的根证书安装到系统的信任存储中。

curl "http://localhost:2019/pki/ca/local/certificates"
-----BEGIN CERTIFICATE-----
MIIByDCCAW2gAwIBAgIQViS12trTXBS/nyxy7Zg9JDAKBggqhkjOPQQDAjAwMS4w
...
By75JkP6C14OfU733oElfDUMa5ctbMY53rWFzQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBpDCCAUmgAwIBAgIQTS5a+3LUKNxC6qN3ZDR8bDAKBggqhkjOPQQDAjAwMS4w
...
9M9t0FwCIQCAlUr4ZlFzHE/3K6dARYKusR1ck4A3MtucSSyar6lgRw==
-----END CERTIFICATE-----

GET /reverse_proxy/upstreams

将已配置的反向代理上游（后端）的当前状态作为 JSON 文档返回。

curl "http://localhost:2019/reverse_proxy/upstreams" | jq
[
	{"address": "10.0.1.1:80", "num_requests": 4, "fails": 2},
	{"address": "10.0.1.2:80", "num_requests": 5, "fails": 4},
	{"address": "10.0.1.3:80", "num_requests": 3, "fails": 3}
]

JSON 数组中的每个条目都是存储在全局上游池中的已配置上游。

• address 是上游的拨号地址。
• num_requests 是上游当前正在处理的活动请求数量。
• fails 是被记住的当前失败请求数量，由被动健康检查配置。

如果您的目标是确定后端的可用性，您需要根据您正在使用的处理器配置检查上游的相关属性。例如，如果您为代理启用了被动健康检查，那么您还需要考虑 fails 和 num_requests 值来确定上游是否被认为可用：检查 fails 数量是否小于为代理配置的最大失败数量（即 max_fails），并且 num_requests 是否小于或等于为每个上游配置的最大请求数量（即整个代理的 unhealthy_request_count 或单个上游的 max_requests）。