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 的值；或者对于 JSON 5，请使用类似 application/json5 的值；等等。

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

示例

设置新的活动配置

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

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

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

POST /stop

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

示例

停止进程

curl -X POST "https://127.0.0.1:2019/stop"

GET /config/[path]

导出 Caddy 在指定路径的当前配置。返回 JSON 正文。

示例

导出整个配置并漂亮地打印它

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

仅导出监听器地址

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

POST /config/[path]

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

作为一种特殊情况，如果满足以下条件，则可以将多个项目添加到数组中

路径以 /... 结尾
路径中 /... 之前的元素引用一个数组
payload 是一个数组

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

baseSlice = append(baseSlice, newElems...)

示例

添加一个监听器地址

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

添加多个监听器地址

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

PUT /config/[path]

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

示例

在第一个槽位中添加一个监听器地址

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

PATCH /config/[path]

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

示例

替换监听器地址

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

DELETE /config/[path]

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

示例

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

curl -X DELETE "https://127.0.0.1:2019/config/"

仅停止您的一个 HTTP 服务器

curl -X DELETE "https://127.0.0.1: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"）。只需在 mutative 请求上将 If-Match 标头设置为先前 GET 请求的 Etag 标头即可。

此基本算法如下

对配置中的任何范围 S 执行 GET 请求。保留响应的 Etag 标头。
对返回的配置进行所需的更改。
在范围 S 内执行 POST|PUT|PATCH|DELETE 请求，将 If-Match 请求标头设置为存储的 Etag 值。
如果响应是 HTTP 412（Precondition Failed），则从步骤 1 重复，或者在尝试太多次后放弃。

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

POST /adapt

适配配置为 Caddy JSON，但不加载或运行它。如果成功，结果 JSON 文档将在响应正文中返回。

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

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

示例

将 Caddyfile 适配为 JSON

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

GET /pki/ca/<id>

按 ID 返回有关特定 PKI 应用 CA 的信息。如果请求的 CA ID 是默认值 (local)，则如果尚未配置 CA，则将配置 CA。如果其他 CA ID 之前未配置，则会返回错误。

curl "https://127.0.0.1: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。如果其他 CA ID 之前未配置，则会返回错误。

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

curl "https://127.0.0.1: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 "https://127.0.0.1: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 对于单个上游）。