How to Fix Collabora Online High CPU Usage from loolwsd / coolwsd

When Collabora Online suddenly uses most of a server's CPU, the most important first step is not to restart it repeatedly or immediately impose a very low CPU limit. First determine whether the load comes from normal document work, one pathological document session, too much parallel work, an idle session that is not being cleaned up, or a version-specific regression. The process name may be coolwsd on current releases and loolwsd on older installations.

Illustrative scenario: imagine an 8-vCPU server running Collabora Online behind Nextcloud. Only a few people appear to be editing documents, but the Collabora container sits around 250% to 350% CPU for several minutes. This is a hypothetical example used throughout this guide, not a measured benchmark or a report from a real deployment.

As of October 2026, Collabora's current stable branch is 26.04, and the official release notes list Collabora Online 26.04.3.3 as released on September 14, 2026. Current configuration templates use the coolwsd name. Collabora's migration tooling still documents the older /etc/loolwsd/loolwsd.xml path for installations from the 6.4 era or earlier, which is why administrators may still encounter both names.

1. Confirm which process is actually consuming CPU

Start at the operating-system or container level. A high number beside coolwsd does not automatically mean the coordinating daemon itself is doing all of the expensive document work. Collabora also runs kit/forkit processes for document sessions, so you want the process tree and per-process CPU usage before changing configuration.

ps -eo pid,ppid,pcpu,pmem,etime,cmd --sort=-pcpu | head -n 25
top -H -p $(pgrep -d, -f 'coolwsd|loolwsd|coolkit|loolkit|forkit')

For Docker, also check the container as a whole:

docker stats --no-stream

Linux 系統頂部視圖顯示一個繁忙的 Collabora coolwsd 進程和幾個佔用 CPU 的工具包進程。 — A process-level view helps separate the main Collabora daemon from document-related kit processes before any tuning is attempted.

Docker 統計資料顯示，Collabora 容器使用的 CPU 比相鄰服務多得多。 — Container-level CPU is useful for confirming that Collabora is the source of host load, but it does not identify the document or child process responsible.

In the illustrative scenario, suppose the container is near 300% CPU and one kit process is consistently at the top of the process list. That points you toward a specific active document session rather than a generic assumption that the entire server is overloaded.

2. Check Collabora's own metrics instead of relying only on top

Collabora Online exposes Prometheus-compatible metrics at /cool/getMetrics. The current SDK manual says this endpoint can report CPU and memory use, running kit processes, views, and other server-usage data. It uses the same authentication as the admin console unless metrics are explicitly configured for unauthenticated access.

不要為了簡化故障排除而公開指標端點。官方 Helm 設定甚至包含了/cool/getMetrics入口處的阻塞和管理 URL 範例。盡可能使用經過身份驗證的內部路徑。

瀏覽器顯示 Collabora Online 的 getMetrics 端點，其中包含流程和文件指標。 — Collabora 指標端點提供伺服器端上下文，可補充 Linux 或 Docker CPU 測量。

查看 CPU 使用率與活動文件或視圖之間的關係。如果 CPU 使用率隨著正常的編輯活動而波動，則可能存在容量或併發問題。如果 CPU 使用率在沒有相應互動操作的情況下持續高位運行，則應檢查是否有過期會話、問題文件、重複的後台任務或軟體問題。

3. 查看 CPU 峰值上升前後一段時間的日誌。

對於由 systemd 管理的軟體包安裝：

journalctl -u coolwsd --since "15 minutes ago" --no-pager
journalctl -u coolwsd -f

對於 Docker：

docker logs collabora --since 15m
docker logs -f collabora

如果您的服務或容器名稱不同，請替換為正確的名稱。檢查是否有重複的文件載入、重複的工具包建立、儲存失敗、當機、重連迴圈或相同的文件鍵反覆出現等情況。文件開啟、重新計算、渲染、轉換或匯出期間短暫的 CPU 使用率升高可能是正常的。更嚴重的警訊是 CPU 使用率持續升高但沒有任何實際進展或重複出現相同的故障。

Collabora 容器日誌視圖，顯示工具包建立、文件活動、自動保存條目和 CPU 使用率過高警告 — 將日誌與 CPU 峰值出現的時間進行關聯，以便區分正常的文件活動和重複或卡住的工作。

4. 每次處理一個文檔，重現峰值

返回假設的伺服器。如果某個工具包進程佔用大量資源，請關閉或隔離可疑文檔，並觀察 CPU 使用率是否下降。然後在伺服器空閒時開啟同一個文件，同時監控進程清單和相關指標。使用一個簡單的測試文件重複上述步驟。

這種比較方法比立即重啟整個服務更有意義：

如果只有一個檔案能夠可靠地觸發峰值，那麼該檔案的內容、公式、嵌入物件、渲染工作負載或特定於文件的錯誤更有可能是罪魁禍首。
如果多個使用者同時上線時，每個檔案都會導致類似的資源飽和，請檢查伺服器容量和並發性。
如果所有使用者活動停止後 CPU 使用率仍然很高，請專注於檢查清理工作、過期工具包、重複的後台任務或回歸問題。
如果問題是在升級後立即出現的，請在更改其他許多變數之前記錄舊版本和新版本。

5. 當單一文件可以獨佔多個核心時，降低每個文件的並發量。

目前的 Collabora 配置範本規定了per_document.max_concurrency處理文件時使用的最大線程數。模板預設值為 4。在配置較低的主機上，或單一複雜文件佔用大量資源時，降低此值可以使 CPU 使用率更可預測。

例如，您可以測試值 2：

<per_document>
    <max_concurrency>2</max_concurrency>
</per_document>

coolwsd.xml 編輯器高亮顯示 per_document max_concurrency 設定為 2 — 降低每個文件的並發性是一種權衡：它可以減少單一文件對 CPU 的使用頻率，但繁重的操作可能需要更長時間。

不要盲目地將數值設為 2。如果使用者經常處理大型電子表格或簡報，且伺服器擁有充足的 CPU 核心，那麼較低的數值反而可能導致運作速度變慢。請先更改一項設置，然後重複相同的工作負載，並比較 CPU 使用率、反應速度和完成時間。

6. 在啟用清理和空閒會話設定之前，請先驗證這些設定是否有效。

目前coolwsd.xml範本包含針對佔用資源的空閒文件的清理邏輯。截至撰寫本文時，此範本的清理檢查間隔為 10,000 毫秒，異常行為持續時間為 60 秒，空閒閾值為 300 秒，CPU 使用率閾值為 85%（文件達到該閾值後將被標記為需要清理）。此外，此範本還為每個文件設定了 3,600 秒的空閒逾時時間。

此範本包含針對每個視圖的逾時設定。目前值顯示，失去焦點的瀏覽器視圖在 300 秒後會變暗並停止更新，而不活動的視圖在 900 秒後會採取類似處理。這些視圖逾時設定與立即卸載整個文件會話不同。

coolwsd.xml 編輯器顯示了清理 CPU 閾值以及每個視圖的失焦和空閒逾時設置 — 清理和視圖空閒控制可以減少浪費的工作，但應該謹慎調整，以免干擾正常的長時間編輯會話。

避免為了讓圖表看起來更好而將 CPU 閾值設定得太低。清理的目的是捕獲消耗資源的無效或閒置文檔，而不是在計算量過大時終止正常的編輯操作。

7. 僅在儲存受控配置變更後才重新啟動

請先備份當前配置。軟體包安裝通常使用/etc/coolwsd/coolwsd.xmlDocker。 Docker 部署可能會將選項作為環境變數或命令列參數傳遞，或將設定檔掛載到容器中。在編輯任何內容之前，請確認目前使用的來源是什麼。

軟體包安裝：

sudo cp /etc/coolwsd/coolwsd.xml /etc/coolwsd/coolwsd.xml.before-cpu-tuning
sudo systemctl restart coolwsd
systemctl status coolwsd --no-pager

對於 Docker 容器：

docker restart collabora
docker ps --filter name=collabora

終端機顯示 coolwsd 重新啟動和 systemd 服務狀態，並附有 Docker 重新啟動指令範例。 — 只有在事先備份的設定變更後才能重新啟動，然後在使用者復原測試之前驗證服務是否運作正常。

如果重新啟動電腦後CPU問題暫時解決，但問題反覆出現，這只能提供診斷訊息，並非永久解決方案。請繼續排查，直到能夠解釋是什麼工作負載或狀態導致了問題再次出現。

8. 在相同工作負荷下，比較前後的變化。

使用相同的文件、大致相同的使用者數量和相同的操作順序。測量時間應持續幾分鐘，而不是僅比較某一瞬間的表現。在範例場景中，成功意味著在重現的工作負載期間，伺服器不再處於飽和狀態，同時文件的開啟、編輯、儲存和協作功能仍然能夠正常運作。

瀏覽器網址列顯示本地 Collabora Online 的 getMetrics 端點 — 每次受控變更後都使用相同的指標端點，以便前後比較基於可比較的伺服器資料。

觀察	可能的下一步行動
一份文件或工具包保持熱度	使用該文件重現問題，保留日誌，並在當前穩定的微版本上進行測試。
CPU追蹤活躍用戶數量	應該審查容量、並發性和部署規模，而不是將負載視為洩漏。
用戶離開後，CPU 使用率仍然很高。	檢查空閒文件、清理行為、重複的後台作業以及孤立的或重新啟動的工具包。
升級後立即開始出現 Spike 問題	在變更大量調優值之前，請記錄確切的版本號，並查看目前的發行說明和已知問題。
降低 max_concurrency 值可以減少 CPU 使用率，但編輯速度會變慢。	逐步增加或增加 CPU 容量；此設定是一種權衡，並非萬能的解決方案。

什麼時候應該進行系統升級而不是簡單的調優？

如果該問題始於某個特定的 Collabora 版本，而您可以使用特定檔案或操作重現該問題，則設定調整可能只是掩蓋了軟體缺陷。 Collabora 建議使用目前穩定分支中的最新版本。截至 2026 年 10 月 7 日，官方 26.04 版本說明頁面列出的最新 Collabora Online 版本為 26.04.3.3。

對於 CODE 用戶，請記住 Collabora 將開發版描述為適用於小型團隊、家庭使用、開發以及嘗試新功能，但並不適用於生產環境。因此，如果 CODE 出現生產環境問題，則應考慮遷移到受支援的 Collabora Online 產品，而不是無休止地調整開發版的行為。

不該做什麼

不要以為coolwsd數值高就一定存在記憶體洩漏或無限循環。
除非確實需要，否則不要在 CPU 事件期間永久啟用偵錯或追蹤日誌記錄；詳細的日誌記錄會增加自身的開銷和儲存壓力。
不要為了方便監控而將管理控制台或指標端點暴露在公共網路上。
在正常活動會話終止之前，請勿降低清理閾值。
請勿將 CPU 配額作為首要診斷步驟。硬性限制雖然可以保護共享主機上的鄰居，但可能會將 CPU 問題轉化為文件渲染緩慢和超時，而無法揭示根本原因。

建議的故障排除順序

確認繁忙的進程是coolwsd舊版本loolwsd進程還是子套件/forkit 進程。
記錄 Docker 或主機 CPU、記憶體、活動文件和視圖數量。
將日誌與確切的峰值視窗進行關聯。
使用一份可疑文件和一份簡單的對照文件重現問題。
per_document.max_concurrency僅當某個文件佔用過多並行 CPU 資源時才進行測試。
檢查清理和空閒設置，但不要設置得太激進。
每次進行受控配置變更後，請重新啟動服務並驗證服務運作狀況。
比較修改前後的相同工作負載，然後檢查目前穩定版本，看看這種行為是否與版本有關。

官方參考資料

本指南中的設定詳情是基於目前的 Collabora Online 來源範本：Collabora Online coolwsd.xml 設定範本。官方 SDK 手冊詳細介紹了日誌記錄、效能控制以及與 Prometheus 相容的指標端點：Collabora Online SDK 手冊。版本檢查請參考廠商發布的Collabora Online 26.04 版本說明。開發版的預期用途請參閱官方CODE 26.04 版本公告。

實際目標並非強迫 Collabora Online 盡可能減少 CPU 使用率，而是讓 CPU 消耗量可解釋且與有效工作量成正比，同時維持可接受的編輯和協作效能。