修正 Collabora Online “Socket 連線意外關閉”問題：WebSocket 和代理程式檢查

Collabora Online 乍看之下可能運作正常，但編輯器一旦嘗試建立即時 WebSocket 連接，就可能發生故障。常見的症狀是文件開始載入後，報告套接字連線意外關閉，有時wss://瀏覽器中也會顯示請求失敗。在 2026 年版本中，在進行任何其他變更之前，需要檢查一個特定於該版本的原因：26.04 分支引入了一個更簡潔的 WebSocket URL，而舊的反向代理規則可能會與之衝突。

Collabora 官方發布的CODE 26.04 版本說明指出，2026 年 6 月 8 日發布的 CODE 26.04.1 版本要求 Apache2 反向代理用戶修改其 ProxyPass 規則，以使用新的精簡版 WebSocket URL。後續發布的 26.04.2.x 版本說明則指出，當新路由無法使用時，CODE 可以回退到舊版 URL，並發出審計警告，引導管理員參考最新的代理設定建議。企業版 Collabora Online 26.04 分支在 2026 年也保持最新，因此管理員在將問題視為隨機網路故障之前，應將從舊版 24.04 或 25.04 指南中復制的任何代理配置與最新的供應商文件進行比較。

這個錯誤到底是什麼意思？

該消息並未指出單一的根本原因。它意味著瀏覽器到 Collabora 的 WebSocket 連線要么從未成功升級，要么已建立但隨後意外終止。這種區別至關重要，因為相應的修復方法有所不同。

1. 檢查故障是否在 26.04 版本升級後出現。

如果問題在從 25.04 或更早版本的 CODE 鏡像升級到 26.04 後立即出現，則應首先懷疑反向代理。這並非猜測：Collabora 在 26.04 版本說明中記錄了 WebSocket URL 的精簡更改，並且官方專案問題報告稱，在升級到 26.04.1 後，WebSocket 連接出現故障，直到修改 Apache 代理規則為止。

不要盲目降級而保留舊代理。回滾可以作為臨時復原措施，但長久之計是將代理程式版本與您計劃運行的版本保持一致。對於 Apache，請使用目前的Collabora Online 代理程式設置，而不是 26.04 版本之前的版本。 Collabora 官方的26.04 WebSocket 問題記錄中記載了一個案例，更新 Apache 規則後恢復了正常運作。

2. 證明 HTTP 在 WebSocket 失敗時仍然有效

首先測試普通的 Collabora 端點：

curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilities

成功回應證明 DNS、TLS、前端代理以及 Collabora 服務的至少一部分可以存取。但這並不證明文件編輯功能可以正常運作。編輯器依賴 WebSocket 路由/cool/，而該路由對代理程式的要求不同。

接下來，開啟瀏覽器開發者工具，重現故障，並使用 WS 篩選器檢查「網路」面板。成功的 WebSocket 握手通常會升級 HTTP 連線；RFC 6455 規定，升級成功時伺服器回應為 HTTP 狀態碼 101。如果您看到的是 400、404、405、502 或立即失敗的請求，請將該時間戳與反向代理和 coolwsd 日誌進行比對。

3. 修復 Nginx WebSocket 路徑和標頭

對於 Nginx 來說，重要的屬性很簡單：請求必須到達 Collabora/cool/路徑，代理必須使用 HTTP/1.1 進行經典的 WebSocket 升級流程，必須轉送Upgrade標Connection頭，必須保留原始主機，並且讀取超時必須足夠長，以便進行編輯會話。

Collabora SDK 手冊長期以來都展示了一個專用的 WebSocket 地址，其中包含Upgrade`<webSocket_name> ` Connection、` Host<webSocket_name>` 和一段很長的 `<webSocket_name> proxy_read_timeout`。 Collabora 專案的一份官方文件也指出了在更廣泛的路由中使用 WebSocket 標頭的必要性/cool。一個保守的、符合 26.04 版本的模式是：

location ^~ /cool/ {
    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 $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

請勿在未調整上游位址、TLS 模型、路徑處理以及任何現有安全控制的情況下，將此配置直接貼到正在運行的生產環境中。正確的做法是在滿足當前 Collabora 路由和頭部要求的前提下，保留您的拓撲結構。

為什麼超時值很重要

WebSocket 編輯會話持續時間較長。 Collabora 專案目前的 Helm 配置明確描述了這一點，並為捆綁的 Nginx 代理程式設定了較大的代理逾時時間。如果您的邊緣負載平衡器、Kubernetes 入口、CDN、防火牆或反向代理關閉空閒連線的時間早於應用程式的預期，使用者可以正常編輯一段時間，然後以固定的時間間隔中斷連線。

如果每次故障發生的時間都大致相同，則應檢查路徑中的每個中間節點，而不僅僅是增加 Nginx 的逾時時間。超時時間最短的節點優先。

4. 確保TLS終止的一致性

常見的部署方式是在 Nginx、Apache、HAProxy、Traefik 或入口控制器處終止 HTTPS 連接，並將純 HTTP 請求轉送到 9980 連接埠上的 Collabora。在這種設計中，Collabora 的官方配置要求後端知道 TLS 連線是由代理程式終止的。 SDK 手冊ssl.enable=false中ssl.termination=true對此模型有詳細說明。

對於 Docker 部署，這通常透過 Collabora 的額外參數來表達：

--o:ssl.enable=false --o:ssl.termination=true

僅當上游確實終止了 TLS 連線時才使用這些配置。如果代理伺服器透過 HTTPS 連接到 Collabora，請設定一致的拓撲結構，不要混用兩種模型。配置不匹配可能會導致錯誤的協定、錯誤的 WebSocket URL、憑證失效或重定向，從而導致升級失敗。

5. 檢查 coolwsd 日誌中的主機和來源不符情況

Collabora 會驗證 WebSocket 來源。如果日誌中包含類似Rejecting WebSocket upgrade「來源」的字樣，後面跟著預期的主機名，請修復外部主機名/連接埠關係，而不是隨意添加寬鬆的標頭。 Collabora 官方問題追蹤器中有一個已記錄的範例，其中配置的伺服器名稱（包含「來源」字樣）與:443瀏覽器來源不匹配，因為缺少明確的連接埠號碼。

可用命令取決於您的安裝情況：

docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtest

在 Web 服務請求失敗的同時，也要找出第一個錯誤。關於升級被拒絕、URI 語法錯誤、主機位址異常或上游伺服器不可用等信息，比通用的瀏覽器彈出視窗更有參考價值。

6. 如果只有基於 Chromium 的瀏覽器發生故障，請檢查 HTTP/2 或 HTTP/3 處理情況。

這是一個比較特殊的情況，但在重建伺服器之前值得檢查一下。 Collabora 專案記錄了一個與 Chromium 相關的案例：代理伺服器直接向 coolwsd 發送了一個 HTTP/2 CONNECT WebSocket 請求，結果收到了 405 Method Not Allowed 錯誤。另一個問題記錄了特定代理路徑中與 HTTP/3/QUIC 相關的文件載入失敗。這些報告並不意味著必須始終停用 HTTP/2 或 HTTP/3；而是意味著中間伺服器必須將客戶端行為轉換為 Collabora 支援的 WebSocket 連線。

如果 Firefox 可以正常運作而 Chrome 在同一帳戶和文件上發生故障，請在代理端擷取協定和狀態碼。除非您的環境中沒有相容的替代方案，否則請優先修復代理/入口的行為，而不是全域停用現代協定。

7. 僅在驗證配置後才重新啟動

先對代理進行語法測試。然後重新加載，而不是反覆盲目重啟：

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2

對於容器，只有當您變更了 Collabora 服務本身的環境或coolwsd設定時才需要重新啟動該服務。如果僅更改了代理，通常只需重新載入代理即可。

如何自行驗證修復是否成功

使用簡短的驗證序列，而不是依賴單一文件的成功開啟：

• 確認/hosting/discovery可/hosting/capabilities透過相同公用主機名稱存取。
• 開啟文件並確認瀏覽器 WS 請求升級成功，而不是傳回 4xx/5xx 錯誤。
• 輸入幾個修改內容，等待比之前故障間隔時間更長的時間，並確認連線保持穩定。
• 儲存並關閉文檔，然後重新開啟以確認 WOPI 往返正常。
• 檢查 coolwsd 和代理程式日誌，查看是否有被拒絕的 WebSocket 升級、URI 解析錯誤或重複的重新連線循環。
• 如果您的部署有負載平衡器或入口，請透過實際生產路徑重複測試，而不是直接連接到連接埠 9980。

你應該選擇哪種解決方案？

如果您已升級至 26.04 版本並使用 Apache 伺服器，則更新代理程式規則是首要任務，因為 Collabora 已明確記錄了此變更。如果斷開連線發生在固定時間後，請重點檢查每個網路躍點的逾時設定。如果所有瀏覽器都立即發生故障，請驗證/cool/路由、UPDATE 標頭、主機/來源一致性以及 TLS 終止。如果只有某個瀏覽器系列出現故障，請在變更 Collabora 本身之前，先比較 HTTP 協定處理情況。

關鍵在於避免預設將「套接字連接意外關閉」視為 Collabora 應用程式崩潰。在許多部署環境中，編輯器、發現端點和 WOPI 主機都運作正常，但反向代理卻錯誤地處理了對即時編輯至關重要的一種連線類型：持久連線的 WebSocket 連線。

官方參考資料

• Collabora CODE 26.04 版本說明
• Collabora Online 26.04 版本說明
• Collabora Online SDK 代理商設置
• CollaboraOnline/線上問題 #15918：26.04 版本升級後 WebSocket 故障
• CollaboraOnline/線上問題 #13751：代理文件中的 WebSocket 標頭
• Collabora 在線 Helm 代理超時預設值
• RFC 6455：WebSocket協議