如何解決 Collabora Online 中的「WOPI 證明驗證失敗」問題

首先從記錄故障訊息的系統入手。

「WOPI 驗證失敗」表示 WOPI 主機無法驗證來自 Collabora Online 的簽章要求。在典型的 Nextcloud Office 設定中，Nextcloud 是 WOPI 主機，Collabora 是 WOPI 用戶端：Collabora 傳送簽名請求，主機對其進行檢查。具體措辭會因整合和版本而異，因此請先確定是哪個元件發出了此訊息以及哪個請求失敗。

此驗證是安全檢查，而非通用連接性測試。它將請求與存取權杖、完整請求 URL 和時間戳綁定，然後使用 Collabora 的私鑰對資料進行簽署。主機使用 Collabora 來發現 XML 中發布的公鑰驗證簽章。 WOPI協定定義描述了已簽署的欄位和標頭。

首先，請重現故障一次，記錄時間、檔案操作、HTTP 狀態碼以及請求或關聯 ID，然後檢查儲存平台日誌和 Collaboracoolwsd日誌中是否有相同的事件。請勿在工單中發布存取權杖、證明標頭或私鑰。

快速診斷表

證據	可能需要檢查的區域	下一步行動
故障發生在重新產生或取代 Collabora 的驗證金鑰之後。	儲存端快取的發現 XML 或不匹配的鍵	刷新 WOPI 主機上的發現，並確認它能看到活動 Collabora 實例的公鑰。
故障僅在某些請求上發生或間歇性發生	多個 Collabora 節點具有不同的證明金鑰，或發現快取不一致	比較每個節點發布的證明金鑰值，並檢查負載平衡器的路由。
代理程式、主機名稱或 URL 變更後發生故障。	用於簽署和驗證的不同請求 URL	比較 Collabora 呼叫的完整 URL 與 WOPI 主機用於驗證證明的 URL。
僅一台主機或一條網路路徑發生故障	可達性、反向代理或主機允許清單配置	測試雙向連接，並將 WOPI 主機允許清單與驗證證明分開檢查。
近期未發現配置更改，且提供的時間戳證明被拒絕	時鐘同步或時間戳解析/新鮮度檢查	檢查兩個系統上的 UTC 時間和 NTP 狀態；驗證主機的時間戳記解釋和允許的年齡。

1. 確認發現暴露了目前的公鑰

Collabora 會在發現端點發布其 WOPI 功能和金鑰證明資訊。從一台可以存取儲存伺服器所用 Collabora URL 的機器上，檢查以下內容：

curl -fsS https://office.example.com/hosting/discovery

在 XML 中尋找包含proof-key目前金鑰的元素value，如果存在，也應包含金鑰oldvalue。請勿將此公共資訊與儲存在 Collabora 伺服器上的私鑰混淆。最有用的比較對像是 WOPI 主機本身所取得的發現回應，因為瀏覽器或管理員工作站可能會透過 DNS、代理或快取收到不同的回應。

已驗證： Collabora 的 WOPI 整合使用簽章驗證，公鑰透過發現機制提供。操作：從實際驗證請求的主機/容器取得發現訊息，然後確認 XML 有效並與儲存平台中配置的 Collabora 端點相符。 Collabora SharePoint 綁定指南詳細介紹了簽章驗證的產生和發現機制。

2. 檢查私鑰是否存在且可讀。

在 Collabora 上，檢查啟動日誌中是否存在證明金鑰檔案缺失或無法讀取的警告。 Collabora 服務必須能夠讀取私鑰以進行簽署。對於打包部署，配置路徑和服務帳戶可能有所不同；請檢查服務的配置目錄及其容器磁碟區掛載點，而不是假設主機路徑。

Collabora 文件coolconfig generate-proof-key記錄了自動金鑰設定失敗的情況。請勿在正常運作的叢集上將其作為例行故障排除命令運行。產生新密鑰會更改簽名身份。如果儲存端仍然信任舊的發現回應，則請求可能會持續失敗，直到主機刷新其使用的公鑰。

sudo coolconfig generate-proof-key

只有在確認金鑰缺失或無效，並規劃好每個 Collabora 節點和 WOPI 主機如何接收符合的金鑰資訊後，才可使用此指令。然後，依照軟體包或容器部署文件中記錄的服務重載流程，從驗證器的網路路徑重新取得服務發現資訊。

3. 尋找節點或快取之間的金鑰不符情況

單一 Collabora 伺服器可以正常運行，而負載平衡部署則可能出現間歇性故障。例如，一個節點可能擁有新產生的私鑰，而另一個節點仍然使用舊金鑰進行簽署；快取了發現資料的主機可能對兩者都不信任。這是部署相關的具體原因，並不能證明所有間歇性錯誤都是由金鑰輪換引起的。

操作：如果允許，透過負載平衡器和直接從每個後端獲取/hosting/discovery資料。比較公鑰值，並檢查 WOPI 主機的發現快取是否為最新。如果節點有意使用不同的金鑰，請驗證儲存整合是否支援該拓撲；否則，請確保叢集中證明金鑰配置的一致性。刷新發現應使用整合支援的機制。避免在沒有證據的情況下編輯資料庫快取或重啟無關服務。

4. 將簽署後的 URL 與主機驗證的 URL 進行比較。

驗證涵蓋了完整的 WOPI 請求 URL（大寫），以及令牌和時間戳。這使得 URL 重寫變得至關重要。反向代理可以變更外部可見的主機名稱、協定、連接埠、路徑或轉義字元。如果 Collabora 對一個 URL 的請求進行簽名，但 WOPI 主機為了驗證而重建了一個不同的 URL，則即使簽名正確，也可能顯示為無效。

操作：關聯代理層和應用層的失敗請求。將驗證器看到的協定、主機名稱、明確連接埠、路徑和編碼字元與驗證程式碼中使用的 URL 進行比較。只有當應用程式依賴轉送主機和轉送協定標頭時，才檢查其處理。保留真實的請求 URL；不要透過停用簽名檢查或信任任意轉送標頭來「修復」問題。

5. 驗證時間戳記和位元組處理

WOPI 驗證包含一個頭部資訊X-WOPI-TimeStamp。在 Microsoft WOPI 規格中，此頭部資訊是一個 64 位元整數，以 100 奈秒為間隔，自公元 0001 年 1 月 1 日起計算，而不是以秒為單位的 Unix 時間戳。如果自訂驗證器將其解析為 Unix 秒數、丟棄數字、更改編碼或錯誤地組裝簽名字節，則可能會拒絕有效的請求。

當主機強制執行資料新鮮度視窗時，時鐘偏差可能是造成問題的原因之一，但具體的容差取決於驗證實作。微軟針對 Microsoft 365 Web 版的指南採用 20 分鐘的年齡檢定；但不要想當然地認為這個時間適用於所有 Collabora 整合。操作：檢查 Collabora 和儲存系統上的 NTP 同步和 UTC 時間，然後查看主機自身文件中記錄的時間戳記規則和解析程式碼。

如果您維護自訂 WOPI 主機，您也需檢查位元組級結構。令牌採用 UTF-8 編碼；長度為位元組計數；URL 為完整的絕對 URL（大寫）；時間戳值必須與指定值完全一致。公鑰必須與發送請求的 Collabora 實例使用的私鑰相對應。

6. 將驗證失敗與允許清單和 TLS 錯誤區分開來

WOPI 主機允許清單決定 Collabora 可以連接哪些儲存主機。 TLS 驗證決定網路對等體的憑證是否可信。證明驗證檢查 WOPI 請求上的簽名。這些控制措施與安全整合相關，但它們不能互換。將主機新增至允許清單並不能修復簽章不符的問題；關閉 TLS 檢查也無法修正過期的公鑰。

對於 Nextcloud 部署，官方故障排除指南建議檢查雙向所需的 HTTP(S) 路徑，查看 Nextcloud 和 Collabora 日誌，並確認 WOPI 主機允許清單條目是否有警告。操作：*根據日誌中的錯誤類別進行操作。將發現端點和網路可達性測試與驗證器測試分開進行。不要為了解決問題而擴大允許清單。

安全恢復序列

記錄失敗請求的確切時間，並確定哪個服務記錄了驗證失敗。
檢查 Collabora 日誌中是否有缺少金鑰的警告；檢查 WOPI 主機網路路徑中的發現 XML。
將發現過程中使用的公鑰與用於簽署請求的私鑰和節點配置進行比較。
檢查負載平衡器的一致性、發現快取以及最近的金鑰、主機名稱、代理或 TLS 變更。
比較已簽署請求 URL 和時間戳處理方式，而不暴露令牌或證明標頭。
使用單一文件重新測試，並在主機日誌中確認相同的請求成功後再恢復正常流量。

如果故障仍然存在，請收集兩端的脫敏日誌、Collabora 和儲存版本、部署類型、涉及的節點數量（單節點或多節點）、已移除金鑰的發現 XML 以及失敗請求的代理路由。將這些資訊分享給相關的供應商或整合維護人員。僅憑具體的錯誤字串無法確定故障原因是過時的發現、URL 規範化、時鐘問題還是自訂驗證器錯誤；請求層級的證據決定了後續的排查方向。