Collabora Online-Verbindungsfehler „Das ist ja peinlich“ beheben

Die Collabora-Online-Meldung „Das ist peinlich, wir können keine Verbindung zu Ihrem Dokument herstellen“ ist ein Symptom, keine Diagnose. Sie erscheint, nachdem die Editor-Shell geladen wurde, die Dokumentsitzung aber nicht abgeschlossen werden kann. In aktuellen Installationen lässt sich das Problem am schnellsten beheben, indem man die fehlerhafte Verbindung im WOPI-Pfad identifiziert, anstatt wahllos Collabora-Einstellungen zu ändern.

Dieser Leitfaden verwendet die aktuelle Nextcloud-35-Administrationsdokumentation und die SDK-Anleitung von Collabora Online (Version 25.04) als Referenz. Die gleiche Vorgehensweise zur Fehlerbehebung gilt für viele ownCloud- und benutzerdefinierte WOPI-Integrationen, die genauen Bezeichnungen der Einstellungen können jedoch je nach Plattform und Version variieren.

Was verursacht üblicherweise diesen Collabora-Verbindungsfehler?

Eine funktionierende Browsersitzung hängt von mehreren separaten Pfaden ab. Der Browser des Benutzers muss sowohl den Speicherserver als auch Collabora erreichen können; der Speicherserver muss Collabora erreichen können; Collabora muss den Speicherserver erreichen können; die Protokolle und Zertifikate müssen kompatibel sein; und der Reverse-Proxy muss die HTTP- und WebSocket-Routen von Collabora korrekt weiterleiten. Die offizielle Fehlerbehebungsseite von Nextcloud listet diese Anforderungen an die bidirektionale Erreichbarkeit explizit auf.

Das bedeutet, es gibt keine allgemeingültige Lösung. Wählen Sie den Reparaturweg anhand des ersten fehlgeschlagenen Tests:

1. Überprüfen Sie die Collabora-Erkennungs- und Funktionsendpunkte.

Beginnen Sie mit der öffentlichen Collabora-URL, die Ihre Integration tatsächlich verwendet. Öffnen Sie diese Endpunkte in einem Browser und auf dem Speicherserver:

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

Die aktuelle Fehlerbehebungsdokumentation von Nextcloud empfiehlt beide Tests. Der Discovery-Endpunkt sollte XML zurückgeben, während Capabilities Collabora-Funktionsdaten liefert. Ein Timeout, eine Zertifikatswarnung, ein 404-Fehler, eine Proxy-Fehlerseite oder eine Weiterleitungsschleife bedeuten, dass Sie das Netzwerk oder den Reverse-Proxy reparieren sollten, bevor Sie die WOPI-Einstellungen ändern.

Prüfen Sie zuerst die öffentlichen Collabora-Discovery- und Capabilities-URLs; beide müssen über denselben Hostnamen erreichbar sein, der von der Integration verwendet wird.

Für eine verlässliche Anleitung zur Endpunktoptimierung siehe Nextcloud Office Troubleshooting und das Collabora Online 25.04 SDK-Handbuch .

2. Testen Sie alle vier Netzwerkrichtungen, nicht nur den Browser.

Ein häufiger Fehler ist die Annahme, dass office.example.comCollabora, nur weil es in einem Desktop-Browser geöffnet wird, auch Dateien vom Speicherserver abrufen kann. Das ist nicht garantiert. Testen Sie es von den tatsächlichen Hosts oder Containern aus:

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

Wenn der öffentliche Hostname in Docker, Kubernetes oder einem privaten Netzwerk unterschiedlich aufgelöst wird, entscheiden Sie, ob Sie das interne DNS korrigieren, eine entsprechende Hostzuordnung hinzufügen oder den Datenverkehr über den öffentlichen Endpunkt leiten. Internes DNS ist in der Regel bei größeren Installationen die eleganteste Lösung; ein Eintrag in der Hosts-Datei ist zwar für kleine, statische Installationen schnell erledigt, wird aber mit der Zeit schwieriger zu pflegen.

Führen Sie Erreichbarkeitstests von den Servern selbst aus durch und verwenden Sie dann das Collabora-Protokoll, um einen Netzwerkfehler von einem WOPI-Vertrauensfehler zu unterscheiden.

3. Korrigieren Sie den Reverse-Proxy, falls WebSockets- oder Collabora-Routen fehlen.

Collabora ist keine herkömmliche statische Webanwendung. Ihr Reverse-Proxy benötigt Routen für Browserressourcen, Discovery/Capabilities, Dokumenten-Traffic und WebSockets. Im SDK-Handbuch von Collabora leitet das Nginx-Beispiel /browserden WebSocket -Pfad und den zugehörigen /hosting/discoveryDatenverkehr weiter ./hosting/capabilities/cool/.../ws/cool/lool

Für die WebSocket-Route muss der Proxy den Host beibehalten und das HTTP-Upgrade weiterleiten. Ein vereinfachtes Nginx-Muster sieht folgendermaßen aus:

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 "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 36000s;
}

Kopieren Sie dies nicht unreflektiert, wenn Sie TLS anders terminieren. Collabora dokumentiert separate Muster für die End-to-End-Terminierung von TLS und SSL. Wenn TLS bei Nginx terminiert wird und die Backend-Verbindung über HTTP läuft, müssen die internen SSL-Einstellungen von Collabora diesem Design entsprechen. Die durchgängige Verwendung von HTTPS ist einfacher zu handhaben, während die TLS-Terminierung am Proxy die Zertifikatsverwaltung innerhalb von Containern reduziert, aber eine zusätzliche Konfigurationsgrenze einführt.

Ein korrekter Reverse-Proxy muss Collabora-HTTP-Routen weiterleiten und das WebSocket-Upgrade für die Dokumentsitzung beibehalten.

4. Überprüfen Sie die Konsistenz von Protokoll, Zertifikat und Hostnamen.

Die aktuelle Office-Konfigurationsdokumentation von Nextcloud gibt an, dass der Collabora Online-Server dasselbe Protokoll wie die Nextcloud-Installation verwenden sollte, wobei HTTPS empfohlen wird. In der Praxis können gemischte öffentliche HTTP/HTTPS-Konfigurationen zu blockierten Inhalten, falschen Weiterleitungszielen oder Fehlern bei der Backend-Zertifikatvalidierung führen.

Prüfen Sie diese Punkte gemeinsam:

• Die in Ihrer Speicherplattform gespeicherte Collabora-URL ist genau die öffentliche URL, die Benutzer erreichen.
• Das von diesem Hostnamen vorgelegte Zertifikat ist für diesen Hostnamen gültig und wird vom Speicherserver als vertrauenswürdig eingestuft.
• Collabora kann das HTTPS-Zertifikat des Speicherservers validieren.
• Ihr Reverse-Proxy leitet den ursprünglichen Host und das Schema korrekt weiter.
• Es gibt keine Weiterleitung vom konfigurierten Collabora-Hostnamen zu einem anderen Hostnamen, den WOPI nicht erwartet.

Ein selbstsigniertes Zertifikat kann in einer Testumgebung akzeptabel sein, sofern alle Komponenten explizit so konfiguriert sind, dass sie ihm vertrauen. Diese Bequemlichkeit geht jedoch auf Kosten der Portabilität und führt häufig zu Fehlern bei späteren Upgrades oder Container-Neuinstallationen. Für den Produktivbetrieb ist eine öffentlich vertrauenswürdige oder von der Organisation vertrauenswürdige Zertifikatskette die sicherere Wahl.

5. Korrigieren Sie die WOPI-Zulassungslisten, anstatt sie zu deaktivieren.

Wenn die Erkennung funktioniert und die Collabora-Protokolle Meldungen wie „ Unauthorized WOPI hostKein akzeptabler WOPI-Host, der dem Ziel entspricht“ anzeigen, liegt das Problem nicht mehr in der grundlegenden Konnektivität, sondern in der Vertrauenskonfiguration. Die offizielle Fehlerbehebungsdokumentation von Nextcloud verweist Administratoren in diesem Fall ausdrücklich auf die Containerprotokolle.

Nextcloud empfiehlt, WOPI-Anfragen mithilfe der Einstellung „Zulassungsliste für WOPI-Anfragen“ auf die IP-Adressen der Collabora-Server zu beschränken . Auf Collabora-Seite müssen die zulässigen WOPI-Speicherhosts mit den Speicher-URLs übereinstimmen, die Collabora tatsächlich empfängt. Für mehrere Speicherdomänen dokumentiert das aktuelle SDK von Collabora WOPI-Aliasgruppen.

Halten Sie die Collabora-Server-URL und die WOPI-Zulassungsliste an die tatsächliche Bereitstellung angepasst; verwenden Sie eng gefasste vertrauenswürdige Einträge, anstatt die Validierung zu deaktivieren.

Die aktuelle Server-URL und die Richtlinien zur WOPI-Zulassungsliste finden Sie in der Nextcloud Office-KonfigurationCOLLABORATION_APP_ADDR . Wenn Sie ownCloud Infinite Scale verwenden, nutzt der zugehörige Kollaborationsdienst die URL der Office-App und COLLABORATION_WOPI_SRCdie extern erreichbare WOPI-Quelle; weitere Informationen finden Sie in der ownCloud-Dokumentation zum Kollaborationsdienst .

Wann sollte man den integrierten CODE anstelle eines separaten Collabora-Servers verwenden?

Bei einer kleinen Nextcloud-Installation reduziert der integrierte CODE-Server die Anzahl extern verwalteter Komponenten. Der Nachteil besteht darin, dass die Nextcloud-Instanz weiterhin darauf angewiesen ist, sich selbst über den im Browser verwendeten Hostnamen zu erreichen. Die Nextcloud-Dokumentation zur Fehlerbehebung weist explizit darauf hin und empfiehlt, den Hostnamen korrekt aufzulösen, wenn der integrierte CODE-Server keine Verbindung herstellen kann.

Ein separater Collabora-Server eignet sich in der Regel besser, wenn Sie unabhängige Skalierung, einen zentralisierten Dienst für mehrere Speicherinstanzen oder eine Produktionsarchitektur mit klareren Ressourcengrenzen benötigen. Da er zusätzliche Konfigurationen für DNS, Proxy, Zertifikate, Firewall und WOPI-Vertrauensstellung erfordert, ist der Betriebsaufwand höher.

Was man nicht tun sollte

• Die WOPI-Validierung sollte nicht als erste Maßnahme deaktiviert werden. Dadurch kann die eigentliche Hostnamenabweichung verschleiert und die Sicherheitsbarriere geschwächt werden.
• Geben Sie Port 9980 nicht direkt frei, nur weil der Proxy nicht funktioniert. Reparieren Sie den Proxy, es sei denn, die direkte Freigabe ist Teil einer beabsichtigten Sicherheitsvorkehrung.
• Gehen Sie nicht davon aus, dass eine 200-Antwort von der Collabora-Homepage beweist, dass die Dokumentenbearbeitung funktioniert. Discovery, Funktionen, WOPI-Dateizugriff und WebSockets sind separate Prozesse.
• Ändern Sie nicht mehrere Ebenen gleichzeitig. Testen Sie nach jeder Änderung, um festzustellen, ob DNS, TLS, Proxying oder WOPI-Vertrauensstellung die tatsächliche Ursache war.

Checkliste zur abschließenden Überprüfung

Nach der Durchführung einer Änderung überprüfen Sie das System in dieser Reihenfolge:

1. Öffnen Sie /hosting/discoveryes /hosting/capabilitiesin einem Browser.
2. Rufen Sie die gleichen Endpunkte vom Speicherserver ab.
3. Rufen Sie vom Collabora-Server die URL für den Speicherserverstatus ab.
4. Öffnen Sie ein Dokument und beobachten Sie dabei gleichzeitig die Collabora- und Speicherprotokolle.
5. Prüfen Sie, ob der Browser die Collabora-WebSocket-Verbindung ohne wiederholte Verbindungsabbrüche herstellt.
6. Prüfen Sie, ob ein zweiter Benutzer ein Testdokument öffnen und bearbeiten kann, falls eine gemeinsame Bearbeitung erforderlich ist.

Wenn alle sechs Prüfungen erfolgreich sind, sollte die allgemeine Fehlermeldung „Das ist peinlich“ keinen Verbindungsfehler mehr verschleiern. Falls die Meldung weiterhin angezeigt wird, erfassen Sie die genauen Collabora-Protokollzeilen und die Browser-Netzwerkfehlermeldung für einen Versuch, ein Dokument zu öffnen. Diese beiden Informationen sind aussagekräftiger als die allgemeine Benutzeroberflächenmeldung selbst.