So konfigurieren Sie Collabora Online hinter Nginx

Was ein funktionierender Reverse-Proxy leisten sollte

Eine korrekte Collabora Online-Bereitstellung hinter Nginx bietet Nutzern eine öffentliche HTTPS-Adresse für den Editor, während der Collabora-Dienst in einem privaten Netzwerk verbleibt. Der Editor sollte seine Browserressourcen laden, Office-Funktionen erkennen, ein Dokument über die verbundene Speicherplattform öffnen und die WebSocket-Verbindung während der Bearbeitung aufrechterhalten. Eine reine Nginx-Syntaxprüfung beweist nicht, dass diese Pfade funktionieren.

Dieses Beispiel geht davon aus, dass ein eigenständiger Collabora-Server oder ein CODE-Container auf Port 9980 lauscht, Nginx die Verbindung herstellt office.example.comund die TLS-Verschlüsselung bei Nginx endet. Ersetzen Sie Hostname und Zertifikatspfad durch Ihre eigenen. Die Backend-Adresse 127.0.0.1:9980gilt nur, wenn Nginx und Collabora denselben Host verwenden und der Dienst an Loopback gebunden ist. Verwenden Sie für separate Container den Collabora-Dienstnamen in einem privaten Docker-Netzwerk, z. B. `/usr/local/` http://collabora:9980.

Vor der Änderung von Nginx

Stellen Sie sicher, dass der öffentliche DNS-Name zum Proxy aufgelöst wird, dass das TLS-Zertifikat diesen Namen exakt abdeckt und dass Nginx Collabora über seine interne Adresse erreichen kann. Wenn Sie Docker verwenden, binden Sie beide Dienste in ein benutzerdefiniertes Netzwerk ein und veröffentlichen Sie den Collabora-Port nicht öffentlich. Wenn Nginx auf dem Host läuft, binden Sie den Container-Port beispielsweise an den Loopback-Port 127.0.0.1:9980:9980. Ihre Firewall sollte die öffentlichen Webports freigeben, die Sie bereitstellen möchten, nicht den Collabora-Backend-Port.

Wählen Sie eine TLS-Konfiguration. Die untenstehende Konfiguration verwendet TLS vom Browser zu Nginx und unverschlüsseltes HTTP über einen vertrauenswürdigen privaten Hop zu Collabora. Dies entspricht der TLS-Terminierung. Falls die Richtlinie auch eine Verschlüsselung zwischen Proxy und Collabora vorschreibt, verwenden Sie HTTPS für den Upstream und konfigurieren Sie Nginx so, dass es dem Backend-Zertifikat vertraut. Ändern Sie nicht nur das proxy_passSchema: Die serverseitigen TLS-Einstellungen müssen mit dem tatsächlichen Collabora-Listener übereinstimmen. Collabora dokumentiert beide Proxy-Konfigurationen in seiner Anleitung für Nginx-Reverse-Proxys und im SDK-Handbuch 25.04 .

Collaboras Proxy-fähige TLS-Optionen festlegen

Für die TLS-Terminierung konfigurieren Sie den Collabora- coolwsdDienst mit ssl.enable=falseden entsprechenden Parametern ssl.termination=true. Die Vorgehensweise hängt von der Installationsmethode von Collabora ab: Bearbeiten Sie die unterstützte coolwsd.xmlKonfiguration oder verwenden Sie die dokumentierten Optionen für Ihr Paket oder Ihren Container. Bei Verwendung des CODE-Docker-Images werden die Optionen üblicherweise als `<options>` übergeben extra_params; prüfen Sie die Image-Dokumentation für Ihre Version und geben Sie die Argumente in Compose korrekt an. Starten Sie den Collabora-Dienst nach der Konfigurationsänderung neu oder erstellen Sie ihn neu.

Diese Einstellungen weisen Collabora an, die externe Verbindung durch den Proxy zu schützen, obwohl die Verbindung vom Proxy zum Backend über HTTP erfolgt. Sie installieren kein öffentliches Zertifikat, konfigurieren kein DNS und autorisieren keinen Speicherserver zur Nutzung von Collabora. Konfigurieren Sie die WOPI-Host-Zulassungsliste oder die Integrationseinstellungen separat entsprechend Ihrer Speicherplattform.

Konfigurieren Sie Nginx so, dass die Editor-Routen weitergeleitet werden.

Nginx muss die Discovery- und Browserressourcen weitergeben und das für die interaktive Bearbeitung verwendete WebSocket-Upgrade beibehalten. Im Folgenden finden Sie ein Beispiel für einen einzelnen Server. Definieren Sie die Umgebungsvariable mapim Nginx - httpKontext, z. B. die Hauptkonfigurationsvariable nginx.conf, nicht innerhalb des virtuellen Hosts.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Fügen Sie den Serverblock in die von Nginx bereitgestellte Site-Konfiguration ein. Dies setzt voraus, dass TLS-Zertifikate bereits installiert sind und die Proxy-zu-Collabora-Verbindung über HTTP erfolgt.

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

Die mit beginnenden Pfade /cooltransportieren die Haupt-WebSocket- und Editor-Anfragen; das Muster enthält /loolaus Kompatibilitätsgründen auch ältere Pfade. Der WebSocket-Proxy von Nginx benötigt die HTTP/1.1-Upgrade-Header, da Upgradees Connectionsich um Hop-by-Hop-Header handelt. Das lange Lese-Timeout verhindert, dass eine ansonsten aktive Bearbeitungsverbindung aufgrund eines kurzen Proxy-Timeouts geschlossen wird. Weitere Informationen finden Sie in der Nginx-WebSocket-Proxy-Dokumentation und der Referenz zum Proxy-Modul .

Für HTTPS auf dem Upstream-Server ändern Sie die Backend-URLs https://und konfigurieren Sie die Upstream-Zertifikatsprüfung und die vertrauenswürdige Zertifikatskette von Nginx entsprechend. Vermeiden Sie es, die Zertifikatsprüfung dauerhaft zu deaktivieren. Befindet sich Nginx in einem separaten Container, ersetzen Sie die Loopback-Adresse durch den Namen des Collabora-Dienstes; 127.0.0.1innerhalb des Proxy-Containers verweist die Adresse auf diesen Proxy-Container.

Bei Verwendung eines URI-Präfixes anstelle /collabora/eines dedizierten Hostnamens ist eine zusätzliche Pfadbehandlung für die Konfiguration und die von Collabora generierten Discovery-URLs erforderlich. Verwenden Sie daher zunächst einen dedizierten Hostnamen, es sei denn, Ihre Plattform unterstützt explizit die Bereitstellung von Unterpfaden. Ein Serverblock, der Anfragen an das Stammverzeichnis weiterleitet, sorgt nicht automatisch dafür, dass die von der Discovery generierten URLs unter einem Präfix funktionieren.

Jede Ebene neu laden und überprüfen.

Überprüfen Sie die Nginx-Konfiguration, bevor Sie sie anwenden, und laden Sie anschließend den Dienst neu:

sudo nginx -t
sudo systemctl reload nginx

Schlägt die Syntaxprüfung fehl, korrigieren Sie zuerst die gemeldete Datei und Zeile. Ein erfolgreicher Neustart bestätigt, dass Nginx die Konfiguration akzeptiert hat, nicht aber, dass der Backend-Server, das Zertifikat oder der WebSocket-Pfad funktionieren. Überprüfen Sie DNS und Zertifikatsgültigkeit separat und fordern Sie anschließend die beiden Collabora-Endpunkte über den öffentlichen Hostnamen an.

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

Der Discovery-Endpunkt sollte XML und nicht etwa eine Nginx-404-Seite oder eine Anmeldeseite zurückgeben; die Capabilities sollten eine Antwort von Collabora liefern. Überprüfen Sie die URLs im Editor des Discovery-XML: Sie sollten den öffentlichen HTTPS-Hostnamen und erreichbare Pfade verwenden, nicht einen Containernamen oder eine interne Adresse. Die untenstehende Beispielabbildung zeigt die erwarteten Antworttypen; die angezeigten Werte dienen nur der Veranschaulichung und stammen nicht von einem Live-Server.

Konfigurieren Sie abschließend Ihre Dokumentenplattform so, dass https://office.example.comsie Collabora als Server verwendet, und öffnen Sie ein Testdokument. Ein hilfreiches Indiz für den Erfolg ist, dass der Editor geladen wird und während des Schreibens, Speicherns und erneuten Öffnens des Dokuments reagiert. In den Entwicklertools des Browsers /cool/sollte die WebSocket-Anfrage unter „Erfolgreich aktualisiert“ angezeigt werden; der HTTP-Statuscode 101 Switching Protocolsentspricht dem erwarteten Ergebnis des WebSocket-Handshakes. Betrachten Sie einen gezeichneten Beispielstatus nicht als Beweis dafür, dass Ihr eigener Server diese Prüfung bestanden hat.

Fehler anhand ihrer Symptome erkennen

• 502 Bad Gateway: Nginx kann den Upstream-Server nicht erreichen. Überprüfen Sie den Dienstnamen, den Port, das Containernetzwerk, den Listener und die Logs. Wenn die Container getrennt sind, verwenden Sie nicht die Loopback-Adresse des Proxy-Containers.
• Fehler 404 bei der Erkennung oder Browser-Ressourcen: Prüfen Sie, ob die Anfrage den korrekten virtuellen Host erreicht und ob der Pfad ohne unbeabsichtigte URI-Umschreibung weitergeleitet wird. Testen Sie die öffentliche URL, nicht nur die Backend-URL.
• Der Editor lädt, hängt sich aber auf oder die Verbindung wird getrennt: Überprüfen Sie die /cool/.../wsAnfrage. Fehlende Upgrade-Header, eine HTTP/1.0-Upstream-Verbindung, ein kurzes Timeout oder ein Proxy, der die Verbindung puffert, können die Bearbeitung unterbrechen. Stellen Sie sicher, dass die Anfrage aktualisiert wird und offen bleibt, solange das Dokument aktiv ist.
• Nicht autorisierter WOPI-Host: Der Proxy kann funktionieren, Collabora lehnt die Speicherplattform jedoch ab. Überprüfen Sie den tatsächlichen WOPI-Hostnamen anhand der Zulassungsliste von Collabora und der Connector-Konfiguration der Plattform. Öffnen Sie das Backend nicht für das öffentliche Internet, um das Problem zu beheben.
• Warnung bei gemischten Inhalten oder fehlerhaftem Zertifikat: Stellen Sie sicher, dass die öffentliche Editor-URL und die URLs in der Discovery-Umgebung HTTPS verwenden und das Zertifikat mit dem Hostnamen übereinstimmt. Wenn Sie TLS bei Nginx beenden, überprüfen Sie auch die entsprechende Einstellung in Collabora.

Sobald diese Prüfungen erfolgreich abgeschlossen sind, sollte das Collabora-Backend privat bleiben und die Logs von Nginx und Collabora bei Aktualisierungen der Komponenten überwacht werden. Dieses Beispiel mit einem einzelnen Upstream-Server konfiguriert weder Hochverfügbarkeit noch Lastverteilung oder dokumentenspezifische Sitzungszuordnung. Bei mehreren Collabora-Replikaten befolgen Sie die Bereitstellungshinweise für den jeweiligen Collabora-Controller oder Load Balancer und testen Sie die Dokumentenzuordnung, bevor Sie den Produktionsdatenverkehr weiterleiten.

Quellen und Versionshinweise

Die Konfigurationsdetails wurden am 6. Oktober 2026 anhand der Collabora-Proxy-Dokumentation und des SDK-Handbuchs (Version 25.04) sowie der Nginx-Referenzen zu WebSocket und dem Proxy-Modul überprüft. Paket- und Containeroptionen können je nach Collabora-Version variieren; überprüfen Sie daher die Einstellungsnamen für Ihre Version, bevor Sie diese anwenden. Dieser Artikel setzt keine bestimmte Speicherplattform voraus und stellt keine Live-Implementierung dar.