修復程式碼文件編輯工作階段在 10 分鐘後斷開連線的問題

如果 Collabora Online Development Edition (CODE) 文件正常打開，編輯功能也正常，但編輯器會在大約 10 分鐘後斷開連接，請先檢查瀏覽器和 CODE 之間的 WebSocket 連線。如果出現可重複的 600 秒斷開連接的情況，則更有可能是反向代理、入口控制器、負載平衡器或防火牆逾時導致的，而不是 CODE 文件中記錄的預設空閒計時器導致的。

這種區別至關重要，因為先更改 CODE 本身的空閒設定可能會掩蓋真正的問題，而沒有修復承載編輯流量的連線。目前的 Collabora 配置範本記錄的是每次檢視 15 分鐘的空閒逾時時間和每份 1 小時的空閒逾時時間，而不是 10 分鐘的編輯會話限制。請參閱上游coolwsd.xml 範本。如果使用者在斷開連線時正在積極輸入，那麼僅針對空閒狀態的 CODE 設定就更難以解釋問題所在。

10分鐘斷線通常意味著什麼

已驗證： Collabora 發布的 Nginx 範例使用了 WebSocket 升級標頭，並且proxy_read_timeout 36000s主 WebSocket 連線為 long 類型。 Nginx 文件中明確指出，如果在配置的讀取逾時時間內未收到任何數據，代理的 WebSocket 連線將關閉，其預設proxy_read_timeout值為 60 秒。請參閱Collabora Online SDK 手冊和Nginx WebSocket 代理文件。

環境相關：即使 CODE 前端的 Nginx 主機看起來配置正確，不同的代理層也可能引入 600 秒的逾時。常見位置包括 Kubernetes Ingress、HAProxy、雲端負載平衡器、WAF 或上游反向代理。具體的超時時間和配置項取決於該組件。

僅憑症狀無法得出結論：「10 分鐘後斷開連接」並不能證明 Nginx 是導致問題的組件。在一次性更改多個層之前，請捕獲失敗的 WebSocket 連接，並將其時間戳與代理和程式碼日誌進行關聯。

操作：開啟瀏覽器開發者工具重現故障，並記錄 WebSocket 要求的確切生命週期。

瀏覽器開發者工具的網路面板已篩選出 WebSocket 流量，顯示 WebSocket 編輯操作在約 10 分鐘後失敗。 — 使用瀏覽器的網頁面板檢查編輯 WebSocket 連線是否在可重複的時間點結束。這只是一個範例診斷視圖，並非實際生產環境中的會話記錄。

步驟 1：確認 WebSocket 連線確實終止了。

開啟一個文檔，然後開啟瀏覽器的開發者工具，切換到「網頁」面板。篩選 WebSocket 流量。程式碼編輯流量通常包含路徑下的 WebSocket 連線/cool/。在故障點之後，保持文件開啟狀態。

當會話斷開時，檢查 WebSocket 請求。最有用的資訊包括其持續時間、關閉時間、初始升級期間的 HTTP 狀態以及瀏覽器是否報告網路錯誤。如果初始連線正常，但101 Switching Protocols在大約 600 秒後關閉，則表示連線生命週期或不活動策略可能在某個環節有問題。

如果 WebSocket 始終無法成功升級，這不是「10 分鐘逾時」的問題；請先修復 WebSocket 路由和標頭。如果編輯器顯示儲存或儲存錯誤時 WebSocket 連接保持連接，則應檢查 WOPI/儲存路徑。

操作：記下開始時間和斷開連線時間，然後將這些時間戳記與反向代理存取/錯誤日誌和 CODE 容器或服務日誌進行比較。

步驟 2：在變更 CODE 空閒值之前，請檢查 CODE 反向代理規則。

對 Nginx 來說，關鍵在於 WebSocket 位址必須傳遞升級標頭，讀取逾時時間要夠長。 Collabora 的 SDK 手冊展示了主 WebSocket 的這種配置模式：

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

如果 TLS 在 Nginx 終止，而 CODE 有意在其後提供純 HTTP 服務，則上游協定可能http://有所不同。請勿盲目複製協定：它必須與您的 CODE 實例的配置方式相符。

一個常見的誤解是，`--except` 參數proxy_connect_timeout控制著已建立編輯會話的生命週期。事實並非如此；它僅在建立與上游伺服器的連接時生效。對於已建立的代理 WebSocket 連接，如果存在一段時間內沒有上游資料的情況，則最直接相關的設定是 `--except` 參數。 Nginx 在其HTTP 代理模組參考文件proxy_read_timeout中記錄了這種行為。

操作：找到與程式碼 WebSocket URL 相符的實際 Nginx 程式碼區塊，並確認逾時設定在那裡，而不僅僅是在不相關的程式碼區塊中location。

程式碼編輯器高亮顯示了一個 Nginx 伺服器區塊，其中包含 WebSocket 升級標頭和一個較長的代理程式讀取逾時。 — 將較長的超時時間設定在實際處理 CODE WebSocket 流量的規則上。上游協定和路徑必須與您的部署完全相符。

步驟 3：考慮 CODE 26.04 代理變更

截至 2026 年 10 月，Collabora 最新發布的 CODE 26.04 版本說明中列出了 CODE 26.04.4.2，該版本於 2026 年 9 月 24 日發布。 26.04 系列引入了更簡潔的 WebSocket URL。 Collabora 指出，現有的代理配置可能需要更新；在後續的 26.04 版本中，如果代理未更新，CODE 可能會回退到舊版 URL 並發出稽核警告。 26.04 版本發佈時，已特別告知 Apache2 使用者更新其 ProxyPass 規則。請參閱官方的CODE 26.04 版本說明。

這並不意味著每次 10 分鐘的斷線都是由 URL 縮減引起的。而是說，在 26.04 版本中，您應該對照您實際運行版本的文件檢查您的反向代理規則，尤其是在升級後出現問題的情況下。

操作：請在產品「關於」資訊或容器鏡像標籤中查看您的 CODE 版本，然後將您的代理程式配置與目前的 Collabora 代理指南進行比較。請勿想當然地認為從舊的 24.04 版本部署複製的規則仍然適用。

步驟 4：檢查 Kubernetes Ingress、HAProxy、Apache 和其他中間件

如果 Nginx 只是 CODE 前端的一層，那麼延長其逾時時間可能不夠。對於使用 ingress-nginx 的 Kubernetes，該專案文件中提供了名為 `@Ingress-Nginx`nginx.ingress.kubernetes.io/proxy-read-timeout和`@WebSocket-Nginx` 的 Ingress 註解nginx.ingress.kubernetes.io/proxy-send-timeout。其 WebSocket 指南建議，對於長時間連接的連接，逾時時間應大於一小時。請參閱官方的Ingress-Nginx 註解參考文件和WebSocket 說明。

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

對於 HAProxy，Collabora 的 SDK 範例對 WebSocket 類型的流量使用了較長的隧道逾時時間。對於 Apache，通用的代理程式逾時時間由 `mod_proxy` 控制ProxyTimeout，但 CODE 26.04 也要求專注於目前的 WebSocket ProxyPass 模式。 Apache 的 ` mod_proxy` 文件解釋了哪些ProxyTimeout內容控制著逾時時間。

操作：繪製從瀏覽器到程式碼的連線路徑，並檢查每一跳。即使單次連線時間超過 600 秒，也可能導致會話終止。

步驟 5：安全地驗證並重新載入代理程式。

編輯完 Nginx 設定後，請在重新載入之前進行測試：

sudo nginx -t
sudo systemctl reload nginx

如果 Nginx 運行在容器中，請使用等效的容器感知驗證和重新載入流程，而不是假設配置systemctl已存在。關鍵在於替換運行配置之前驗證語法。

操作：一次更改一層，記錄先前的值，驗證配置，然後重新測試相同的文件工作流程。

終端機視窗顯示 nginx 設定語法驗證，隨後成功執行了 nginx 重載指令。 — 在重新載入反向代理配置之前，請先驗證其配置，以免逾時修復引入新的可用性問題。

步驟 6：用比原截止時間更長的測試來驗證修復效果

文件重新開啟後不要停止測試。保持同一編輯會話連接，並持續一段時間，遠遠超出之前的故障點。對於持續 10 分鐘的症狀，20 到 30 分鐘的驗證視窗比 2 分鐘的冒煙測試更有用。保持“網頁”面板打開，並偶爾進行編輯，以便區分活躍編輯狀態和完全空閒的選項卡。

一個好的結果有三個標誌：WebSocket 連線保持超過 10 分鐘，編輯器繼續接受編輯而無需重新連接提示，並且在中間件或 CODE 日誌中沒有出現相應的逾時。

如果將最近的代理超時時間增加 10 分鐘後連接仍然關閉，這可以作為另一跳仍然具有 600 秒策略的有力證據。

操作：繼續向外追踪，直到找到發出關閉或逾時訊號的組件。

瀏覽器開發者工具的網路面板顯示，WebSocket 連線狀態為 101，12 分鐘後仍保持連線狀態。 — 更改後，請驗證 WebSocket 連線是否能保持超過先前的 10 分鐘截止時間；此處顯示的持續時間僅供參考。

不要將 CODE 的空閒計時器與 10 分鐘的網路斷開混淆。

上游 CODE 配置範本目前記錄的per_view.idle_timeout_secs值為 900 秒，即 15 分鐘。其描述指出，當使用者不活動時，視圖會變暗，更新也會停止。文件等級的idle_timeout_secs預設值為 3600 秒，即 1 小時，之後才會卸載閒置文件。

這些值值得檢查，看看你的行為是否符合它們，但這兩個預設值都無法解釋精確的 600 秒斷線現象。如果之前有人自訂過coolwsd.xml環境變數、Helm 值或容器參數，那麼你的部署可能與預設值有所不同。

操作：僅在確定故障是網路層級還是應用程式層級之後，才檢查有效的 CODE 配置。不要先增加所有空閒值。

快速診斷表

觀察到的行為	接下來最有用的檢查	不要想當然
在使用者活動期間，WebSocket 連線大約會在 600 秒後關閉。	代理、入口、負載平衡器或防火牆逾時	程式碼內建了10分鐘的編輯時間限制。
WebSocket 永遠不會到達 HTTP 101 狀態碼。	升級標頭、路由、TLS 上游方案、目前 26.04 代理路徑	單單增加暫停次數就能有所幫助。
升級到 CODE 26.04 後發生故障。	將代理規則與目前的 26.04 指南進行比較。	舊的 24.04 代理配置自動等效
僅影響空閒/後台標籤頁	程式碼按視圖空閒行為加上中間空閒逾時	活動會話故障和空閒會話故障的原因相同
WebSocket 連線保持開啟狀態，但儲存失敗。	WOPI/儲存日誌和保存請求	WebSocket 超時是根本原因

結論

對於一個在 10 分鐘後可重複斷開連接的 CODE 編輯會話，最有效的處理步驟是：確認 WebSocket 連接失敗，驗證匹配的反向代理規則，檢查每個中間環節的超時情況，考慮 CODE 26.04 的代理路徑變更，安全地重新加載，並在超過之前的截止時間後進行測試。只有當觀察到的行為和實際配置都指向需要更改時，才更改 CODE 的空閒設定。

如果故障時間無法重現，或 CODE 日誌同時顯示崩潰、進程終止、記憶體壓力或 WOPI 錯誤，則不要再將其視為簡單的逾時問題。這些症狀需要不同的診斷。