🧹升級與移除

0.2.0 改變既有設定的路由、綁定位址、壓縮與用戶端識別行為。從 0.2.0-rc.N 升級也需要檢查。修補版本 0.2.1 與 0.2.2 不需要調整設定。替換二進位檔之前，請閱讀完整的 Before you upgrade 清單及各項連結。以下整理最可能影響部署的變動。

⚠️ 0.2.0 的變更

檢查項目	需要調整或預期的結果
路由	依指令順序選出第一條匹配路由。全域匹配的 redir、route 或 handle 可排在較具體的 respond 之前。使用互斥的 handle 區塊或明確的 route 順序。
路徑	忽略 ASCII 大小寫，並解碼一次百分比編碼。handle_path 與 URI 移除也忽略大小寫。大括號是字面值；擷取群組或區分大小寫時使用 path_regexp。等長的同層路徑保留檔案順序。
區塊匹配器	handle、handle_path 與 route 只接受 *、/path 或 @name。將 handle *.php 改成具名的 path *.php 匹配器。
監聽器	bind 適用於明確位址、連接埠及自動重新導向。listen 保留指定的 IP。bind 與 default_bind 只接受一個位址。同一連接埠共用監聽器；受 bind 限制的網站與全介面監聽器並存時會被拒絕。
位址	具名網站帶連接埠但沒有 scheme 時使用 HTTPS。明文請寫 http://。只有 scheme 的位址使用全域連接埠。[::1] 是網站名稱；同一連接埠的 0.0.0.0 與 [::] 合併為 IPv6 監聽器。
用戶端識別	servers 內每個範圍只寫一次 trusted_proxies static …。需要時將 CF-Connecting-IP 列入 client_ip_headers。client_ip 與 {client_ip} 是轉送的用戶端；remote_ip 與 {remote_host} 是對端。{remote_ip} 會被拒絕。
請求限制	本文大小沒有預設上限；需要時設定 request_body { max_size … }。標頭完成與本文兩次讀取之間的停頓預設皆為 60 秒；安靜的上傳可能需要較長的 limits { body_timeout … }。
錯誤頁	handle_errors 現在也處理閘道、逾時與 413 錯誤。自己的 root 與 file_server 會以錯誤狀態提供頁面。必要時用狀態碼限制原本的全域錯誤區塊。
編碼	沒有 encode 就不壓縮。區塊、gzip 等級（預設 5）、回應匹配器與最小長度皆生效。encode off 不接受區塊。靜態回應一律依編碼變化；有 encode 的網站代理回應亦同。重新編碼弱化代理 ETag；靜態與 sidecar 驗證值會改變。no-transform 停用編碼。
回應快取	新鮮度包含上游年齡。所有快取路由的 max_size 必須一致；重載會套用容量變更。flush_interval -1 不納入快取。所有 Vary 行都參與變體；無效 Vary 與 Vary: * 不儲存。
Admin API	不存在的設定讀取回應 200 null。讀取會遮蔽機密，重新載入匯出內容前須還原。設定寫入遵守帶路徑的 If-Match；收到 412 後重新讀取該路徑與 ETag。重載期間仍可讀取。
指標	加入全域 metrics 才會收集，否則擷取端點回應空本文。儀表板需改用重新命名的 caddy_* 系列。
命令列	可用 --config／-c 與 --adapter caddyfile|json，不可同時提供位置參數路徑。沒有預設檔案時 run 只啟動管理端點；檔案缺少必須失敗時請指定路徑。validate 現在解析 TLS 檔案並檢查金鑰配對。
TLS	內部 CA 移至 pki/authorities/local/，不遷移舊資料；須重新信任根憑證。精確名稱不再繼承萬用字元的 client_auth，需要時明確加入。手動 TLS 必須有網站名稱。
上游	權重 0 排空上游；大於 100 及所有主要上游皆為 0 會驗證失敗。lb_try_duration 限制新嘗試，不限制進行中的回應。上游可能收到請求後僅重試冪等方法。
協定	CONNECT 得到 405 並關閉 H1；沒有可用連接埠的目標得到 400。HTTP/1 格式錯誤的目標與 chunked 本文得到 400 並關閉連線。FastCGI HEAD 沒有本文、過大參數得到 431、損壞本文中止回應。
生命週期	HTTP、管理或 H3 UDP 連接埠被佔用時停止啟動。SIGTERM 在 grace_period 內排空。重啟仍有連線空窗，政策變更優先重載。

已知發行缺陷仍然適用。內建代理錯誤產生的 502 或 504 帶有 Proxy-Status，自訂 handle_errors 回應不帶此欄位。未能重用 keepalive 的日誌等級由 ERROR 改為 DEBUG。

📦 保留原有安裝

升級前備份設定、目前的二進位檔與整個 TLS 儲存區，保留擁有者資訊，並保護含私密金鑰的備份。安裝程式保留 /etc/Pingclair/Pingclairfile、/var/lib/pingclair/.local/share/pingclair 的憑證儲存區及網站檔案；替換二進位檔、範例設定與 systemd unit，然後重啟服務。設定中的 storage file_system 路徑優先於慣用儲存位置。

保留舊儲存區備份以便回復。信任新根憑證不會讓舊用戶端自動信任它，只回復二進位檔也不會還原舊根憑證或設定結構。

🛡️ 切換前先檢查

使用尚未替換上線版本的 新 二進位檔對正式設定執行 validate。它不開啟監聽器，但執行者必須讀得到設定所列的每個憑證與金鑰。再於測試部署檢查受影響路由、大小寫變體、轉送用戶端身分、錯誤頁、上傳、壓縮與指標。

main 原始碼建置回報 v0.0.0-dev+<sha>，沒有 checkout 時為 v0.0.0-dev；發行版回報自己的標記，例如 v0.2.2。安裝時檢查標記與發布的校驗值。dev 版本字串不代表已安裝穩定版。

⬆️ 安裝穩定版

安裝程式會選擇穩定版通道：

curl -fsSL https://pingclair.com/install.sh | sudo bash
pingclair version
pc service status

確認 pingclair version 顯示 v0.2.2、服務正常執行，並檢查網站路由的回應。

安裝程式沒有指定版本的旗標。容器請固定目標標記：

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:v0.2.2

docker compose pull
docker compose up -d
docker compose logs pingclair

保留設定與 TLS 儲存區的 volumes。latest 跟隨穩定版，alpha 預覽不會推進它。啟動前必須釋出主機連接埠。

⏪ 回復舊版

停止新服務，還原備份的二進位檔、設定與 TLS 儲存區及其擁有者，使用還原的二進位檔驗證後再啟動。0.2.0 寫出的設定可能無法由舊版本載入。不要以不完整備份覆寫執行中的憑證儲存區。

🧹 移除安裝

sudo pc service stop
sudo systemctl disable pingclair
sudo rm /etc/systemd/system/pingclair.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/pingclair /usr/local/bin/pc

這些命令保留 /etc/Pingclair、/var/lib/pingclair 與 /var/log/pingclair，包括憑證與網站檔案。只有確定不再需要重新安裝或回復時，才刪除保留資料。

🧭 下一步

• 安裝：安裝位置與前提條件。
• 以服務方式執行：重載、重啟與日誌。
• 專案狀態：尚存的發行限制。