Wie man den ONLYOFFICE Document Server hinter einem HAProxy Load Balancer betreibt

Die wichtigste Regel lautet: Die Integration des ONLYOFFICE Document Servers hinter HAProxy ist für ein einzelnes Backend unkompliziert, ein Editor-Cluster mit mehreren Knoten erfordert jedoch mehr als einfaches Round-Robin. Die aktuelle API-Dokumentation von ONLYOFFICE besagt, dass Anfragen für dasselbe Dokument während der gemeinsamen Bearbeitung denselben Document-Server-Knoten erreichen müssen. Für moderne Integrationen empfiehlt sich die Verwendung von shardkeyAbfrageparametern, die der Load Balancer für dokumentenbasierte Zugriffssteuerung nutzen kann.

Wenn Sie nur einen Dokumentenserver verwenden und HAProxy für die HTTPS-Terminierung, einen stabilen öffentlichen Hostnamen oder zentrale Integritätsprüfungen nutzen möchten, ist die Konfiguration einfacher. Bei zwei oder mehr Dokumentenserver-Knoten verwenden Sie die gleichen Proxy-Grundlagen, fügen aber ein Routing hinzu, das auf der HTTPS-Terminierung basiert, shardkeyanstatt davon auszugehen, dass das herkömmliche Round-Robin-Verfahren ausreicht.

Die folgenden Beispiele wurden anhand der aktuellen ONLYOFFICE-Proxy-Dokumentation , der ONLYOFFICE-Shard-Key-Dokumentation und der aktuellen HAProxy-WebSocket-Richtlinien überprüft .

Wenn diese Konfiguration gut passt

HAProxy ist ein sinnvolles Frontend, wenn Sie eine einzige öffentliche URL benötigen https://docs.example.com, TLS-Terminierung am Load Balancer, aktive Integritätsprüfungen oder mehrere Document-Server-Knoten hinter einem Endpunkt. Es ist auch nützlich, wenn Ihre Nextcloud, ownCloud, Ihr benutzerdefiniertes DMS oder Ihre Anwendung niemals direkt mit einem einzelnen Document-Server-Knoten verbunden werden soll.

Diese Anleitung setzt Folgendes voraus:

• HAProxy kann jeden Dokumentenserver über das interne Netzwerk erreichen.
• Jeder Dokumentenserver funktioniert bereits direkt, bevor der Load Balancer eingeführt wird.
• Der öffentliche Hostname wird zu HAProxy aufgelöst.
• Ihr TLS-Zertifikat deckt den öffentlichen Hostnamen ab.
• Wenn Sie mehrere Knoten betreiben, werden diese als unterstützte Multi-Server-ONLYOFFICE-Architektur bereitgestellt und nicht als unabhängige Standalone-Server, die lediglich zufällig einen Load Balancer gemeinsam nutzen.

Schritt 1: Überprüfen Sie jeden Dokumentenserver, bevor Sie HAProxy hinzufügen.

Beginnen Sie nicht mit dem Load Balancer. Stellen Sie zunächst sicher, dass alle Backend-Systeme vom HAProxy-Host aus fehlerfrei funktionieren. ONLYOFFICE dient /healthcheckals Endpunkt zur Überprüfung der Editorverfügbarkeit. Ein fehlerfreier Server gibt einen entsprechenden Wert zurück true; die Prüfung umfasst Kernabhängigkeiten wie Datenbank, Message Broker, Redis-Verbindung und Speicher.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

Erwartetes Ergebnis:

true
true

Wenn ein Backend-System hier ausfällt, beheben Sie zuerst das Problem an diesem Knoten. Häufige Ursachen sind Firewall-Regeln, ein falscher interner Port, nicht laufende Dokumentenserver-Dienste oder nicht verfügbare unterstützende Dienste.

Schritt 2: HTTP-Modus und Timeouts festlegen, die Editorverbindungen tolerieren

ONLYOFFICE ist eine HTTP-Anwendung und verwendet während der Bearbeitung langlebige WebSocket-Verbindungen. HAProxy kann WebSockets nach dem HTTP-Upgrade automatisch weiterleiten, die Timeout-Richtlinie ist jedoch weiterhin relevant. Die HAProxy-Dokumentation empfiehlt einen timeout tunnelWert für aktualisierte WebSocket-Verbindungen.

Eine praktische Ausgangsbasis ist:

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

Ein einstündiges Tunnel-Timeout ist ein Beispiel, keine allgemeingültige Vorgabe. Wählen Sie einen Wert, der dem Bearbeitungsverhalten, den Sicherheitsrichtlinien und den Ressourcenbeschränkungen Ihrer Organisation entspricht. Wenn sich Bearbeiter regelmäßig trennen, vergleichen Sie dieses Intervall mit den Leerlauf-Timeouts von HAProxy und etwaigen vorgelagerten Firewalls oder Reverse-Proxys.

Schritt 3: HTTPS beenden und den ursprünglichen Anfragekontext beibehalten

ONLYOFFICE benötigt explizit weitergeleitete Header, wenn es hinter einem Proxy ausgeführt wird. Insbesondere X-Forwarded-Prototeilt es dem Dokumentenserver mit, ob der ursprüngliche Client HTTP oder HTTPS verwendet hat, und X-Forwarded-Hostbewahrt den vom Client angeforderten Hostnamen.

Ein übersichtliches HAProxy-Frontend kann folgendermaßen aussehen:

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

Im modernen HTTP-Modus von HAProxy müssen Sie normalerweise keine NGINX-ähnlichen Header-Regeln manuell neu erstellen Upgrade. ConnectionHAProxy erkennt das HTTP-zu-WebSocket-Upgrade und schaltet die Verbindung in den Tunnelmodus. Wichtig ist, keine Regeln einzufügen, die die Upgrade-Anfrage beschädigen oder unterbrechen.

Um die Client-IP-Adresse sichtbar zu machen, fügen Sie dies option forwardforim Backend hinzu. Dadurch wird ein X-Forwarded-ForHeader aus der Quelladresse des Clients generiert.

Schritt 4: Gesundheitsprüfungen hinzufügen und die richtige Ausgleichsregel auswählen

Einzeldokumentenserver

Wenn HAProxy als Frontend für einen Dokumentenserver dient, kann das Backend einfach sein:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

In diesem Design fungiert HAProxy hauptsächlich als Reverse-Proxy, TLS-Endpunkt und Health-Gate.

Mehrere Dokumentenserver-Knoten

Für eine reale Multi-Node-Bereitstellung sollten Sie sich bei der gemeinsamen Bearbeitung nicht auf das einfache Round-Robin-Verfahren verlassen. Laut der aktuellen Dokumentation von ONLYOFFICE müssen alle Anfragen, die zum selben Dokument gehören, denselben Server erreichen. Browser-zu-Server-Anfragen an den Editor enthalten automatisch einen Shard-Schlüssel. Anwendungen sollten diesen Shard-Schlüssel, ?shardkey=<document-key>sofern dokumentiert, zu Befehls-, Konvertierungs- und Document-Builder-Anfragen hinzufügen.

HAProxy unterstützt Hashing von URL-Abfrageparametern, daher ist ein geeignetes Backend für die standardmäßige ONLYOFFICE Docs API:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

Der Algorithmus von HAProxy url_paramberechnet einen Hashwert für den ausgewählten Abfrageparameter. Fehlt dieser Parameter, greift HAProxy auf das normale Load-Balancing-Verhalten zurück. Daher ist es besonders wichtig, dass Ihre Integration den Shard-Schlüssel bei Anfragen sendet, bei denen ONLYOFFICE dies empfiehlt.

WOPI verhält sich anders.WOPISrc ONLYOFFICE gibt an, dass WOPI-Integrationen den Abfrageparameter für denselben Routing-Zweck verwenden . Kopieren Sie die balance url_param shardkeyZeile nicht unverändert in ein WOPI-Design und gehen Sie nicht davon aus, dass dadurch die erforderliche Affinität gewährleistet wird.

HAProxy sicher validieren und neu laden

Vor dem Neuladen des Dienstes überprüfen Sie die Konfiguration:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Erst nach erfolgreicher Syntaxprüfung neu laden:

sudo systemctl reload haproxy
sudo systemctl status haproxy

Verwendet Ihre Distribution einen anderen Dienstmanager oder Konfigurationspfad, passen Sie die Befehle entsprechend an. Ein Neustart ist einem unnötigen erzwungenen Neustart vorzuziehen, wenn Ihr HAProxy-Paket ein sanftes Neuladen der Konfiguration unterstützt.

Testen Sie über die öffentliche URL, nicht nur innerhalb des Backend-Netzwerks.

Testen Sie nun, was die Benutzer und Ihre Dokumentenmanagement-Plattform tatsächlich erreichen werden:

curl -sS https://docs.example.com/healthcheck

Der erwartete Körper ist:

true

Überprüfen Sie anschließend das TLS-Zertifikat:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

Öffnen Sie abschließend ein echtes Dokument über die integrierende Anwendung. Ein Integritätscheck bestätigt lediglich, dass der Dokumentenserver-Endpunkt bereit ist; er beweist jedoch nicht, dass Rückruf-URLs, JWT-Konfiguration, Dokument-Downloads, Speicher-Rückrufe oder die Multi-Node-Affinität korrekt sind.

Was zu überprüfen ist, wenn der Editor zwar lädt, aber die Verbindung abbricht oder das Speichern fehlschlägt.

Benötigen Sie Haftsitzungen?

Die herkömmliche IP-Adressbindung ist für ONLYOFFICE nicht die optimale Standardlösung. Mehrere Benutzer, die dieselbe Datei bearbeiten, können unterschiedliche Client-IP-Adressen haben, und ein Benutzer kann verschiedene Dokumente öffnen, die nicht auf demselben Knoten liegen müssen. Die dokumentenbasierte Adressbindung mithilfe des Shard-Keys von ONLYOFFICE ist präziser, da der Routing-Key das bearbeitete Dokument und nicht die Netzwerkadresse des Benutzers repräsentiert.

Aus demselben Grund sollte eine einfache, auf Cookies basierende Sticky Session nicht als Ersatz für das von ONLYOFFICE dokumentierte Routing-Verhalten betrachtet werden. Verwenden Sie den dokumentierten Shard-Key der Anwendung, wenn Sie eine Multi-Node-Docs-API-Bereitstellung erstellen.

Checkliste für die abschließende Konfiguration

• Jeder Dokumentenserver gibt trueeinen Wert zurück /healthcheck, bevor er zu HAProxy hinzugefügt wird.
• HAProxy läuft im HTTP-Modus für das ONLYOFFICE-Frontend und -Backend.
• Die HTTPS-Verbindung wird mit einem Zertifikat abgeschlossen, das für den öffentlichen Hostnamen des Dokumentenservers gültig ist.
• X-Forwarded-Protound X-Forwarded-Hostwerden korrekt weitergeleitet.
• Das Timeout des WebSocket-Tunnels ist lang genug für echte Bearbeitungssitzungen.
• Backend-Integritätsprüfungen entfernen ausgefallene Knoten aus dem Betrieb.
• Der Datenverkehr der Multi-Node Docs API verwendet shardkey-basierte Affinität, nicht nur einfaches Round-Robin.
• WOPISrcWOPI-Implementierungen verwenden ein für . geeignetes Routing .
• Der Gesundheitscheck funktioniert, und durch die Integration kann ein echtes Dokument geöffnet, bearbeitet und gespeichert werden.

Für einen einzelnen Dokumentenserver dient HAProxy hauptsächlich als einfacher Reverse-Proxy und TLS-Schicht. Bei mehreren Dokumentenserver-Knoten liegt der entscheidende Unterschied im dokumentenbasierten Routing. Konzipieren Sie den Proxy zunächst gemäß dieser Anforderung und ergänzen Sie ihn anschließend um Integritätsprüfungen, HTTPS und Timeout-Anpassungen.