Wie man den ONLYOFFICE Document Server-Fehler 502 Bad Gateway hinter Nginx behebt

Beim Öffnen einer ONLYOFFICE Docs-URL zeigt der Browser die Fehlermeldung „502 Bad Gateway“ an, oder ein Nextcloud/ownCloud-Connector kann den Dokumentenserver nicht erreichen. In beiden Fällen empfängt Nginx üblicherweise eine Anfrage, erhält aber keine gültige Antwort vom Upstream-Server. Dieser Upstream-Server kann der interne Dokumentendienst von ONLYOFFICE, ein Docker-Container oder ein anderer Reverse-Proxy sein. Ermitteln Sie zunächst, welcher Nginx-Server den Fehler 502 zurückgegeben hat, und testen Sie dann den nächsten Hop direkt, bevor Sie die Konfiguration ändern.

Die aktuelle Linux-Fehlerbehebungsanleitung von ONLYOFFICE empfiehlt, die Dienste und die Protokolle des Dokumentenservers zu überprüfen ds-docservice. ds-converterDie Anleitung zum Reverse-Proxy weist außerdem auf weitergeleitete Host- und Protokoll-Header hin. Die folgende Vorgehensweise prüft zuerst den Dienststatus, dann das Nginx-Routing und das Docker-Netzwerk.

1. Ermitteln Sie, welcher Nginx-Server den Fehler 502 zurückgibt.

Die Paketinstallation von ONLYOFFICE beinhaltet eine eigene Nginx-Konfiguration, und eine Bereitstellung kann auch einen externen Nginx-Reverse-Proxy umfassen. Docker kann einen weiteren Netzwerk-Hop hinzufügen. Allein das Erscheinen der 502-Fehlerseite gibt möglicherweise keine Auskunft über die zugrunde liegende Ebene. Vergleichen Sie daher die öffentliche URL mit einem lokalen Health-Check und dem Nginx-Fehlerprotokoll.

Bei einer paketbasierten Linux-Installation testen Sie den lokalen Dokumentenserver-Endpunkt:

curl -i http://127.0.0.1/healthcheck

Wenn der Server so konfiguriert ist, dass er ONLYOFFICE auf einem anderen lokalen Port als dem Standardport bereitstellt, verwenden Sie diesen Port. Eine fehlerfreie Installation gibt normalerweise eine HTTP-Erfolgsantwort zurück true. Schlägt diese lokale Anfrage fehl, beheben Sie das Problem mit dem Dokumentenserver, bevor Sie einen externen Proxy bearbeiten. Wenn die Anfrage lokal erfolgreich ist, der öffentliche Hostname jedoch einen 502-Fehler zurückgibt, konzentrieren Sie sich auf den externen Nginx-Upstream, das Protokoll, die Header und den Firewall-Pfad.

Prüfen Sie, welche Prozesse die erwarteten Ports belegen:

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

Die Portbelegung variiert je nach Topologie. Eine gängige Docker-Zuordnung weist beispielsweise dem Host-Port 8080 den Container-Port 80 zu; eine Paketinstallation kann ihren eigenen Nginx-Server auf dem Host verwenden. Gehen Sie nicht automatisch davon aus, dass dies 127.0.0.1:80der korrekte Upstream-Server ist, nur weil sich beide Dienste auf demselben Rechner befinden.

2. Überprüfen Sie die ONLYOFFICE-Dienste und -Protokolle.

Bei der Installation eines Linux-Pakets sollten Sie den Dokumentendienst und den Konverter überprüfen:

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

Die Fehlerbehebungsanleitung von ONLYOFFICE listet diese Dienste auf und nennt unzureichenden Arbeitsspeicher, einen Port-80-Konflikt sowie Dienstprotokolle als mögliche Fehlerquellen, falls die Docs-Dienste nicht starten. Wenn ein Dienst beendet ist, prüfen Sie zunächst dessen Fehler und starten Sie anschließend nur den betroffenen Dienst neu.

sudo systemctl restart ds-docservice

Das Hauptverzeichnis für Linux-Protokolle ist /var/log/onlyoffice/documentserver/. Überprüfen Sie die Nginx-Fehlerprotokolle und die Docservice-Protokolle auf Meldungen wie „Verbindung abgelehnt“, „Zeitüberschreitung beim Upstream-Prozess“ oder eine fehlende Datei. Diese deuten auf unterschiedliche Ursachen hin: Eine abgelehnte Verbindung bedeutet in der Regel, dass der Upstream-Prozess oder -Port nicht verfügbar ist, während eine Zeitüberschreitung bedeuten kann, dass der Dienst überlastet oder blockiert ist.

Prüfen Sie auch den verfügbaren Speicherplatz und Arbeitsspeicher, falls Dienste wiederholt beendet werden:

df -h
free -h

Starten Sie einen fehlerhaften Dienst nicht immer wieder neu, ohne vorher seine Protokolle zu überprüfen; ein Neustart kann das Symptom zwar kurzzeitig verbergen, behebt aber keinen Portkonflikt, keine fehlende Abhängigkeit und kein Ressourcenproblem.

3. Überprüfen Sie, ob Nginx auf den erreichbaren Upstream-Server verweist.

Lesen Sie den aktiven virtuellen Host und bestätigen Sie die genaue Adresse und den Port proxy_pass. Fragen Sie von dem Rechner oder Container, auf dem Nginx läuft, direkt den Upstream-Server an. Beispiel: Wenn der Container Port 80 als Host-Port 8080 veröffentlicht:

curl -i http://127.0.0.1:8080/healthcheck

Ersetzen Sie die Beispieladresse durch den Endpunkt, der vom Proxy tatsächlich erreichbar ist. Falls Nginx in einem separaten Docker-Container läuft, 127.0.0.1bezieht sich die Angabe auf diesen Nginx-Container selbst, nicht auf den Docker-Host oder den ONLYOFFICE-Container. Verwenden Sie einen erreichbaren Dienstnamen in einem gemeinsam genutzten Docker-Netzwerk oder die korrekte Hostadresse und den veröffentlichten Port.

Prüfen Sie, ob das Upstream-Schema mit dem Backend übereinstimmt. Verwenden Sie es nur, wenn http://der Backend-Listener unverschlüsseltes HTTP sendet und https://für TLS konfiguriert ist. Das Senden von HTTP an einen TLS-Port oder von TLS an einen unverschlüsselten HTTP-Port kann dazu führen, dass ein funktionierender Dienst für Nginx nicht erreichbar erscheint.

4. Weitergeleitete Header und WebSocket-Proxying prüfen.

Die Anleitung von ONLYOFFICE für Reverse-Proxys empfiehlt, die ursprünglichen Protokoll- und Hostnamen beizubehalten X-Forwarded-Proto, X-Forwarded-Hostdamit die Anwendung sie kennt. Auch die offiziellen Nginx-Beispiele übergeben Upgrade-Header. Falls ein externer Proxy vor ONLYOFFICE geschaltet ist, vergleichen Sie dessen Konfiguration mit dem offiziellen Szenario, das Ihrer Topologie entspricht.

Im Folgenden wird ein vereinfachtes Beispiel für einen Docker-Container gezeigt, der dem Host-Port 8080 zugeordnet ist. Fügen Sie die mapDirektive in den Nginx- httpKontext ein und passen Sie Hostname, TLS-Konfiguration und Upstream-Port an Ihre Konfiguration an:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 $connection_upgrade;
    }
}

Dies ist ein Referenzmuster und kein direkter Ersatz für jede Installation. Insbesondere sollten Sie es nicht einfach über die mitgelieferte ONLYOFFICE-Nginx-Konfiguration einfügen, ohne zu wissen, welcher Serverblock die Ports 80 und 443 belegt. Falls Nginx denselben Host wie das installierte ONLYOFFICE verwendet, prüfen Sie zunächst, ob es zu Portkonflikten kommt, und leiten Sie den externen Proxy an den für Ihre Bereitstellung konfigurierten internen Listener weiter.

Nach der Bearbeitung sollte die Konfiguration getestet werden, bevor Nginx neu geladen wird:

sudo nginx -t
sudo systemctl reload nginx

Schlägt der Konfigurationstest fehl, korrigieren Sie die gemeldete Datei und Zeile, bevor Sie die Anwendung neu laden. Ein Syntaxfehler und ein Upstream-Fehler (502) sind unterschiedliche Probleme; ein erfolgreicher Test nginx -tbestätigt die Syntax, nicht aber, dass der Upstream-Server antwortet.

5. Falls ONLYOFFICE in Docker ausgeführt wird, überprüfen Sie dessen Zustand und die Portzuordnung.

Prüfen Sie, ob der Container ausgeführt wird und welcher Host-Port veröffentlicht ist:

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

Die offizielle Docker-Installationsanleitung ordnet Host-Ports dem Container-Port 80 zu. Im Beispiel werden die Container-Logs überprüft, falls die Willkommensseite nicht geladen wird. Verwenden Sie den angezeigten Port als docker portUpstream-Port auf dem Host. Wenn sowohl Nginx als auch ONLYOFFICE als Container ausgeführt werden, platzieren Sie diese im selben Netzwerk und leiten Sie den Datenverkehr an den ONLYOFFICE-Dienstnamen und den Container-Port weiter, anstatt an die Loopback-Adresse des Hosts.

Überprüfen Sie den Integritätsstatus des Containers, falls Ihre Compose-Datei eine Integritätsprüfung definiert. Das aktuelle Upstream-Compose-Beispiel prüft http://localhost:8000/info/info.jsoninnerhalb des Containers. Ein Container, der ausgeführt wird, kann dennoch einen fehlerhaften Dokumentendienst aufweisen. Falls der Container neu startet oder fehlerhaft ist, verwenden Sie die Protokolle, um Datenbankstart, Speichernutzung und Konfiguration zu untersuchen, bevor Sie den externen Proxy ändern.

ONLYOFFICE dokumentiert persistente Docker-Pfade für Protokolle, Zertifikate und den Dateicache. Vermeiden Sie das Löschen von Volumes während der Fehlersuche; diese könnten Zertifikate oder andere Daten enthalten, die zur Wiederherstellung des Dienstes benötigt werden.

6. Neu laden, den Health-Endpunkt testen und die Integration erneut testen.

Nachdem ein bestätigtes Problem behoben wurde, testen Sie den öffentlichen Hostnamen und vergleichen Sie ihn mit dem lokalen Endpunkt:

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

Verwenden Sie Ihre tatsächliche Dokumentenserver-URL. Eine erfolgreiche Antwort sowohl auf der lokalen Upstream-Adresse als auch auf dem öffentlichen Hostnamen zeigt an, dass Nginx den Backend-Server erreichen und eine Statusmeldung zurückgeben kann. Öffnen Sie anschließend die Willkommensseite des Dokumentenservers und versuchen Sie die Aktion erneut, die ursprünglich in Nextcloud, ownCloud oder Ihrem anderen Connector fehlgeschlagen ist.

Wenn der Health-Check erfolgreich ist, der Connector aber weiterhin einen Fehler meldet, liegt die Ursache möglicherweise außerhalb des Nginx-502-Pfads – beispielsweise in der Connector-URL, der TLS-Vertrauensstellung oder den JWT-Einstellungen. Vergleichen Sie diese Werte mit der Connector- und der ONLYOFFICE-Konfiguration, anstatt die Proxy-Timeouts weiterhin ohne weitere Anpassungen zu ändern.

Schnelle Diagnose

Offizielle Referenzen

• ONLYOFFICE Docs-Fehlerbehebung für Linux
• ONLYOFFICE Docs hinter einem Proxy
• Offizielles ONLYOFFICE Nginx HTTPS-zu-HTTP-Proxy-Beispiel
• ONLYOFFICE Docs Docker-Installation und Portzuordnung
• ONLYOFFICE Document Server Compose-Beispiel