Collabora hinter Nginx einsetzen, ohne WebSockets zu beeinträchtigen

Installieren Sie Collabora auf einem dedizierten HTTPS-Hostnamen in Nginx, leiten Sie die Pfade für Editor und Discovery an `<service-name>` weiter coolwsdund übergeben Sie die WebSocket-Upgrade-Header explizit an die aktiven Socket-Routen. Bei einem einzelnen Host kann Nginx die öffentliche TLS-Verschlüsselung beenden und HTTP-Verbindungen über eine private Schnittstelle zu Collabora herstellen. Laufen Nginx und Collabora in unterschiedlichen Containern, verwenden Sie den Collabora-Dienstnamen im gemeinsamen Netzwerk anstelle von `<service-name>` 127.0.0.1.

Dieses Beispiel setzt voraus, dass Benutzer Zugriff haben https://office.example.comund Nginx das Zertifikat verwaltet. Der Standard-Listening-Port von Collabora ist 9980; verwenden Sie den in Ihrer Umgebung erreichbaren Port. Ein URL-Präfix wie z. B. https://example.com/collabora/erfordert abgestimmte Pfad- und Service-Root-Einstellungen, daher wird diese Root-Host-Konfiguration nicht unverändert angewendet.

1. Definieren Sie die Upstream- und WebSocket-Verbindungszuordnung

Fügen Sie im Nginx- httpKontext einen Upstream-Namen für Collabora und eine Map hinzu, die den Verbindungsheader upgradenur dann setzt, wenn ein Client eine WebSocket-Anfrage stellt. Platzieren Sie diesen Block außerhalb aller anderen serverBlöcke. Ersetzen Sie die Adresse, falls Nginx Collabora auf anderem Wege erreicht.

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

Wenn Nginx selbst ein Container ist, 127.0.0.1bezieht sich dies auf diesen Nginx-Container und nicht auf den Collabora-Container. In einem gemeinsam genutzten Docker-Netzwerk kann der Upstream stattdessen server collabora:9980;über den Dienstnamen erfolgen, der in diesem Netzwerk aufgelöst wird.

2. Fügen Sie den virtuellen HTTPS-Host und die Collabora-Routen hinzu.

Innerhalb des HTTPS- serverBlocks für office.example.com`/` leiten Sie die Browserressourcen, Discovery-Endpunkte, WebSocket-Verbindungen und die übrigen Collabora-Pfade weiter. Die Adressen richten sich nach den Proxy-Richtlinien von Collabora. Platzieren Sie die spezifischen Socket-Adressen oberhalb der übergeordneten Route cool`/ lool`, damit Nginx die WebSocket-Header korrekt anwendet.

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Ersetzen Sie die Zertifikatspfade durch die Dateien Ihres Hosts. Wenn Ihre Installation keine Administrationskonsole verwendet, /cool/adminwsist der Speicherort für die Dokumentbearbeitung möglicherweise nicht erforderlich; der Hauptpfad /cool/.../wsist jedoch unerlässlich. Die proxy_read_timeouthier angegebene Stunde dient lediglich als Beispiel und ist keine allgemeingültige Vorgabe. Das Standard-Read-Timeout von Nginx für Proxys beträgt 60 Sekunden zwischen aufeinanderfolgenden Lesevorgängen. Wählen Sie einen Wert, der länger ist als die für Ihre Sitzungen erforderlichen Leerlaufzeiten, oder nutzen Sie, sofern unterstützt, geeigneten WebSocket-Ping-Verkehr.

3. Passen Sie den TLS-Modus von Collabora an den Proxy-Hop an.

Nutzer sollten Collabora über HTTPS erreichen, auch wenn der private Nginx-zu-Collabora-Hop HTTP verwendet. Konfigurieren Sie in dieser TLS-Terminierungskonfiguration coolwsdden Proxy so, dass er als TLS-Terminator fungiert: SSL ist auf dem internen Listener deaktiviert und die SSL-Terminierung aktiviert. Wenden Sie diese Einstellungen mit der von Ihrem Paket oder Container-Image unterstützten Methode an und starten Sie Collabora anschließend gemäß der Dokumentation neu.

Verwenden Sie HTTP als Upstream nur in einem vertrauenswürdigen privaten Netzwerk und blockieren Sie den öffentlichen Zugriff auf Port 9980. Falls die Richtlinie eine Verschlüsselung zwischen Nginx und Collabora erfordert, verwenden Sie HTTPS als Upstream und konfigurieren Sie die Zertifikatsprüfung korrekt. Deaktivieren Sie die Prüfung nicht, um eine Zertifikatsabweichung zu verschleiern. Die Dokumentation der Proxy-Einstellungen von Collabora unterscheidet zwischen SSL am Proxy und SSL zwischen Proxy und Collabora coolwsd.

Legen Sie außerdem in der Speicherintegration die Collabora-URL auf den öffentlichen HTTPS-Hostnamen fest. Laut Nextcloud-Administrationshandbuch müssen Browser und beide Server über HTTP(S) mit übereinstimmenden externen Protokollen erreichbar sein. Beschränken Sie die WOPI-Zulassungsliste auf den erwarteten Speicherhost und die Collabora-Adresse; erweitern Sie sie nicht, um einen Proxy-Routing-Fehler zu beheben.

4. Testen Sie die Konfiguration von beiden Seiten

Überprüfen Sie die Nginx-Syntax, bevor Sie sie neu laden:

sudo nginx -t
sudo systemctl reload nginx

Wenn Nginx in einem Container läuft, verwenden Sie stattdessen die Validierungs- und Neuladeprozedur dieses Containers. Testen Sie vom Nextcloud-Host aus die öffentlichen Collabora-Endpunkte mit dem tatsächlichen Hostnamen:

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

Öffnen Sie diese HTTPS-URLs auch in einem Benutzerbrowser. Die Erreichbarkeit wird geprüft, aber eine erfolgreiche Anfrage allein beweist nicht, dass die Dokumentbearbeitung funktioniert. Öffnen Sie ein Dokument und überprüfen Sie im Netzwerk-Panel des Browsers, ob die Ressourcen geladen werden und die /cool/.../wsVerbindung bestehen bleibt. Eine erfolgreiche HTTP/1.1-WebSocket-Verbindung zeigt üblicherweise eine 405-Fehlermeldung an 101 Switching Protocols; die genaue Darstellung kann vom Browser und dem verwendeten Protokoll abhängen. Wenn diese Standardkonfiguration in Firefox funktioniert, aber in Chromium fehlschlägt, überprüfen Sie die Anfragemethode und das Protokoll. Ein Collabora-Problembericht für Version 25.04 dokumentiert eine Chromium-WebSocket-Verbindung über HTTP/2, die den Fehlercode CONNECT405 zurückgibt; der Bericht ist noch offen (Stand: 9. Oktober 2026). Dies ist ein versionsspezifischer Bericht und kein allgemeines Verhalten. Vergleichen Sie Ihre Collabora-, Nginx- und Browserversionen, bevor Sie die HTTP/2-Einstellungen ändern. Siehe Collabora-Problem 12155 .

Schlägt die Erkennung fehl, überprüfen Sie das Nginx-Fehlerprotokoll und vergewissern Sie sich über Hostname, Port und Protokoll des Upstream-Servers. Funktioniert die Erkennung, die Bearbeitungsverbindung jedoch nicht, prüfen Sie die WebSocket-Route, die Header, das Timeout und die Collabora-Protokolle. Ein WOPI-Autorisierungsfehler deutet auf die Whitelist des Speicherhosts hin. Die Nextcloud Office-Fehlerbehebungsanleitung empfiehlt, die Erreichbarkeit über Browser, Nextcloud und Collabora zu prüfen und anschließend die Protokolle beider Server zu analysieren.

Die Nginx -WebSocket-Proxy-Anleitung erklärt, warum UpgradeParameter Connectionexplizit übergeben werden müssen und warum das Verhalten bei Leerlauf-Timeout relevant ist. Informationen zum Verhalten der Direktiven finden Sie in der Referenz des Nginx-Proxy-Moduls . Sobald die Prüfungen erfolgreich waren, öffnen, bearbeiten, speichern und öffnen Sie ein Testdokument, bevor Sie Benutzer einladen, die neue Route zu verwenden.