如何安全地備份和還原 Collabora CODE 設定文件

Collabora 線上開發版 (CODE) 26.04.4.2 於 2026 年 9 月 24 日發布。這對於備份計劃至關重要，因為 26.04 版本還更改了針對較新 WebSocket URL 的建議反向代理路徑處理的部分內容。如果您正在準備升級、遷移或災難恢復，僅備份一個 XML 檔案可能不足以重現一個正常運作的部署。

經過驗證的核心部分非常簡單：Collabora 的主伺服器設定檔/etc/coolwsd/coolwsd.xml位於官方 CODE 容器內。官方 Docker 文件也支援將該檔案從容器複製出來、再複製回來，或從主機掛載到容器中。需要注意的是，除了該檔案之外，其他部分都有所不同：Docker 環境變數、掛載點、WOPI 驗證金鑰、TLS 終止以及反向代理程式配置。

本指南展示了一種保守的備份和復原流程，適用於原生軟體包安裝和 Docker 部署。它特意將 Collabora 文件中確認的內容與取決於您自身部署情況的內容區分開來。

Collabora CODE備份應該包含哪些內容？

已驗證： /etc/coolwsd/coolwsd.xml這是 Collabora Online 的主要設定檔。 Collabora 官方文件中直接記錄了此路徑，並指出該文件包含所有可用伺服器選項的說明。請參閱Collabora Online SDK 官方手冊。

部署方式不同：完整的復原可能還需要用於啟動服務的配置。對於 Docker，這可能包括 Compose YAML 檔案、環境變數、綁定掛載、金鑰以及從主機掛載的檔案。對於原生安裝，如果反向代理虛擬主機和憑證在同一伺服器上管理，則可能包括這些設定。

操作：在建立歸檔檔案之前，請記下您的執行個體是原生軟體包安裝還是 Docker/Compose 部署。不要假設相同的恢復步驟適用於兩者。

開始之前常見的誤解

備份 coolwsd.xml 檔案不會備份使用者文件。

CODE 通常透過 WOPI 連接到儲存平台。文件仍然由此儲存平台（例如 Nextcloud 或其他 WOPI 主機）控制。因此，恢復 CODE 配置並不會恢復文件本身。

操作：使用WOPI產品本身的備份程序備份WOPI主機及其資料儲存。將此CODE備份視為服務配置備份。

Docker 容器並非備份

容器可以從鏡像重新建立。透過環境變數或綁定掛載傳遞的配置可能存在於容器外部，而僅在容器內部進行的編輯可能會在容器被替換時遺失。

操作：保存部署定義和主機掛載的文件，而不僅僅是容器檔案系統。

將舊的 coolwsd.xml 檔案複製到較新的版本上並不總是最安全的復原方法。

CODE 版本之間的配置選項可能會有所變化。 Collabora 目前的發行說明顯示，26.04 系列版本中伺服器和代理程式配置持續發生變化，包括針對精簡 WebSocket URL 的更新代理程式建議。請參閱官方的 CODE 26.04 發行說明。

操作：每次備份時都會記錄代碼版本。還原到不同版本時，在完全替換之前，請將已儲存的檔案與新軟體包的預設檔進行比較。

步驟 1：記錄已安裝版本和部署類型

首先記錄足夠的資訊以重現部署環境。對於容器部署，請檢查正在運行的容器及其映像：

docker ps --filter name=collabora
docker inspect collabora --format '{{.Config.Image}}'
docker inspect collabora --format '{{json .Mounts}}'

如果您的容器使用不同的名稱，請collabora相應地進行替換。官方映像已發布collabora/code；Docker Hub 目前在最新版本中將 26.04.4.2 映像列為最新版本。請參閱Docker Hub 上的官方 Collabora CODE 映像。

對於原生軟體套件安裝，請使用您實際使用的軟體套件管理器記錄軟體套件版本。例如，在 Debian 或 Ubuntu 系統上：

dpkg-query -W 'coolwsd*' 'collaboraoffice*' 2>/dev/null

操作：將版本輸出儲存到與設定存檔相同的受保護備份目錄。

步驟 2：備份核心配置和部署元數據

本地軟體包安裝

建立僅包含根目錄的備份目錄，並將整個/etc/coolwsd目錄歸檔，而不是僅選擇主 XML 檔案。這樣可以保留已安裝軟體包或本機自訂設定中放置在該目錄下的任何其他檔案。

sudo install -d -m 700 /var/backups/collabora
sudo tar -C /etc -czpf \
  /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  coolwsd

此命令特意/etc在歸檔之前進行更改，以便歸檔檔案包含相對coolwsd/路徑而不是絕對檔案系統路徑。

Docker 或 Docker Compose

Collabora 的文檔指出，官方鏡像包含該鏡像/etc/coolwsd/coolwsd.xml，管理員可以將其複製出來、修改它、複製回來，或從容器外部掛載它。

如果該檔案尚未從主機綁定掛載，請將其複製出來：

sudo install -d -m 700 /var/backups/collabora
docker cp collabora:/etc/coolwsd/coolwsd.xml \
  /var/backups/collabora/coolwsd.xml

接下來，記錄容器的設定方式：

docker inspect collabora --format '{{json .Config.Env}}' \
  > /var/backups/collabora/container-env.json

docker inspect collabora --format '{{json .Mounts}}' \
  > /var/backups/collabora/container-mounts.json

重要：環境變數輸出可能包含密碼、管理員控制台憑證、主機名稱或其他敏感資訊。請確保這些檔案僅供 root 使用者讀取，並對異地副本進行加密或其他保護措施。

如果您使用 Docker Compose，請從主機複製實際的 Compose 檔案以及任何引用的環境或金鑰檔案。它們的具體位置取決於您的部署環境，因此沒有可以安全假定的通用路徑。

操作：確認備份包含真實資料來源。如果coolwsd.xml主機檔案已綁定掛載，請備份主機檔案。如果配置是透過環境變數提供的，請保留定義這些變數的 Compose/run 配置。

步驟 3：僅在適用時包含驗證金鑰、代理程式設定和 TLS。

這些組件之所以重要，正是因為它們在每次安裝中都不完全相同。

WOPI 驗證金鑰： Collabora 文件指出，RPM 和 DEB 安裝套件會自動產生 WOPI 驗證金鑰對。對於 Docker，該密鑰對不包含在公共映像中；使用時，必須產生密鑰並將其提供給容器，通常透過磁碟區來實現。手冊中記錄coolconfig generate-proof-key了密鑰的產生方法。由於 Docker 金鑰位於不可變映像之外，因此遺失主機端掛載的金鑰可能會導致用於 WOPI 驗證簽章的身分發生變更。

操作：使用容器的掛載清單來確定任何驗證金鑰掛載點的主機位置，並安全地備份該主機端的檔案或目錄。如果您的部署未使用路徑，請勿自行建立路徑。

反向代理： Apache、Nginx、HAProxy、Traefik 或其他代理伺服器可以持有公用主機名稱、TLS 終止、WebSocket 路由和請求轉送規則。在 CODE 26.04 版本中，Collabora 更新了針對新型緊湊型 WebSocket URL 的代理指南，同時在某些情況下保留了舊版回退方案。

操作：備份用於服務您的 Collabora 主機名稱的代理程式配置。其檔案系統路徑取決於您的作業系統和代理，因此請從目前代理組態中識別它，而不是從教學課程複製通用路徑。

TLS 憑證：僅當該主機實際擁有這些憑證時才進行備份。如果 TLS 連線終止於負載平衡器、入口控制器、CDN 或獨立的反向代理，則憑證備份應保存在這些位置。

第四步：在需要之前驗證備份

命令執行成功tar還不夠。也要測試歸檔檔案是否可以列出，以及預期的主設定檔是否存在。

sudo tar -tzf /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  | grep 'coolwsd/coolwsd.xml'

建立用於異地驗證的校驗和：

cd /var/backups/collabora
sha256sum * > SHA256SUMS

然後使用您常用的備份系統將備份複製到第二個受保護的位置。不要將唯一的備份副本保留在您正在保護的同一台主機上。

操作：至少測試一次將檔案提取到臨時目錄的操作。從未打開過的備份檔案只是一個假設。

步驟 5：保守地恢復，然後驗證正在執行的服務

復原原生安裝

建議先安裝相同的 CODE 版本。停止服務，將壓縮包解壓縮到臨時目錄，然後將已儲存的配置與新安裝的預設組態進行比較：

sudo systemctl stop coolwsd
sudo mkdir -p /root/collabora-restore
sudo tar -xzf /var/backups/collabora/coolwsd-etc-YYYY-MM-DD.tar.gz \
  -C /root/collabora-restore

sudo diff -u \
  /etc/coolwsd/coolwsd.xml \
  /root/collabora-restore/coolwsd/coolwsd.xml

如果版本符合且您打算完全替換，請先保留新目錄作為回溯副本：

sudo cp -a /etc/coolwsd /etc/coolwsd.pre-restore
sudo cp -a /root/collabora-restore/coolwsd/. /etc/coolwsd/
sudo systemctl start coolwsd

如果版本不同，請合併您實際更改的設置，而不是盲目地替換新文件。這樣可以避免丟棄新版本引入的新預設值或必要元素。

復原 Docker 部署

根據已錄製的映像版本和原始 Docker Compose 檔案或定義重新建立容器docker run。在啟動容器之前，將主機綁定掛載的設定、驗證金鑰和其他外部檔案還原到其原始主機路徑。

如果您特意將文件保存coolwsd.xml在容器內而不是作為綁定掛載，Collabora 文件中的方法允許您將文件複製回來。實際上，主機綁定掛載更容易重現，因為配置在容器替換後仍然存在。

操作：先恢復部署定義，再恢復它所引用的檔案。這樣可以確保環境變數、磁碟區和 XML 配置保持一致。

如何確認恢復操作是否成功

不要僅以進程是否啟動來判斷是否成功。也要從客戶端使用的相同網路路徑檢查服務。

對於本地安裝：

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

對於 Docker：

docker ps --filter name=collabora
docker logs --tail 100 collabora

Collabora 文件中/hosting/capabilities說明，此端點可用於擷取正在執行的產品名稱和版本等資訊。請使用您的 Collabora 公共 URL 進行測試：

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

請將主機名稱替換為您自己的主機名稱。另外，請從 WOPI 主機開啟真實文檔，並驗證透過正常的反向代理路徑進行編輯、儲存和重新連線是否有效。

操作：只有在功能端點回應且實際文件可以開啟和儲存後，才認為恢復完成。

實用備份檢查清單

最終建議

最可靠的 Collabora CODE 恢復方案並非複製單一文件。應將coolwsd.xmlCODE 版本、部署定義以及所有設定資訊保留在一個可復原的集合中。僅在架構實際需要的地方新增驗證金鑰、代理程式規則和 TLS 資料。對於升級，盡可能恢復到相同版本；如果升級到更新的版本，請比較並合併配置，而不是在未審核的情況下覆蓋新的預設值。

截至 2026 年 10 月 6 日，根據 Collabora 官方 26.04 版本說明和 Docker 映像元數據，CODE 版本為 26.04.4.2。由於鏡像版本、代理建議和配置選項會不斷更新，因此在進行未來遷移之前，請務必再次查看這些官方來源。