Webship 工程

Webship 中的 TLS 憑證：嵌入式 ACME CA

了解 Webship 1.4.0 如何使用其內建 CA 發行並輪換每個網站的私有 TLS 證書、客戶端信任的運作方式，以及內建身份如何與公共 ACME 和手動證書共存。

發佈於 2026年9月13日

# Webship 中的 TLS 憑證：嵌入式 ACME CA

TLS 證書有兩個功能：它有助於加密連接，並告訴客戶端正在與哪個身份對話。加密可以很強，但受眾的信任決策可能是錯的。這就是為什麼證書自動化必須從一個問題開始：誰必須信任這個網站？

Webship 1.4.0 為每個已配置的網站獨立做出這個選擇。公共網站可以使用瀏覽器信任的 ACME 證書，內部服務可以使用 Webship 內嵌的私人證書授權機構，而已經擁有 PKI 的網站可以保留操作員管理的證書文件。它們都可以共用一個 Webship 進程，而不需共用一個私鑰或一個信任邊界。

四種自動證書模式，可依據網站選擇

certificate_mode 欄位屬於每個 [[sites]] 條目。它不是全域開關。

| 模式 | 信任來源 | 最適合 | 驗證路徑 | | --- | --- | --- | --- | | 每站點 | 公共瀏覽器和作業系統信任庫 | 具有單一確切主機名的公共站點 | 公共 ACME 使用 TLS-ALPN-01 | | 車隊 | 公共瀏覽器和作業系統信任存儲 | 在明確註冊的域名下的大量第三層和第四層名稱集合 | 公共 ACME 配合 DNS-01 以及穩定的憑證分片 | | 嵌入式 | 由操作員安裝的私人 Webship 根 | 內部服務、管理設備、私人車隊及測試環境 | 進程中簽發；無外部驗證 | | 共享 | 公共瀏覽器和作業系統的信任庫 | 有意使用單一公共多 SAN 群組的傳統部署 | 使用 TLS-ALPN-01 的公共 ACME |

預設為 per_site。它會為網站的精確名稱訂購一個公共憑證。Fleet 模式是適用於許多深層子域的可擴展公共選項。Embedded 模式使用 Webship 的私有內部 CA。Shared 模式仍可用於相容性，但它不是預設選項。

在 [sites.tls] 下，完整的證書和金鑰總是優先於該站點的自動簽發。

“embedded ACME CA” 的意思是什麼

配置部分名為 [acme_ca]，但嵌入的 CA 並不是公共或可通過網絡訪問的 ACME 服務。它不提供目錄端點，不接受遠程註冊，不調用任何註冊者 API，也不執行任何控制權證明挑戰。

相反，Webship 將整個私人發行流程保留在一個過程中：

網站選擇 certificate_mode = "embedded"。
Webship 在配置的狀態目錄中載入或建立私人根身份。
Webship 為該網站生成一個新的私鑰。
嵌入的根為該確切名稱簽發了一份葉證書。
Webship 在將完成的身份安裝到實時 TLS 解析器之前會進行驗證。
該憑證隨後可供該網站的每個啟用協議使用。

一個 ACME 風格的網路挑戰只會證明 Webship 對自身有效，因此嵌入的路徑故意沒有網路協議。[acme_ca] 部分是私有 PKI 狀態：它定義了根的位置以及發行的葉子證書有效的時間長度。

為一個網站配置嵌入式證書

這是一個私人網站的最小形狀：

~~~toml listen = "0.0.0.0:443"

[tls] unknown_sni = "reject"

[自動_tls] enabled = true cache_dir = "/var/lib/webship/acme"

[acme_ca] state_dir = "/var/lib/webship/acme-ca" leaf_validity_days = 90

[[網站]] domain = "service.internal.example" root = "/srv/service" certificate_mode = "內嵌"

[sites.protocols] h1 = true h2 = true h3 = true ~~~

當嵌入式站點首次需要時，根身份會被懶惰地創建。Webship 將根密鑰以受限權限保存在 state_dir 中。根證書的有效期為十年；葉子證書的有效期由 leaf_validity_days 控制。

將兩個儲存位置都視為生產狀態：

ACME 快取自動管理網站身份。
嵌入式 CA 狀態目錄保存著私有根身份。
服務帳號需要存取權限，但應用程式使用者不需要。
備份必須保持機密性和檔案權限。
生產、開發和測試應使用不同的根目錄和不同的目錄。

刪除根目錄並不會“重置 TLS”。它會創建一個新的信任錨。信任舊根的客戶端會拒絕使用替代根簽發的憑證，直到它們的信任存儲被更新。

私人信託是有意的

嵌入式憑證授權中心（CA）簽發的憑證不會自動被公共瀏覽器或作業系統信任。只有在操作員將導出的 Webship 根憑證安裝到客戶端的信任存儲中後，它們才會被信任。

這使得嵌入模式非常適合於：

通過設備管理註冊的公司管理的筆記本電腦和手機；
帶有明確 CA 憑證的內部服務間流量；
私人電器和受控邊緣車隊；
必須運行真實 TLS 行為的開發和測試環境；
無法依賴公共憑證機構的隔離網路。

這並不是適用於普通公共網站的正確模式，因為其訪客使用未管理的瀏覽器。對於精確的公共名稱，請使用公共每網站發行；對於大型公共子域集合，請使用集群發行；僅對有意的舊版多 SAN 部署使用共享；或從已信任的 PKI 中手動獲取文件。

僅將根憑證分發給客戶端。切勿分發根私鑰。擁有該私鑰將使持有人有權簽發所有已註冊客戶端信任的身份。

公有和私有證書可以共存

Webship 1.4.0 可以在同一監聽器上混合使用憑證策略：

~~~toml listen = "0.0.0.0:443"

[tls] unknown_sni = "reject"

[自動_tls] enabled = true directory_url = "https://acme-v02.api.letsencrypt.org/directory" cache_dir = "/var/lib/webship/acme" contacts = ["mailto:ops@example.com"] 接受服務條款 = true

[acme_ca] state_dir = "/var/lib/webship/acme-ca" leaf_validity_days = 90

[[網站]] domain = "www.example.com" root = "/srv/public" certificate_mode = "每個站點"

[[網站]] domain = "control.internal.example" root = "/srv/control" certificate_mode = "內嵌"

[[網站]] domain = "payments.example.com" root = "/srv/payments"

[sites.tls] cert = "/etc/webship/payments-fullchain.pem" key = "/etc/webship/payments-private-key.pem" ~~~

在這裡，www.example.com 獲取其自身的公共 ACME 證書。control.internal.example 從內嵌的 CA 獲取私人證書。payments.example.com 保持在操作員的外部 PKI 下，因為其明確的檔案具有優先權。

公共 ACME 目錄會被嵌入的網站忽略。嵌入的根目錄從不簽署公共網站。手動網站從不會被自動地加入任何自動化工作流程。

H1、H2、H3 和 WebTransport 的單一憑證解析器

證書選擇發生在 TLS 握手期間，在 HTTP 請求存在之前。Webship 使用 ClientHello 伺服器名稱來選擇網站身份，然後協商應用程式協議。

HTTP/1.1 和 HTTP/2 在 TCP 上使用 TLS。
HTTP/3 和 WebTransport 在 UDP 上的 QUIC 中使用 TLS。
一個有效的網站身份可以用於所有啟用的協議。
HTTP/3 也需要 UDP 可達性；H1 和 H2 使用 TCP 路徑。
Alt-Svc 可以在保留 TCP 回退的同時宣傳 H3。

TCP、TLS 和 QUIC 使用相同的網站識別身份模型。精確名稱優先，當配置了通配符證書時，最長有效的通配符獲勝，未知名稱的 SNI 可以被拒絕，而不是接收不相關的默認證書。

當未識別的主機名稱必須關閉時，在多站點監聽器上使用 unknown_sni = "reject"。在部署到生產環境之前，測試已識別的名稱、未識別的名稱以及您預期的無 SNI 行為。

在沒有服務間隙的情況下旋轉嵌入身份

Webship 通過其經認證、回環綁定的 MCP 伺服器公開憑證狀態和受控變更：

webship.tls.get_status 報告目前使用的憑證解析器及續期狀態。
webship.tls.reissue_certificate 僅當該站點使用嵌入模式時，才會立即重新簽發自動管理的站點證書。
webship.tls.reload 透過正常受保護的 TLS 路徑重新載入憑證狀態。
webship.acme_ca.status 報告私有 CA 是否被選取、其狀態目錄、憑證有效期、簽發次數、撤銷次數，以及近期使用的域名範例。
webship.sites.apply 根據固定的配置版本添加或移除站點。

對於嵌入式重新發行，Webship 在替換生效之前會創建並驗證替換品。目前有效的身份將繼續使用，直到新的身份準備就緒。只有在安裝了替換品之後，已退役的身份才會被記錄。

即時重新簽發操作刻意拒絕公用 per_site 證書。公用續期必須保留在公用 ACME 生命週期內，而不能與私人進行中的簽署混淆。共享模式成員資格也會重新啟動時被凍結，因為改變多 SAN 群組會重建身份邊界。

MCP 是一個特權控制介面。保持迴路模式，要求使用 TLS 和強效承載令牌，對遠程管理使用經驗證的通道，並審核每一次變更。

重要的失敗界限

一個安全的憑證系統必須以正確的方向失敗。

一個新配置的嵌入式網站在發行待處理期間不會接收其他網站的身份。
無效的替換不會被安裝在有效的憑證上。
明確的手動檔案防止自動擁有該網站。
在 HTTP 路由之前，未知的命名 SNI 可以被拒絕。
嵌入的 CA 保持私密，並且沒有遠端註冊端點。
公共和嵌入式身份在自動 TLS 狀態中使用不同的快取路徑。

嵌入式 CA 未初始化的警告意味著 Webship 無法啟動配置的狀態目錄。請在向受影響的站點發送流量之前，修正所有權、權限、持久性或存儲可用性。不要通過複製其他環境的根密鑰來繞過此錯誤。

生產檢查清單

啟用嵌入模式之前：

確認每個必須信任該網站的客戶群體。
建立一個受控的過程來導出和安裝根憑證。
為生產、開發和測試使用獨立的根狀態。
持續並保護嵌入式 CA 狀態目錄和自動 TLS 快取。
在專用服務帳戶下運行 Webship，該帳戶僅能訪問所需的金鑰資料。
在每個其信任邊界必須明確的網站上選擇 certificate_mode。
設定並測試未知 SNI 政策。
故意啟用 H1、H2 和 H3，並驗證 TCP 和 UDP 路徑。
在生產環境之外練習重新發行、重新啟動、備份、還原和客戶端信任驗證。
在部署前運行 webship --check-config，然後從真實客戶端驗證發行者、名稱、有效性、鏈條和協商的協議。

先選擇信任，再選擇自動化

內嵌 CA 消除了私有基礎設施對外部證書服務的依賴。它不會使私有根證書在全球范圍內被信任，也不會免除操作員的 PKI 責任。

Webship 自動化金鑰生成、簽署、驗證、安裝、輪換，以及整個協議的證書選擇。操作員仍然擁有根目錄管理、客戶端註冊、環境隔離、備份、恢復，以及使用公有或私有信任路徑的決策權。

這種分離就是其特色。一個自給自足的伺服器可以在不假裝成公共 CA 的情況下自動化私有 TLS，而公共網站仍然可以在相同的流程中使用瀏覽器信任的每站或整個網絡的證書發行。

在部署之前，請閱讀版本化的 Webship 1.4.0 文件。RFC 5280 定義了證書配置文件和驗證，RFC 6066 定義了 TLS 伺服器名稱信號，RFC 8446 定義了 TLS 1.3，RFC 8555 定義了公開 ACME，RFC 9525 定義了服務身份驗證。