Die WebSocket-Verbindung von Collabora über den Proxy wiederherstellen

Wenn Collabora Online meldet, dass eine Socket-Verbindung unerwartet geschlossen wurde, prüfen Sie zunächst, ob die WebSocket-Anfrage des Browsers coolwsdüber den Reverse-Proxy läuft. Passen Sie die Proxy-Route an die Collabora-Version an, behalten Sie das WebSocket-Upgrade und den URL-Pfad bei und testen Sie anschließend ein Dokument, während Sie die Netzwerk- und Serverprotokolle des Browsers überwachen. Falls das Problem nach einem Upgrade auf CODE 26.04 hinter Apache aufgetreten ist, prüfen Sie ProxyPasszuerst die Apache-Regeln: Die Versionshinweise zu Collabora 26.04 weisen auf eine Änderung der kompakten WebSocket-URL hin.

Ein WebSocket ist die dauerhafte, bidirektionale Verbindung, die Collabora zwischen Browser und Server nutzt, solange ein Dokument geöffnet ist. Ein Reverse-Proxy ist der Dienst, der die öffentliche Anfrage entgegennimmt und an Collabora weiterleitet. Die Fehlermeldung verweist zwar auf diese Verbindung, beweist aber nicht, dass der Proxy die Ursache ist; ein abgelehnter WOPI-Host, eine falsche öffentliche URL, ein TLS-Fehler oder ein falsches Backend können die Sitzung ebenfalls unterbrechen.

Bevor Sie irgendetwas ändern, ermitteln Sie Ihre Route.

Notieren Sie die Collabora-Version bzw. das Image-Tag, die Proxy-Software, den öffentlichen Collabora-Hostnamen und ob die TLS-Verschlüsselung beim Proxy oder bei Collabora endet. Überprüfen Sie den Dienstnamen und das aktuelle Image, ohne die Bereitstellung zu ändern.

docker compose ps collabora
docker compose images collabora

Ersetzen Sie collabora<servicename> durch den Dienstnamen in Ihrer Compose-Datei. Verwenden Sie für einen Nicht-Compose-Container <containername> docker psund docker inspect<imagename>, um Container und Image zu identifizieren. Gehen Sie nicht davon aus, dass das latestTag noch auf dieselbe Version verweist, die Sie letzte Woche getestet haben.

1. Prüfen Sie, wo der WebSocket-Handshake abbricht.

Öffnen Sie im Browser die Entwicklertools, wählen Sie „Netzwerk“ , filtern Sie nach „WS“ oder „WebSocket“ und versuchen Sie erneut, ein Dokument zu öffnen. Die Anfrage-URL sollte verwendet werden, wss://wenn die öffentliche Seite HTTPS verwendet. Wählen Sie die fehlgeschlagene Anfrage aus und notieren Sie sich deren Status, URL-Pfad und Antwortheader. Ein erfolgreicher Handshake gibt normalerweise eine Antwort zurück 101 Switching Protocolsund bleibt so lange aktiv, wie die Dokumentsitzung aktiv ist.

• Es wird keine WebSocket-Anfrage angezeigt: Überprüfen Sie die Collabora-URL der Integrations-App, die Browserkonsole, das DNS und alle Weiterleitungs- oder Mixed-Content-Fehler, bevor Sie die Serverregeln bearbeiten.
• Die Anfrage liefert den Statuscode 400 oder 404: Vergleichen Sie den angeforderten Pfad mit der Route, die Ihr Proxy weiterleitet, und der von der installierten Collabora-Version unterstützten Route. Ein Statuscode 400 mit coolwsdder Meldung „Ungültige oder unbekannte Anfrage“ kann bedeuten, dass die Anfrage Collabora mit einem nicht akzeptierten Pfad erreicht hat.
• Die Anfrage liefert den Fehlercode 502 oder 504 zurück: Prüfen Sie, ob der Proxy den konfigurierten Collabora-Upstream erreichen kann und ob Adresse und Port auf den richtigen Container oder Host verweisen.
• Die Anfrage liefert den Statuscode 101 zurück und wird später geschlossen: Überprüfen Sie Proxy, Load Balancer, Firewall und die Leerlauf-Timeouts des Client-Netzwerks. Da WebSockets eine lange Lebensdauer haben, kann ein zwischengeschaltetes System, das inaktive Verbindungen zu früh schließt, einen ansonsten erfolgreichen Verbindungsaufbau unterbrechen.

2. Vergleichen Sie die Proxy-Regel mit Ihrer Collabora-Version.

Verwenden Sie die aktuellen Reverse-Proxy-Einstellungen von Collabora für Ihre Proxy-Software und -Version. Stellen Sie sicher, dass die WebSocket-Route als solche behandelt wird, der Proxy die Upgrade-Header weiterleitet und Pfad und kodierte Abfragezeichenfolge beibehält, anstatt sie umzuleiten oder zu überschreiben. Der Proxy muss außerdem Hostname und Schema konsistent mit den in Collabora konfigurierten Einstellungen für externen Servernamen und TLS-Terminierung senden.

Prüfen Sie für Nginx die WebSocket-spezifische Location und die HTTP/1.1-, Weiterleitungs- Upgradeund ConnectionRouting-Direktiven im aktuellen Beispiel von Collabora. Vergleichen Sie für Apache die ProxyPassRegel und die Reihenfolge mit dem aktuellen Beispiel; kopieren Sie keine alte /cool/…/wsÜbereinstimmung unverändert, ohne zu prüfen, welche Anforderungen Ihre installierte Version aktuell stellt.

Diese Versionsprüfung ist für CODE 26.04 relevant. Die Release Notes von Collabora vom 8. Juni 2026 beschreiben eine kompaktere WebSocket-URL und weisen darauf hin, dass Benutzer von Apache-Reverse-Proxys ProxyPassdies berücksichtigen müssen. In späteren Versionen von CODE 26.04 wurde ein Fallback-Verhalten für ältere URLs eingeführt, sodass eine ältere Regel in einigen Builds möglicherweise noch funktioniert. Der aktualisierte WebSocket-Bericht von Collabora für CODE 26.04 dokumentiert diese Nachbearbeitung. Der Fallback ersetzt nicht die Anpassung der aktuellen Proxy-Konfiguration an die installierte Version. Lesen Sie die Release Notes zu CODE 26.04 und das aktualisierte SDK-Beispiel gemeinsam.

3. Erfassen Sie einen Fehler und nehmen Sie eine gezielte Änderung vor.

Starten Sie einen kurzen Log-Stream, bevor Sie versuchen, das Dokument erneut zu verarbeiten. Die Docker- --sinceOption begrenzt die anfängliche Ausgabe, während --followneue Zeilen gestreamt werden; siehe die Docker Compose-Log-Referenz .

docker compose logs --since=2m --follow collabora

Notieren Sie den Zeitpunkt des Tests und suchen Sie in den Collabora- und Proxy-Logs nach derselben Anfrage. Falls der Browser einen Pfad anfordert, den der Proxy an das falsche Backend weiterleitet, aktualisieren Sie nur diese WebSocket-Route mithilfe des versionsgleichen Beispiels von Collabora. Falls die Anfrage Collabora erreicht, aber Host, Ursprung oder Schema abgelehnt werden, vergleichen Sie den öffentlichen Hostnamen und Port mit dem konfigurierten Servernamen und den weitergeleiteten Headern. Falls das Log stattdessen eine WOPI-Hostablehnung oder eine fehlgeschlagene Dateiinformationsanfrage anzeigt, prüfen Sie den zulässigen Host des Integrationsservers und dessen Erreichbarkeit vom Collabora-Container aus. Dies ist ein separater Schritt vom WebSocket-Handshake des Browsers.

Laden Sie den Proxy neu, nachdem Sie seine Konfiguration mit dem Syntaxprüfungsbefehl des Proxys validiert haben. Vermeiden Sie es, TLS-Terminierung, Host-Zulassungslisten und URL-Umschreibungen gleichzeitig zu ändern: Die Änderung einer Ursache pro Test macht das nächste Ergebnis interpretierbar. Deaktivieren Sie die TLS-Verifizierung nicht und erlauben Sie nicht jeden WOPI-Host als Abkürzung.

4. Überprüfen Sie die Korrektur vom Browser bis zum Dokument.

Versuchen Sie es erneut mit demselben Dokument. Überprüfen Sie in den Entwicklertools, ob die WebSocket-Anfrage erfolgreich beantwortet wird 101 Switching Protocolsund die Verbindung bestehen bleibt. Stellen Sie sicher, dass das Dokument vollständig geladen wird, die Verbindung aufrechterhalten wird und eine kleine Änderung erfolgreich gespeichert wird. Ein einwandfreier Verbindungsstatus allein reicht nicht aus, wenn der Zugriff auf die WOPI-Datei oder das Speichern weiterhin fehlschlägt.

Falls der Handshake weiterhin fehlschlägt, vergleichen Sie den Browser-Anfragepfad, die Proxy-Zugriffs-/Fehlerzeile und den entsprechenden coolwsdLogeintrag mit demselben Zeitstempel. Dieser Vergleich an drei Punkten zeigt, ob Browser, Proxy, Collabora-Route oder WOPI-Host als nächstes untersucht werden sollte. Schwärzen Sie bei Anfragen an den Support Zugriffstoken, Dokumentkennungen, Benutzernamen und private Hostnamen sowohl in den Browserdetails als auch in den Logs.