快速開始

完成安裝後，依照本頁建立設定、驗證並啟動伺服器，再確認網站能正常回應。

🧾 開始之前

安裝程式留下了一個在 80 連接埠上執行的服務，它使用的是 /etc/Pingclair/Pingclairfile 裡的設定。實驗期間先把它停掉，讓連接埠空出來：

sudo pc service stop

mkdir -p ~/demo/public
cd ~/demo
echo '<h1>hello from ~/demo/public</h1>' > public/index.html

1. ✍️ 撰寫設定

建立 ~/demo/Pingclairfile：

{
    admin 127.0.0.1:2019
}

http://localhost:8080 {
    file_server ./public
}

有三個細節很重要：

最上方沒有名稱的區塊放的是全域選項。admin 會開啟 Admin API，pingclair start、stop 與 reload 都透過它連到執行中的伺服器。
網站位址中的 http:// scheme 會強制使用明文。少了它，Pingclair 會把 localhost 當成一個名稱，用自家憑證授權單位簽發的憑證提供 HTTPS，而一般的 HTTP 用戶端只會收到空回應（HTTPS）。
file_server 的根目錄是相對於工作目錄的。

2. ✅ 執行前先驗證

pingclair validate

✅ Configuration 'Pingclairfile' is valid!

validate 預設讀取 ./Pingclairfile，也會偵測 ./Caddyfile。它會編譯設定並執行語意檢查，例如憑證路徑是否存在。驗證不是參考意見：沒通過的設定就不會執行，失敗時最後一行會印出原因。

3. 🧭 查看編譯後的設定

pingclair adapt --pretty

{
  "debug": false,
  "servers": [
    {
      "name": "localhost",
      "names": [
        "localhost"
      ],
      "listen": [
        "[::]:8080"
      ],

編譯後的 JSON 是伺服器使用的設定格式。若指令的行為不符預期，請先檢查此輸出。以下命令可顯示 pingclair fmt 的格式調整：

pingclair fmt --diff

fmt 輸出標準格式，每層以一個定位字元縮排。

4. 🚀 執行

在前景執行，日誌會一直顯示在你的終端機上：

pingclair run Pingclairfile

加上 --watch，每次存檔都會重新載入設定，這就是開發時的工作循環：

pingclair run --watch Pingclairfile

♻️ Configuration reloaded successfully
✅ Configuration reloaded completed successfully in 2.478622ms

或者在背景執行，關掉 shell 之後它仍會繼續運作：

pingclair start -c Pingclairfile

✅ Pingclair started in the background (pid 4432)

pingclair start、stop 與 reload 透過 Admin API 連到執行中的伺服器，這就是上面的設定要寫 admin 的原因。pingclair run 則不需要它。

5. 🔍 驗證

curl -i http://localhost:8080/

ETag 與 Last-Modified 代表檔案伺服器確實從磁碟讀取了檔案，本文就是 public/index.html。要停止背景執行的伺服器：

pingclair stop

✅ Pingclair stopped

⚡ 使用單一命令啟動伺服器

下列三個子命令不需要設定檔，適合本機測試與臨時環境：

pingclair file-server --listen :8081 --root ./public
pingclair reverse-proxy --from :8082 --to 127.0.0.1:8081
pingclair respond --listen :8083 -s 200 -b "hello from respond"

每個命令啟動時都會印出它的監聽位址：

🚀 Starting file server on :8081 serving ./public (browse: false)
🚀 Starting reverse proxy: :8082 -> ["127.0.0.1:8081"]
Server address: [::]:8083

送到 :8082 的每個請求都會代理到 :8081 上的檔案伺服器，:8083 則以你傳入的本文回應。respond 僅供開發使用。

🔁 移進服務裡

服務執行的是 /etc/Pingclair/Pingclairfile，設定放到那裡才能在重開機後繼續生效：

sudo cp Pingclairfile /etc/Pingclair/Pingclairfile
sudo pingclair validate /etc/Pingclair/Pingclairfile
sudo pc service reload
curl -i http://localhost/

pc service reload 會請執行中的伺服器重新讀取檔案，unit 的做法是送出 SIGUSR1。pingclair reload 透過 Admin API 走到同一段程式碼，還會回報伺服器對這個檔案的判定，因此需要全域選項區塊裡的 admin；sudo kill -USR1 "$(systemctl show -p MainPID --value pingclair)" 則兩者都不需要。

不論走哪條路，都請先驗證、事後再讀結果：systemctl reload 只回報訊號已送達，伺服器的判定——套用了，或附理由拒絕——會寫進 unit 的狀態列與 journal。被拒絕的重載會讓舊設定繼續提供服務，這正是拒絕的用意。完整說明請見以服務方式執行。

⚠️ 無法運作時

Address already in use。 安裝程式的服務仍佔著 :80，或有其他行程佔用了你的連接埠。sudo ss -ltnp | grep :80 會列出佔用者；sudo pc service stop 可以釋放預設的那個。
對 http://localhost:8080 出現 Empty reply from server。 你正在用明文跟 TLS 監聽器說話。請在網站位址加上 http:// scheme，或改用 https:// 連線並信任內部憑證。
Cannot reach admin API at 127.0.0.1:2019。 設定裡沒有 admin 選項，所以沒有東西在等 pingclair stop 與 pingclair reload。請把它加進全域選項區塊，或在前景行程按 Ctrl-C 停止。
curl 連 loopback 位址時卡住。 有系統代理攔截了請求。請改用 curl --noproxy '*' 再試一次。
驗證失敗並顯示 Unsupported feature。 這個指令認得但沒有實作，訊息會指出替代方案，例如 encode br：代理的回應沒有實作 Brotli，所以訊息會指向 encode zstd gzip。

🧭 下一步

HTTPS：從 Let’s Encrypt 或內部憑證授權單位，為公開網域名稱取得憑證。
以服務方式執行：unit、它的重載語意，以及它的日誌。
Pingclairfile：語言本身，包括匹配器、片段與匯入。

🏃快速開始