API

Caddy 是透過管理端點設定的，可以使用 REST API 透過 HTTP 存取。您可以在 Caddy 設定中設定這個端點。

預設位址：localhost:2019

可以透過設定 CADDY_ADMIN 環境變數來變更預設位址。有些安裝方法可能會將其設定為其他值。Caddy 設定中的位址永遠優先於預設值。

任何變更後，最新的設定都會儲存到磁碟（除非停用）。您可以在重新啟動後使用 caddy run --resume 恢復最後一個運作的設定，這可確保在斷電或類似情況下設定的耐用性。

若要開始使用 API，請嘗試我們的 API 教學，或者如果您只有一分鐘的時間，請嘗試我們的 API 快速入門指南。

POST /load 設定或取代目前的設定
POST /stop 停止目前的設定並結束程序
GET /config/[path] 匯出命名路徑中的設定
POST /config/[路徑] 設定或取代物件；附加到陣列
PUT /config/[路徑] 建立新物件；插入陣列
PATCH /config/[路徑] 取代現有物件或陣列元素
DELETE /config/[路徑] 刪除指定路徑的值
在 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/[路徑]

匯出 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/[路徑]

將 Caddy 的設定變更為請求的 JSON 主體中指定的設定。如果目標值是陣列，POST 會附加；如果是物件，它會建立或取代。

在特殊情況下，如果

路徑以 /... 結尾
/... 之前的路徑元素是指陣列
酬載是陣列

則可以將許多項目新增到陣列中。

baseSlice = append(baseSlice, newElems...)

範例

在 Go 語法中，這會產生與以下相同的結果

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/[路徑]

將 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/[路徑]

將 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/[路徑]

移除 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"
}

要使用它，只要對 /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 尾端標記即可。

此演算法的基本原理如下

對設定中的任何範圍 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>

根據其 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）。