修正 Collabora Online 載入時出現黑屏或空白文檔的問題

首先檢查 WebSocket 連線以及兩台伺服器的可及性。如果Collabora Online 編輯器開啟後顯示黑屏、白屏或空白文檔畫布，通常是因為文檔 UI 載入完成前發生故障。如果所有文件都出現此問題，請先檢查瀏覽器到 Collabora 的路由、反向代理以及 Nextcloud 到 Collabora 的連線。如果只有一個文件出現問題，請測試另一個文檔，並在更改伺服器設定之前檢查該文件的權限和格式。

請依下列順序操作：檢查瀏覽器，測試 Collabora 的發現端點，讀取整合日誌和伺服器日誌，然後僅修正證據指向的代理或 WOPI 設定。重置瀏覽器快取可以幫助解決資源過期的問題，但無法修復損壞的 WebSocket 或無法存取的 WOPI 主機。以下介面圖為示意圖範例；實際標籤和請求路徑會因瀏覽器、雲端平台、代理程式和 Collabora 版本而異。

透過症狀快速診斷

你所看到的	首先要檢查的地方	可能的下一步行動
所有文件都保持空白或持續載入。	瀏覽器網頁選項卡和 Collabora 代理	檢查失敗的`/cool/…/ws`、`/browser`或發現請求
Collabora URL 可以正常使用，但 Nextcloud 無法開啟檔案。	Nextcloud 辦公室 URL、WOPI 允許清單和伺服器日誌	確認公用 URL 正確且伺服器雙向連線正常
只有一份文件是空白的。	文件權限、共享狀態、格式和文件完整性	在變更全域代理設定之前，請先嘗試使用已知有效的文件。
在一個瀏覽器中可以運行，但在另一個瀏覽器中則不行。	瀏覽器控制台、擴充功能和快取的網站數據	測試隱私視窗並比較失敗的請求

1. 確定問題是出在瀏覽器端還是伺服器端

首先，開啟一個已知可讀的文檔，然後在不同的瀏覽器或隱私視窗中嘗試開啟同一個文件。如果一個文件無法開啟而其他文件可以打開，請檢查使用者是否仍可以在文件平台下載或預覽該文件。檔案損壞、格式不支援、共享過期或缺少權限等問題可能看起來像是編輯器的問題，但更改反向代理並不能解決檔案本身的問題。

若要進行瀏覽器端檢查，請在重新載入空白文件之前開啟開發者工具。在基於 Chromium 的瀏覽器中，按 Ctrl+ F12Shift+E Ctrl+Shift+I，選擇「網路」，啟用「保留日誌」，然後重新載入。篩選ws“/ cooletc/ browserwebsite ...

瀏覽器文件編輯器顯示空白頁面，開發者工具網路面板顯示對 /cool/abc123/ws 的 WebSocket 要求失敗，HTTP 狀態為 502。 — 當編輯器畫布保持空白時，WebSocket 請求失敗是一個有用的線索；顯示的請求和狀態具有指示意義。

請求失敗通常/cool/…/ws指向 WebSocket 握手或代理問題。狀態碼 A502通常表示代理無法從上游取得可用回應；狀態碼 B404可能表示路徑未路由；狀態碼 C403可能表示主機或存取規則被拒絕。這些狀態碼可以縮小搜尋範圍，但需要相符的代理程式日誌和 Collabora 日誌才能確定確切原因。如果失敗的請求涉及 JavaScript 或 CSS 文件/browser，請檢查代理程式是否將這些靜態資源轉送至 Collabora 服務。

如果在隱私視窗中網路請求成功，請暫時停用封鎖腳本或跨站請求的瀏覽器擴充程序，然後僅清除雲端和 Collabora 主機名稱的網站資料。在更改伺服器配置之前重新測試。如果相同的請求在「網路」標籤中仍然失敗，請勿將清除快取作為主要解決方法。

2. 確認 Collabora URL 和發現端點

若要整合 Nextcloud，請在 Office 管理設定中驗證 Collabora Online 伺服器 URL。請使用瀏覽器可存取的公用 URL，並確保主機名稱和連接埠正確。 Nextcloud 目前的指南建議 Collabora 和 Nextcloud 服務應使用相同的協定；建議使用 HTTPS。如果一個服務配置了其他協議，http://而另一個服務卻透過其他方式訪問，https://則可能導致混合內容請求被阻止或回調失敗。

包含 Collabora Online 伺服器 URL 欄位和「儲存」按鈕的 Office 管理設定面板。 — 檢查整合指向的公共 Collabora URL 是否是瀏覽器和儲存伺服器應該存取的位址；設定標籤因平台而異。

在受影響用戶端的瀏覽器中，開啟 ` <example_hostname> https://office.example.com/hosting/discovery` 和https://office.example.com/hosting/capabilities`<example_hostname>`，並將範例主機名稱替換為您自己的主機名稱。發現端點應傳回描述所支援的文件操作的 XML；功能應傳回來自 Collabora 伺服器的回應。如果發生瀏覽器錯誤、登入頁面、代理程式 404 錯誤或閘道錯誤，則表示公共路由無法到達預期的 Collabora 端點。

然後從 Nextcloud 主機進行測試，因為僅靠瀏覽器測試無法證明伺服器之間可以相互通訊：

curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/discovery
curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/capabilities

請替換office.example.com為已設定的 Collabora 主機名稱。成功的 HTTP 回應是可及性檢查的有效指標，而逾時、DNS 故障、TLS 錯誤或 5xx 回應則需要在對應的網路、憑證、DNS 或代理層進行解決。對於 Collabora 伺服器必須回呼 Nextcloud 的部署，也需要從 Collabora 主機測試 Nextcloud 狀態 URL：

curl -fsS https://cloud.example.com/status.php

請使用您實際的 Nextcloud 主機名稱。內建 CODE 安裝可以使用內部代理 URL 而不是單獨的公共 Collabora 主機名，因此請按照該部署的說明進行操作，而不是直接套用獨立伺服器範例中的步驟。

3. 檢查 WebSocket 路由和反向代理

Collabora 透過多個路由提供瀏覽器資源和文件會話。反向代理必須轉送已安裝版本所需的路徑，包括編輯器資源、發現和功能端點以及文件 WebSocket 路由。目前的 Collabora 文件使用 [此處應填寫具體路徑] /cool/…/ws；較舊的部署可能仍保留對舊路徑的配置。 Nextcloud 的遷移文件特別指出了從 [此處應填寫具體路徑]到[此處應填寫具體路徑] 以及從 [此處應填寫具體路徑]到 [此處應填寫具體/lool路徑] 的歷史路徑變更。loleafletbrowserloolcool

在代理程式配置中，請檢查 WebSocket 位置是否符合到更廣泛的通配符規則之前，代理程式是否轉送了代理軟體所需的升級標頭，以及上游是否指向實際的 Collabora 服務和連接埠。此外，請確認代理保留了預期的主機和協定訊息，並允許長時間保持連線開啟。如果 TLS 終止於代理，請確保 Collabora 的 SSL 終止設定與此設計相符。

程式碼編輯器顯示了 Nginx WebSocket 位置以及升級和連接代理程式標頭。 — WebSocket 代理程式規則需要正確的路由和升級處理；此摘錄並非完整的配置。

上面的簡短程式碼片段展示了 Nginx 式代理程式可能需要的 WebSocket 標頭類型；它並非完整的代理程式配置。請勿單獨貼上此程式碼，也不要混合使用來自不同版本的指令。請將您的完整配置與Collabora 官方反向代理指南中針對您所執行的代理程式和 Collabora 版本的設定進行比較。編輯代理檔案後，請在重新載入之前，請使用該伺服器的 configuration-test 命令驗證其語法。

4. 檢查 WOPI 主機驗證和伺服器日誌

Collabora 使用 WOPI（Web 應用程式開放平台介面）從連接的儲存服務（例如 Nextcloud）請求文件。 Collabora 伺服器必須接受 WOPI 主機，且儲存伺服器必須能夠存取 Collabora 服務。在 Nextcloud 中，檢查 Office 設定和 WOPI 請求的允許清單。僅新增預期的 Collabora 伺服器位址；不要停用主機驗證或允許任意主機，以免出現空白畫面消失的情況。

請讀取問題重現時的日誌。對於 Docker 部署，Nextcloud 的故障排除指南中記錄如何檢查容器日誌；請使用實際的容器名稱或 ID：

docker logs --tail 100 collabora

對於基於軟體包的安裝，服務名稱和日誌目標位置取決於作業系統和軟體包版本。 systemd 的常見檢查包括：

sudo journalctl -u coolwsd -n 100 --no-pager

尋找符合的時間戳記以及有關未經授權的 WOPI 主機、CheckFileInfo請求失敗、TLS 驗證失敗、儲存不可用或 WebSocket 連線失敗的錯誤訊息。如果出現「沒有符合的 WOPI 主機」的訊息，通常表示為整合配置的儲存主機名稱與 Collabora 允許的主機名稱不符。請更正主機名稱或允許清單條目，而不是新增無關的網域名稱。

終端機顯示 docker logs --tail 100 collabora 和 WOPI 主機拒絕訊息。 — 將 Collabora 日誌訊息與請求時間進行比較；此訊息是 WOPI 允許清單不符的範例。

同時檢查同一請求時間的文件平台日誌。如果 Collabora 無法連接到 Nextcloud，請檢查 Collabora 主機的 DNS 解析、防火牆規則、公網或內部網路路由，以及該服務是否嘗試透過容器網路內部解析方式不同的主機名稱存取自身。 Nextcloud 的故障排除手冊建議檢查雙向連接，並使用伺服器日誌來確定故障方。

5. 重新測試文檔，並僅進行針對性修改。

修復路由、URL、憑證或允許清單條目後，僅在部署需要時才重新載入代理程式和受影響的服務。重新開啟開發者工具，重新載入文件，並確認先前失敗的請求現在可以完成。文件應該能夠渲染頁面或工作表，接受少量編輯，並成功儲存該編輯。如果出現空白頁面消失但無法儲存，則仍表示存在未解析的 WOPI 或儲存連線。

發現功能正常，但 WebSocket 連線失敗：專注於代理程式的 WebSocket 路由、升級處理、上游位址和連線逾時。
瀏覽器可以存取 Collabora，但 Nextcloud 無法存取：測試 Nextcloud 主機的 DNS、防火牆、TLS 信任和路由。
Collabora 報告未經授權的 WOPI 主機：請將整合設定中的確切儲存主機名稱與 WOPI 主機允許清單進行比較。
升級後只有舊版本安裝會失敗：將代理路徑與已安裝版本的文件進行比較，並在需要時更新舊版本/lool或/loleaflet路由。
連接性檢查通過後，只有一個檔案失敗：在更改全域設定之前，請先驗證檔案存取權限並測試副本或其他支援的格式。

成功的解決方案是什麼樣子的

可靠的結果不僅僅是編輯器工具列出現。文件內容能夠正常渲染，沒有持續的編輯器或 WebSocket 請求失敗，並且無害的測試編輯能夠保存並在刷新後仍然保留。如果問題仍然存在，請保留一段簡短的、經過編輯的瀏覽器網頁/控制台日誌摘錄以及相應的 Nextcloud、代理和 Collabora 日誌。日誌可能包含主機名稱、使用者名稱、檔案識別碼或令牌，因此在共用之前請務必刪除敏感資訊。

有關目前部署的具體步驟，請參閱Nextcloud Office 故障排除指南、Nextcloud Office 設定參考和Collabora 遷移說明。針對 ownCloud、其他 WOPI 主機、內建 CODE 服務或容器平台的具體檢查步驟可能與 Nextcloud 的範例有所不同。