修正 Collabora Online “好吧，這太尷尬了”連接錯誤

Collabora Online 的「抱歉，我們無法連接到您的文件」訊息只是一個症狀，而不是診斷結果。它會在編輯器介面載入完畢但文檔會話無法完成時出現。在目前的部署環境中，最快的解決方法是找出 WOPI 路徑中哪個連線出現故障，而不是隨意更改 Collabora 設定。

本指南以 Nextcloud 35 的最新管理文件和 Collabora Online 25.04 SDK 指南為參考。同樣的故障排除邏輯也適用於許多 ownCloud 和自訂 WOPI 集成，但具體的設定名稱可能因平台和版本而異。

通常是什麼原因導致Collabora連線錯誤？

一個正常運作的瀏覽器會話依賴多個獨立的路徑。使用者的瀏覽器必須能夠存取儲存伺服器和 Collabora；儲存伺服器必須能夠存取 Collabora；Collabora 也必須能夠存取儲存伺服器；協定和憑證必須相容；反向代理必須正確轉送 Collabora 的 HTTP 和 WebSocket 路由。 Nextcloud 的官方故障排除頁面明確列出了這些雙向可及性要求。

這意味著沒有一個普遍適用的正確修復方案。請根據第一次失敗的測試結果選擇修復路徑：

1. 驗證 Collabora 發現與功能端點

首先，找到您的整合實際使用的 Collabora 公共 URL。在瀏覽器和儲存伺服器上開啟以下端點：

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

Nextcloud 目前的故障排除文件建議同時進行這兩項測試。發現端點應傳回 XML，而功能測試應傳回 Collabora 功能資料。如果出現逾時、憑證警告、404 錯誤、代理品牌錯誤頁面或重定向循環，則表示您應該在修改 WOPI 設定之前修復網路或反向代理問題。

首先檢查 Collabora 的公共發現和功能 URL；兩者必須可透過整合使用的相同主機名稱存取。

有關權威的端點指導，請參閱Nextcloud Office 故障排除和Collabora Online 25.04 SDK 手冊。

2. 測試所有四個網路方向，而不僅僅是瀏覽器。

一個常見的錯誤是假設office.example.comCollabora 既然能在桌面瀏覽器中打開，就能從儲存伺服器取得檔案。但事實並非如此。請在實際主機或容器中進行測試：

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

如果公用主機名稱在 Docker、Kubernetes 或私人網路內部解析方式不同，則需要決定是否要修復內部 DNS、新增對應的主機映射，或是透過公用端點進行路由。通常情況下，大規模部署時內部 DNS 較簡潔；對於小型靜態部署，新增 hosts 檔案項目雖然快捷，但維護起來會更加困難。

從伺服器本身執行可達性測試，然後使用 Collabora 日誌將網路故障與 WOPI 信任故障區分開來。

3. 如果缺少 WebSocket 或 Collabora 路由，請修復反向代理程式。

Collabora 不是一個普通的靜態 Web 應用程式。它的反向代理需要路由來處理瀏覽器資源、發現/功能、文件流量和 WebSocket 通訊。在 Collabora 的 SDK 手冊中，Nginx 範例會轉送WebSocket/browser路徑以及相關的流量。/hosting/discovery/hosting/capabilities/cool/.../ws/cool/lool

對於 WebSocket 路由，代理程式必須保留主機名稱並執行 HTTP 升級。一個簡化的 Nginx 模式如下：

location ~ ^/cool/(.*)/ws$ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 36000s;
}

如果您採用不同的 TLS 終止方式，請勿盲目複製此設定。 Collabora 文件中分別提供了端對端 TLS 和 SSL 終止的模式。如果 TLS 在 Nginx 終止，且後端連線為 HTTP，則 Collabora 的內部 SSL 設定必須與此設計相符。在所有地方都使用 HTTPS 更易於理解，而 TLS 在代理處終止雖然可以減少容器內部的憑證處理，但會引入新的設定邊界。

正確的反向代理必須轉送 Collabora HTTP 路由，並保留文件會話的 WebSocket 升級。

4. 檢查協定、憑證和主機名稱的一致性

Nextcloud 目前的 Office 設定文件指出，Collabora Online 伺服器應使用與 Nextcloud 安裝相同的協議，建議使用 HTTPS。但實際上，混合使用公共 HTTP/HTTPS 配置可能會導致內容被屏蔽、重定向目標錯誤或後端憑證驗證失敗。

請將以下項目一併核對：

• 儲存在您儲存平台中的 Collabora URL 就是使用者可存取的公開 URL。
• 此主機名稱提供的憑證對該主機名稱有效，並受到儲存伺服器的信任。
• Collabora 可以驗證儲存伺服器的 HTTPS 憑證。
• 您的反向代理能夠正確轉送原始主機和協定。
• 不會從配置的 Collabora 主機名稱重新導向到 WOPI 未預期的另一個主機名稱。

在實驗室環境中，如果每個元件都明確配置為信任自簽名證書，則該證書或許可行，但這種便利性會犧牲可移植性，並經常導致後續升級或容器重建失敗。對於生產環境而言，使用公開信任或組織信任的憑證鏈才是更安全的選擇。

5. 修正 WOPI 允許列表，而不是停用它們。

如果發現流程正常，且 Collabora 日誌顯示類似「Unauthorized WOPI host沒有與目標相符的可接受的 WOPI 主機」之類的訊息，則問題已從基本連線問題轉移到信任設定問題。 Nextcloud 的官方故障排除文件明確指出，管理員應查看容器日誌以解決此問題。

在儲存方面，Nextcloud 建議使用「WOPI 請求允許清單」設置，將 WOPI 請求限制在 Collabora 伺服器的 IP 位址範圍內。在 Collabora 端，允許的 WOPI 儲存主機必須與 Collabora 實際接收到的儲存 URL 相符。對於多個儲存域，Collabora 目前的 SDK 文件中提供了 WOPI 別名組的說明。

保持 Collabora 伺服器 URL 和 WOPI 允許清單與實際部署保持一致；使用範圍較小的受信任條目，而不是關閉驗證。

請參閱Nextcloud Office 設定文檔，以了解目前伺服器 URL 和 WOPI 允許清單指南。如果您使用 ownCloud Infinite Scale，其協作服務會使用 [此處應填寫特定 URL]COLLABORATION_APP_ADDR作為 Office 應用程式 URL 和COLLABORATION_WOPI_SRC外部可存取的 WOPI 來源；請參閱ownCloud 協作服務文件。

何時應該使用內建程式碼而不是單獨的 Collabora 伺服器？

對於小型 Nextcloud 安裝，內建的 CODE 伺服器可以減少外部管理元件的數量。但缺點是，它仍然依賴 Nextcloud 實例能夠透過瀏覽器中使用的主機名稱存取自身。 Nextcloud 的故障排除文件直接指出了這一點，並建議在內建 CODE 無法連接時正確解析該主機名稱。

當您需要獨立擴充、為多個儲存實例提供集中式服務，或需要資源邊界更清晰的生產架構時，通常使用獨立的 Collabora 伺服器會更為合適。但它會增加 DNS、代理、證書、防火牆和 WOPI 信任配置，因此維運負擔也更高。

不該做什麼

• 不要將停用 WOPI 驗證作為首選解決方案。這樣做可能會掩蓋實際的主機名稱不符問題，從而削弱安全邊界。
• 不要因為代理伺服器故障就直接暴露 9980 連接埠。除非直接暴露連接埠是出於安全考慮，否則請先修復代理伺服器。
• 不要以為 Collabora 主頁回傳 200 狀態碼就代表文件編輯功能正常。發現、功能、WOPI 檔案存取和 WebSocket 連線是相互獨立的過程。
• 不要一次性更改多個層級。每次更改後都要進行測試，以便確定真正的原因究竟是 DNS、TLS、代理還是 WOPI 信任。

最終核查清單

修改完成後，請依下列順序驗證系統：

1. /hosting/discovery透過/hosting/capabilities瀏覽器打開。
2. 從儲存伺服器取得相同的端點。
3. 從 Collabora 伺服器取得儲存伺服器狀態 URL。
4. 開啟一個文檔，同時查看 Collabora 和儲存日誌。
5. 確認瀏覽器能夠建立 Collabora WebSocket 連接，不會重複斷開連接。
6. 確認如果需要協作編輯，第二個使用者可以開啟和編輯測試文件。

如果所有六項檢查都成功，則通用的「哎呀，真尷尬」訊息應該不再掩蓋連線失敗。如果該訊息仍然存在，請擷取一次文件開啟嘗試的 Collabora 日誌行和瀏覽器網路故障資訊；這兩項證據比通用的 UI 訊息本身更有用。