如何配置 Collabora 編輯會話的空閒逾時時間

Collabora Online 有一些設定聽起來像是“空閒超時”，但它們控制的是不同的行為。如果使用者仍在工作時編輯器變暗或停止更新，請調整每個視圖的非活動設定。如果文件在所有使用者離開後仍然保持載入狀態，請調整每個文件的逾時設定。如果編輯器實際斷開連接，請在變更 Collabora 的空閒策略之前檢查反向代理程式的 WebSocket 逾時設定。

目前的 Collabora Online 設定範本規定，每次瀏覽的空閒逾時時間為 15 分鐘，瀏覽器標籤頁失去焦點時的逾時時間為 5 分鐘，空閒文件卸載前的逾時時間為 1 小時。這些預設值可能會因版本和打包方式而異，因此在進行任何變更之前，請檢查已安裝版本隨附的配置。以下值指的是本指南中使用的目前模板，並不保證適用於所有 CODE 或企業部署。

根據您想要的行為選擇設定。

環境	它控制著什麼	使用它	權衡
`per_view.idle_timeout_secs`	當使用者處於非活動狀態時，即使瀏覽器標籤頁仍保持焦點狀態，也會降低螢幕亮度並停止更新。目前模板預設值：900 秒。	人們需要更長的時間來閱讀、審查或編輯，而無需持續互動。	較長的逾時時間會使空閒視圖保持活動狀態更長時間，並可能佔用更多客戶端和伺服器資源。
`per_view.out_of_focus_timeout_secs`	當瀏覽器標籤頁失去焦點時，降低亮度並停止更新。目前模板預設值：300 秒。	使用者在協作過程中會在文件和其他選項卡之間切換。	較長的逾時時間可以保持後台標籤頁更新；開啟多個文件會消耗更多資源。
`per_document.idle_timeout_secs`	正在卸載已閒置的文件。目前模板預設值：3600 秒。	文件在編輯視圖變為非活動狀態或關閉後，仍長時間保留在記憶體中。	較短的值可以更快地釋放文檔進程，但之後重新開啟可能需要重新載入文件。
`per_document.idlesave_duration_secs`和`autosave_duration_secs`	當修改後的文件在不活動後或按自動儲存計畫儲存時，目前範本預設值為：30 秒和 300 秒。	您正在調整保存頻率或調查保存行為。	這些是保存間隔，而非會話過期設定。更改這些設定不會阻止空閒視圖變暗。
反向代理 WebSocket 超時	代理伺服器會保持瀏覽器 WebSocket 連線開啟多久。	編輯器會在一段時間後斷開連接或發生故障，尤其是在閒置時。	長時間連接需要在每個代理層、負載平衡層和入口層保持相同的限制。

Collabora 在其目前的 coolwsd 配置範本和配置參考文件中記錄了各項的含義和預設值。視圖空閒逾時與關閉帳戶或撤銷存取權限不同：它會使視圖變暗並停止更新。文件逾時會卸載空閒的文件流程；它並非用於終止正在編輯的使用者的計時器。

修改 coolwsd.xml 中的設置

對於基於軟體包的安裝，請尋找coolwsd.xml正在執行的服務所使用的活動檔案。常見位置包括 `/etc/config/services/` /etc/coolwsd/coolwsd.xml，但路徑會因發行版和舊版本而異。請勿假設編輯範例檔案或未使用的已掛載副本會變更正在執行的服務。

備份目前文件，然後僅編輯現有設定項下的相關值<per_view>。<per_document>例如，以下程式碼片段設定了 30 分鐘的非活動用戶逾時、15 分鐘的後台標籤頁逾時以及兩小時的空閒文件卸載：

<per_view>
    <idle_timeout_secs>1800</idle_timeout_secs>
    <out_of_focus_timeout_secs>900</out_of_focus_timeout_secs>
</per_view>
<per_document>
    <idle_timeout_secs>7200</idle_timeout_secs>
</per_document>

這是一個節選，並非完整的替換配置。請保留版本附帶檔案中的屬性、註解、巢狀和其他元素；某些版本需要額外的 XML 屬性。如果您只想變更選項卡保持焦點狀態時的變暗程度，請僅編輯每個視圖的空閒值。同時提高每個視圖的值和文件卸載值會使您難以確定是哪個設定解決了問題。

使用部署支援的設定工具驗證 XML，然後依照該軟體套件文件中所述的方法重新啟動或重新載入 Collabora。查看啟動日誌，尋找設定解析錯誤，並確認執行進程已載入目標檔案。如果活動進程中不存在相應的設定更改，則該更改將無效。

在 Docker 或 Kubernetes 中設定相同的選項

在 Collabora 的 Docker 映像中，管理員通常extra_params使用--o:選項語法傳遞配置選項。以下 Compose 風格的值範例說明了這一點：

extra_params=--o:per_view.idle_timeout_secs=1800 --o:per_view.out_of_focus_timeout_secs=900 --o:per_document.idle_timeout_secs=7200

僅當您的鏡像和部署圖表支援此功能時才使用extra_params。對於 Kubernetes、Helm 或 Operator 管理的安裝，請將選項放在圖表或自訂資源的支援設定欄位中，而不是編輯產生的容器檔案。在 Compose 中變更環境變數時，請重新建立或重新部署服務，以便新值生效；簡單的重新啟動可能會重複使用現有的容器配置。

請勿在衝突位置（例如已掛載的 XML 檔案和環境變數）設定相同的選項，除非您已檢查該版本的優先權規則。重新部署後，請檢查容器啟動日誌和目前配置。如果選項名稱或容器行為有差異，請參考 Collabora 專案的原始程式碼庫和版本相符的部署文件。

單獨檢查反向代理逾時。

Collabora 編輯器使用 WebSocket 進行持續的瀏覽器通訊。即使 Collabora 文件和視圖的逾時時間設定得非常長，代理伺服器仍然可能關閉原本有效的 WebSocket 連線。在這種情況下，使用者可能會看到斷開連接、重新連接提示，或者編輯器停止接收更新，而不是簡單的視圖變暗。

比較代理程式的讀取/發送逾時、任何入口或雲端負載平衡器的空閒逾時，以及 Collabora 預期的會話行為。整個路由上的超時時間必須相容。 Collabora 的代理設定指南包含 WebSocket 代理程式設定和長連線範例。請根據您的特定代理和版本應用相應的指南；不要盲目地將舊的 Nginx 配置區塊複製到不同的代理或不相關的路由。

故障模式是一個有用的線索。如果使用者只看到非活動視圖變暗，請進行檢查per_view。如果所有使用者在大致相同的時間間隔斷開連接，請檢查該時間戳記的代理程式和負載平衡器日誌。如果文件僅在所有參與者離開後才關閉，則文件逾時時間更為重要。

一次只測試一個超時情況

記錄目前活動配置中的值，並記下您的 Collabora 版本和部署方法。
開啟一個測試文檔，使用兩個使用者或兩個瀏覽器會話，以便觀察活動視圖和非活動視圖。
僅更改與症狀相符的超時設定。例如，要防止在焦點已啟動但無任何動作的標籤頁中螢幕變暗，只需調整逾時設定per_view.idle_timeout_secs即可。
透過支援的方法重新啟動或重新部署，然後確認新值出現在活動配置或啟動日誌中。
等待超過之前的閾值。確認視圖是否仍變暗，第二位使用者是否仍收到更新，以及編輯內容是否繼續儲存。
關閉測試文件的所有視圖，並觀察空閒文件是否在預期範圍內卸載。
檢查 Collabora 和代理日誌，查看是否有 WebSocket 關閉、XML 解析錯誤、儲存失敗或意外的進程清理。

請勿在未儲存的生產文件上測試變更。在允許空閒文件進程卸載之前，請確認修改後的文件已儲存到儲存後端。如果問題僅在未儲存的變更中出現，請將自動儲存和儲存錯誤作為單獨的問題進行檢查，而不是延長每次逾時時間。

平衡便利性、資源利用和可靠性

較長的單視圖逾時時間適合需要間歇性查看文件或在多個瀏覽器標籤頁中工作的團隊。較短的超時時間會導致不活躍的視圖更快停止更新，這或許可以減少後台活動，但可能會打斷正在查看文件的讀者。單一文檔逾時時間是另一種資源管理策略：延長逾時時間可以延長未使用文件的載入時間，而縮短逾時時間則可能導致使用者返回時需要重新載入文件。

對於大多數部署，只需更改與觀察到的行為相符的最少設定即可。保持保存間隔不變，為團隊設定合理的每個視圖的非活動窗口，有意設定後台標籤頁超時，並且僅當日誌或計時表明存在連接層問題時才調整代理 WebSocket 限制。升級後請重新檢查已安裝版本的配置模板，因為預設值和支援的設定可能會變更。