透過代理程式恢復 Collabora 的 WebSocket 連接

當 Collabora Online 報告套接字連線意外關閉時，首先檢查瀏覽器發出的 WebSocket 請求是否coolwsd透過反向代理到達。將代理路由與 Collabora 版本相匹配，保留 WebSocket 升級和 URL 路徑，然後測試一個文檔，同時觀察瀏覽器的網路面板和伺服器日誌。如果問題出現在 Apache 伺服器後升級到 CODE 26.04 版本之後，請先ProxyPass檢查 Apache 規則：Collabora 26.04 版本說明中提到了精簡 WebSocket URL 的變更。

WebSocket 是 Collabora 在文件開啟期間，瀏覽器與其伺服器之間建立的長期雙向連線。反向代理是接收公共請求並將其轉發給 Collabora 的服務。錯誤訊息指向該連接，但這並不能證明反向代理是導致問題的原因；被拒絕的 WOPI 主機、錯誤的公共 URL、TLS 不匹配或錯誤的後端也可能導致會話中斷。

範例文件編輯器錯誤對話框，提示套接字連接意外關閉 — 對話方塊顯示套接字關閉訊息，從而啟動此故障排除檢查。

在做出任何更改之前，請先確定您的路線

記下 Collabora 版本或鏡像標籤、代理軟體、Collabora 公共主機名，以及 TLS 連線終止於代理伺服器或 Collabora 伺服器。在不更改部署的情況下，檢查服務名稱和目前鏡像：

docker compose ps collabora
docker compose images collabora

替換collabora為 Compose 檔案中的服務名稱。對於非 Compose 容器，請使用 ` <container-name>`docker ps和docker inspect`<image-name>` 來識別容器和鏡像。不要假設 ` latest<version>` 標籤仍然指向您上週測試的版本。

1. 查看 WebSocket 握手過程停止的位置

在瀏覽器中，開啟開發者工具，選擇「網路」，篩選WS或 WebSocket，然後重試開啟一個文件。如果公共頁面使用 HTTPS，則應使用請求 URL wss://。選擇失敗的請求，並記下其狀態、URL 路徑和回應頭。成功的握手通常會傳回結果101 Switching Protocols，並在文件會話處於活動狀態時保持開啟狀態。

範例瀏覽器網路面板篩選出 WebSocket 請求，其中失敗的請求傳回狀態碼 400。 — 使用 WebSocket 請求的狀態和路徑來定位失敗的躍點；此面板是一個範例。

沒有出現 WebSocket 要求：在編輯伺服器規則之前，請檢查整合應用程式的 Collabora URL、瀏覽器控制台、DNS 以及任何重新導向或混合內容錯誤。
請求返回 400 或 404：請將請求的路徑與代理轉發的路由以及已安裝的 Collabora 版本支援的路由進行比較。如果傳回 400 錯誤，coolwsd並提示“無效或未知請求”，則可能表示 Collabora 收到的請求路徑不被接受。
請求返回 502 或 504：檢查代理程式是否可以連接到配置的 Collabora 上游，以及位址和連接埠是否指向正確的容器或主機。
請求返回 101，然後稍後關閉：請檢查代理程式、負載平衡器、防火牆和用戶端網路的空閒逾時。 WebSocket 連線持續時間較長，因此過早關閉空閒連線的中間方可能會中斷原本成功的連線建立。

2. 將代理規則與您的 Collabora 版本進行比較

請使用 Collabora 目前針對您使用的代理軟體及其版本的反向代理設定。檢查 WebSocket 路由是否正確處理，代理是否轉送升級標頭，以及代理是否保留路徑和編碼後的查詢字串，而不是重定向或重寫它們。此外，代理程式傳送的公共主機和協定必須與 Collabora 配置的外部伺服器名稱和 TLS 終止設定保持一致。

對於 Nginx，請查看Collabora 目前範例中WebSocket 的特定位置及其 HTTP/1.1、`http://localhost:8000`Upgrade和轉送指令。對於 Apache，請將規則和順序與目前範例進行比較；切勿在未檢查已安裝版本目前請求的情況下直接貼上舊的符合項目。ConnectionProxyPass/cool/…/ws

此版本檢查對 CODE 26.04 至關重要。 Collabora 於 2026 年 6 月 8 日發布的發行說明中提到了一個更簡潔的 WebSocket URL，並指出 Apache 反向代理用戶需要進行相應的調整ProxyPass。 26.04 的後續工作為舊版 URL 新增了回退機制，因此舊規則可能仍然適用於某些版本；Collabora 的 26.04 WebSocket 問題報告對此進行了詳細說明。此回退機制並不能取代將目前代理程式配置與已安裝版本進行配對。請同時閱讀CODE 26.04 的發行說明和更新後的 SDK 範例。

範例：經過編輯的 coolwsd 日誌模式，顯示了對緊湊型 WebSocket 路徑的無效請求 — 這個經過編輯的範例展示了無效請求路徑的類型，需要將其與代理轉送的路由進行比較；它不是即時日誌擷取。

3. 找出一次失敗案例，並做出一次有針對性的改變。

在重試文件之前，先啟動一個簡短的日誌流。 Docker 的--since選項限制了初始輸出，而--follow串流輸出則換行；請參閱Docker Compose 日誌參考。

docker compose logs --since=2m --follow collabora

記錄測試時間，並在 Collabora 和代理日誌中找到相同的請求。如果瀏覽器要求的路徑被代理程式路由到錯誤的後端，則僅使用 Collabora 的版本匹配範例更新該 WebSocket 路由。如果請求到達 Collabora 但主機、來源或協定被拒絕，請將公共主機名稱和連接埠與配置的伺服器名稱和轉送的標頭進行比較。如果日誌顯示 WOPI 主機被拒絕或文件資訊請求失敗，請檢查整合伺服器的允許主機及其從 Collabora 容器的可及性；這與瀏覽器 WebSocket 握手是不同的步驟。

使用代理本身的語法檢查指令驗證其配置後，重新載入代理程式。避免同時更改 TLS 終止、主機允許清單和 URL 重寫：每次測試只更改一個原因，才能使後續結果可解釋。不要為了圖方便而關閉 TLS 驗證或允許所有 WOPI 主機。

4. 從瀏覽器驗證文件的修復情況

重試同一文件。在開發者工具中，確認其 WebSocket 請求已返回101 Switching Protocols並保持開啟。確認文件已完成載入、連線保持正常，並且能夠成功儲存少量編輯內容。如果 WOPI 檔案存取或保存仍然失敗，僅連線狀態正常是不夠的。

瀏覽器網路面板範例，顯示狀態為 101 的 WebSocket 請求，以及切換協定和已連線狀態。 — 瀏覽器端收到 101 回應和開啟的連接，表示 WebSocket 握手成功。

如果握手仍然失敗，請比較瀏覽器請求路徑、代理存取/錯誤訊息以及coolwsd相同時間戳記的匹配日誌條目。這三點比較可以幫助確定下一步應該調查的物件是瀏覽器、代理程式、Collabora 路由還是 WOPI 主機。尋求協助時，請務必從瀏覽器詳細資料和日誌中刪除存取權杖、文件識別碼、使用者名稱和私有主機名稱等資訊。