安裝 | Pingclair

Pingclair 以單一 Linux 二進位檔發布。本頁說明 v0.2.2 的安裝步驟、檔案位置與服務檢查方式。

🧾 你需要準備的

一台 x86_64 或 aarch64 的 Linux 主機；兩種架構都有發行版二進位檔。
sudo 或 root 權限：安裝程式會寫入 /usr/local/bin、/etc/Pingclair、/var/lib/pingclair 與 /etc/systemd/system。
走服務路線需要 systemd。沒有 systemd 的主機，請改用 Docker，或在前景執行伺服器；兩者下面都有說明。
如果要取得公開憑證，80 與 443 連接埠必須能從網際網路連到（HTTPS）。在雲端執行個體上，這通常也代表要在供應商的防火牆裡開放它們。

macOS 可以從原始碼編譯，並支援用於開發，但不是正式發布的平台。

📦 從發行版二進位檔安裝

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

這支腳本會讀取 releases.pingclair.com 上的發行頻道，印出即將安裝的 tag，並用該頻道為這個封存檔公布的 SHA-256 進行比對——不相符的封存檔會被拒絕，不會解開。如果連不到那台主機，它會退回使用 GitHub releases API 與封存檔旁公布的校驗和檔案，所以安裝不必依賴單一供應商。接著它會建立服務使用者、授予該使用者綁定低號連接埠的 capability、寫入預設設定、安裝 unit，並啟動服務。

若要使用尚未發行的修正，請改為在主機上編譯 main：

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

--main 會在主機上 clone 並編譯伺服器。它需要 Rust 1.99 或更新版本，以及 BoringSSL 與 jemalloc 所需的 C 工具鏈：cmake、clang、libclang-dev、g++ 與 git。腳本在 apt 與 dnf 系統上都會自行安裝這些套件。由於 BoringSSL 要從原始碼編譯，第一次建置需要好幾分鐘。

🗂️ 安裝程式留下了什麼

路徑	內容
`/usr/local/bin/pingclair`	伺服器二進位檔。
`/usr/local/bin/pc`	指向同一個二進位檔的符號連結，用於簡寫。
`/etc/Pingclair/Pingclairfile`	服務執行的設定。
`/etc/Pingclair/Pingclairfile.example`	附註解的範例，升級時不會被覆寫。
`/var/lib/pingclair/.local/share/pingclair`	憑證儲存區：也就是服務使用者的資料目錄，二進位檔預設就會在這裡找。
`/var/lib/pingclair/html`	在 80 連接埠上提供的佔位網站。
`/var/log/pingclair`	設定了 `log` 輸出之後，日誌寫入的位置。
`/etc/systemd/system/pingclair.service`	unit，已啟用並正在執行。

安裝完成後，服務使用下列預設設定提供歡迎頁面：

# 🦀 Pingclair default configuration file
# Management commands: pc service <start|stop|reload|status>

:80 {
    # Welcome page
    file_server /var/lib/pingclair/html
}

服務使用者與憑證儲存區只在不存在時才會建立，既有的 /etc/Pingclair/Pingclairfile 也永遠不會被取代。正因如此，重新執行安裝程式等於升級，而不是重設（升級與移除）。

✅ 確認安裝結果

檢查已安裝的版本：

pingclair version

0.2.2 發行版會顯示 v0.2.2。pc version 會顯示相同版本。接著檢查服務狀態：

pc service status

● pingclair.service - Pingclair High-Performance Web Server
     Loaded: loaded (/etc/systemd/system/pingclair.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-09-22 03:21:55 UTC; 42s ago
       Docs: https://pingclair.com/start/service/
   Main PID: 27630 (pingclair)
     Status: "Serving"
      Tasks: 12 (limit: 627)
     Memory: 8.2M (peak: 8.5M)

Status: "Serving" 來自伺服器本身，而不是 systemd 看到一個「還活著」的行程就算數：這個 unit 的類型是 notify，伺服器要等所有監聽器都綁定完成後才會回報就緒。

最後，直接問伺服器：

curl -i http://localhost/

帶有 ETag 與 Last-Modified 的 200 代表回應來自檔案伺服器，本文就是 /var/lib/pingclair/html 裡的佔位頁面。

🐳 Docker

公開的映像檔以設定檔模式執行：entrypoint 是 pingclair，預設命令是 run /etc/pingclair/Pingclairfile。映像檔把 /etc/pingclair 與 /var/lib/pingclair 宣告為 volume，並公開 80 與 443 連接埠。

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:v0.2.2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3
    volumes:
      - ./conf:/etc/pingclair:ro
      - ./site:/srv:ro
      - pingclair_tls:/var/lib/pingclair

volumes:
  pingclair_tls:

mkdir -p conf site
printf ':80 {\n    file_server /srv\n}\n' > conf/Pingclairfile
echo '<h1>hello from the container</h1>' > site/index.html
docker compose up -d
curl -i http://localhost/

有三點很容易弄錯：

不要加 command:。 映像檔的預設值已經是 run /etc/pingclair/Pingclairfile，覆寫它就會取代這個命令。
掛載整個 /var/lib/pingclair，而不只是憑證目錄。 儲存區會在憑證旁邊保存狀態，只掛載一部分的容器在重建後就會遺失這些狀態。
固定使用已發行的 tag。 latest 會跟著最新的發行版走；正式環境應該像範例一樣寫明版本。公開的 tag 列在套件頁面上。

如果你的使用者不在 docker 群組裡，請在命令前加上 sudo，或用 sudo usermod -aG docker "$USER" 加入群組一次，再開啟新的登入工作階段。在 Ubuntu 上，docker compose 外掛來自 docker-compose-v2 套件。

🛠️ 從原始碼編譯

git clone https://github.com/dorianverlaine/pingclair
cd pingclair
cargo build --release

需求：Rust 1.99.0（CI 固定的版本）、cmake、clang、libclang-dev、g++ 與 git。BoringSSL 會在建置過程中從原始碼編譯，所以第一次建置需要好幾分鐘。

⚠️ 安裝失敗時

This script must be run as root。 腳本會寫入家目錄以外的位置並安裝 unit。請用 sudo 重新執行。
Fedora 上出現 setcap: command not found。 那是 libcap 套件。安裝程式會自動加裝，但手動建置的主機可能沒有；少了這個 capability，服務就無法綁定 80 與 443 連接埠。
安裝完立刻出現 Job for pingclair.service failed。 請看 journalctl -u pingclair -n 20。常見原因是設定沒通過驗證，或 80 連接埠已經有其他程式在監聽。
服務在執行，但從外部連不到。 監聽器已經綁定，封包卻始終沒有抵達。請先檢查供應商的防火牆或安全群組，再檢查主機本身的規則。
主機沒有 systemd。 二進位檔已經裝好也能用，但安裝程式的服務步驟無法執行。請改用 Docker，或 pingclair run。

🧹 再次移除

升級與移除會帶你完成移除，並指出哪些目錄存有值得保留的資料。

🧭 下一步

快速開始：用你自己的設定取代佔位設定，提供一個真正的網站。
HTTPS：為公開網域名稱取得憑證。
以服務方式執行：unit 做了什麼，以及如何安全地重載。

📦安裝