跳到內容
PingclairPingclair

Admin API

Admin API 在伺服器行程內提供設定讀取與替換、就緒檢查及指標擷取。pingclair reload 與 pingclair stop 使用它。

📌 本頁描述 v0.2.2。

🔌 啟用管理端點

Section titled “🔌 啟用管理端點”

只有寫出全域 admin 或在沒有設定檔時執行 pingclair run，才有此 API。預設位址為 127.0.0.1:2019。

{
    admin 127.0.0.1:2019
}


http://:8080 {
    respond "ok"
}

管理連接埠被佔用時會以 failed to bind admin API on ADDR 停止啟動。admin off 不綁定管理端點。

🔐 存取驗證

Section titled “🔐 存取驗證”
  • admin <address> <token> 要求每個請求帶 Authorization: Bearer <token>；缺少或錯誤時回應 401 與 WWW-Authenticate: Bearer。
  • 沒有 token 時記錄警告，只允許 loopback 用戶端；其他用戶端得到 403。
  • admin { … } 的 origins 與 enforce_origin 限制瀏覽器來源。沒有 Origin 的請求可通過，除非啟用 enforce_origin。

/live 與 /ready 也受相同檢查保護。

🧭 端點

Section titled “🧭 端點”
方法與路徑 作用
GET /live 行程存活時回應 200，包含排空期間。
GET /ready 所有監聽器綁定後回應 200；之前及開始停止後回應 503。
GET /metrics Prometheus 文字格式；未收集時為空本文。
GET /config/[path] 讀取整份執行中設定或其中一個值。
POST、PUT、PATCH、DELETE /config/[path] 修改其中的值並套用結果。
GET … DELETE /id/<id> 透過文件的 @id 欄位定位相同操作。
POST /load 替換整份設定。
POST /adapt 將 Pingclairfile 轉為 JSON，不套用。
POST /stop 優雅停止行程。
GET /reverse_proxy/upstreams 列出設定中的上游，包括 handle 內的上游。
GET /cache 回應快取使用量與容量。
POST /cache/purge 清除一個快取 URL，本文為 {"host": "…", "path": "…"}。

設定文件是 pingclair adapt 輸出的 Pingclair 結構。Caddy 的 {"apps": …} 文件會被指名拒絕，而這個拒絕是刻意的邊界、不是缺漏的轉接器：兩份文件沒有任何共同的頂層鍵或處理器名稱，接受 Caddy 的 JSON 等於要再維護一套跟著 Caddy 模組樹跑的設定介面。POST /load 除了自己的 JSON 之外，還接受 Caddyfile（Content-Type: text/caddyfile），也就是維運人員實際放在 git 裡的格式。

📄 設定讀寫

Section titled “📄 設定讀寫”
  • 不存在的設定路徑、物件鍵或陣列索引回應 200 與 JSON null，並附 ETag。寫入不存在的路徑仍可能失敗，診斷會指出最近的父層。
  • 設定讀取附帶路徑限定的 Etag。設定寫入可帶相同路徑的 If-Match，過期時回應 412 並保留原設定；沒有 If-Match 是無條件寫入。此規則不擴充至 /load 或 /adapt。
  • 讀取以 [redacted] 遮蔽管理 token、DNS 憑證、Basic Auth 雜湊，以及機密標頭或 FastCGI env 值。機密標頭包括 Authorization、Proxy-Authorization、Cookie、Set-Cookie，及名稱含 api-key、token、secret 或 password 的欄位。
  • 儲存的真實值不變，透過路徑寫入可原地修改。/load 與 POST /config 拒絕把 [redacted] 當成機密重新載入；請先還原真實值。
  • 重載期間仍可讀取，每個請求使用授權它的同一份已發布世代。寫入與其他重載競爭時可能得到 409，條件寫入也可能得到 412；重新讀取並驗證授權後再試。

🔁 載入可修改的範圍

Section titled “🔁 載入可修改的範圍”

載入以不可分割的方式替換設定。請求只看見舊或新的完整狀態；編譯失敗時舊設定繼續提供服務。需要新 socket 或改變啟動政策的設定會得到 409 與 restart_required，不會部分套用：

  • 新增、移除或移動監聽位址。
  • 新增 TLS 主機名稱或改變憑證拓撲。
  • 修改啟動時固定的全域政策，包括 metrics 與 trusted_proxies。
  • 在允許 session resumption 的監聽器啟用雙向 TLS。

從空設定啟動的行程是例外：Unix 上第一次 /load 可加入明文 HTTP 監聽器。TLS 與 HTTP/3 需從檔案啟動。全域行程日誌等可重載選項不受上述啟動政策限制。

📊 指標

Section titled “📊 指標”

只有設定全域 metrics 才收集。否則 /metrics 與網站的 metrics 路由回應 200 及空本文。metrics { per_host } 為設定的主機名稱加入 host 標籤，其餘 Host 歸入 other。

0.2.0 將以下標準系列重新命名：

0.2.0 之前 0.2.0 起
pingclair_requests_total caddy_http_requests_total
pingclair_request_duration_seconds caddy_http_request_duration_seconds
pingclair_request_size_bytes caddy_http_request_size_bytes
pingclair_response_size_bytes caddy_http_response_size_bytes
pingclair_response_duration_seconds caddy_http_response_duration_seconds
pingclair_request_errors_total caddy_http_request_errors_total
pingclair_admin_http_requests_total caddy_admin_http_requests_total
pingclair_reverse_proxy_upstreams_healthy caddy_reverse_proxy_upstreams_healthy

Histogram 的 _bucket、_sum 與 _count 跟隨系列改名，舊名稱不再匯出。沒有對應名稱的連線、過載、快取、日誌丟棄、上游時間／錯誤／重試、TLS、H3、就緒、設定版本、佇列、circuit 與行程資源指標保留 pingclair_。名稱相同不代表完整標籤結構與 Caddy 相同。

🧭 相關頁面

Section titled “🧭 相關頁面”