修正自架 Docker 伺服器上 ONLYOFFICE 協同編輯的延遲問題

如果 ONLYOFFICE 在自架的 Docker 伺服器上協同編輯速度很慢，請不要立即修改未公開的編輯器參數。首先，將問題分解為三個可衡量的方面：伺服器資源壓力、反向代理/WebSocket 行為以及儲存或容器層級的錯誤。協同編輯依賴長時間的即時通信，因此即使伺服器能夠成功開啟文檔，當多人同時輸入時，速度仍然可能會很慢。

本指南通篇使用假設範例：一個小型團隊在 NGINX 後端使用 Docker 執行 ONLYOFFICE Docs。一兩個使用者可以正常編輯，但當六個人同時開啟同一個文件時，遊標更新會延遲，其他使用者的變更也會在明顯停頓後才顯示。此範例僅用於教學，並非實際部署的基準測試或報告。

截至 2026 年 10 月，ONLYOFFICE Docs 9.4 是官方更新日誌中列出的最新版本。 9.4 版本也更改了社群版架構，移除了對 RabbitMQ 和資料庫的依賴，因此針對舊版所寫的建議可能不再適用於目前的社群版環境。在從舊論壇貼文複製優化建議之前，請務必確認您安裝的版本。

1. 在更改任何內容之前，請先測量延遲。

ONLYOFFICE 文檔，其中包含多個協作指示器，顯示多人正在編輯同一個專案計畫文件。 — 範例：在同一文件中讓多個使用者重現延遲，以便您可以比較每次變更前後的行為。

假設出現這種情況，第一個錯誤的做法是隨意重啟服務，然後寄望於延遲消失。正確的做法是建立一個可重複的測試。使用多個瀏覽器會話或測試帳戶開啟同一個文檔，進行簡短的編輯，並記錄哪些操作出現延遲：本地螢幕上的按鍵操作、遠端遊標移動、其他使用者的文字顯示、儲存狀態，還是文檔的初始載入。

這些症狀指向不同的瓶頸。如果編輯器在本機瀏覽器上卡死，可能是用戶端 CPU 過載或文件過於複雜。如果本機輸入即時生效，但遠端編輯延遲，請檢查網路路徑和 WebSocket 會話。如果開啟的文件越多，所有操作速度越慢，請檢查伺服器的 CPU、記憶體、交換空間和磁碟 I/O。

ONLYOFFICE 在官方 Docker 安裝指南中描述了其 Docker 部署和基本要求。對於 Docker Compose，請遵循官方 Docker Compose 說明。

2. 在使用者編輯時檢查 CPU 和記憶體壓力

Ubuntu 終端機執行 docker stats 指令，顯示文件伺服器容器及相關服務的 CPU、記憶體和網路使用情況 — 在實際的低谷期運行`docker stats`；在無人編輯時拍攝的快照可能會掩蓋瓶頸。

在 Docker 主機上運行：

docker stats

在測試群組編輯文件伺服器容器時，請對其進行監控。同時，使用以下工具檢查主機資源：

free -h
uptime
vmstat 1
df -h

ONLYOFFICE 官方的 Docker 要求明確指出，文件中列出的配置至少需要 4 GB 記憶體和 40 GB 可用磁碟空間，並且還有交換空間要求。企業指南也明確指出，容量取決於並發活躍使用者數量以及文件的數量、類型和大小。這些數值是基準值，並非保證 4 GB 記憶體就能為所有工作負載提供流暢的協作體驗。

在我們的範例中，假設docker stats當六個人同時輸入時，文件伺服器容器會重複佔用大部分可用 CPU 資源。這有力地證明了：添加代理超時並不會增加 CPU 使用量。下一步是移除過於嚴格的 Docker CPU 限制、將容器遷移到更快的宿主機，或降低並發工作負載。相反，如果 CPU 使用量仍然不高，則在購買硬體之前應繼續進行調查。

已發布的容量指南的官方參考資料是ONLYOFFICE Docs Docker 系統要求。

3. 檢查磁碟空間、掛載點和檔案快取

Ubuntu 終端機顯示 df -h 輸出以及 ONLYOFFICE 資料和日誌目錄的 Docker 掛載映射 — 在指責編輯器或網路之前，請先驗證可用空間以及容器的日誌和檔案快取的實際位置。

ONLYOFFICE 的 Docker 文件列出了持久化儲存位置，包括/var/log/onlyoffice日誌和/var/lib/onlyoffice檔案快取。請檢查支援這些路徑的檔案系統，而不僅僅是主機的根檔案系統。

df -h
docker inspect documentserver --format '{json .Mounts}'

如果綁定掛載指向速度較慢的網路檔案系統或磁碟空間不足，則文件開啟、轉換和快取活動會增加延遲。如果磁碟空間接近飽和，請在進行應用程式調優之前先解決磁碟空間不足的問題。 ONLYOFFICE 的 Linux 故障排除文件明確指出，磁碟空間不足可能是轉換問題的原因之一。

該專案還建議，當需要持久化日誌、快取儲存或外部資料庫/Redis/RabbitMQ 服務時，應將相關資料儲存在容器外部。請參閱官方 Docker 卷指南。

4. 驗證反向代理是否保持即時連接

NGINX 設定編輯器顯示代理 HTTP 1.1、升級和連接標頭、轉送的主機和協定標頭以及長時間讀取逾時。 — 反向代理必須保留 WebSocket 升級路徑和 ONLYOFFICE 期望的原始主機/協定資訊。

許多自架部署方案將 ONLYOFFICE 置於 NGINX、Apache、HAProxy 或 Traefik 之後。 ONLYOFFICE 官方代理文件明確要求轉發諸如 `--password` 和X-Forwarded-Proto`--password`之類的標頭X-Forwarded-Host。 ONLYOFFICE 隨附的配置也支援 HTTP/1.1 和 WebSocket 升級處理。

對於 NGINX，請將您的配置與 ONLYOFFICE 的官方範例進行比較，而不是貼上其他產品的通用 WebSocket 程式碼片段。一個典型的配置模式包括：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Forwarded-Host $the_host;
proxy_set_header X-Forwarded-Proto $the_scheme;

具體配置map指令和代理位置至關重要。請使用供應商提供的完整拓撲範例。支援的設定資訊已發佈在「在代理程式後使用 ONLYOFFICE 文件」中。

假設團隊中的 Docker 主機擁有充足的 CPU 和內存，但瀏覽器卻反覆透過企業級 NGINX 層重新連接協作通道。這表示問題出在代理路徑上，而不是文檔伺服器的運算能力。

5. 在瀏覽器中確認 WebSocket 會話

瀏覽器開發者工具的網路標籤顯示了一個 ONLYOFFICE 文件和一個 HTTP 狀態碼為 101 的 WebSocket 請求。 — 正常的 WebSocket 升級通常表現為狀態碼為 101 的 WebSocket 請求，並且在編輯文件時保持開啟。

開啟瀏覽器開發者工具，選擇「網路」面板，篩選 WebSocket 流量，然後重新載入編輯器。成功的 WebSocket 握手通常會顯示 HTTP 連接101 Switching Protocols，並且連線會保持開啟。不要將長時間處於「待處理」狀態的 WebSocket 連線視為故障；正常的 WebSocket 連線應該保持開啟。

重要的是重複斷開/重新連接的行為、握手失敗、代理錯誤或與協作延遲相關的長時間斷開。如果遠端編輯延遲恰好發生在 WebSocket 重新連接的同時，那麼現在就存在一個具體的網路問題需要解決。

檢查 TLS 終止、代理空閒逾時、負載平衡器規則、WAF 策略以及任何可能無法保留 WebSocket 流量的中間層。如果存在多個代理層，請逐一測試每一個躍點，而不要假設只有公共 NGINX 實例參與其中。

6. 驗證預期的容器和特定版本架構

終端機執行 docker compose ps 指令，並列出 ONLYOFFICE 文件伺服器及其支援容器，狀態為「運行中」。 — 使用`docker compose ps`或`docker ps`來確認您的特定部署所需的服務是否實際運作。

跑步：

docker compose ps
# or
docker ps

不要想當然地認為所有現代 ONLYOFFICE 部署都必須使用相同的 Redis、PostgreSQL 或 RabbitMQ 容器集合。版本差異至關重要。 ONLYOFFICE 指出，從 Docs 9.4 開始，開源社群版已簡化為單一進程架構，並移除了對 RabbitMQ 和資料庫的依賴。企業版、開發者版、舊版社群部署以及自訂 Compose 堆疊的配置可能有所不同。

這意味著一篇 2023 年的故障排除文章中提到的「RabbitMQ 一定是瓶頸所在」可能與目前的社群版實例無關。請確定您實際運行的鏡像和版本：

docker inspect documentserver --format '{.Config.Image}'
docker image ls onlyoffice/documentserver

ONLYOFFICE官方文件的更新日誌顯示，版本編號為 9.4.0，發布日期為 2026 年 5 月 20 日。廠商發布的Docs 9.4 版本公告解釋了社群版架構的變更。

7. 暫時啟用調試日誌記錄並將其與延遲關聯起來

在編輯活動緩慢期間，管理員正在比較容器資源使用情況，此時 Ubuntu 終端機正在執行 ONLYOFFICE 堆疊的 Docker 統計資料。 — 在同一個可複現的慢速期間收集資源資料和日誌，以便關聯時間戳記而不是孤立地檢查時間戳。

ONLYOFFICE 提供了一個文件齊全的 Docker 環境變數用於偵錯日誌記錄。如需進行短暫的故障排除，請新增：

DS_LOG_LEVEL=DEBUG

然後根據您的部署方法重新建立或重新啟動相關容器，並查看日誌：

docker logs -f documentserver
# Docker Compose:
docker compose logs -f documentserver

官方文件指出，Docker 日誌也可在/var/log/onlyoffice/documentserver容器內部查看，如果掛載了主機，則也可在對應的主機日誌目錄中查看。當開啟或轉換檔案速度緩慢時，轉換器日誌非常有用；而協作編輯問題則應與文件伺服器日誌以及瀏覽器/網路觀察結果進行關聯分析。

收集所需資訊後，請關閉 DEBUG 日誌記錄。詳細日誌記錄僅用於診斷，非永久性效能設定。請依照ONLYOFFICE Docs 中「啟用偵錯日誌記錄」的供應商步驟進行操作。

8. 如果您使用的是舊版鏡像，請謹慎更新。

NGINX 配置編輯器顯示了 ONLYOFFICE 文件伺服器的轉送標頭和代理設定 — 升級前，請保留您已知的良好代理和整合設定；升級後，請重新測試完全相同的協同編輯場景。

如果部署版本嚴重落後於支援的版本線，更新可以包含錯誤修復和架構改進。但是，對於生產環境的協作伺服器而言，「拉取最新版本並重新啟動」並非提升效能的安全方法。

首先記錄目前鏡像標籤、compose 檔案、JWT 設定、掛載磁碟區、反向代理配置和整合配置。如果您的變更流程需要可重複性，請使用固定版本。 ONLYOFFICE 的 Docker 安裝指南詳細說明如何指定特定版本，官方變更日誌則列出了變更內容。

在有意停止繁忙的生產文件伺服器之前，請務必遵循 ONLYOFFICE 針對您的版本和部署環境提供的關機指南，以確保安全地處理正在進行的編輯會話。請勿使用包含未儲存使用者工作的基準文件作為升級測試。

假設案例如何縮小真正解決方案的範圍

回到由六位共同編輯組成的範例團隊。故障排除結果取決於您的觀察結果：

觀察	最有用的下一步行動
隨著更多編輯人員加入，文件伺服器 CPU 使用率達到飽和。	移除不合適的 CPU 限製或增加運算能力；代理調優無法解決 CPU 資源不足的問題。
記憶體耗盡，主機頻繁進行交換。	增加記憶體或減少工作負載；檢查容器限制和並發開啟的文件數量。
磁碟空間接近飽和，或快取/日誌磁碟區位於速度較慢的儲存裝置上。	在進行應用程式調優之前，請釋放空間或將工作負載遷移到適當的本機儲存。
WebSocket 反覆斷開連接，而 CPU 佔用率仍然很低	修復反向代理/負載平衡器路徑，並將其與 ONLYOFFICE 的官方代理範例進行比較。
只有大型的舊文件開啟速度才會很慢。	檢查轉換日誌、磁碟效能和文件複雜性，而不是假設協同編輯本身有問題。
問題出現在版本或代理程式變更之後。	如果您的回滾計畫允許，請將變更後的鏡像/配置與先前已知的良好配置進行比較並重新測試。

Docker部署的實用基準

對於小型自架部署，請從 ONLYOFFICE 公佈的最低配置開始，但請根據實際並發活動量而非註冊用戶總數來調整配置。將持久性日誌和快取保存在延遲可預測的儲存裝置上。除非您已測量過工作負載，否則請避免設定過高的 CPU 或記憶體限制。確保 Docker 主機在正常編輯負載下不會進行交換。

將 ONLYOFFICE 部署在基於供應商支援範例的反向代理程式配置之後，以保留 WebSocket 升級和轉送的主機/協定標頭。在實際協同編輯期間監控伺服器，而不僅僅是在空閒時。如果需要更深入的證據，請暫時啟用 DEBUG 日誌記錄，並將日誌時間戳與瀏覽器 WebSocket 行為和主機指標進行關聯。

不該做什麼

不要local.json因為論壇帖子稱其為“性能調整”就更改未記錄的值。
不要認為顯示為「pending」的持久性 WebSocket 連線已損壞；長時間存在的 WebSocket 連線是正常的。
不要因為舊的部署架構圖中使用了 Redis、RabbitMQ 或 PostgreSQL 就添加它們。請先檢查您的版本和架構。
不要為了降低延遲而停用 TLS 驗證、JWT 安全性或代理保護。
不要將空閒伺服器指標與使用者實際報告延遲的時間段進行比較。
升級生產實例時，請務必保留磁碟區、配置和回滾路徑。

結論

ONLYOFFICE 協同編輯延遲問題，最容易解決的方法是將其視為一個可衡量的系統問題。重現延遲，觀察 Docker 和主機資源在負載下的狀態，檢查儲存情況，確認瀏覽器透過每個代理程式保持正常的 WebSocket 連接，並僅檢查延遲發生時間段內的日誌。一旦確定瓶頸是計算、記憶體、磁碟、網路/代理行為，還是特定版本/配置更改，修復就變成了有針對性的，而不是推測性的。

有關目前部署詳情，請使用ONLYOFFICE Docker 安裝文件、官方反向代理範例、偵錯日誌指南和官方文件變更日誌。