透過檢查金鑰、發現和 URL 來修復 WOPI 驗證錯誤

當 WOPI 主機報告「證明驗證失敗」或「無效的 WOPI 證明」時，首先要確認哪個系統記錄了拒絕資訊。如果儲存主機拒絕了 Collabora 的簽署請求，請在變更 WOPI 主機允許清單或停用證明檢查之前，請檢查證明金鑰對和發現回應。對於軟體包安裝，Collabora 通常會產生金鑰對；對於 Docker、Kubernetes 和多副本部署，必須提供金鑰對並保持其一致性。

在更改密鑰之前，請先確定失敗的檢查。

WOPI 驗證使用已簽署的請求和 WOPI 用戶端在其發現元資料中發布的公鑰。它獨立於 Collabora 的受信任 WOPI 主機清單、TLS 憑證驗證以及儲存主機的存取令牌檢查。當私鑰遺失或與發布的公鑰不匹配時，密鑰重新生成可以有所幫助，但如果只有一個副本發生更改或主機仍然緩存著發現數據，則可能會產生新的不匹配。

儲存主機日誌記錄了因 WOPI 證明無效而被拒絕的 CheckFileInfo 請求。 — 主機端無效性證明訊息首先指向金鑰發現、簽章建構或請求時間。

日誌中的證據	可能需要檢查的區域
儲存主機在收到 CheckFileInfo 或其他 WOPI 請求時顯示“無效的 WOPI 證明”	Collabora 的證明金鑰、主機發現資料、URL 重構或時間戳
Collabora 顯示「未經授權的 WOPI 主機」或「沒有可接受的 WOPI 主機」。	WOPI 主機允許清單/網域配置，而非驗證金鑰
令牌無效、過期或存取被拒絕（無證明錯誤）	主機頒發的存取權令牌、權限或令牌過期時間

檢查 Collabora 和儲存主機日誌中一個失敗的請求；僅憑瀏覽器載入指示器無法識別驗證金鑰失敗。

選擇適合部署狀況的維修方案。

首先選擇幹擾最小的方案。對於基於軟體包的安裝，請先驗證現有的金鑰檔案和服務日誌；Collabora 目前的文件指出，RPM 和 Debian 軟體包安裝會自動產生 WOPI 驗證金鑰對。如果這些文件存在且穩定，通常無需輪換密鑰。

終端檔案清單顯示了單獨的 proof_key 和 proof_key.pub 檔案。 — Collabora 使用私鑰證明，並透過 WOPI 發現發布其匹配的公鑰。

部署	建議採取的措施	權衡
單一軟體包管理伺服器	保留產生的密鑰對；僅當密鑰缺失或不匹配時才修復權限或重新產生。	改動很小，但請驗證您的軟體包版本和配置路徑。
單一 Docker 容器	產生一對資料並將其持久性掛載到容器中。	coolwsd 需要持久捲和正確的讀取權限。
Kubernetes 或多個副本	在每個 Collabora 實例中掛載一個共享的 Secret/金鑰對。	副本間簽章必須一致；輪替也必須更新主機的發現視圖。
代理伺服器後的主機 URL 已更改	驗證用於簽章驗證的公用方案、主機、路徑和查詢字串	比密鑰輪換更複雜，但可以避免不必要的憑證變更。

Collabora 24.04 版手冊指出，公開的 Docker 映像不包含驗證金鑰對；請自行產生並持久掛載。官方 Helm Chart 支援驗證金鑰 Secret。切勿為每個副本產生單獨的金鑰對，否則負載平衡可能會導致故障間歇性發生。

安全地檢查和修理鑰匙對。

找到已配置的金鑰路徑。在 Collabora 主機或容器內，檢查coolwsd.xml證明金鑰路徑的設置，並確認私鑰和公鑰是否都可用。通常位於 `<path>` /etc/coolwsd/，但軟體包和容器的佈局可能有所不同。切勿將私鑰貼到日誌、工單或聊天記錄中。
檢查密鑰是否匹配。對於常用的預設路徑，比較指紋（不顯示私密金鑰）：`<path_to_path>`sudo openssl pkey -in /etc/coolwsd/proof_key -pubout -outform DER | sha256sum和 ` openssl pkey -pubin -in /etc/coolwsd/proof_key.pub -outform DER | sha256sum<path_to_path>`。產生的哈希值應該匹配。如果您的路徑不同，請替換為實際配置的路徑。如果無法讀取私鑰，請根據服務的安全模型修正其所有權和權限；不要將其設定為全域可讀。
僅在必要時重新產生密鑰對。如果私鑰遺失或金鑰對不匹配，請使用sudo coolconfig generate-proof-key已安裝該工具的本機工具。對於 Docker，請在適當的持久化位置產生金鑰對，然後將這兩個檔案掛載到 Collabora 期望的位置，並確保 coolwsd 進程可以讀取私鑰。在託管平台上，請使用其支援的 Secret 機制，而不是手動編輯正在運行的 pod。
確保所有實例保持一致。對於副本，請將相同的金鑰對部署到每個實例，然後重新啟動或重新部署 Collabora，使其讀取檔案。之後，使用儲存主機支援的機制刷新或重新取得儲存主機上的 WOPI 發現資訊。密鑰輪換會更改公鑰；快取或其他仍在使用舊密鑰的副本可能會導致故障後服務繼續運行。

Kubernetes 磁碟區面板顯示，同一個 WOPI 金鑰 Secret 掛載在兩個正在運行的 Collabora pod 中。 — 副本應共用一個持久的證明金鑰對，以便每個實例都能以一致的方式對請求進行簽署。

密鑰匹配但證明驗證仍然失敗

檢查兩個系統的時間同步狀況。 WOPI 驗證請求包含時間戳記；主機可能會拒絕過時或超出時間視窗的時間戳記。確認 NTP 或平台的時間服務運作正常，且伺服器報告的 UTC 時間合理。切勿為了規避時鐘問題而放鬆時間戳檢查。

接下來，檢查主機用於重建簽名請求的公共 URL。驗證與請求 URL（包括相關查詢參數）相關聯，WOPI 規範要求用於驗證的 URL 表示形式必須與簽章形式相符。即使 Collabora 已對公共 HTTPS URL 進行簽名，終止 HTTPS 的反向代理也可能導致應用程式看到內部 HTTP URL。請根據 WOPI 主機的官方指南配置受信任代理程式標頭和應用程式的外部 URL 設定；切勿重寫驗證邏輯或移除查詢參數。

如果僅在金鑰輪換後驗證失敗，請刷新發現並驗證所有 Collabora 副本是否公開相同的公鑰。如果僅透過某個代理程式或某個副本路由的請求失敗，請比較該路徑的日誌和配置，而不是再次輪換密鑰。停用驗證可能會削弱安全檢查，不應將其用作生產環境的解決方案。