修正 Nextcloud 中 ONLYOFFICE 的「文件無法儲存」錯誤

您在 Nextcloud 中開啟一個 DOCX 文件，ONLYOFFICE 正常加載，您進行修改後，編輯器卻提示「文件無法儲存」。您很容易會認為瀏覽器遺失了文件，或者 ONLYOFFICE 本身無法寫入磁碟。但在 Nextcloud 整合中，這通常並不是解決問題的正確方向。

關鍵在於保存機制。 Nextcloud 會提供 ONLYOFFICE Docs 文件 URL 和文件路徑callbackUrl。 ONLYOFFICE 下載文件，建立編輯會話，然後回調 Nextcloud，以便 Nextcloud 取得更新後的文件並替換已儲存的版本。 ONLYOFFICE 官方整合文件對此回調機制進行了詳細說明。這表示即使用於儲存的返迴路徑發生故障，編輯器仍然可以成功開啟。解決方法：將開啟和儲存操作視為兩個獨立的網路測試。

首先要看已驗證的行為，而不是錯誤文字。

根據目前的官方整合文檔，ONLYOFFICE 的 Nextcloud 連接器採用伺服器到伺服器的工作流程：文檔伺服器必須可從 Nextcloud 訪問，Nextcloud 也必須可從文檔伺服器存取。編輯完成後，ONLYOFFICE 會向回調 URL 傳送 POST 請求；Nextcloud 隨後會下載編輯後的文件並取代先前的版本。請參閱ONLYOFFICE Nextcloud 整合官方指南和ONLYOFFICE API 中關於 Nextcloud 整合的說明。

已驗證：即使編輯器已打開，錯誤的或無法存取的回呼路徑也可能導致保存失敗。 ONLYOFFICE 的故障排除文件明確指示管理員檢查 DocService 日誌，並在發生儲存錯誤時驗證回呼 URL 是否可存取。操作：不要先重新安裝編輯器或清除瀏覽器快取；請先測試伺服器到伺服器的路徑。

1. 運行連接器的內建連接檢查

在 Nextcloud 主機上，以 Web 伺服器使用者身分執行 ONLYOFFICE 連接器檢查。在典型的 Debian 或 Ubuntu 系統上：

cd /var/www/nextcloud
sudo -E -u www-data php occ onlyoffice:documentserver --check

Nextcloud 的具體路徑和 HTTP 使用者可能會因發行版或容器佈局而異。 Nextcloud 官方管理手冊建議occ以 HTTP 使用者身分執行，以確保檔案所有權的一致性。 ONLYOFFICE 文件occ onlyoffice:documentserver --check用作連接器連接測試。

這可以證明：它可以揭示明顯的文檔伺服器配置或連接錯誤。但它不能證明：在實際編輯會話期間產生的每個回調都能成功通過所有代理、DNS 路由和身份驗證層。操作：如果檢查通過但保存仍然失敗，則繼續執行回呼並記錄日誌，而不是聲明整合正常。

2. 驗證公用伺服器和內部伺服器位址

在 Nextcloud 中，開啟「設定」→「管理」→「ONLYOFFICE」。 ONLYOFFICE 文件主位址必須可供相關客戶端和服務使用。如果因為 Docker 網路、NAT、分離式 DNS 或防火牆策略等原因導致公用 URL 無法在內部路由，請展開進階伺服器設定。

官方連接器針對這種情況提供了單獨的內部位址：

• ONLYOFFICE Docs 伺服器內部請求位址：Nextcloud 用於存取 ONLYOFFICE 的位址。
• ONLYOFFICE Docs 內部請求的伺服器位址：ONLYOFFICE 用於存取 Nextcloud 以進行回調和相關伺服器間通訊的位址。

例如，同一 Compose 網路上的兩個容器可能可以在內部使用服務名稱，而瀏覽器仍然使用公共 HTTPS 主機名稱。不要盲目複製這種模式：這些名稱必須能夠在您的網路中實際解析。操作：從發起請求的機器或容器測試每個方向的請求。

一個常見的誤解：“編輯器可以打開，所以 DNS 和路由都沒問題”

這個結論並不可靠。瀏覽器、Nextcloud 和 ONLYOFFICE Docs 是三個不同的網路參與者。瀏覽器可能可以存取到某個位址，office.example.com但文件伺服器容器可能無法解析或連接到該cloud.example.com位址。同樣，Nextcloud 可能透過內部主機名稱存取 ONLYOFFICE，但回呼指向的卻是無法存取的公共位址。

操作：進入 ONLYOFFICE 容器或主機，並測試其預期使用的 Nextcloud 位址。向 Nextcloud 主機發送基本的 HTTPS 請求可以確認 DNS/TCP/TLS 可達性，但請注意，status.php請求成功並不代表真正的回呼授權或 POST 處理已驗證。

3. 更改代理規則前請檢查 JWT

JWT 是另一個經常造成混淆​​的地方。從 ONLYOFFICE Docs 7.2 開始，JWT 預設啟用，並會自動產生一個金鑰。官方說明要求文件伺服器和 Nextcloud ONLYOFFICE 連接器使用相同的金鑰。目前的連接器文件還提供了未使用預設授權標頭的安裝的授權標頭設定。

已驗證：共用金鑰必須匹配。部署方式不同：管理金鑰的具體位置取決於 ONLYOFFICE 是透過軟體包安裝、在 Windows 系統上安裝還是在 Docker 容器中安裝。在 Docker 部署中，JWT_SECRET通常使用環境變數；也可以在 [此處應填寫伺服器設定資訊] 查看有效的伺服器設定/etc/onlyoffice/documentserver/local.json。

操作步驟：比較雙方的有效金鑰和標頭設置，然後在伺服器端變更後重新啟動 ONLYOFFICE 服務或容器。切勿透過永久停用 JWT 來「修復」問題；這樣做會移除安全控制，而不是修正配置。詳細資訊請參閱ONLYOFFICE 的 JWT 配置指南。

4. 檢查 ONLYOFFICE 和 Nextcloud 在儲存失敗時的日誌

ONLYOFFICE 建議檢查 DocService 日誌以尋找儲存錯誤。對於 Linux 和 Docker 安裝，文件伺服器日誌位於` / etc/var/log/onlyoffice/documentserver / docservice docker logs -f <container>...DS_LOG_LEVEL=DEBUG

在 Nextcloud 中，預設的基於檔案的日誌通常nextcloud.log位於已配置的資料目錄中。您可以使用以下命令尋找活動路徑：

sudo -E -u www-data php occ log:file

Nextcloud 也提供了日誌讀取器應用的文件log:tail和可用時間。操作步驟：重現一次保存失敗，記下時間戳，然後比較雙方的情況。網路拒絕、TLS 錯誤、401/403 回應、5xx 回應或儲存異常都指向截然不同的修復方法。log:watch

5. 在不削弱生產安全性的前提下，修復 TLS 和反向代理問題

自簽章或私下核發的憑證在對應的憑證授權單位 (CA) 不受信任時，可能會破壞伺服器間的 HTTPS 連線。連接器提供了一個「停用憑證驗證（不安全）」選項，但 ONLYOFFICE 明確指出該選項不安全，並建議將其替換為由受信任的 CA 頒發的憑證。操作：僅在受控環境中將繞過憑證驗證作為簡短的診斷步驟；持久的解決方案是使用雙方伺服器都信任的有效憑證鏈。

如果 ONLYOFFICE 前端部署了反向代理，請確認其能夠維持預期的協定、主機和升級行為。 ONLYOFFICE 發布了專門的反向代理設定指南，包括轉發的標頭和 WebSocket 相關設定。請參閱ONLYOFFICE 的 Nextcloud 反向代理程式配置指南。

部署方式不同：僅憑保存錯誤無法推斷出特定的 Nginx、Apache、Traefik、HAProxy、ingress-controller 或 CDN 配置。建議：將您的代理程式配置與供應商提供的範例配置進行比較，並檢查回呼期間記錄的 HTTP 狀態，然後再隨意變更逾時或標頭。

6. 如果回呼到達 Nextcloud，檢查儲存和寫入失敗狀況

一旦日誌證明回調成功到達 Nextcloud，就繼續向下檢查堆疊。 Nextcloud 必須能夠檢索新文件並取代已儲存的版本。本機檔案系統權限、唯讀掛載、磁碟空間耗盡、配額限制、外部儲存不可用或應用程式/儲存異常都可能導致最終寫入失敗。

已知資訊： ONLYOFFICE 的回呼狀態值用於區分可儲存的文件和儲存錯誤，回呼中包含一個指向已編輯文件的 URL，以供儲存服務檢索。官方回呼處理程序文件將狀態 2 定義為可保存，狀態 3 定義為保存錯誤。

光是瀏覽器訊息無法得知：故障究竟發生在 ONLYOFFICE、網路路徑、Nextcloud 還是底層儲存。操作：不要僅僅因為編輯器提示無法保存就遞歸地更改 Nextcloud 資料目錄中的檔案所有權。請先在 Nextcloud 日誌中確認是否有儲存端錯誤。

7. 了解「儲存」按鈕和強制儲存行為

另一個誤解是，每次點擊「儲存」按鈕都會立即替換 Nextcloud 儲存的檔案。連接器可以使用中間儲存或強制儲存選項。官方整合指南指出，啟用「編輯時保留中間版本（強制儲存）」後，點擊「儲存」按鈕會將變更直接傳送到儲存；否則，變更會保留在編輯器快取中，稍後會執行正常的最終儲存流程。

這對於故障排除至關重要。如果只有強制保存失敗而正常關閉並保存成功，反之亦然，那麼時間戳和回調狀態就成了寶貴的證據。操作：在明確定義的流程中重現故障，並擷取該次嘗試的日誌，而不是混合使用手動儲存、關閉瀏覽器和多個並發編輯器標籤頁等操作。

快速診斷表

如何驗證修復效果

在非關鍵資料夾中使用一個小型測試 DOCX 檔案。在 ONLYOFFICE 中開啟它，輸入一行唯一的文字（例如時間戳記），等待編輯器報告變更已儲存，然後正常關閉編輯器。從 Nextcloud 重新開啟該文件，並確認文字存在。接下來，如果您的部署使用了版本歷史記錄，請檢查版本歷史記錄，並查看同一時間段內的伺服器日誌。

然後再次運行連接器檢查：

sudo -E -u www-data php occ onlyoffice:documentserver --check

好的結果不僅僅是“編輯器打開”。完整的測試是：Nextcloud 可以存取 ONLYOFFICE，ONLYOFFICE 可以存取 Nextcloud 上的回呼位址，驗證成功，Nextcloud 可以取得更新後的文件，並且儲存後端接受了替換。

當原因尚不明確時

如果所有日誌均未顯示明顯故障，請在一次受控復現過程中暫時提高 ONLYOFFICE 和 Nextcloud 的日誌級別，然後將日誌等級恢復正常。 Nextcloud 警告稱，DEBUG 日誌等級非常詳細，可能會影響效能，因此應將其作為診斷措施，而非永久的生產環境設定。在變更日誌等級前，請務必查閱Nextcloud 的日誌文件。

此時，請儲存準確的時間戳記、HTTP 狀態碼、連接器版本、Nextcloud 版本、ONLYOFFICE Docs 版本、拓撲結構以及相關的已編輯日誌行。這些資訊遠比瀏覽器顯示的通用「文件無法儲存」訊息更有用。

官方參考資料

• ONLYOFFICE：Nextcloud 整合指南
• ONLYOFFICE Docs API 故障排除
• ONLYOFFICE 回呼處理程序 API
• ONLYOFFICE JWT 配置
• Nextcloud 日誌配置