Collabora-Verbindungsfehler mit coolwsd-Protokollen verfolgen

Für einen Collabora Online Development Edition (CODE)-Container erhöhen Sie coolwsddie Protokollierungsstufe auf „true“ debug, stellen Sie sicher, dass die Bereiche „true“ Socketund WebSocket„true“ nicht deaktiviert sind, und reproduzieren Sie dann einen Fehler beim Öffnen eines Dokuments, während Sie die Containerprotokolle verfolgen. Übergeben Sie in Docker Compose die Einstellungen über die extra_paramsUmgebungsvariable des CODE-Images und erstellen Sie den Dienst neu. Verwenden Sie diese Option tracenur, wenn die Debug-Ausgabe nicht anzeigt, wo die Verbindung abbricht, und kehren Sie nach Abschluss des Vorgangs zur vorherigen Stufe zurück.

Diese Methode eignet sich für Docker- oder Compose-Bereitstellungen, bei denen die Containerkonfiguration aktualisiert werden kann. Bei einer nativen Paketinstallation wird /etc/coolwsd/coolwsd.xmlstattdessen der zugehörige Service Manager verwendet. Die Einstellung liefert zusätzliche Diagnosedetails; sie behebt jedoch keine Proxy-, WOPI-Host-, Zertifikats- oder Netzwerkprobleme selbstständig.

1. Beginnen Sie mit einer kontrollierten Reproduktion.

Wählen Sie ein Dokument aus und notieren Sie sich den Zeitpunkt des Öffnungsversuchs, die öffentliche Collabora-URL und den Namen des Containers oder des Compose-Dienstes. Vermeiden Sie wiederholtes Aktualisieren mehrerer Dateien: Ein einziger Versuch erleichtert die Zuordnung der Browser-Symptome, Proxy-Protokolle, Integrationsserver-Protokolle und CoolWSD-Einträge.

Prüfen Sie, ob der Container ausgeführt wird, und ermitteln Sie seinen Namen:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Ersetzen Sie collaboraunten stehenden Platzhalter durch den Containernamen, der auf Ihrem Host angezeigt wird. Beginnen Sie die folgende Ausgabe kurz bevor Sie das Problem reproduzieren:

docker logs --since 2m --follow --timestamps collabora

--followEs werden neue Ausgaben gestreamt, --sinceder anfängliche Verlauf eingeschränkt und --timestampsDocker-Zeitstempel hinzugefügt. Docker dokumentiert diese Optionen in seiner Container-Log-Referenz . In Compose können Sie `<service-key>` verwenden docker compose logs --since=2m --follow collabora, wobei collabora`<service-key>` der Dienstschlüssel ist.

2. Aktivieren Sie coolwsd für den Test im Debug-Modus.

Das Collabora-Konfigurationsschema unterstützt benannte Ebenen wie `<level>` warning, ` <level>` notice, `<level>` und `<level> `. Es definiert außerdem `<level>`; die dokumentierte Standardeinstellung deaktiviert unter anderem die ausführliche Ausgabe von ` <level>` und `<level>`. Dies ist für die Fehlerbehebung bei Verbindungsproblemen wichtig: Eine alleinige Änderung der Ebene kann dazu führen, dass die wichtigsten Handshake-Details unterdrückt werden. Diese Optionen sind in der Collabora-Konfigurationsvorlage `coolwsd` und im Handbuch des Collabora Online SDK (Abschnitt „Docker-Konfiguration“; geprüft im Oktober 2026) dokumentiert.informationdebugtracedisabled_areasSocketWebSocket

Für das offizielle collabora/codeImage fügen Sie die beiden Optionen zum bestehenden Wert des Dienstes hinzu extra_params. Behalten Sie alle Optionen bei, die bereits von Ihrer Installation benötigt werden, wie z. B. SSL-Terminierung oder Servername:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

Die zweite Option ermöglicht Socketdie WebSocketNutzung ausführlicher Protokollierung, während die anderen beiden Bereiche deaktiviert bleiben Admin. PixelFügen Sie diese beiden Bereiche während dieses Tests nicht wieder zur Liste der deaktivierten Bereiche hinzu. Die Dokumentation des CODE-Images beschreibt extra_paramseine Möglichkeit, Befehlszeilenoptionen an coolwsd zu übergeben. Wenn Ihre Bereitstellung eine eingebundene Konfigurationsdatei oder ein vom Hersteller verwaltetes Image verwendet, folgen Sie stattdessen der Konfigurationsmethode dieser Bereitstellung.

Wenden Sie die Compose-Bearbeitung an, indem Sie den Dienst neu erstellen:

docker compose up -d --force-recreate collabora

Verwenden Sie Ihren tatsächlichen Compose-Dienstnamen. Aktualisieren Sie bei einem kurzlebigen Container, der mit `compose up` gestartet wurde docker run, dessen Laufzeitkonfiguration und erstellen Sie ihn mit denselben Volumes, Netzwerken, Ports und anderen Optionen neu. Laut CODE-Handbuch akzeptiert das Image extra_paramsbeim Start `compose up`; gehen Sie nicht davon aus, dass die Änderung der Umgebung eines bereits erstellten Containers den laufenden `coolwsd`-Prozess beeinflusst.

3. Lesen Sie die Verbindung der Reihe nach.

Reproduzieren Sie den Fehler einmal und überprüfen Sie nur diesen Zeitraum. Suchen Sie in der Ausgabe nach Begriffen wie WebSocket„“, WOPI„“ ERR, „“ und WRN„“ und vergleichen Sie anschließend die Zeitstempel. Die genaue Formulierung und die Protokollbereiche variieren je nach Collabora-Version. Behandeln Sie diese daher eher als Kategorien zur Überprüfung denn als garantiert wörtliche Meldungen.

• Zum Testzeitpunkt wurden keine neuen coolwsd-Einträge gefunden: Die Anfrage erreicht diesen Container möglicherweise nicht. Überprüfen Sie die konfigurierte öffentliche URL, DNS-Einträge, Load Balancer, Reverse-Proxy-Zugriffs-/Fehlerprotokolle und ob Sie die richtige Replik überwachen.
• Der Browser erreicht den Dienst, aber die WebSocket-Verbindung wird nicht aufrechterhalten: Untersuchen Sie die Proxy-Verarbeitung des WebSocket-Upgrades, des weitergeleiteten Hosts und Schemas, der TLS-Terminierung, des Pfad-Routings und der Leerlauf-Timeouts. Vergleichen Sie dies mit der Browser-Entwicklerkonsole und den Proxy-Logs; coolwsd kann eine Anfrage, die der Proxy nie weiterleitet, nicht erklären.
• Es tritt eine WOPI-Anfrage auf, die fehlschlägt: Überprüfen Sie die WOPI-URL des Integrationsservers, die Konfiguration der Host-Zulassungsliste oder des Alias, die Erreichbarkeit vom Collabora-Container aus sowie die Antwort des Integrationsservers. Ein WOPI-Fehler ist ein separates Ereignis, unabhängig von der Browser-zu-Collabora-WebSocket-Verbindung.
• WOPI funktioniert, aber der Browser trennt die Verbindung weiterhin: Konzentrieren Sie sich als Nächstes auf die WebSocket-Route und browserseitige Verbindungsfehler. Diese Vorgehensweise grenzt die Suche ein; sie beweist jedoch nicht, welcher Proxy oder welche Netzwerkeinstellung falsch ist.

Wenn Docker keine Ausgabe liefert, obwohl der Dienst aktiv ist, überprüfen Sie die Protokollierungskonfiguration im Container. Der Docker-Befehl `log` liest die Standardausgabe und die Fehlerströme des Containers. Eine Installation, die für das Schreiben in eine Datei konfiguriert ist, verwendet möglicherweise stattdessen einen Pfad wie beispielsweise `/usr/local/log` /var/log/coolwsd.log, wie in ihrer Konfiguration definiert. Überprüfen Sie die tatsächliche Datei, anstatt diesen Pfad anzunehmen.

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Wenn die Dateiprotokollierung aktiviert ist, verwenden Sie den konfigurierten Pfad, zum Beispiel:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Überprüfen Sie das Ergebnis und stellen Sie die normale Protokollierung wieder her.

Führen Sie nach dem Test einen begrenzten Lesevorgang durch, um zu bestätigen, dass der beabsichtigte Versuch neue Einträge erzeugt hat:

docker logs --since 5m --timestamps collabora

Ein nützliches Ergebnis erhalten Sie, wenn Sie den fehlgeschlagenen Verbindungsaufbau einem CoolWSD-Ereignis zuordnen oder feststellen können, dass die Anfrage diesen Container nie erreicht hat. Anschließend können Sie ermitteln, welche Verbindungsphase weiter untersucht werden muss. Falls Sie die Ausgabe filtern müssen, verwenden Sie zunächst ein kurzes Zeitfenster.

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Stellen Sie die vorherigen Werte wieder her logging.levelund disabled_areaserstellen Sie den Dienst anschließend neu. Debug- und Trace-Protokolle erzeugen deutlich mehr Ausgaben und können sensible Betriebsdetails enthalten. Schwärzen Sie vor der Weitergabe von Protokollen Zugriffstoken, Dokumentnamen, Benutzerkennungen, Hostnamen und interne Adressen. Falls es sich bei dem Dienst nicht um das offizielle CODE-Image handelt, bestätigen Sie den Konfigurationspfad und die unterstützten Parameter mit dem jeweiligen Image-Betreuer.