如何使用 coolwsd 日誌等級來偵錯 Collabora 線上連線日誌

Collabora Online 目前的公共設定模板仍然公開了 `<configuration>` 屬性logging.level，coolwsd.xml支援的值範圍從warning`<configuration> ` 到 `<configuration> debug` 和 ` trace<configuration>`。如果連線失敗，請暫時提高 `<configuration>` 級別，重現一次連線失敗，檢查服務的實際日誌目標，完成後恢復到正常等級。 XML 中顯示的值並不總是有效值：啟動命令或容器設定可能會覆寫它，而 WebSocket 日誌記錄等高詳細程度的日誌區域可能會被單獨停用。

本指南重點介紹如何診斷瀏覽器與 Collabora 之間的連線失敗或文件開啟失敗。它使用最新的公開原始碼coolwsd.xml.in模板和 Collabora 官方資料，更新日期為 2026 年 10 月 6 日。軟體包預設值和服務名稱可能會因版本和部署而異，因此在複製路徑或重新啟動命令之前，請確認您正在執行的實例。

coolwsd 日誌等級會改變什麼？

coolwsd是 Collabora Online WebSocket 守護程序，它是處理瀏覽器會話和文件活動的伺服器程序。其日誌等級決定了進程輸出的詳細程度。當前來源模板列出了命名級別，包括fatal` <log-level>` critical、error`<log-level> `、` warning<log-level> ` notice、`<log-level> information` debug、`<log-level>` 和trace`<log-level>`，以及數字級別 0 到 8。數字值從最少到最多。對於初步診斷，` debug<log-level>` 是一個合理的等級；trace僅在需要更詳細的連線資訊時才使用 `<log-level>`。

此單獨level_startup設定控制初始啟動期間的日誌記錄，之後日誌等級會恢復到預設等級level。目前範本將啟動日誌等級設為trace；但這並不表示正常執行時間日誌等級仍為 trace。請避免level_startup在服務運行後出現問題時變更此設定。

更詳細的輸出會增加日誌量，並且可能包含 URL、位址、會話標識符或其他操作細節。請將日誌視為敏感資訊；僅收集所需時間視窗內的信息，並在分享前對敏感資訊進行減敏處理。

步驟 1：確定此 Collabora 實例的運作方式

首先確定 Collabora Online 是以系統服務形式運行，還是運行在 Docker 或 Podman 容器中，亦或是 Kubernetes 環境中。這一點至關重要，因為在運行中的容器內更改文件可能無法持久保存，並且容器日誌可能會輸出到標準輸出而不是文件。

系統軟體包：檢查正在執行的服務及其單元名稱（通常為 `<service_name>`）coolwsd。配置通常為 ` /etc/coolwsd/coolwsd.xml<config_name>`。舊版本可能使用舊版loolwsd路徑。
Docker 或 Podman：確定容器名稱及其配置方式。通常，配置的持久化來源是綁定掛載的檔案或部署變數。
Kubernetes：請檢查 Helm 值、ConfigMap 或部署清單coolwsd.xml。直接編輯 Pod 只是臨時性的。

文字編輯器顯示了 coolwsd.xml 日誌記錄部分，其中常規等級為警告，啟動等級為追蹤。 — 目前公共配置範本為正常日誌記錄和初始啟動階段分別設定了不同的值。

編輯之前，請備份實際的設定檔或儲存部署值的副本。如果您不確定執行進程讀取的是哪個文件，請先檢查其服務定義或啟動命令。看似無操作的常見原因是編輯了範例文件而不是活動配置。

步驟二：暫時提高啟動級別

在活動狀態下coolwsd.xml，找到該<logging>部分並僅更改其中的值<level>。從開始debug。如果連接嘗試仍然無法提供足夠的詳細信息，請短暫使用trace進行一次重現。保持現有的level_startup、檔案設定和無關配置不變。

<config>
  <logging>
    <level>trace</level>
    <level_startup>trace</level_startup>
  </logging>
</config>

coolwsd.xml 日誌等級已從警告變更為跟踪，並標記為臨時日誌等級。 — 當偵錯資訊不足顯示足夠細節時，請暫時使用追蹤；保留啟動設定和其他 XML 選項。

這是一個簡化的 XML 結構範例，並非完整設定檔的替代品。對於容器部署，請透過該鏡像或圖表支援的持久化機制設定此選項。 Collabora 官方原始碼包含命令列配置覆蓋選項，因此如果該值似乎被忽略，請檢查啟動參數或部署參數中是否存在其他logging.level值。

如果日誌寫入文件，目前來源範本會在 `/etc/log/log/file` 下記錄檔案路徑logging.file，通常位於/var/log/coolwsd.log`/etc/log/file`。但是，在生產環境中，文件日誌記錄可能會被停用。如果您啟用檔案輸出或使用自訂路徑，請確認cool服務帳戶擁有寫入權限，且 systemd 允許服務寫入該位置。切勿為了解決權限問題而將日誌設定為全域可讀。

步驟 3：重新啟動或重新部署，然後重現一次

大多數打包配置會在服務重新啟動後生效。請在適當的維護視窗或測試實例期間重新啟動服務，因為正在進行的編輯會話可能會中斷。對於 systemd 服務，典型的指令是：

sudo systemctl restart coolwsd
sudo systemctl status coolwsd --no-pager

請使用主機上的實際服務名稱。對於容器，請更新持久化配置並重新啟動或重新部署該容器。對於 Kubernetes，請透過正常的發布流程套用清單或 Helm 變更。在重現問題之前，請確認流程能夠正常啟動。

記錄確切時間、受影響的使用者或測試帳戶、文件開啟步驟以及瀏覽器中可見的錯誤。重現故障一次後，停止產生請求。與大量不相關的會話相比，單次嘗試更容易在 Collabora、反向代理和儲存或 WOPI 主機之間進行關聯。

步驟 4：讀取部署日誌來源

對於 systemd 服務，請在重現問題時參考日誌：

sudo journalctl -u coolwsd -f

若要檢查最近一段時間內的記錄，請使用 ` sudo journalctl -u coolwsd --since "10 minutes ago".`。如果您的單元有其他名稱，請替換為實際名稱。對於 Docker，請使用 `.`docker logs --since 10m --follow CONTAINER_NAME並將 `<container_name>` 替換CONTAINER_NAME為實際的容器名稱或 ID。 Podman 和 Kubernetes 有各自的日誌命令；請查閱部署的運行時文檔，而不是假設主機文件存在。

兩個終端視窗分別顯示 coolwsd 和 docker 的 journalctl 日誌，其中容器名稱佔位符為空，沒有範例輸出。 — 從活動日誌接收器讀取；Docker 命令中的容器名稱文字是一個佔位符，需要替換為您的實際容器名稱。

如果啟用了檔案日誌記錄，請檢查配置的路徑，例如 `/etc/logging/` sudo tail -F /var/log/coolwsd.log。您文件中的路徑可能有所不同。缺少文件本身並不意味著服務沒有產生任何日誌；它可能將日誌寫入了日誌日誌或容器輸出。

步驟 5：關聯連線序列

首先尋找記錄時間戳處的條目。搜尋警告和錯誤標記以及與連線相關的術語，例如 `<command>`、`<command>` WOPI、WebSocket` Socket<command>` 或相關的請求路徑。在文件中，一個重點突出的初步篩選條件可以是：

grep -Ei 'ERR|WRN|WOPI|WebSocket' /var/log/coolwsd.log

然後按順序檢查：瀏覽器是否訪問了公共 URL，反向代理是否轉發了請求，WebSocket 升級是否完成，以及 Collabora 是否聯繫了文件託管方？代理程式的存取日誌和錯誤日誌可以回答 coolwsd 日誌無法回答的問題，例如請求是否到達了服務。如果瀏覽器報告 WebSocket 連線失敗，但 coolwsd 沒有記錄到符合的請求，請在變更文件權限之前，請檢查 DNS、TLS 終止、防火牆規則和反向代理路由。

目前設定範本將 `<catch_logging_logging_name>` Socket、 `<catch_logging_name>` WebSocket、Admin`<catch_logging_name>` 和 ` <catch_logging_name>` 列為高詳細輸出的Pixel預設選項。如果追蹤日誌記錄已啟用但缺少套接字詳細信息，請檢查此設定。若要進行簡短的診斷，請僅從逗號分隔的停用清單中移除相關的 `<catch_logging_logging_name>`或 ` <catch_logging_name>` 區域，並保留不相關的排除項。重新啟動或重新部署並重複相同的受控測試。收集證據後，恢復原始清單。disabled_areasSocketWebSocket