使用 coolwsd 日誌追蹤 Collabora 連線失敗

對於 Collabora Online Development Edition (CODE) 容器，請將coolwsd日誌等級提升至最高debug，確保 ` <logging_name> Socket` 和 `<logging_name> WebSocket` 區域未被停用，然後重現一次文件開啟失敗的情況，同時查看容器日誌。在 Docker Compose 中，透過 CODE 映像的環境變數傳遞這些設置extra_params，並重新建立服務。trace僅當偵錯輸出未顯示連線中斷的位置時才使用此方法，完成後請恢復到先前的層級。

此方法適用於 Docker 或 Compose 部署，您可以在其中更新容器配置。原生軟體套件安裝/etc/coolwsd/coolwsd.xml則使用其服務管理員。此設定會新增診斷詳細資訊；但它本身並不能修復代理程式、WOPI 主機、憑證或網路問題。

範例終端面板顯示了 docker logs --since 10m --follow collabora 和 coolwsd 輸出範例 — 範例終端檢視顯示了有時間限制的 Docker 日誌流；範例行並非實際伺服器輸出。

1. 首先進行一次受控複製

選擇一個文檔，並記下您嘗試開啟它的時間、Collabora 公共 URL 以及容器或 Compose 服務名稱。避免重複刷新多個文件：一次嘗試更容易將瀏覽器症狀、代理程式日誌、整合式伺服器日誌和 coolwsd 條目匹配起來。

檢查容器是否正在運行並確定其名稱：

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

請將以下內容替換collabora為您主機上顯示的容器名稱。在重現問題之前不久，請開始執行以下輸出：

docker logs --since 2m --follow --timestamps collabora

--follow串流新輸出、--since限制初始歷史記錄並--timestamps新增 Docker 時間戳記。 Docker 在其容器日誌參考文件中記錄了這些選項。在 Compose 中，您可以使用 `<service_key>` docker compose logs --since=2m --follow collabora，其中collabora`<service_key>` 是服務金鑰。

2. 將 coolwsd 設定為調試模式以進行測試

Collabora 配置方案支援命名級別，包括`<level> warning`、notice` <level>` information、debug`<level>`、`<level>` 和`<level> trace`。它也定義了`<level>`；文件中記錄的預設值會停用 `<level>`和`<level>` 等區域的disabled_areas高詳細輸出。這對於連接故障排除至關重要：僅更改等級可能仍會抑制最有用的握手詳細資訊。這些選項在Collabora coolwsd 配置範本和Collabora Online SDK 手冊（Docker 配置部分；2026 年 10 月查閱）中有詳細說明。SocketWebSocket

對於官方collabora/code鏡像，請將這兩個選項新增到服務的現有extra_params值中。保留安裝所需的任何選項，例如 SSL 終止或伺服器名稱：

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

第二個選項保留Socket並WebSocket啟用高詳細日誌記錄，同時保持Admin和Pixel停用狀態。在此測試期間，請勿將這兩個區域重新新增至停用清單。 CODE 鏡像文件將其描述extra_params為向 coolwsd 傳遞命令列選項的一種方式。如果您的部署使用已掛載的設定檔或供應商管理的鏡像，請改用該部署的設定方法。

範例程式碼編輯器，顯示 coolwsd 日誌等級設定為 debug，並且停用區域僅限於管理員和像素級使用者。 — 圖示的 XML 片段提高了日誌級別，並啟用了 Socket 和 WebSocket 輸出以進行連接測試。

透過重新建立服務來套用 Compose 編輯：

docker compose up -d --force-recreate collabora

請使用您實際的 Compose 服務名稱。對於使用 `--container-name` 啟動的短期容器docker run，請更新其運行配置，並使用相同的磁碟區、網路、連接埠和其他選項重新建立它。 CODE 手冊指出映像extra_params在啟動時接受 `--container-name`；不要假設更改已建立容器的環境會變更正在執行的 coolwsd 進程。

3. 依序閱讀連接訊息

重現故障一次，並僅查看該時間段內的日誌。在輸出中搜尋諸如WebSocket“”、WOPI“ ERR”、“”和“”之類的詞語WRN，然後比較時間戳。具體的措詞和日誌區域會因 Collabora 版本而異，因此請將這些字詞視為需要檢查的類別，而不是保證包含所有資訊的確切內容。

測試時沒有新的 coolwsd 條目：請求可能未到達此容器。請檢查配置的公共 URL、DNS、負載平衡器、反向代理存取/錯誤日誌，以及您是否正在追蹤正確的副本。
瀏覽器已連線至服務，但 WebSocket 連線未保持開啟：請檢查代理程式對 WebSocket 升級的處理、轉送的主機和協定、TLS 終止、路徑路由以及空閒逾時情況。對比瀏覽器開發者控制台和代理程式日誌；coolwsd 無法解釋代理從未轉發的請求。
WOPI 請求出現但失敗：請檢查整合伺服器的 WOPI URL、主機允許清單或別名配置、Collabora 容器的可及性以及整合伺服器的回應。 WOPI 錯誤與瀏覽器到 Collabora 的 WebSocket 連線是不同的階段。
WOPI 請求成功，但瀏覽器仍斷開連線：接下來需要重點檢查 WebSocket 路由和瀏覽器端的連線錯誤。此步驟縮小了搜尋範圍，但無法確定是哪個代理或網路設定出了問題。

示例性終端範例，以連接序列的形式排列，包含客戶端、WOPI 和 WebSocket 日誌類別。 — 使用時間戳按順序追蹤各個階段；本範例中的文字僅供參考，並非經過驗證的日誌擷取。

如果 Docker 服務處於活動狀態但沒有任何輸出，請檢查容器內的日誌配置。 Docker 的 log 指令會讀取容器的標準輸出和錯誤流；如果配置為將日誌寫入文件，則可能會使用/var/log/coolwsd.log設定檔中定義的路徑，例如 `/usr/local/bin`。請檢查實際的檔案路徑，而不是假設該路徑：

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

如果啟用了檔案日誌記錄，請使用配置的路徑，例如：

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. 驗證結果並恢復正常日誌記錄

測試結束後，執行有界讀取以確認預期的嘗試是否產生了新的條目：

docker logs --since 5m --timestamps collabora

如果能將失敗的開啟操作與 coolwsd 事件對應起來，或確定請求從未到達此容器，就能得到有用的結果，進而確定需要跟進的連結階段。如果需要篩選輸出，請先使用較短的時間視窗：

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

示例性終端視圖，顯示了一個五分鐘的 Docker 日誌查詢，其中包含與關閉相關的範例輸出。 — 該面板顯示了一個五分鐘的查詢，其中包含示例性的關機條目；請使用能夠覆蓋您自身複現過程的視窗。

恢復先前的logging.level配置disabled_areas值，然後重新建立服務。偵錯和追蹤等級會產生更多輸出，其中可能包含敏感的操作細節。共享日誌前，請對存取令牌、文件名稱、使用者識別碼、主機名稱和內部位址進行編輯。如果該服務並非官方 CODE 鏡像，請與該鏡像的維護者確認其配置路徑和支援的參數。