⌨️命令列

Pingclair 是單一二進位檔。從執行伺服器到檢查設定，每一項工作都是它的子命令：

pingclair <command> [<args…>]

角括號代表必填的值，方括號代表選填的值，… 代表可以重複的值。每個命令都支援 --help，pingclair help <command> 會印出相同的內容。不帶命令執行二進位檔，會印出命令清單。

📌 本頁描述 v0.2.2。

安裝程式也會把二進位檔連結為 pc，所以下面每個命令都有兩個字母的簡寫：pc validate、pc service reload 等等。兩者是同一個程式：pc 是符號連結，不是第二個二進位檔。

🚩 全域旗標

旗標	作用
-v、--verbose	將這次執行的日誌層級提高到 debug。可以寫在命令之前或之後。與 caddy -v 不同，它不會印出版本。
-h、--help	印出所附加命令的說明。
-V、--version	印出版本。只能用在最上層。

🧭 命令一覽

命令	作用
run	在前景執行伺服器。
reload	透過 Admin API 套用修改後的設定，並回報伺服器對它的判定。
start	啟動一個脫離終端機的伺服器。
stop	透過 Admin API 停止執行中的伺服器。
completion	印出 shell 自動補全腳本。
environ	印出伺服器將看到的環境變數。
list-modules	列出編譯進這個二進位檔的模組。
build-info	印出建置資訊，包括工具鏈。
manpage	把 man page 寫入一個目錄。
storage-export	把憑證儲存區寫成 tar 封存檔。
storage-import	從該 tar 檔還原憑證儲存區。
trust	把內部 CA 根憑證安裝到系統信任儲存區。
untrust	再把它移除。
respond	提供固定的回應，供開發使用。
reverse-proxy	不用設定檔就代理到上游。
file-server	不用設定檔就提供一個目錄。
validate	編譯設定並回報它哪裡有問題。
adapt	印出 Pingclairfile 編譯後的 JSON 形式。
fmt	格式化 Pingclairfile，或顯示格式化會改變什麼。
hash-password	為 basic_auth 產生密碼雜湊。
version	印出版本。
service	控制已安裝的 systemd unit。

0.2.0 變更：新增 storage export 與 storage import，作為 Caddy 對 storage-export 與 storage-import 的寫法。帶連字號的名稱仍然可以使用。

pingclair run

以一份設定文件在前景執行伺服器。日誌輸出到標準輸出與標準錯誤，按 Ctrl-C 會關閉伺服器。

pingclair run [OPTIONS] [PATH]

參數	預設值	作用
PATH	./Pingclairfile，其次 ./Caddyfile	要載入的設定檔或目錄。

旗標	作用
-c、--config <CONFIG>	指定設定檔，不可同時提供位置參數路徑；-c - 一律讀取標準輸入。
--adapter caddyfile|json	覆寫副檔名推斷；JSON 是 Pingclair 的結構。明確 adapter 只接受單一檔案。
-r、--resume	載入 Admin API 最後自動儲存的設定，而不是檔案，與 caddy run --resume 相同。兩者同時存在時，覆寫 PATH。
-w、--watch	每秒檢查一次設定檔的修改時間，每次變更後重新載入。供本機開發使用。

pingclair run --watch

沒有路徑且兩個預設檔案都不存在時，run 會只啟動 127.0.0.1:2019 的 Admin API。Unix 上第一次 /load 可加入明文 HTTP 監聽器；TLS 與 H3 必須從檔案啟動。明確指定不存在的路徑仍會失敗。沒有檔案來源時 SIGUSR1 只回報無法從檔案重載，SIGHUP 會被忽略。

若要讓伺服器在終端機關閉後繼續執行，請使用已安裝的 unit（以服務方式執行）。

pingclair reload

透過 Admin API（POST /load）把設定檔送給執行中的伺服器。由伺服器自己回應這個請求，所以這個命令能回報檔案是否已套用。訊號做不到這一點：systemd 只能確認訊號已送達。

pingclair reload [OPTIONS]

旗標	預設值	作用
-c、--config <CONFIG>	./Pingclairfile，其次 ./Caddyfile	要套用的設定檔。
--address <ADDRESS>	127.0.0.1:2019	Admin API 位址。

執行中的設定必須以全域 admin 選項啟用 Admin API；少了它，就沒有東西可以連線。伺服器無法套用新檔案時（最常見的原因是新增或搬移了監聽器），命令會失敗，先前的設定則繼續提供服務。

sudo pingclair reload -c /etc/Pingclair/Pingclairfile

pingclair start

以背景行程啟動伺服器，shell 結束後它仍會繼續執行，不需要服務管理器。

pingclair start [OPTIONS]

旗標	預設值	作用
-c、--config <CONFIG>	./Pingclairfile，其次 ./Caddyfile	要載入的設定檔。

這個行程會脫離終端機，輸出也會被丟棄，所以它的日誌不會保存在任何地方。在有 systemd 的主機上，已安裝的 unit 是更好的工具：它會收集日誌、失敗時重啟，也知道監聽器何時綁定完成。請見以服務方式執行。

pingclair stop

以 Admin API 的 POST /stop 停止執行中的伺服器。與 reload 一樣，執行中的設定需要有 admin 選項。

pingclair stop [OPTIONS]

旗標	預設值	作用
--address <ADDRESS>	127.0.0.1:2019	Admin API 位址。

pingclair completion

為一種 shell 印出自動補全腳本。支援的名稱就是這個參數接受的那些：bash、zsh、fish、powershell、elvish。

pingclair completion <SHELL>

pingclair completion zsh > ~/.zfunc/_pingclair

pingclair environ

印出這個行程繼承的環境變數，每行一個 NAME=value，讓你在啟動前就能檢查 PINGCLAIR_TLS_STORE 這類的值。與 caddy environ 不同，它不會印出伺服器推算出的路徑。

pingclair environ

pingclair list-modules

列出編譯進這個二進位檔的模組。--json 會以 JSON 印出同一份清單，供腳本使用。

0.2.0 變更：接受 --versions、--packages 與 -s／--skip-standard，每個模組皆為 standard，--skip-standard 因此輸出空白。

admin API 以 Caddy 自己的名稱列出，而且只列這裡真的會回應的部分：admin.api.load、admin.api.metrics 與 admin.api.reverse_proxy。admin.api.pki 刻意不在清單中，因為 /pki/ 沒有被服務——這份清單要能預告後續請求會得到什麼，所以它不再只印一個 admin-api 標籤。

pingclair list-modules [--json]

pingclair build-info

印出建置資訊：版本、目標平台，以及產生這個二進位檔的工具鏈。回報缺陷時很有用，因為它能指出確切的建置。

pingclair build-info

pingclair manpage

把 man page 寫入一個必須已經存在的目錄。這個旗標是必填的，所以不會意外寫進目前的目錄。

pingclair manpage --directory /usr/local/share/man/man1

pingclair storage-export

把憑證儲存區寫成 tar 封存檔。儲存區是 PINGCLAIR_TLS_STORE 指定的那一個，否則就是執行命令的使用者的資料目錄。範例中的前綴讓 root shell 指向服務帳號的儲存區，而不是 root 自己的。-o - 會把封存檔寫到標準輸出。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair \
  pingclair storage-export -o /tmp/store.tar

封存檔裡有私鑰，所以會以 600 權限寫入，應該放在加密的媒體上，而不是放進會送到儲存桶的備份裡。TLS 指南說明了它包含什麼，以及何時該搬移它。

pingclair storage-import

從 storage-export 寫出的封存檔還原儲存區。-i - 會從標準輸入讀取封存檔。

0.2.0 變更：兩個命令都接受 -c／--config <file>，該檔案中的全域 storage file_system <path> 選項會指定儲存區。什麼都不會還原的匯入會被拒絕。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair \
  pingclair storage-import -i /tmp/store.tar

pingclair trust

把內部憑證授權單位（tls internal）的根憑證安裝到系統信任儲存區。之後，使用該儲存區的用戶端就會接受這個憑證授權單位簽發的憑證。根憑證從 PINGCLAIR_TLS_STORE 指定的儲存區讀取。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair trust

HTTPS 頁面說明了何時需要這麼做，以及如何確認它生效。

📌 內部根憑證位於 <store>/pki/authorities/local/root.crt。舊 internal/ 目錄不遷移，升級後須重新執行 pingclair trust。

pingclair untrust

從系統信任儲存區移除該根憑證。已簽發的憑證仍留在磁碟上，但用戶端不再信任它們。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair untrust

pingclair respond

對每個請求都提供同一個固定的回應（狀態碼、標頭與本文）。它是給開發用的，也適合拿一個永遠以相同方式回應的源站來測試用戶端。

pingclair respond [OPTIONS]

旗標	預設值	作用
-s、--status <STATUS>	200	要回傳的狀態碼。
-H、--header <HEADERS>	無	以 Field: value 表示的回應標頭。可重複。
-b、--body <BODY>	空	回應本文。
-l、--listen <LISTEN>	隨機的 loopback 連接埠	監聽位址。

pingclair respond --status 503 --header 'Retry-After: 30' --body 'down for maintenance'

沒有 --listen 時，會選一個空閒的 loopback 連接埠並印出來，所以兩個開發用伺服器永遠不會搶同一個連接埠。

pingclair reverse-proxy

不用設定檔，就把一個監聽器代理到一個或多個上游。--to 是必填的；重複使用它可以把請求分散到多個上游。反向代理指南以設定檔的方式說明同樣的內容。

pingclair reverse-proxy [OPTIONS] --to <TO>

旗標	預設值	作用
--from <FROM>	localhost	要監聽的位址。
--to <TO>	必填	上游位址。可重複以指定多個。
--header-up <HEADERS_UP>	無	送往上游的請求標頭，以 Field: value 表示。可重複。
--header-down <HEADERS_DOWN>	無	送回下游的回應標頭，以 Field: value 表示。可重複。
--insecure	關閉	不驗證上游的 TLS 憑證。
--internal-certs	關閉	由內部 CA 簽發這個監聽器的憑證，而不是嘗試取得公開憑證。
--disable-redirects	關閉	不建立 HTTP 轉 HTTPS 的重新導向監聽器。
-c、--change-host-header	關閉	把送往上游的 Host 標頭改寫為上游位址，與 Caddy 相同。

pingclair reverse-proxy --from :8080 --to 127.0.0.1:3000

pingclair file-server

不用設定檔，就以 HTTP 提供一個目錄。

pingclair file-server [OPTIONS]

旗標	預設值	作用
--listen <LISTEN>	:80	要監聽的位址。
--root <ROOT>	.	要提供的目錄。
-b、--browse	關閉	顯示目錄列表。
-d、--domain <DOMAIN>	無	以 HTTPS 提供這個網域；--listen 必須是一個連接埠。
--access-log	關閉	每個請求寫一行存取紀錄。
--no-compress	關閉	停用回應壓縮。
--file-limit <FILE_LIMIT>	無	目錄列表最多顯示的檔案數。
--templates	關閉	把 .html 檔案當作模板算繪，與 Caddy 相同。

pingclair file-server --root ./public --browse --listen :8080

壓縮、快取標頭與單頁應用程式的後備路由應該寫在設定檔中；靜態網站指南說明了這些內容。

pingclair validate

編譯設定並回報找到的第一個問題，不會啟動任何東西。設定被拒絕時結束碼不為零，所以這個命令可以當作部署腳本中的關卡。

pingclair validate [OPTIONS] [PATH]

參數	預設值	作用
PATH	./Pingclairfile，其次 ./Caddyfile	要檢查的設定檔或目錄。

validate 同樣接受 -c／--config 與 --adapter caddyfile|json，但沒有輸入時會失敗。它會讀取、解析每個手動憑證與金鑰，確認兩者配對，不開啟監聽器。

sudo pingclair validate /etc/Pingclair/Pingclairfile

pingclair adapt

印出 Pingclairfile 編譯後的 JSON 文件。這是 Pingclair 自己的 schema，也就是 validate、run 與 Admin API 的 /load 接受的格式。與 caddy adapt 不同，輸出不是 Caddy 的 {"apps": …} 形式，Caddy 也無法載入它。

--pretty 會為 JSON 加上縮排。adapt 一律先驗證，--validate 仍被接受但不改變行為。匯出格式的匹配器改用標記表示法，handle 容器稱為 pipeline，重試政策為單一 predicate；舊格式仍可載入。

0.2.0 變更：adapt 在印出之前一律會驗證，所以結束碼 0 代表這個建置能載入結果。--validate 仍會被接受，但不會改變任何事。

pingclair adapt [OPTIONS]

旗標	預設值	作用
-c、--config <CONFIG>	./Pingclairfile，其次 ./Caddyfile	要讀取的設定檔。
-p、--pretty	關閉	為 JSON 加上縮排。
--validate	關閉	相容旗標；一律先驗證。

pingclair adapt --pretty --validate

pingclair fmt

格式化 Pingclairfile 並印出結果。沒有路徑時讀取 ./Pingclairfile；- 則讀取標準輸入。

0.2.0 變更：輸入原本沒有格式化時，fmt 會以狀態碼 1 結束，所以它能像 caddy fmt 一樣擋下 commit；--overwrite 仍以 0 結束。--config <path> 與 -w 作為 Caddy 的寫法被接受，縮排也從兩個空白改為每層一個 tab。

pingclair fmt [OPTIONS] [PATH]

旗標	作用
-o、-w、--overwrite	把格式化後的內容寫回檔案，而不是印出來。
-d、--diff	印出視覺化的差異，而不是格式化後的檔案。

pingclair fmt --diff              # what would change
pingclair fmt --overwrite         # apply it

pingclair hash-password

為 basic_auth 指令產生密碼雜湊。省略 --plaintext 時，密碼從標準輸入讀取，這樣它就不會留在 shell 歷史紀錄中。

pingclair hash-password [OPTIONS]

旗標	預設值	作用
-p、--plaintext <PLAINTEXT>	從標準輸入讀取	要雜湊的密碼。
--algorithm <ALGORITHM>	bcrypt	bcrypt 或 argon2id。
--bcrypt-cost <COST>	14	bcrypt 成本，4 到 31。越高越慢，也越強。
--argon2id-time <TIME>	1	argon2id 迭代次數。
--argon2id-memory <MEMORY>	65536	argon2id 記憶體成本，單位為 KiB。
--argon2id-threads <THREADS>	4	argon2id 平行度。
--argon2id-keylen <KEYLEN>	32	argon2id 輸出長度，單位為位元組。

pingclair hash-password --algorithm argon2id

把輸出貼進指令中；basic_auth 條目示範了周圍的語法。

pingclair version

發行版印出自己的標記，例如 v0.2.2。main 建置印出 v0.0.0-dev+<commit>，沒有 git checkout 時為 v0.0.0-dev。build-info 與 list-modules --versions 使用相同字串。

pingclair version

pingclair service

控制安裝程式寫入的 systemd unit。它包裝了 systemctl，所以兩者都能用；這個子命令讓 unit 的命令和其他命令放在一起。

pingclair service <start|stop|restart|reload|status>

子命令	作用
start	啟動 unit。
stop	停止 unit。
restart	重啟 unit，監聽器變更或全行程層級的選項變更都需要這麼做。
reload	以訊號請執行中的伺服器重新讀取設定檔。結果出現在 unit 的狀態列與 journal 中，而不是這個命令的結束碼。
status	印出 unit 的狀態。

它只能在有 systemd 的 Linux 上運作；在其他平台上會拒絕執行。unit 本身的說明請見以服務方式執行。

🧾 這些選項從哪裡來

命令列定義在伺服器原始碼的單一檔案 pingclair/src/cli/mod.rs 中，本頁依照它的順序編排。那裡的命令旗標一改，本頁也會跟著改。