So richten Sie einen Collabora Online-Cluster mit mehreren Knoten ein

Ein Collabora Online-Cluster besteht nicht einfach nur aus mehreren fehlerfreien coolwsdServern hinter einem Round-Robin-Loadbalancer. Die gemeinsame Bearbeitung setzt voraus, dass Anfragen für dasselbe Dokument an denselben Collabora-Knoten gesendet werden. WOPISrcAus diesem Grund dokumentiert das Kubernetes-Chart von Collabora das Routing anhand der WOPI-Dokumentkennung. Diese Anleitung verwendet das gepflegte Collabora-Helm-Chart für Kubernetes als konkretes Multi-Node-Setup und beschreibt, welche Änderungen für einen anderen Ingress-Controller oder eine Nicht-Kubernetes-Bereitstellung erforderlich sind.

Bestätigt: Das Collabora-Chart unterstützt mehrere Replikate und beschreibt die Dokumentenaffinität WOPISrc. Bereitstellungsabhängig: Ingress-Annotationen, TLS-Terminierung, Ressourcenanforderungen und die Eignung eines Session-Controllers. Nicht sicher davon auszugehen, dass jeder Load Balancer oder jede „Sticky Session“-Einstellung die Dokumentenaffinität beibehält. Überprüfen Sie das controllerspezifische Verhalten und testen Sie es, bevor Sie Benutzer in den Cluster verschieben.

Was der Cluster leistet – und was er nicht leistet

In einer Standard-Multi-Replikat-Bereitstellung kann jeder Collabora-Knoten Dokumente bereitstellen, während ein Proxy die Anfragen für jedes Dokument an einen Knoten weiterleitet. Dadurch werden die einzelnen Dokumente im gesamten Pool verteilt. Dies bedeutet jedoch nicht, dass jeder Knoten denselben Live-Bearbeitungsprozess nutzt oder dass ein Dokument, dessen Bearbeitung läuft, nahtlos verschoben werden kann, wenn sein Knoten ausfällt.

Collabora dokumentiert außerdem einen COOL-Controller für Kubernetes, der einen anderen Ansatz für das Sitzungsmanagement bietet. Dessen Routing und Konfiguration unterscheiden sich von einem eigenständigen Replikatpool. Dieser Artikel konfiguriert das einfachere WOPI-Quellaffinitätsmodell; kombinieren Sie es nicht mit controllerspezifischen Routentoken-Einstellungen, es sei denn, Sie haben den Controller für Ihre Release bereitgestellt und konfiguriert.

Vorgehensweise: Entscheiden Sie, ob Sie einen einfachen replizierten Collabora-Dienst für Kapazität und Knotenredundanz benötigen oder eine Controller-verwaltete Konfiguration mit sitzungsbasierter Funktionsweise. Letztere erfordert zusätzliche Komponenten und versionsspezifische Konfigurationen. Lesen Sie die Übersicht zum Collabora Online Controller, wenn Sie diese Option in Betracht ziehen.

Bevor Sie bereitstellen

• Ein funktionierender Kubernetes-Cluster, Helm, DNS für einen öffentlichen Collabora-Hostnamen und ein TLS-fähiger Ingress- oder Reverse-Proxy.
• Eine WOPI-Integration wie Nextcloud, die so konfiguriert ist, dass sie den einzigen öffentlichen Collabora-Hostnamen anstelle einzelner Pod-Adressen verwendet.
• Der oder die WOPI-Hosts, die Collabora akzeptieren darf, werden in der Chart- collabora.aliasgroupsKonfiguration eingegeben.
• Ausreichend CPU und Arbeitsspeicher für die Dokumentenverarbeitung sowie eine Möglichkeit zur Überprüfung des Pod-Zustands, der Eingangsprotokolle und der Ressourcennutzung.
• Ein Wartungsfenster für die erste Einführungsphase und ein Testdokument mit zwei separaten Benutzerkonten.

Ein dedizierter Collabora Online-Dienst unterscheidet sich vom in Nextcloud integrierten CODE-Server. Nextcloud beschreibt seine integrierte Option als für den persönlichen Gebrauch oder kleine Teams gedacht und ohne die erweiterten Skalierungsfunktionen eines dedizierten Servers. Empfehlung: Wenn Sie einen Collabora-Pool mit mehreren Knoten benötigen, planen Sie den Einsatz eines dedizierten Dienstes und prüfen Sie das für Ihre Bereitstellung geeignete Lizenz- und Supportmodell. Weitere Informationen finden Sie im Nextcloud Office-Installationshandbuch .

Schritt 1: Wählen Sie das Routing-Modell aus

Das dokumentierte Standalone-Modell verwendet einen Hashwert WOPISrc, der das Dokument in WOPI-Anfragen identifiziert. Anfragen für ein Dokument müssen denselben Pod erreichen; Anfragen für verschiedene Dokumente können auf verschiedene Pods verteilt werden. Eine generische Round-Robin-Regel erfüllt diese Anforderung nicht.

Maßnahme: Verwenden Sie eine in der Chart-Dokumentation unterstützte Ingress-Implementierung, z. B. die dokumentierten NGINX- oder HAProxy-Ingress-Beispiele, oder nutzen Sie den im Chart enthaltenen Reverse-Proxy im Namespace, falls der Cluster keinen geeigneten Ingress-Controller zulässt. Wenn Sie einen anderen Proxy verwenden, stellen Sie sicher, dass dieser Anfragen über die WOPI-Quelle sowohl für normale HTTP-Anfragen als auch für dauerhafte WebSocket-Verbindungen konsistent weiterleiten kann.

Schritt 2: Überprüfen Sie das Diagramm und wählen Sie eine Version aus

Die Tabelle und ihre Werte ändern sich mit der Zeit. Prüfen Sie vor der Installation die aktuelle offizielle README-Datei der Tabelle und die Werte, anstatt eine Konfiguration aus einer älteren Version zu kopieren. Die folgenden Beispiele basieren auf der aktualisierten Collabora-Tabellendokumentation vom 6. Oktober 2026. Die aktuellen Versionshinweise und Werte des Repositorys sind für Ihre Installation maßgeblich.

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

Aktion: Wählen Sie eine Chart-Version, die Ihrer Änderungsrichtlinie entspricht, und notieren Sie die Version des bereitgestellten Collabora-Images. Fixieren Sie die Chart-Version für wiederholbare Aktualisierungen; vermeiden Sie die Verwendung einer ungeprüften, dynamischen Version in der Produktion. Die zugehörige Einrichtungsanleitung finden Sie in der README-Datei von Collabora Online für Kubernetes .

Schritt 3: Werte für drei Replikate vorbereiten

Dieses Beispiel setzt den NGINX Ingress Controller, TLS-Terminierung am Ingress und einen externen WOPI-Host voraus cloud.example.com. Ersetzen Sie beide Hostnamen durch Ihre eigenen. Falls die TLS-Terminierung an anderer Stelle erfolgt oder Sie HAProxy verwenden, nutzen Sie stattdessen die entsprechende, dokumentierte Konfiguration dieses Controllers.

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

Die oben genannten Hash-Annotationen und Timeout-Werte werden im NGINX-Beispiel des Diagramms dargestellt. Diese extra_paramsZeile ist nur dann relevant, wenn der Reverse-Proxy TLS beendet und die Verbindung zu Collabora über HTTP herstellt. Wenden Sie sie nicht unverändert an, wenn Ihre TLS-Topologie abweicht. Konfigurieren Sie das Ingress-TLS-Secret und den Host entsprechend Ihrem Zertifikatsmanager und den lokalen Diagrammwerten; die anbieterspezifischen Einstellungen sind im Auszug nicht enthalten.

Aktion: Speichern Sie dies unter einem anderen Namen my_values.yaml, fügen Sie die für Ihren Ingress erforderliche TLS-Konfiguration hinzu und vergleichen Sie jeden Schlüssel mit dem der ausgewählten Chart-Version values.yaml. Stellen Sie sicher, dass der öffentliche Hostname von Collabora in DNS, TLS, der Collabora-URL der Integration und im Proxy-Routing einheitlich ist.

Schritt 4: Installieren Sie die Collabora-Version

Installieren Sie die Datei in einem dedizierten Namensraum. Ersetzen Sie <chart-version>die Platzhalter durch die in Schritt 2 ausgewählte Version; die spitzen Klammern dienen lediglich der Erläuterung und sollten nicht wörtlich eingegeben werden.

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

Bei einer bestehenden Version empfiehlt sich ein geplantes Helm-Upgrade, nachdem die Migrationshinweise und die gerenderten Änderungen der Version geprüft wurden. Vermeiden Sie es, ein größeres Image- oder Chart-Update gleichzeitig mit Ihrer ersten Skalierungsänderung bereitzustellen; die Änderung jeweils nur einer Variable erleichtert die Fehlersuche.

Aktion: Überprüfen Sie die Freigabe und warten Sie, bis alle Replikate bereit sind:

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

Drei gewünschte Replikate sind kein Beweis dafür, dass drei fehlerfreie Knoten den Datenverkehr verarbeiten. Überprüfen Sie die Bereitschaft, kürzliche Neustarts, die Planung und die Eingangs-Endpunkte. Falls Pods weiterhin ausstehen, prüfen Sie die verfügbare Clusterkapazität sowie die Ressourcenanforderungen und -limits in den Diagrammwerten.

Schritt 5: Verbinden Sie die WOPI-Anwendung

Legen Sie in den Office-Integrationseinstellungen der Dateiplattform die Collabora-Server-URL auf den öffentlichen Endpunkt fest, z. B. https://office.example.com. Verwenden Sie für die Anwendung keine Pod-IP-Adresse oder einen Kubernetes-spezifischen Dienstnamen, es sei denn, die Integration selbst läuft innerhalb des Clusters und privates Routing wird von Ihrem Design explizit unterstützt.

Der Hostname aliasgroupsmuss den WOPI-Host identifizieren, der Dokumente speichert und bereitstellt; es handelt sich nicht um den Collabora-Hostnamen. Eine Diskrepanz kann zu Validierungsfehlern des WOPI-Hosts führen, selbst wenn die Collabora-Pods und der Ingress fehlerfrei funktionieren.

Aktion: Geben Sie dieselbe öffentliche Collabora-URL in der Integrationskonfiguration ein, speichern Sie diese und überprüfen Sie, ob die Verbindungs- oder Erkennungsprüfung erfolgreich ist. Falls dies fehlschlägt, überprüfen Sie die WOPI-Zulassungsliste der Anwendung, die Collabora-Aliasgruppen sowie DNS-, TLS- und Proxy-Header, bevor Sie die Replikatanzahl ändern.

Schritt 6: Dokumentenaffinität und Zusammenarbeit testen

Öffnen Sie ein Testdokument und prüfen Sie die Ingress- oder Proxy-Logs, um festzustellen, welches Backend es bereitstellt. Öffnen Sie anschließend dasselbe Dokument in einer zweiten Benutzersitzung und vergewissern Sie sich, dass beide Benutzer die Änderungen des jeweils anderen bearbeiten und sehen können. Öffnen Sie ein anderes Dokument und prüfen Sie, ob der Load Balancer es an einen anderen fehlerfreien Pod weiterleiten kann. Der Test dient der Überprüfung von Routing und Zusammenarbeit und nicht nur der Frage, ob die Landingpage den HTTP-Statuscode 200 zurückgibt.

Maßnahme: Prüfen Sie, ob der WOPI-Quellhash vorhanden ist und konsistent auf die Anfragen für dasselbe Dokument angewendet wird, einschließlich des WebSocket-Upgrades. Falls Benutzer die Änderungen anderer nicht sehen, vergleichen Sie die Backend-Auswahl für dasselbe Dokument, bevor Sie den WOPI-Host oder den Browser-Cache untersuchen.

Schritt 7: Testen der Integritätsbehandlung und des Knotenverlusts

Bereitschaftsprüfungen sollen verhindern, dass fehlerhafte oder neu gestartete Pods außer Betrieb genommen werden. Das Diagramm enthält Einstellungen für Start-, Bereitschafts- und Lebendigkeitsprüfungen, das genaue Verhalten und die Zeitabläufe hängen jedoch von der gewählten Diagrammversion und dem Cluster ab. Wenn ein Pod nicht mehr verfügbar ist, können aktuell auf diesem Pod ausgeführte Dokumente unterbrochen werden; ein einfacher Affinitätspool sollte nicht als Live-Sitzungsreplikation bezeichnet werden.

Maßnahme: Entfernen Sie in einer Testumgebung während einer aktiven Bearbeitungssitzung einen Pod vom Dienst, beobachten Sie das Clientverhalten und das Proxy-Routing und öffnen Sie anschließend das Dokument erneut, um sicherzustellen, dass es einen fehlerfreien Pod erreicht. Führen Sie diesen Test nicht ohne genehmigten Wartungsplan an aktiven Produktionsdokumenten durch. Um eine stabilere Sitzungskontinuität zu gewährleisten, evaluieren Sie den COOL Controller und dessen versionsspezifische Route-Token-Konfiguration.

Schritt 8: Überwachen, optimieren und gezielt aufrüsten

Verfolgen Sie Pod-Neustarts, CPU- und Speicherauslastung, Anfrage- und WebSocket-Fehler, Eingangslatenz sowie Benutzerberichte zum Laden von Dokumenten oder zum Wiederverbinden. Die Dokumentation zu den Diagrammen von Collabora enthält Hinweise zur Kubernetes-Überwachung. Legen Sie die Ressourcen anhand der beobachteten Arbeitslast fest, anstatt Beispielwerte zu kopieren: Dokumentgröße, gleichzeitige Sitzungen, Schriftarten und Bearbeitungsmuster beeinflussen die Kapazität.

Collabora empfiehlt, auf allen Load-Balanced-Knoten dieselbe Version zu verwenden, damit Clients konsistente, versionsspezifische Webressourcen erhalten. Nutzen Sie bei Aktualisierungen die vom Chart unterstützte Rollout-Strategie, überwachen Sie die Bereitschaft und die Protokolle und testen Sie ein geöffnetes Dokument von mehreren Benutzern, bevor Sie die Änderung als abgeschlossen deklarieren.

Maßnahme: Speichern Sie die Chart-Version, die Image-Version, die Wertedatei und die Testergebnisse zusammen in Ihrem Änderungsdatensatz. Planen Sie Aktualisierungen, stellen Sie sicher, dass alle Replikate die gewünschte Version verwenden, und erstellen Sie einen Rollback-Plan, der mit dem vom Chart unterstützten Rollback-Verhalten kompatibel ist.

Häufige Irrtümer, die Sie überprüfen sollten

• „Drei Replikate bilden automatisch einen funktionierenden Cluster.“ Replikate allein konfigurieren keine Dokumentenaffinität. Stellen Sie sicher, dass die Ingress-Hashes auf der WOPI-Quelle basieren oder dass Ihr Controller das gewünschte Session-Routing bereitstellt.
• „Sticky Sessions basierend auf der IP-Adresse eines Benutzers reichen aus.“ Das entspricht nicht der Regel, die Collabora in seinem Diagramm für seinen eigenständigen Kubernetes-Pool beschreibt. Benutzer, die an einem Dokument zusammenarbeiten, müssen sich auf demselben Knoten befinden, selbst wenn sie von verschiedenen Geräten oder Netzwerken kommen. Konfigurieren Sie die dokumentenbasierte Affinität und testen Sie sie mit zwei Benutzern.
• „Eine fehlerfreie Homepage beweist, dass der Cluster bereit ist.“ Sie beweist lediglich, dass eine HTTP-Anfrage erfolgreich beantwortet wurde. Testen Sie das Öffnen und gemeinsame Bearbeiten eines Dokuments, WebSocket-Upgrades und das Verhalten, wenn ein Pod nicht verfügbar ist.
• „Das Hinzufügen eines Knotens garantiert, dass aktive Sitzungen den Ausfall eines Knotens überstehen.“ Ein einfacher WOPI-Quellaffinitätspool leitet ein Dokument an einen Knoten weiter; er stellt jedoch nicht sicher, dass dessen Bearbeitungsprozess im Arbeitsspeicher repliziert wird. Bestätigen Sie das erwartete Wiederherstellungsverhalten in einem kontrollierten Test oder bewerten Sie die separaten Sitzungsverwaltungsfunktionen des Controllers.

Bei Installationen ohne Kubernetes ist das Architekturprinzip identisch, jedoch gelten die Kubernetes-Chart-Befehle und Ingress-Annotationen nicht. Verwenden Sie die Proxy-Konfiguration für Ihre Collabora-Version und Ihren Load Balancer, stellen Sie sicher, dass dauerhafte WebSocket-Verbindungen unterstützt werden, und implementieren Sie das Routing pro Dokument mithilfe der WOPI-Quelle. Das Handbuch des Collabora Online SDK beschreibt Load Balancing und die WOPISrcAffinitätsanforderung; überprüfen Sie den entsprechenden Abschnitt im Handbuch für Ihre Version.