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"）。只需在變更請求上將 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）。