API

Caddy 通过一个管理端点进行配置，该端点可以通过 HTTP 使用 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；或对 JSON5 使用 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 正文。如果目标值是数组，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 正文。如果目标是数组中的位置（索引），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 正文。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，以便更方便地直接访问这些部分。

只需向对象添加名为 "@id" 的字段并赋予其一个唯一名称。例如，如果你有一个希望经常访问的反向代理处理器：

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

使用时，直接向 /id/ API 端点发出请求，方式与对应的 /config/ 端点相同，但无需写出整个路径。该 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（Precondition Failed，前提条件失败），则从第 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 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 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）。