📌專案狀態

本頁列出 v0.2.2 的支援功能、設定限制與已知缺陷，方便部署前確認。

📌 0.2.2 發行版

目前的發行版是 v0.2.2，0.2 系列最新的修補版本。CHANGELOG記錄每個發行版的變更，以及標記版本時已知的缺陷。0.2.1 與 0.2.2 不需要調整設定：handle_path 與沒有參數的 handle 並列時，由符合請求的路由回答；listener 可以允許名稱含底線的請求欄位；重新載入後新增的存取日誌 channel 會收到記錄。0.3 開發線位於 main，不屬於這個發行版。

v0.1.x 系列已停止維護：沒有修正、沒有回溯移植，也不會發布安全公告。請升級離開它：v0.1.x 會解析 Admin API 的 api_key 欄位，卻從來不讀取，所以它的 Admin API 實際上沒有驗證任何人。

✅ 這個發行版支援的功能

領域	支援內容
協定	以同一份設定，在 TCP 上提供 HTTP/1.1 與 HTTP/2，並透過 QUIC 提供 HTTP/3。
TLS	透過 ACME 自動取得公開憑證、持久化的內部憑證授權單位，以及由你提供的憑證檔案。
靜態檔案	檔案服務，支援 zstd 與 gzip 壓縮、range 請求與條件式請求。
反向代理	多個上游、多種負載平衡策略、主動健康檢查，以及備援上游。
FastCGI	在 HTTP/1.1、HTTP/2 與 HTTP/3 上支援 php_fastcgi。
速率限制	依匹配器進行的精確本機速率限制。
可觀測性	支援輪替的存取日誌，以及 Prometheus 指標。
管理	用來檢視狀態與重新載入設定的 Admin API。

🛡️ 伺服器刻意拒絕的名稱

Caddyfile 格式定義的名稱比 Pingclair 實作的多。尚未支援的名稱， 會在載入檔案時被拒絕，錯誤訊息會指出缺少的是哪一項功能； 含有這類名稱的設定無法啟動。

以下完整清單來自 0.2.2 中的登錄表，列出 Pingclair 能辨識為 Caddy 語法、 但尚未在該上下文中實作的名稱。

指令：

copy_response、copy_response_headers、fs、invoke、log_append、 log_name、map、push、skip_log、tracing。

copy_response 與 copy_response_headers 可以作為 handle_response 的子指令使用； 只有把它們寫成獨立指令時才會被拒絕。

全域選項：

acme_ca、acme_ca_root、acme_eab、cert_issuer、cert_lifetime、ech、 events、fallback_sni、filesystem、frankenphp、key_type、 ocsp_interval、on_demand_tls、preferred_chains、renew_interval、 shutdown_delay、storage_clean_interval。

tls { … } 裡的選項：

protocols、ciphers、curves、alpn、load、ca、ca_root、key_type、 eab、issuer、get_certificate、on_demand、reuse_private_keys、 insecure_secrets_log、force_automate。

🧭 重要的相容性差異

• 一個名稱受到支援，不代表它能用在 Caddy 的每一種上下文。例如，copy_response 必須寫在 handle_response 裡。
• DNS-01 支援 Cloudflare。其他 provider 名稱會被拒絕，不會退回另一種驗證方式。
• encode br 會被拒絕，因為代理回應沒有串流式 Brotli 實作。請使用 zstd 或 gzip。
• storage file_system <path>、ocsp_stapling off 與 handle_errors 已在 0.2.0 上實作；仍把它們列為不支援的舊文件已經過時。
• 請求欄位名稱若含底線會被丟棄（Caddy 也是如此），除非 servers { expected_underscore_headers … } 列出該名稱，或以 * 結尾的前綴。這個選項在 0.2.2 才實作；在此之前，這類欄位在三個傳輸層都會被丟棄，且無法保留下來。

⚠️ 已知限制

憑證儲存區僅支援本機目錄，不支援共用儲存後端、外掛或 Caddy 原生 JSON 結構；第四層代理屬於 0.3 開發線。DNS-01 支援 Cloudflare，其他 provider 名稱會被拒絕，不會退回另一種驗證方式。CONNECT 與 TRACE 會得到附帶 Allow 的 405；格式錯誤的 CONNECT 目標得到 400。宣告的 request trailers 不會轉送；宣告 Trailer 的上游回應會保留其狀態與本文，trailer 欄位則被丟棄。

🐛 0.2.2 的已知缺陷

CHANGELOG 的已知缺陷章節記錄了以下限制，每一項都有對應的未關閉 issue。設定驗證不會偵測這些執行期缺陷。

• 負載下的 WebSocket 升級： 忙碌機器上約 10–15% 失敗，101 之後立即 EOF，沒有可避免此競態的設定；問題出在 pingora-proxy（cloudflare/pingora#946）。
• 帶有 Content-Length 的 HTTP/1.1 回應： 來源宣告長度的代理本文，會等到本文結束才送出。帶有即時性訊號的回應——text/event-stream，或設定 flush_interval -1 的路由——已經會串流；HTTP/2 與 HTTP/3 不受影響（#296）。
• 未宣告的 request trailers： 在 HTTP/1 上，沒有 Trailer 宣告就送出的 trailer 區段會被丟棄，aws-chunked 上傳的 checksum 因此不會到達來源，而請求仍正常取得回應（#257）。
• 升級連線的半關閉： 用戶端半關閉會結束 tunnel，遺失後端尚未送完的位元組（#274）。
• HTTP/3 上的回應快取： 有 cache 區塊的路由，在 HTTP/1.1 與 HTTP/2 由儲存區回答，在 HTTP/3 則回到來源（#297）。
• 103 Early Hints： 上游的中間回應只會到達 HTTP/1.1 用戶端；HTTP/2 與 HTTP/3 會丟棄（#207）。
• HTTP/3 傳輸參數： 77 項 h3spec 檢查中有 18 項失敗；修正屬於 QUIC 函式庫（#282）。

🔁 升級至 0.2.2

升級指南整理最可能影響 0.1.x 與候選版本設定的變動。Before you upgrade 清單是完整的發行檢查表。

🐛 回報缺陷

請在 Pingclair 問題追蹤器回報缺陷與文件錯誤。

📚 相關頁面

• CHANGELOG：發行變動與已知缺陷。
• 效能測量：歷史測量條件。
• 架構：元件與請求處理。