升級與移除

一次升級只替換兩樣東西 —— 二進位檔與 service unit —— 你的設定與憑證不動。本頁示範這件事、容器裡的對應做法、必須往回退時的回滾路徑，以及拆除步驟。

🧾 什麼能撐過什麼

路徑	升級時
`/etc/Pingclair/Pingclairfile`	保留。安裝程式只在它缺失時才寫入。
`/etc/Pingclair/Pingclairfile.example`	被目前範例替換。
`/var/lib/pingclair/.local/share/pingclair`	保留。已簽發的憑證與 ACME 狀態原地不動。
`/var/lib/pingclair/html`	保留。
`/usr/local/bin/pingclair` 與 `pc`	被新版本替換。
`/etc/systemd/system/pingclair.service`	被重寫，然後服務重啟。

⬆️ 用安裝程式升級

curl -fsSL https://pingclair.com/install.sh | sudo bash

指令稿向 GitHub 查詢最新 release tag、印出來、驗證壓縮包的 SHA-256、替換二進位檔與 unit，然後重啟服務。已經存在的設定檔不會被碰，這才使它成為升級而不是重置：

Detected architecture: x86_64
Fetching latest release from dorianverlaine/pingclair...
Installing v0.2.0-rc.3 — a release candidate, not a final release.
pingclair-linux-x86_64.tar.gz: OK
✅ Installation Complete!
Config: /etc/Pingclair/Pingclairfile

確認新版本，並確認舊設定仍在提供服務：

pingclair version
pc service status
curl -i http://localhost/

v0.2.0-rc.3

安裝程式總是裝最新 release。沒有指定版本的旗標；需要特定版本時，用下面的回滾。

🐳 升級容器

主機上什麼都沒裝，所以升級就是改 tag 再 pull。在 compose 檔案裡固定新版本：

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:v0.2.0-rc.3

docker compose pull
docker compose up -d
docker logs pingclair 2>&1 | head -3

🚀 Starting Pingclair with config: /etc/pingclair/Pingclairfile
🚀 Starting Pingclair v0.2.0-rc.3
📄 Loaded configuration from: /etc/pingclair/Pingclairfile

設定與憑證儲存區都在磁碟區裡，所以新容器會在舊容器留下的位置找到它們。兩點要注意：

對映了 80 連接埠的容器，在 systemd 服務執行時起不來。 停掉其中一個： sudo pc service stop，或者改容器一側的發佈連接埠。
latest 會跟隨最新 release。 正式環境請固定版本，讓升級是一個決定，而不是一次 pull 的副作用。

⏪ 回滾到舊版本

新版本必須退回去時，從發佈主機取上一個版本，用它公佈的 digest 核對，然後替換二進位檔：

mkdir -p /tmp/rollback && cd /tmp/rollback
version=0.2.0-rc.2
base="https://releases.pingclair.com/pingclair/releases/$version"
curl -fsSL "$base/release.json" -o release.json
tarball=pingclair-linux-x86_64.tar.gz
expected="$(jq -r ".assets[] | select(.name == \"$tarball\") | .digest" release.json | sed 's/^sha256://')"
curl -fsSLO "$base/$tarball"
printf '%s  %s\n' "$expected" "$tarball" | sha256sum -c -
mkdir -p extract && tar -xzf "$tarball" -C extract

pingclair-linux-x86_64.tar.gz: OK

sudo systemctl stop pingclair
sudo install -m 0755 extract/pingclair /usr/local/bin/pingclair
sudo systemctl start pingclair
pingclair version

v0.2.0-rc.2

然後針對回滾後的版本驗證設定，因為舊版本沒有實作的指令會按名字被拒絕，而不是被忽略：

sudo pingclair validate /etc/Pingclair/Pingclairfile

🧹 移除

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

之後 systemctl status pingclair 會回答 Unit pingclair.service could not be found，指令消失，80 連接埠上沒有任何監聽。留在磁碟上的，是刻意保留的你的資料：

/etc/Pingclair/Pingclairfile      設定，仍然有效
/var/lib/pingclair/.local/share/pingclair          已簽發憑證與 ACME 狀態
/var/lib/pingclair/html           預留網站
/var/log/pingclair                日誌輸出目錄

如果打算重新安裝，請保留 /var/lib/pingclair/.local/share/pingclair：憑證與內部根都會存活，信任該根的用戶端也繼續可用。若這台主機不再使用 Pingclair，就全部刪掉，包括服務帳號：

sudo rm -rf /etc/Pingclair /var/lib/pingclair /var/log/pingclair
sudo userdel pingclair

⚠️ 出問題時

裝上了意料之外的版本。 安裝程式總是取最新的 release tag。用 pingclair version 確認；如果確實需要特定版本，用上面的回滾。
升級後服務起不來。 讀 sudo pingclair validate /etc/Pingclair/Pingclairfile。新版本拒絕的指令會帶著名字與替代方案 fail closed，journal 會指出要改哪一行。
容器立刻結束。 docker logs <container> 會說明原因。常見原因是掛載的設定目錄裡沒有 /etc/pingclair/Pingclairfile，或者主機上連接埠已被占用。
重建儲存區後用戶端拒絕憑證。 內部憑證授權單位重新產生後，舊根不再簽任何東西。用 sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair trust 裝新的根。

🧭 下一步

安裝：本頁保留或刪除的目錄配置。
以服務方式執行：升級會重寫的 unit。
專案狀態：目前版本支援什麼、拒絕什麼。

🧹升級與移除