Collabora Online-Fehler „Socket-Verbindung unerwartet geschlossen“ beheben: WebSocket- und Proxy-Prüfungen

Collabora Online kann auf den ersten Blick einwandfrei funktionieren, aber dennoch ausfallen, sobald der Editor versucht, eine WebSocket-Verbindung herzustellen. Typisches Symptom ist ein Dokument, das zunächst geladen wird und dann meldet, dass die Socket-Verbindung unerwartet geschlossen wurde, manchmal begleitet von einer fehlgeschlagenen wss://Anfrage im Browser. In Version 26.04 gibt es einen versionsspezifischen Grund, dies zu überprüfen, bevor Sie Änderungen vornehmen: Der 26.04-Zweig führte eine kompaktere WebSocket-URL ein, mit der ältere Reverse-Proxy-Regeln in Konflikt geraten können.

Die offiziellen Versionshinweise von Collabora CODE 26.04 besagen, dass CODE 26.04.1 (veröffentlicht am 8. Juni 2026) von Apache2-Reverse-Proxy-Nutzern die Anpassung ihrer ProxyPass-Regel für die neue, kompakte WebSocket-URL erforderte. Die späteren Versionshinweise zu 26.04.2.x besagen, dass CODE auf die ältere URL zurückgreifen kann, wenn die neue Route nicht verfügbar ist, und eine Warnung ausgibt, die Administratoren auf die aktuellen Proxy-Empfehlungen hinweist. Der Enterprise-Zweig von Collabora Online 26.04 ist ebenfalls im Jahr 2026 aktuell. Administratoren sollten daher jede aus einer älteren Anleitung (24.04 oder 25.04) kopierte Proxy-Konfiguration mit der neuesten Herstellerdokumentation vergleichen, bevor sie das Problem als zufälligen Netzwerkfehler behandeln.

Was der Fehler tatsächlich bedeutet

Die Meldung nennt keine eindeutige Ursache. Sie bedeutet, dass die Browser-zu-Collabora-WebSocket-Verbindung entweder nie erfolgreich aktualisiert wurde oder zwar hergestellt, aber dann unerwartet wieder abgebrochen wurde. Diese Unterscheidung ist wichtig, da die Lösungsansätze unterschiedlich sind.

1. Prüfen Sie, ob der Fehler nach einem Upgrade auf Version 26.04 aufgetreten ist.

Wenn das Problem unmittelbar nach dem Wechsel von Version 25.04 oder einem älteren CODE-Image auf 26.04 auftrat, sollte der Reverse-Proxy als erstes verdächtigt werden. Dies ist keine Spekulation: Collabora hat die Änderung der kompakten WebSocket-URL in den Versionshinweisen zu 26.04 dokumentiert, und ein offizielles Projekt-Issue berichtete von WebSocket-Fehlern nach einem Upgrade auf 26.04.1, bis die Apache-Proxy-Regeln angepasst wurden.

Lösen Sie das Problem nicht durch ein blindes Downgrade, ohne den alten Proxy zu verändern. Ein Rollback kann zwar vorübergehend Abhilfe schaffen, die dauerhafte Lösung besteht jedoch darin, den Proxy an die gewünschte Version anzupassen. Verwenden Sie für Apache die aktuellen Collabora Online-Proxy-Einstellungen anstelle einer Version vor 26.04. Im WebSocket-Problembericht von Collabora für Version 26.04 ist ein Fall dokumentiert, in dem die Aktualisierung der Apache-Regeln den Betrieb wiederherstellte.

2. Beweisen Sie, ob HTTP funktioniert, während WebSocket fehlschlägt.

Testen Sie zuerst die regulären Collabora-Endpunkte:

curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilities

Eine erfolgreiche Antwort beweist, dass DNS, TLS, der Frontend-Proxy und zumindest ein Teil des Collabora-Dienstes erreichbar sind. Sie beweist jedoch nicht , dass die Dokumentbearbeitung funktioniert. Der Editor verwendet eine WebSocket-Route unter [URL einfügen] /cool/, die andere Proxy-Anforderungen hat.

Öffnen Sie anschließend die Entwicklertools Ihres Browsers, reproduzieren Sie den Fehler und untersuchen Sie das Netzwerk-Panel mit dem WS-Filter. Ein erfolgreicher WebSocket-Handshake führt normalerweise zu einem Upgrade der HTTP-Verbindung; RFC 6455 definiert die Serverantwort als HTTP-Statuscode 101, wenn das Upgrade erfolgreich war. Sollten Sie stattdessen die Statuscodes 400, 404, 405, 502 oder eine sofort fehlgeschlagene Anfrage sehen, vergleichen Sie diesen Zeitstempel mit den Logs des Reverse-Proxys und von CoolWSD.

3. Korrigieren Sie den Nginx-WebSocket-Pfad und die Header.

Für Nginx sind die wichtigen Eigenschaften unkompliziert: Die Anfrage muss den Collabora-Pfad erreichen /cool/, der Proxy muss HTTP/1.1 für einen klassischen WebSocket-Upgrade-Ablauf verwenden, die UpgradeHeader Connectionmüssen weitergeleitet werden, der ursprüngliche Host muss erhalten bleiben und das Lese-Timeout muss lang genug für eine Bearbeitungssitzung sein.

Das Collabora SDK-Handbuch zeigt seit Langem einen dedizierten WebSocket-Speicherort mit den Parametern Upgrade` <webSocket>`, Connection`<webSocket> Host`, `<webSocket>` und einem langen Parameter proxy_read_timeout. Ein offizielles Dokumentationsproblem des Collabora-Projekts wies ebenfalls auf die Notwendigkeit von WebSocket-Headern im übergeordneten Pfad hin /cool. Ein konservatives, mit Ubuntu 26.04 kompatibles Muster sieht folgendermaßen aus:

location ^~ /cool/ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

Kopieren Sie diese Konfiguration nicht in eine bestehende Produktionsumgebung, ohne die Upstream-Adresse, das TLS-Modell, die Pfadverarbeitung und alle vorhandenen Sicherheitskontrollen anzupassen. Die richtige Vorgehensweise ist, Ihre Topologie beizubehalten und gleichzeitig die aktuellen Routen- und Header-Anforderungen von Collabora zu erfüllen.

Warum Timeout-Werte wichtig sind

WebSocket-Bearbeitungssitzungen sind lang anhaltend. Die aktuellen Helm-Werte des Collabora-Projekts beschreiben dies explizit und verwenden ein hohes Proxy-Timeout für den integrierten Nginx-Proxy. Falls Ihr Edge-Loadbalancer, Kubernetes-Ingress, CDN, Ihre Firewall oder Ihr Reverse-Proxy inaktive Verbindungen schneller schließt, als die Anwendung erwartet, können Benutzer eine Zeit lang normal bearbeiten und werden dann in regelmäßigen Abständen getrennt.

Tritt der Fehler jedes Mal nach etwa der gleichen Anzahl von Sekunden auf, sollten Sie alle Zwischenstationen im Pfad überprüfen, anstatt nur das Timeout von Nginx zu erhöhen. Das kürzeste Timeout ist maßgebend.

4. Sicherstellen, dass die TLS-Terminierung konsistent ist

Eine gängige Bereitstellungsmethode beendet HTTPS bei Nginx, Apache, HAProxy, Traefik oder einem Ingress-Controller und leitet unverschlüsseltes HTTP an Collabora auf Port 9980 weiter. In diesem Fall erfordert die offizielle Collabora-Konfiguration, dass das Backend weiß, dass TLS vom Proxy beendet wird. Die SDK-Dokumentation ssl.enable=falsebeschreibt ssl.termination=truedieses Modell.

Bei einer Docker-Bereitstellung wird dies üblicherweise über die zusätzlichen Parameter von Collabora ausgedrückt:

--o:ssl.enable=false --o:ssl.termination=true

Verwenden Sie diese Einstellungen nur, wenn TLS tatsächlich vorgelagert beendet wird. Verbindet sich der Proxy stattdessen über HTTPS mit Collabora, konfigurieren Sie diese Topologie einheitlich und vermeiden Sie eine Vermischung der beiden Modelle. Eine Inkompatibilität kann zu falschen Schemas, fehlerhaften WebSocket-URLs, Zertifikatsfehlern oder Weiterleitungen führen, die das Upgrade verhindern.

5. Überprüfen Sie die CoolWSD-Protokolle auf Host- und Ursprungskonflikte.

Collabora validiert WebSocket-Ursprünge. Enthält das Log Einträge wie „ Rejecting WebSocket upgradegefolgt von einem Ursprung und einem erwarteten Host“, korrigieren Sie die Zuordnung von externem Hostnamen und Port, anstatt willkürlich permissive Header hinzuzufügen. Im offiziellen Collabora-Issue-Tracker finden Sie ein dokumentiertes Beispiel, in dem ein konfigurierter Servername :443ohne expliziten Port nicht mit dem Browserursprung übereinstimmte.

Welche Befehle nützlich sind, hängt von Ihrer Installation ab:

docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtest

Achten Sie auf den ersten Fehler, der gleichzeitig mit der fehlgeschlagenen WS-Anfrage auftritt. Meldungen über abgelehnte Upgrades, fehlerhafte URI-Syntax, einen unerwarteten Host oder einen nicht verfügbaren Upstream-Server sind aussagekräftiger als das allgemeine Browser-Popup.

6. Falls nur Chromium-basierte Browser Probleme haben, überprüfen Sie die HTTP/2- oder HTTP/3-Verarbeitung.

Dies ist zwar ein speziellerer Fall, aber es lohnt sich, ihn vor einem Serverneubau zu überprüfen. Das Collabora-Projekt hat einen Chromium-bezogenen Fall dokumentiert, in dem ein Proxy eine HTTP/2-CONNECT-WebSocket-Anfrage direkt an coolwsd weiterleitete und den Fehlercode 405 (Methode nicht erlaubt) erhielt. Ein weiterer Eintrag beschreibt Fehler beim Laden von Dokumenten über HTTP/3/QUIC in einem bestimmten Proxy-Pfad. Diese Berichte bedeuten nicht, dass HTTP/2 oder HTTP/3 grundsätzlich deaktiviert werden müssen; sie bedeuten lediglich, dass der Vermittler das Clientverhalten in eine von Collabora unterstützte WebSocket-Verbindung übersetzen muss.

Wenn Firefox mit demselben Konto und Dokument funktioniert, Chrome jedoch nicht, erfassen Sie das Protokoll und den Statuscode des Proxys. Beheben Sie das Verhalten des Proxys/Ingress-Servers, anstatt moderne Protokolle global zu deaktivieren, es sei denn, Ihre Umgebung bietet keine kompatible Alternative.

7. Starten Sie das System erst neu, nachdem Sie die Konfiguration überprüft haben.

Führen Sie zunächst einen Syntaxtest für den Proxy durch. Laden Sie die Seite anschließend neu, anstatt wiederholte Neustarts ohne Vorbereitung durchzuführen.

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2

Bei Containern sollte der Collabora-Dienst nur dann neu gestartet werden, wenn die Umgebung oder die Einstellungen des Containers geändert wurden coolwsd. Eine Änderung, die nur den Proxy betrifft, erfordert normalerweise lediglich einen Proxy-Neustart.

So überprüfen Sie selbst die Reparatur

Verwenden Sie eine kurze Verifizierungssequenz, anstatt sich auf das erfolgreiche Öffnen eines einzelnen Dokuments zu verlassen:

• Bestätigen Sie /hosting/discovery, dass /hosting/capabilitiesdie Benutzer über denselben öffentlichen Hostnamen erreichbar sind.
• Öffnen Sie ein Dokument und überprüfen Sie, ob die Browser-WS-Anfrage erfolgreich aktualisiert wird und nicht den Fehlercode 4xx/5xx zurückgibt.
• Geben Sie mehrere Änderungen ein, warten Sie länger als das bisherige Fehlerintervall und vergewissern Sie sich, dass die Verbindung stabil bleibt.
• Speichern und schließen Sie das Dokument und öffnen Sie es anschließend erneut, um zu überprüfen, ob die WOPI-Roundtrip-Verbindung in Ordnung ist.
• Überprüfen Sie die Protokolle von coolwsd und dem Proxy auf abgelehnte WebSocket-Upgrades, URI-Parsing-Fehler oder wiederholte Verbindungsschleifen.
• Falls Ihre Bereitstellung über einen Load Balancer oder Ingress verfügt, wiederholen Sie den Test über die reale Produktionsroute, anstatt sich direkt mit Port 9980 zu verbinden.

Welche Lösung sollten Sie wählen?

Wenn Sie auf Version 26.04 aktualisiert haben und Apache verwenden, ist die Aktualisierung der Proxy-Regeln die wichtigste Maßnahme, da Collabora diese Änderung explizit dokumentiert hat. Tritt die Verbindung nach einer bestimmten Zeit ab, überprüfen Sie die Timeout-Einstellungen an jedem Netzwerk-Hop. Ist der Fehler sofort in allen Browsern zu beobachten, überprüfen Sie /cool/das Routing, die Upgrade-Header, die Host-/Ursprungskonsistenz und die TLS-Terminierung. Tritt der Fehler nur bei einer Browserfamilie auf, vergleichen Sie die HTTP-Protokollverarbeitung, bevor Sie Änderungen an Collabora selbst vornehmen.

Entscheidend ist, dass die Meldung „Socket-Verbindung unerwartet geschlossen“ nicht standardmäßig als Absturz der Collabora-Anwendung interpretiert wird. In vielen Installationen funktionieren Editor, Discovery-Endpunkt und WOPI-Host einwandfrei, während der Reverse-Proxy die für die Live-Bearbeitung wichtigste Verbindungsart – die langlebige WebSocket-Verbindung – fehlerhaft verarbeitet.

Offizielle Referenzen

• Collabora CODE 26.04 – Versionshinweise
• Collabora Online 26.04 – Versionshinweise
• Collabora Online SDK-Proxy-Einstellungen
• CollaboraOnline/online Problem #15918: WebSocket-Fehler nach Upgrade auf Version 26.04
• CollaboraOnline/Online-Problem #13751: WebSocket-Header in der Proxy-Dokumentation
• Collabora Online Helm Proxy-Timeout-Standardeinstellungen
• RFC 6455: Das WebSocket-Protokoll