Verfolgen Sie den Upstream, um den Nginx-Fehler 502 von ONLYOFFICE zu beheben.

Überprüfen Sie zunächst die Verbindung zwischen Nginx und ONLYOFFICE Docs und lesen Sie anschließend das Fehlerprotokoll, das der 502-Antwort entspricht. Ein 502 Bad Gateway bedeutet, dass ein Gateway keine gültige Antwort von seinem Upstream-Server erhalten konnte; dies beweist jedoch nicht automatisch, dass die öffentliche Nginx-Konfiguration die Ursache ist. In Docker besteht die übliche Lösung darin, Nginx an den Dienstnamen des Dokumentenservers auf dessen internem Port 80 zu senden und sicherzustellen, dass beide Container dasselbe Netzwerk verwenden.

Was sollten Sie überprüfen, bevor Sie Nginx bearbeiten?

Ein Reverse-Proxy ist ein Server, der Clientanfragen entgegennimmt und an einen anderen Server weiterleitet. In einer typischen Installation verarbeitet der öffentliche Nginx-Server HTTPS-Anfragen und leitet diese über HTTP an ONLYOFFICE Docs weiter. Da ONLYOFFICE Docs intern ebenfalls einen eigenen Nginx-Server verwendet, kann eine 502-Fehlerseite sowohl vom externen Proxy als auch vom Dokumentenserver-Container selbst generiert werden.

Ermitteln Sie zunächst, welcher Server die Antwort gesendet hat. Vergleichen Sie den Server-Header und den Zeitstempel der Seite mit den Protokollen des äußeren Proxys und des Dokumentservers. Überprüfen Sie bei einer Docker-Umgebung den Containerstatus und die letzten Startmeldungen.

docker ps --filter name=onlyoffice-documentserver
docker logs --tail 100 onlyoffice-documentserver

Wenn der Container neu gestartet wird oder gerade erst gestartet wurde, überprüfen Sie das Protokoll, bevor Sie die Proxy-Einstellungen ändern. ONLYOFFICE weist darauf hin, dass der erste Start ein bis zwei Minuten dauern kann, während die Datenbank initialisiert wird. Bei einer nativen Linux-Installation überprüfen Sie die Protokolle ds-docservicedes Dokumentenservers ds-convertermit systemctl statusdem Befehl `document server logs` /var/log/onlyoffice/documentserver/.

Verwenden Sie die entsprechenden offiziellen ONLYOFFICE Linux-Anweisungen zur Fehlerbehebung, falls ein Dienst gestoppt wird.

Kann Nginx den vorgelagerten Dokumentenserver erreichen?

Testen Sie vom Nginx-Container oder -Host aus, nicht nur von Ihrem Laptop. Container in separaten Docker-Netzwerken können sich nicht über ihren Dienstnamen auflösen, selbst wenn beide ausgeführt werden. Wenn Nginx und ONLYOFFICE ein benutzerdefiniertes Docker-Netzwerk gemeinsam nutzen, verwenden Sie den Compose-Dienstnamen oder einen auflösbaren Containernamen und den Listening-Port des Containers. Die offizielle Docker-Installationsanleitung gibt Port 80 als Standard-Listener für den Dokumentenserver an; ein veröffentlichter Host-Port wie 8080:80 ändert den internen Port nicht.

Führen Sie im Proxy-Container folgenden Befehl aus:

curl -I http://onlyoffice-documentserver:80/

Ersetzen Sie <Compose-Dienstname> onlyoffice-documentserverdurch Ihren tatsächlichen Compose-Dienstnamen. Falls die Meldung „Host konnte nicht aufgelöst werden“ erscheint, verbinden Sie beide Container mit demselben Docker-Netzwerk oder korrigieren Sie den Upstream-Namen. „Verbindung abgelehnt“ bedeutet in der Regel, dass der Zielhost zwar aufgelöst wurde, aber auf diesem Port keine Verbindungen akzeptiert werden, der Container noch nicht bereit ist oder der falsche Port verwendet wurde. Bei einer nativen Installation testen Sie stattdessen die lokale Adresse und den konfigurierten Port, z. curl -I http://127.0.0.1/B.

Der Docker-Leitfaden von ONLYOFFICE behandelt den Standardport, Portzuordnungen, Startverzögerung und Containerprotokolle: Docker-Installation und -Verifizierung .

Wie korrigiert man das Nginx-Proxy-Ziel?

Im HTTPS-Virtual-Host für den Hostnamen ONLYOFFICE muss proxy_passauf den erreichbaren Upstream-Server verwiesen werden. Dieses Beispiel geht von einem gemeinsam genutzten Docker-Netzwerk und dem oben gezeigten Dienstnamen aus; passen Sie ihn an Ihre Bereitstellung an.

location / {
    proxy_pass http://onlyoffice-documentserver:80;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Richten Sie einen containerisierten Proxy nur dann auf eine 127.0.0.1:8080Hostadresse, wenn der Dokumentenserver tatsächlich im selben Container lauscht oder die Hostadresse explizit konfiguriert und erreichbar ist. „Innerhalb eines Containers“ 127.0.0.1bedeutet „innerhalb eines Containers“ den Container selbst. Vermeiden Sie außerdem HTTPS-Anfragen an den Upstream-Server, wenn der Endpunkt des Dokumentenservers unverschlüsseltes HTTP verwendet.

Das weitergeleitete Protokoll und der Host teilen ONLYOFFICE mit, welche öffentliche URL der Client verwendet hat. Die Upgrade-Header ermöglichen WebSocket-Verbindungen für die Live-Kommunikation mit dem Editor. ONLYOFFICE bietet gepflegte Beispiele für den Betrieb von Docs hinter einem Proxy , einschließlich der Nginx-HTTPS-zu-HTTP-Konfiguration . Vergleichen Sie diese mit dem vollständigen Beispiel, falls Ihre Umgebung mehrere Proxy-Hops umfasst oder ein URL-Pfadpräfix verwendet.

Bevor Sie Änderungen anwenden, überprüfen Sie die Konfiguration mit ` nginx -tnginx --valid` und laden Sie Nginx anschließend mit der für Ihren Host oder Container vorgesehenen Methode neu. Starten Sie nicht alle Dienste gleichzeitig neu; ein kontrollierter Neustart erleichtert es, festzustellen, ob die Korrektur im Upstream-Repository das Ergebnis verändert hat.

Was passiert, wenn ONLYOFFICE weiterhin einen 502-Fehler zurückgibt?

Wenn der äußere Proxy die Willkommensseite des Dokumentenservers erreichen kann, aber /healthcheckden Fehlercode 502 zurückgibt, liegt das Problem möglicherweise im Dokumentenserver selbst und nicht im öffentlichen Nginx-Server. Überprüfen Sie die Container-Logs und die internen Dienstlogs des Dokumentenservers. Bei nativen Linux-Installationen überprüfen Sie die oben genannten Befehle zum Dienststatus und das Logverzeichnis. Wenn der /welcome/Dienst antwortet, der Health-Check jedoch fehlschlägt, betrachten Sie dies als separate Signale: Eine statische Willkommensseite beweist nicht, dass der Dokumentenserver und seine Abhängigkeiten fehlerfrei funktionieren.

Deaktivieren Sie JWT nicht, um dieses Problem zu beheben. Die JSON Web Token (JWT)-Validierung authentifiziert Integrationsanfragen; eine JWT-Abweichung führt in der Regel zu einem Autorisierungsfehler und nicht zu einem Verbindungsproblem auf Netzwerkebene. Überprüfen Sie die JWT-Einstellungen nur, wenn der Proxy antwortet, die Integration aber einen Autorisierungs- oder Tokenfehler meldet.

Prüfen Sie abschließend, ob Nginx den korrekten Hostnamen an den richtigen virtuellen Host weiterleitet. Ein Tippfehler im Hostnamen server_name, im Upstream-DNS-Namen oder im Port kann dazu führen, dass der Datenverkehr umgeleitet wird oder der Proxy eine veraltete Konfiguration verwendet. Überprüfen Sie das Nginx-Fehlerprotokoll auf Zeilen wie „“ host not found in upstream, connect() failed„“ oder upstream timed out„“. Jede dieser Zeilen verweist auf eine andere Ebene.

Wie überprüft man die Fehlerbehebung?

Testen Sie die Upstream-Verbindung vom Proxy-Netzwerk erneut, überprüfen Sie dann den Endpunkt für öffentliche Gesundheit und öffnen Sie ein Dokument über die verbundene Plattform:

curl -I https://docs.example.com/healthcheck

Eine erfolgreiche Health-Check-Antwort sollte nicht mehr den Fehlercode 502 liefern, und ein Dokument sollte sich öffnen und während der Bearbeitung verbunden bleiben. Falls der Upstream-Test erfolgreich ist, die öffentliche Anfrage aber weiterhin fehlschlägt, konzentrieren Sie sich auf den ausgewählten virtuellen Nginx-Host, dessen geladene Konfiguration und dessen Protokolle. Funktioniert die öffentliche Willkommensseite, der Health-Check liefert aber weiterhin den Fehlercode 502, fahren Sie mit der internen Servicediagnose von ONLYOFFICE fort.

Informationen zum Verhalten von Nginx-Direktiven finden Sie in der offiziellen Dokumentation des Nginx-Proxy-Moduls . Die genauen Befehle und Dienstnamen können je nach Docker-Compose-Projekt, Linux-Distribution und ONLYOFFICE-Version variieren. Ersetzen Sie daher die Platzhalter durch Ihre tatsächlichen Namen und überprüfen Sie die Protokolle der Komponente, die die Antwort generiert hat.