Behebung von Nginx 502 Bad Gateway-Fehlern: Schritt-für-Schritt-Anleitung

Die Behebung von Nginx 502 Bad Gateway-Fehlern beginnt mit dem Verständnis, dass Nginx normalerweise der Überbringer ist, nicht die eigentliche Ursache des Fehlers. Ein 502 bedeutet, dass Nginx versucht hat, mit einem Upstream-Dienst zu kommunizieren und keine gültige Antwort erhalten hat.

Dieser Upstream-Dienst kann eine Node.js-App, PHP-FPM, Gunicorn, Puma, ein Container oder ein anderer HTTP-Server sein. Ihre Aufgabe ist es, herauszufinden, wo die Übergabe fehlschlägt.

Was ein 502 Bad Gateway in Nginx bedeutet

Nginx sitzt normalerweise vor einem Anwendungsserver. Es nimmt öffentlichen Datenverkehr an, verarbeitet TLS, serviert statische Dateien und leitet dynamische Anfragen an den Upstream weiter.

Ein 502 erscheint, wenn diese Upstream-Verbindung fehlschlägt oder etwas zurückgibt, das Nginx nicht verwenden kann. Häufige Ursachen sind:

• Der Anwendungsprozess wurde gestoppt.
• Nginx zeigt auf den falschen Port oder Socket.
• Ein Unix-Socket hat die falschen Berechtigungen.
• Der Upstream-Dienst stürzt während der Anfrage ab.
• Eine Firewall oder ein Container-Netzwerk blockiert die Verbindung.
• Der Upstream sendet eine ungültige HTTP-Antwort.

Beginnen Sie mit dem genauen Anforderungspfad, der fehlschlägt. Wenn nur /api einen 502 zurückgibt, aber statische Seiten geladen werden, ist Ihre statische Dateiauslieferung in Ordnung und der Proxy oder das App-Backend ist wahrscheinlich das Problem. Wenn jede Seite fehlschlägt, könnte das Problem ein breiteres Nginx-, DNS- oder Upstream-Verfügbarkeitsproblem sein.

Schritt 1: Überprüfen Sie den Nginx-Status und die Konfiguration

Bestätigen Sie zuerst, dass Nginx läuft:

systemctl status nginx

Testen Sie dann die Konfiguration:

nginx -t

Wenn der Konfigurationstest fehlschlägt, beheben Sie das zuerst, bevor Sie die Anwendung verfolgen. Nginx läuft möglicherweise noch mit einer älteren Konfiguration oder schlägt beim Neuladen fehl.

Nach einem erfolgreichen Konfigurationstest laden Sie Nginx neu:

systemctl reload nginx

Starten Sie nicht blind auf einem stark ausgelasteten Server neu, es sei denn, Sie verstehen die Auswirkungen. Ein Neuladen reicht normalerweise nach einer Konfigurationsänderung aus und ist weniger störend.

Überprüfen Sie als nächstes den aktiven Server-Block. Suchen Sie nach proxy_pass, fastcgi_pass oder uwsgi_pass. Ein typischer Reverse-Proxy könnte Folgendes enthalten:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Das bedeutet, dass Nginx eine Anwendung auf dem lokalen Port 3000 erwartet. Wenn die App tatsächlich auf 3001 oder nur innerhalb eines Docker-Netzwerks läuft, wird Nginx fehlschlagen.

Für befehlsorientiertere Überprüfungen siehe Nginx-Konfigurationstestbefehle.

Schritt 2: Überprüfen Sie den Upstream-Dienst

Testen Sie jetzt den Upstream direkt vom Nginx-Host aus. Wenn Nginx an 127.0.0.1:3000 weiterleitet, führen Sie aus:

curl -i http://127.0.0.1:3000/

Wenn das fehlschlägt, liegt das Problem nicht am Browser oder öffentlichen DNS. Nginx kann das Backend nicht erreichen, weil das Backend ausgefallen ist, woanders lauscht oder die Anfrage ablehnt.

Überprüfen Sie den Anwendungsprozess:

ss -ltnp

Suchen Sie nach dem erwarteten Port. Wenn der Dienst einen Unix-Socket verwendet, überprüfen Sie den Socket-Pfad:

ls -l /run/app/app.sock

Der Nginx-Worker-Benutzer muss auf diesen Socket zugreifen können. Auf vielen Linux-Systemen läuft Nginx als www-data, nginx oder ein dienstspezifischer Benutzer. Wenn der Socket einem anderen Benutzer gehört und nicht gruppenlesbar oder beschreibbar ist, wie erforderlich, protokolliert Nginx möglicherweise einen Berechtigungsfehler und gibt einen 502 zurück.

Für ein PHP-FPM-Setup bestätigen Sie, dass der Pool läuft:

systemctl status php-fpm

Der Dienstname kann eine Version enthalten, wie php8.2-fpm, abhängig von der Distribution.

Schritt 3: Lesen Sie das Nginx-Fehlerprotokoll

Das Nginx-Fehlerprotokoll sagt Ihnen normalerweise, mit welchem Fehlermodus Sie es zu tun haben. Häufige Protokollmeldungen sind:

connect() failed (111: Connection refused) while connecting to upstream

Das bedeutet, dass Nginx den Host erreicht hat, aber nichts die Verbindung auf diesem Port angenommen hat.

upstream timed out while reading response header from upstream

Das bedeutet, dass Nginx verbunden war, aber das Backend nicht rechtzeitig geantwortet hat.

permission denied while connecting to upstream

Das deutet oft auf Unix-Socket-Berechtigungen oder Sicherheitskontrollen wie SELinux hin.

Überprüfen Sie aktuelle Fehler mit:

tail -n 100 /var/log/nginx/error.log

Auf systemd-basierten Systemen können Sie auch überprüfen:

journalctl -u nginx -n 100

Stimmen Sie den Zeitstempel im Protokoll mit dem Zeitpunkt Ihrer Browseranfrage ab. Das verhindert, dass Sie alten Fehlern nachjagen, die nicht mehr relevant sind.

Für einen tieferen Einblick in die Protokollarbeit siehe Analysieren von Nginx-Fehlerprotokollen.

Schritt 4: Beheben Sie die häufigsten Ursachen

Sobald Sie den Fehlermodus kennen, wenden Sie die kleinste Korrektur an, die dazu passt.

Wenn die App nicht läuft, starten oder starten Sie den Anwendungsdienst neu:

systemctl restart your-app

Testen Sie dann den Upstream mit curl, bevor Sie durch Nginx testen.

Wenn Nginx auf den falschen Port zeigt, aktualisieren Sie das proxy_pass-Ziel und laden Sie Nginx neu. Stellen Sie sicher, dass Ihre App und Nginx auch bezüglich IPv4 versus IPv6 übereinstimmen. Eine App, die auf 127.0.0.1 lauscht, ist nicht dasselbe wie eine, die nur auf ::1 lauscht.

Wenn Docker involviert ist, überprüfen Sie, ob Nginx auf dem Host oder innerhalb eines Containers läuft. 127.0.0.1 innerhalb eines Containers zeigt auf diesen Container, nicht auf den Host. Möglicherweise benötigen Sie einen Docker-Dienstnamen, ein Bridge-Netzwerk oder einen veröffentlichten Port.

Wenn der Upstream ein Timeout hat, überprüfen Sie die Anwendungsprotokolle. Das Backend könnte bei Datenbankabfragen, externen API-Aufrufen oder Startarbeiten hängen bleiben. Das Erhöhen von Nginx-Timeouts kann Symptome verbergen, wird aber eine defekte oder überlastete App nicht reparieren.

Wann Sie einen Fachmann hinzuziehen sollten

Ziehen Sie einen leitenden Ingenieur oder Hosting-Anbieter hinzu, wenn 502-Fehler die Produktion betreffen und die Ursache nach Überprüfung der Protokolle, des Upstream-Status und der letzten Bereitstellungen nicht offensichtlich ist. Holen Sie sich auch Hilfe, wenn das Problem Lastverteiler, Container-Orchestrierung, SELinux-Richtlinien oder Timeout-Tuning bei hohem Datenverkehr betrifft.

Vermeiden Sie bei Produktionssystemen wiederholte zufällige Neustarts. Sie können Beweise beseitigen und es schwieriger machen, den Ausfall zu verstehen.

Ein 502 Bad Gateway-Fehler ist behebbar, wenn Sie den Anforderungspfad der Reihe nach verfolgen. Bestätigen Sie, dass Nginx gültig ist, testen Sie den Upstream direkt, lesen Sie die genaue Fehlerprotokollzeile und wenden Sie die Korrektur an, die zum Fehler passt. Dieser Ansatz ist schneller und sicherer, als Timeouts zu ändern oder Dienste blind neu zu starten.