如何建構包含多個節點的 Collabora Online 集群

Collabora Online 叢集並非只是幾台運作正常的coolwsd伺服器透過輪詢負載平衡器連接而成。協作編輯依賴將對相同文件的請求傳送到同一個 Collabora 節點。WOPISrc因此，Collabora 的 Kubernetes Chart 文件中明確規定如何使用 WOPI 文檔識別碼進行路由。本指南以維護完善的 Collabora Helm Chart 為例，展示了具體的 Kubernetes 多節點部署方案，並指出了針對不同入口控制器或非 Kubernetes 部署所需進行的變更。

已驗證：WOPISrc Collabora 的圖表支援多副本，並使用.描述每個文件的親和力。部署相關：入口註解、TLS 終止、資源請求以及是否需要會話控制器。不建議假設：任何負載平衡器或所有「黏性會話」設定都能保持文件親和性。在將使用者遷移到叢集之前，請確認特定控制器的行為並進行測試。

集群的功能——以及它不具備的功能

在標準的多副本部署中，每個 Collabora 節點都可以提供文件服務，同時透過代理程式將每個文件的請求傳送到其中一個節點。這樣就將不同的文檔分散到整個節點池中。但這並不意味著每個節點共享同一個即時編輯進程，也不意味著正在運行的文件在其所在節點停止運行時總是可以無縫遷移。

Collabora 還提供了適用於 Kubernetes 的 COOL Controller 文檔，該控制器採用了不同的會話管理方法。其路由和配置與獨立副本池有所不同。本文配置了更簡單的 WOPI 來源親和性模型；除非您已為您的版本部署並配置了控制器，否則請勿將其與控制器特定的路由令牌設定結合使用。

操作：確定您需要的是具備基本複製功能的 Collabora 服務（用於容量和節點冗餘），還是具有會話感知功能的控制器管理架構。後者包含更多元件和特定於版本的配置。如果您正在評估該方案，請查看Collabora 線上控制器概述。

部署前

一個可運行的 Kubernetes 叢集、Helm、公共 Collabora 主機名稱的 DNS，以及一個支援 TLS 的入口或反向代理。
WOPI 整合（例如 Nextcloud）配置為使用單一公共 Collabora 主機名稱而不是單獨的 pod 位址。
在圖表配置中輸入 Collabora 可以接受的 WOPI 主機collabora.aliasgroups。
足夠的 CPU 和記憶體來滿足文件工作負載的需求，此外還提供了一種方法來檢查 pod 健康狀況、入口日誌和資源使用情況。
初始部署的維護視窗和包含兩個獨立使用者帳戶的測試文件。

專用的 Collabora Online 服務與 Nextcloud 內建的 CODE 伺服器不同。 Nextcloud 將其內建選項描述為面向個人使用者或小型團隊，不具備專用伺服器的高級可擴充性功能。建議：如果您需要多節點 Collabora 池，請規劃專用服務，並確認適合您部署的授權和支援模式。請參閱Nextcloud Office 安裝指南。

步驟 1：選擇路由模型

文件中記錄的獨立模型使用雜湊值WOPISrc來識別 WOPI 請求中的文件。對同一文件的請求必須傳送到同一個 Pod；對不同文件的請求可以分佈在不同的 Pod 中。通用的輪詢規則無法滿足此要求。

操作：使用圖表文件支援的 Ingress 實現，例如文件中提供的 NGINX 或 HAProxy Ingress 範例；或者，如果叢集不支援適當的 Ingress 控制器，則使用圖表命名空間內的反向代理。如果使用其他代理，請驗證其是否能夠一致地路由 WOPI 來源的請求，包括普通的 HTTP 請求和長時間運行的 WebSocket 連線。

步驟 2：檢查圖表並選擇版本

圖表及其數值會隨時間變化。安裝前，請務必查看目前官方圖表的 README 文件及其數值，切勿直接複製舊版配置。以下範例遵循 Collabora 維護的圖表文件（更新於 2026 年 10 月 6 日）；請以倉庫的當前版本說明和數值為準。

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions
helm show values collabora/collabora-online

操作：選擇一個符合變更控制策略的圖表版本，並記錄它部署的 Collabora 鏡像版本。鎖定圖表版本以實現可重複的升級；避免在生產環境中依賴未經審核的浮動版本。圖表本身的設定指南是Collabora Online for Kubernetes 的 README 檔案。

步驟 3：準備三個副本的值

本範例假設使用 NGINX Ingress Controller，TLS 終止於入口，外部 WOPI 主機位於 [cloud.example.com此處應填入主機名稱]。請將兩個主機名稱替換為您自己的主機名稱。如果 TLS 終止於其他位置或您使用 HAProxy，請使用該控制器對應的、已記錄的設定。

replicaCount: 3

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true

上述雜湊註釋和逾時值顯示在圖表的 NGINX 範例中。該extra_params行僅適用於反向代理終止 TLS 並透過 HTTP 連線到 Collabora 的情況。如果您的 TLS 拓樸結構不同，請勿直接套用此行。請根據您的憑證管理員和本機圖表值配置入口 TLS 金鑰和主機；此處省略了這些特定於提供者的設定。

操作：將其另存為my_values.yaml，新增入口所需的 TLS 配置，並將每個金鑰與所選圖表版本的金鑰進行比較values.yaml。保持 Collabora 公共主機名稱在 DNS、TLS、整合的 Collabora URL 和代理路由中保持一致。

步驟 4：安裝 Collabora 版本

安裝到專用命名空間。替換<chart-version>為步驟 2 中所選的版本；此處的尖括號僅為說明性佔位符，不應按字面意思輸入。

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

對於現有版本，請在查看版本遷移說明和已渲染的變更後，使用計劃內的 Helm 升級。避免在首次進行擴展更改的同時部署主要鏡像或圖表更新；一次只更改一個變數可以更容易地隔離故障。

操作：檢查發布情況並等待所有副本準備就緒：

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

三個所需的副本並不能證明三個健康節點都在處理流量。請檢查就緒狀態、最近的重新啟動情況、調度情況以及入口端點。如果 Pod 仍處於掛起狀態，請檢查叢集可用容量以及圖表值中的資源請求和限制。

步驟 5：連接 WOPI 應用程式

在文件平台的 Office 整合設定中，將 Collabora 伺服器 URL 設定為公共端點，例如 `https://example.com/collabora/server/ https://office.example.comurl`。除非整合本身運行在叢集內部，並且您的設計明確支援私有路由，否則請勿將應用程式指向 Pod IP 或僅限 Kubernetes 的服務名稱。

主機名稱aliasgroups必須標識儲存和提供文件的 WOPI 主機；它不是 Collabora 主機名稱。即使 Collabora Pod 和 Ingress 運作正常，主機名稱不符也可能導致 WOPI 主機驗證失敗。

操作：在整合配置中輸入相同的 Collabora 公共 URL，儲存配置，並驗證其連接性或發現檢查是否成功。如果失敗，請在變更副本數之前檢查應用程式的 WOPI 允許清單、Collabora 的別名群組、DNS、TLS 和代理程式標頭。

步驟 6：測試文件相容性和協作性

開啟一個測試文檔，檢查入口日誌或代理日誌，確認該文檔由哪個後端伺服器處理。然後，從第二個使用者會話開啟同一個文檔，驗證兩個使用者是否都能編輯並看到對方的變更。開啟另一個文檔，確認負載平衡器能否將其傳送到另一個運作正常的 Pod。此測試旨在驗證路由和協作，而不僅僅是登入頁面是否傳回 HTTP 200 狀態碼。

操作：驗證 WOPI 來源雜湊是否存在，並確認是否一致地應用於針對相同文件產生的所有請求，包括 WebSocket 升級後的請求。如果使用者看不到彼此的編輯內容，請先比較同一文件的後端選擇，然後再檢查 WOPI 主機或瀏覽器快取。

步驟 7：測試健康處理和節點遺失

就緒檢查應確保不健康或正在啟動的 Pod 不提供服務。此圖表包含啟動、就緒和存活探測設置，但具體行為和時間取決於所選圖表版本和叢集。 Pod 不可用可能會中斷目前在該 Pod 上執行的文件；基本親和池不應被描述為即時會話複製。

操作：在測試環境中，在編輯會話進行期間移除一個 Pod，觀察客戶端行為和代理路由，然後重新開啟文件並確認其連接到運作正常的 Pod。未經批准的維護計劃，請勿在生產環境中的活躍文件上執行此測試。為了更嚴格地保證會話連續性，請評估 COOL 控制器及其特定版本的路由令牌設定。

步驟 8：有意識地監控、調整和升級

追蹤 Pod 重新啟動、CPU 和記憶體使用情況、請求和 WebSocket 錯誤、入口延遲以及使用者關於文件載入或重新連接的報告。 Collabora 的圖表文件包含 Kubernetes 監控指南。根據觀察到的工作負載設定資源，而不是複製範例數字：文件大小、並發會話數、字型和編輯模式都會影響容量。

Collabora 建議在所有負載平衡節點上執行相同版本，以便用戶端能夠獲得一致的、特定版本的 Web 資源。升級期間，請使用圖表支援的部署策略，監控就緒狀態和日誌，並在宣布變更完成之前，測試多個使用者開啟的文件。

操作：將圖表版本、鏡像版本、值檔和測試結果儲存在變更記錄中。安排升級，確認所有副本都統一到預期版本，並保留與圖表支援的回滾行為相容的回滾計劃。

常見誤區核查

「三個副本會自動建立一個工作集群。」僅使用副本無法設定文件親和性。請確認 WOPI 來源上的入口雜湊值，或者您的控制器是否提供了預期的會話路由。
「基於使用者 IP 位址的黏性會話就足夠了。」但這並非 Collabora 獨立 Kubernetes 池的設定規則。即使使用者來自不同的裝置或網絡，協作處理相同文件的使用者也必須連接到同一個節點。請配置基於文件的親和性，並使用兩位使用者進行測試。
「健康的首頁表示叢集已準備就緒。」但這只證明一個 HTTP 請求已成功返回。測試開啟和協作編輯文件、WebSocket 升級以及 pod 不可用時的行為。
「新增節點可確保活動會話在節點遺失後仍然存在。」基本的 WOPI 來源親和性池會將文件路由到某個節點；但它並不能保證其記憶體中的編輯過程會被複製。請在受控測試中確認預期的恢復行為，或評估 Controller 的獨立會話管理功能。

對於非 Kubernetes 安裝，架構原理相同，但 Kubernetes chart 指令和 ingress 註解不適用。請使用適用於您的 Collabora 版本和負載平衡器的代理程式配置，確保支援長時間的 WebSocket 連接，並使用 WOPI 來源實作基於文件的路由。 Collabora Online SDK 手冊中描述了負載平衡和WOPISrc親和性要求；請參閱手冊中與您使用的版本對應的章節。