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 会追加；如果为对象，则会创建或替换。

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

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

在这种情况下，有效负载数组中的元素将被扩展，并且每个元素都将被追加到目标数组。用 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"）。只需将可变请求上的 If-Match 标头设置为先前 GET 请求的 Etag 尾部。

此算法的基本步骤如下

对配置中的任何范围 S 执行 GET 请求。保存响应的 Etag 尾部。
对返回的配置进行所需的更改。
在范围 S 内执行 POST|PUT|PATCH|DELETE 请求，将 If-Match 标头设置为最近的 Etag 值。
如果响应为 HTTP 412（前提条件失败），请从步骤 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>

返回有关特定 PKI 应用程序 CA 的信息，方法是使用其 ID。如果请求的 CA ID 是默认值（local），则如果 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

返回特定 PKI 应用程序 CA 的证书链，方法是使用其 ID。如果请求的 CA ID 是默认值（local），则如果 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 用于单个上游）。