TLS：可以調整什麼

📌 下方 TLS 範例使用目前工作目錄的 ./certs/；請放入自己的憑證、配對金鑰或用戶端 CA 檔案。驗證也會讀取這些檔案。

Pingclair 會為網站名稱自動取得憑證。本頁說明如何設定憑證來源、HTTP/3 與用戶端憑證驗證。不支援的 TLS 選項會在載入時被拒絕。

📌 本頁描述 v0.2.2。

🧾 開始之前

已安裝並執行 Pingclair（安裝）。
關於憑證授權單位的部分，需要一個解析到這台主機的名稱，或在實驗機上使用內部憑證授權單位（HTTPS）。

🌐 提供哪些協定

協定集合寫在全域的 servers 區塊中：

{
    servers {
        protocols h1 h2 h3
    }
}

以 sudo ss -lun | grep ':443 ' 實測：

設定	UDP 443 監聽器
`protocols h1 h2`	0 — 沒有 HTTP/3
`protocols h1 h2 h3`	1 — 已啟用 HTTP/3

⚠️ 這份清單決定的是 HTTP/3，而且只決定 HTTP/3。只列 h1 並不會關閉 HTTP/2：設定 protocols h1 時，提出 h2 的用戶端仍然協商出了 HTTP/2。伺服器從清單中讀取的唯一資訊是 h3 在不在裡面，所以沒有任何設定能停用 HTTP/2。沒有 protocols 這一行時，HTTP/3 是開啟的。

在個別網站上，http3 off 的用意是把一個名稱排除在 HTTP/3 之外，同時讓 QUIC 監聽器繼續為其他名稱提供服務：

https://internal.test {
    tls {
        internal
        http3 off
    }
    file_server /srv/site
}

http3 off 會拒絕該網站的 QUIC 握手，並停止在 Alt-Svc 宣告 HTTP/3。同一連接埠的其他網站仍可使用 QUIC。

🏛️ 憑證來源

三種來源，都在 HTTPS 頁面上示範過：

來源	設定	用途
Let’s Encrypt	單純的公開名稱	公開名稱，在背景自動續期。
內部憑證授權單位	`tls internal`	實驗用名稱、私有源站、tunnel。
你自己的檔案	`tls { cert … key … }`	在其他地方簽發的憑證。

續期在背景執行。全域選項 renewal_window_ratio 以每張憑證有效期的比例，設定續期要提早多久開始。

🔐 用戶端憑證

client_auth 會讓伺服器向用戶端要求憑證。先用 openssl 建立一個小型憑證授權單位與一張用戶端憑證，再把網站指向該憑證授權單位的憑證檔案：

https://internal.test {
    tls {
        internal
        client_auth {
            mode require_and_verify
            trusted_ca_cert_file ./certs/client-ca.crt
        }
    }
    file_server /srv/site
}

實測：沒有用戶端憑證的請求會在交握時失敗，同一個請求加上 --cert client.crt --key client.key 則回應 200。

模式有 request、require、verify_if_given 與 require_and_verify。拼錯的模式會被拒絕，並附上完整清單 (expected request, require, verify_if_given or require_and_verify)。

⚠️ trusted_ca_cert 接受的是憑證本身，以 base64 編碼寫成一行；trusted_ca_cert_file 接受的則是路徑。把路徑傳給前者可以通過編譯，但會在啟動時以 trusted_ca_cert is not a certificate: not valid base64: Invalid symbol 45 失敗——45 就是 -----BEGIN 裡的 -。這個檔案也必須讓 pingclair 使用者讀得到。

精確名稱網站的 client_auth 優先於萬用字元網站；精確網站沒有此區塊時，不要求用戶端憑證。若仍需要驗證，請在精確網站明確加入 client_auth。憑證用途擴充欄位若排除用戶端驗證，握手會被拒絕。

📦 搬移憑證儲存區

儲存區存放已簽發的憑證、ACME 帳號，以及內部憑證授權單位。以套件安裝時，它位於 /var/lib/pingclair/.local/share/pingclair，也就是服務帳號家目錄底下的資料目錄。以其他使用者身分執行的命令，會去找該使用者自己的資料目錄，所以範例都設定了 PINGCLAIR_TLS_STORE；少了它，root 會使用 /root/.local/share/pingclair。storage-export 與 storage-import 負責搬移儲存區：

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-export -o /tmp/store.tar
sudo systemctl stop pingclair
sudo rm -rf /var/lib/pingclair/.local/share/pingclair
sudo mkdir -p /var/lib/pingclair/.local/share/pingclair && sudo chown pingclair:pingclair /var/lib/pingclair/.local/share/pingclair
sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-import -i /tmp/store.tar
sudo systemctl start pingclair

✅ Store exported to /tmp/store.tar
✅ Store imported into /var/lib/pingclair/.local/share/pingclair

這次執行中有三個細節。不論檔名是什麼，封存檔都是 單純的 tar，以 600 權限寫入，所以要讀回來需要 root。匯入會還原封存檔中記錄的擁有者。此外，儲存區裡還有 autosave.json，也就是 Admin API 最後套用的設定，所以匯入也會把它還原。

📌 0.2.0 : 內部憑證授權單位會照 Caddy 的方式存放在 pki/authorities/local/ 底下。舊的 internal/ 目錄不會被遷移：伺服器會建立新的憑證授權單位，每個用戶端都必須再次信任新的根憑證（pingclair trust）。全域的 storage file_system <path> 選項也能在設定中指定儲存區的位置。

如果之後服務以 Internal CA I/O error: Permission denied 拒絕啟動，代表服務帳號無法寫入儲存區的檔案；執行 sudo chown -R pingclair:pingclair /var/lib/pingclair/.local/share/pingclair 即可修正，網站也會恢復回應。

🚫 無法調整的部分

下列 Caddy TLS 選項尚未支援，載入時會被明確拒絕：

Caddy-compatible directive 'tls ciphers' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls curves' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls alpn' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls on_demand' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet

因此，加密套件、曲線、ALPN 清單與隨需簽發都由建置決定，而不是由設定決定。伺服器也不做 OCSP stapling。如果其中哪一項對你很重要，那是功能請求，而不是設定錯誤。

⚠️ 無法運作時

client_auth 以 not valid base64 拒絕啟動。 你把路徑傳給了 trusted_ca_cert；檔案的寫法是 trusted_ca_cert_file。
持有有效憑證的用戶端被拒絕。 請確認簽發它的 CA 就是 trusted_ca_cert_file 裡的那一個，而且憑證沒有過期。
tls ciphers／tls curves／tls alpn／tls on_demand 讓檔案被拒絕。 它們沒有實作；請見上一節。
設定 protocols h1 h2 後 HTTP/3 仍在執行。 這不應該發生，因為那份清單控制的就是它。如果 UDP 443 仍在監聽，代表正在執行的檔案不是你編輯的那一份（重載意味著什麼）。
搬移儲存區後服務無法啟動。 是擁有者的問題，如上所述。

🧭 下一步

HTTPS：取得憑證的四種方式，以及它們確切的日誌內容。
HTTP/3：設定 HTTP/3，並確認用戶端使用的協定版本。
tls：指令參考。

🛡️TLS：可以調整什麼