將空白的 Collabora 文件追蹤到故障層

首先檢查空白畫面是影響單一文件還是所有文件，然後檢查瀏覽器的網路和控制檯面板，以及 Collabora 和儲存平台的日誌。空白畫布只是一個症狀，而非診斷結果：編輯器可能在文件連接、WOPI 授權或嵌入式資源失敗時載入。

一個文件編輯器，頁面空白，工具列下方顯示載入指示器。 — 症狀範例：編輯器框架出現，但文件畫佈在載入時保持空白。

1. 確定問題是出在文件、瀏覽器或服務上

在同一應用程式中開啟一個已知正常的文檔，然後嘗試在另一個受支援的瀏覽器或隱私視窗中開啟受影響的文件。診斷過程中請勿編輯原始文件。單一文件故障可能表示文件格式、內容或權限有問題；多個文件故障可能表示共享服務或網路發生了變更。

你所觀察到的	接下來最有用的檢查	權衡
其中一份文件是空白的。	嘗試使用相同格式的其他文件；檢查儲存應用程式的文件和 WOPI 日誌。	隔離速度快，但不能排除檔案特定的解析或權限問題。
所有文件在同一個瀏覽器中都無法正常運作。	隱私視窗、另一個瀏覽器、擴充功能和瀏覽器控制台。	風險低且速度快，但瀏覽器變通方法無法修復伺服器問題。
所有使用者和瀏覽器均失敗	網路請求、反向代理、WOPI 主機政策和伺服器日誌。	診斷價值較高，但變更可能會影響每個使用者；請先取得目前設定。

隱私視窗只是一種測試方法，並非最終解決方案。如果隱私視窗有效，請逐一停用擴充程序，或僅在確認沒有未同步的工作後，才清除受影響來源的網站資料。清除所有瀏覽器資料可能會導致使用者退出登錄，並刪除無關的網站狀態。

2. 找到更改設定之前失敗的請求

在 Chrome 或 Chromium 瀏覽器中，開啟開發者工具（快速鍵F12或Ctrl+Shift+I），選擇「網路」，啟用「保留日誌」，然後重新載入頁面。篩選WS（WebSocket）請求並檢查失敗訊息；Chrome 開發者工具「網路」參考文件解釋了請求篩選器和狀態詳情。檢查控制台是否有 CSP、憑證、混合內容或 JavaScript 錯誤。

瀏覽器開發者工具的網路面板顯示狀態碼為 502 的失敗文件和 WebSocket 請求。 — 網路面板範例：失敗的文件和 WebSocket 請求指向路由或上游連線問題；實際的請求名稱和狀態代碼因部署而異。

解讀證據，而不是應用通用的替代方法：

編輯器資源或路徑出現 404 錯誤/browser/：檢查反向代理是否將目前的 Collabora 路徑轉送到正確的上游。
如果出現 502 錯誤、逾時或 WebSocket 連線立即關閉的情況，請檢查上游連線是否可達、代理程式記錄、WebSocket 處理情況以及要求路徑。可存取的/hosting/discovery端點僅證明基本的 HTTP 存取權限，並不能證明編輯器的即時連線有效。
日誌中出現 403 或「未授權的 WOPI 主機」：請依據 Collabora 允許的 WOPI 主機驗證 WOPI URL 中指定的儲存主機。
CSP 或憑證錯誤：請修正嵌入來源或憑證鏈的確切位置。請勿停用瀏覽器安全設定或大幅放寬內容安全策略以載入頁面。

對於 WebSocket 請求，目標是成功握手；顯示的狀態取決於 HTTP 版本和代理路徑，因此不要將單一預期狀態編號視為通用狀態。

3. 將修復方案與出錯層相符。

檢查雙向 URL 方案

Nextcloud 目前的故障排除指南指出，使用者的瀏覽器必須透過 HTTP(S) 協定存取兩個伺服器，Nextcloud 必須能夠存取 Collabora，而 Collabora 也必須能夠存取 Nextcloud。指南還要求兩個服務使用相同的協定。請在瀏覽器中分別造訪 Collabora 的公共位址和公共位址進行測試https://office.example.com/hosting/discovery。https://office.example.com/hosting/capabilities在 Nextcloud 主機上，請使用下列命令：

curl -fsS https://office.example.com/hosting/discovery -o /dev/null

curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

請將範例主機名稱替換為您的實際 Collabora URL。這些檢查旨在確認 HTTP 連線是否暢通，而非編輯是否成功。如果伺服器連線成功但瀏覽器連線失敗，請檢查公用 DNS、TLS、防火牆或代理伺服器的暴露情況。 Nextcloud Office 故障排除指南列出了這些連線檢查，並建議查看應用程式日誌。

僅當請求涉及代理路由時才修復代理路由。

如果靜態編輯器資源傳回 404 錯誤或即時連線傳回 502 錯誤，請將您的反向代理路由與 Collabora 的官方代理設定進行比較。確保代理將所需的 Collabora 路徑傳送到正確的上游伺服器，並支援瀏覽器使用的 WebSocket 連線。保留部署所需的外部主機和 HTTPS 資訊。切勿在未檢查其假設的情況下，複製其他代理程式、URL 前綴或 Collabora 版本的配置。使用專用的 Collabora 主機名稱通常更容易調試；基於路徑的路由需要一致的前綴處理。

修正 WOPI 允許列表，無需開放它們

WOPI 是 Collabora 用於透過儲存平台取得和保存文件的協定。 WOPI 主機通常是 Nextcloud 或其他儲存平台的主機名，而不是 Collabora 的主機名稱。如果日誌顯示錯誤No acceptable WOPI hosts found，請在 Collabora 的 WOPI 主機配置中新增或修正正確的儲存主機名，然後確認儲存平台的 WOPI 請求允許清單中包含 Collabora 伺服器位址。 Nextcloud 建議將 WOPI 請求限制為預期的 Collabora IP 位址，並按照其Office 配置指南配置 Collabora 以信任預期的主機。

通用服務日誌面板顯示未授權 WOPI 主機警告以及與允許主機不符。 — WOPI 主機不符的範例診斷視圖。請在您自己的伺服器日誌和配置中確認實際的主機名稱和允許清單值。

新增特定的受信任主機比停用主機驗證或允許廣泛的網域名稱更安全。記錄目前設置，僅更改相關條目，並僅在部署需要時重新啟動或重新載入服務。如果您使用 Docker，請使用 `<command>` 命令檢查最近的 Collabora 輸出docker logs --since=10m <collabora-container>；將佔位符號替換為實際的容器名稱。對於軟體包或 Kubernetes 安裝，請改用其服務或 Pod 日誌。

4. 驗證編輯器，而不僅僅是健康端點

重新載入同一文檔。確認資源已載入、即時連線保持開啟、內容已顯示且控制台錯誤已停止。如果問題仍然存在，請使用第二個文件和另一個使用者進行測試。儲存一個無害的測試編輯，然後重新開啟以驗證讀取和儲存功能是否正常。

一個通用文件編輯器，顯示文字以及一個狀態正常的網路面板，其中包含成功的 WebSocket 請求。 — 復原檢查範例：文件內容可見，網路面板顯示 WebSocket 連線已完成；請在您自己的瀏覽器中確認相同的訊號。

如果畫布仍然空白，但請求現在可以成功，請檢查伺服器日誌中是否存在文件轉換或檔案特定的錯誤，並與另一個格式相同的檔案進行比較。如果問題在 Collabora、瀏覽器或代理更新後立即出現，請在維護視窗期間測試受控回滾或特定版本的代理程式更改，而不是一次性更改多個變數。清除瀏覽器快取僅在證據顯示客戶端資源過期時才有用；它無法修復被封鎖的路由或被拒絕的 WOPI 請求。