Diagnose und Behebung von Nginx 502 Bad Gateway Fehlern

Nginx ist ein leistungsstarker und beliebter Webserver sowie Reverse-Proxy, der häufig zum Ausliefern statischer Inhalte, zum Lastenausgleich von Datenverkehr und zum Weiterleiten von Anfragen an verschiedene Upstream-Anwendungsserver wie PHP-FPM, Node.js, Python Gunicorn oder Apache Tomcat verwendet wird. Wenn Nginx Probleme bei der Kommunikation mit einem dieser Upstream-Server hat, antwortet es typischerweise mit einem "502 Bad Gateway"-Fehler.

Dieser Artikel bietet eine umfassende Schritt-für-Schritt-Anleitung zum Verstehen, Diagnostizieren und Beheben von Nginx 502 Bad Gateway Fehlern. Wir untersuchen die häufigsten Ursachen, statten Sie mit praktischen Fehlerbehebungstechniken mithilfe von Befehlszeilentools aus und bieten umsetzbare Lösungen, um Ihre Webdienste schnell wieder online zu bringen. Egal, ob Sie Systemadministrator, Entwickler sind oder Ihren eigenen Server verwalten, dieser Leitfaden hilft Ihnen, einen der häufigsten Nginx-Fehler effektiv zu beheben.

Verständnis des Nginx 502 Bad Gateway Fehlers

Ein 502 Bad Gateway Fehler zeigt an, dass Nginx, das als Reverse-Proxy fungiert, eine ungültige Antwort von einem Upstream-Server erhalten hat. Das bedeutet, dass Nginx erfolgreich eine Verbindung zu einem Upstream-Server hergestellt hat, aber entweder keine Antwort, eine unvollständige Antwort oder eine Antwort erhalten hat, die es nicht verstehen konnte. Entscheidend ist, dass das Problem nicht bei Nginx selbst liegt, sondern bei dem Dienst, mit dem Nginx kommunizieren möchte.

Zu den gängigen Upstream-Servern gehören:

PHP-FPM: Für PHP-Anwendungen (z. B. WordPress, Laravel).
Gunicorn/uWSGI: Für Python-Anwendungen (z. B. Django, Flask).
Node.js: Für JavaScript-Anwendungen.
Apache Tomcat: Für Java-Anwendungen.
Andere Webserver: Wie der Apache HTTP Server, der bestimmte Inhalte bereitstellt.

Der 502-Fehler ist ein wichtiger Indikator dafür, dass das Backend Ihrer Anwendung nicht korrekt funktioniert oder für Nginx nicht zugänglich ist.

Schritt-für-Schritt-Diagnose

Der Schlüssel zur Behebung eines 502-Fehlers ist die systematische Diagnose. Beginnen Sie mit den wahrscheinlichsten Ursachen und untersuchen Sie schrittweise weiter.

1. Zuerst die Nginx-Fehlerprotokolle prüfen

Ihre Nginx-Fehlerprotokolle sind die primäre Informationsquelle. Sie enthalten oft spezifische Details darüber, warum Nginx nicht mit dem Upstream-Server kommunizieren konnte.

Speicherort: Typischerweise unter /var/log/nginx/error.log zu finden.
Befehl: Verwenden Sie tail -f, um die Protokolle in Echtzeit zu überwachen, während Sie versuchen, den Fehler zu reproduzieren.

tail -f /var/log/nginx/error.log

Worauf Sie achten sollten:
* connect() failed (111: Connection refused): Zeigt an, dass der Upstream-Server auf der angegebenen Adresse/Port nicht lauscht oder eine Firewall die Verbindung blockiert.
* upstream timed out: Der Upstream-Server hat zu lange für eine Antwort benötigt.
* upstream prematurely closed connection: Der Upstream-Server hat die Verbindung geschlossen, bevor eine vollständige Antwort gesendet wurde.
* no live upstreams while connecting to upstream: Nginx konnte keine konfigurierten verfügbaren Upstream-Server finden.

2. Status des Upstream-Servers überprüfen

Sobald Sie Hinweise aus den Nginx-Fehlerprotokollen haben, überprüfen Sie den Status Ihres Upstream-Anwendungsservers.

Für PHP-FPM:

bash systemctl status phpX.X-fpm # Ersetzen Sie X.X durch Ihre PHP-Version, z. B. php7.4-fpm sudo service phpX.X-fpm status
Für Node.js/Python/Andere benutzerdefinierte Apps:
Prüfen Sie, ob der Prozess läuft.

bash ps aux | grep node ps aux | grep gunicorn
Wenn Sie einen Prozessmanager wie PM2 (Node.js) oder Supervisor (allgemein) verwenden, überprüfen Sie dessen Status.

bash pm2 status sudo supervisorctl status

Wenn der Dienst nicht läuft, versuchen Sie, ihn zu starten, und überprüfen Sie dessen eigene Protokolle auf Fehler.

systemctl start phpX.X-fpm
# Oder
sudo service phpX.X-fpm start

3. Netzwerk-Konnektivität zum Upstream überprüfen

Stellen Sie sicher, dass Nginx den Upstream-Server über den konfigurierten Port oder Socket-Pfad erreichen kann.

Für TCP/IP-Verbindungen (z. B. 127.0.0.1:8000):
Verwenden Sie telnet oder nc (netcat), um die Port-Konnektivität vom Nginx-Server aus zu testen.

bash telnet 127.0.0.1 8000 nc -vz 127.0.0.1 8000
Eine erfolgreiche Verbindung sollte Connected to 127.0.0.1. oder succeeded! anzeigen. Wenn es hängt oder Connection refused anzeigt, lauscht der Upstream-Dienst nicht oder eine Firewall blockiert ihn.
Für Unix-Sockets (z. B. unix:/run/php/phpX.X-fpm.sock):
Überprüfen Sie, ob die Socket-Datei existiert und die korrekten Berechtigungen hat.

bash ls -l /run/php/phpX.X-fpm.sock
Nginx sollte Lese-/Schreibberechtigungen für diese Socket-Datei haben. Der Nginx-Benutzer (z. B. www-data) muss Teil der Gruppe sein, der der Socket gehört (z. B. www-data oder php-fpm).

Häufige Ursachen und Lösungen

Basierend auf Ihren Diagnose-Schritten sind hier die häufigsten Ursachen für 502-Fehler und deren Behebung.

1. Upstream-Server läuft nicht oder ist abgestürzt

Ursache: Die Anwendung, zu der Nginx weiterleiten soll (z. B. PHP-FPM, Gunicorn, Node.js-App), läuft nicht oder ist abgestürzt.

Lösung: Starten oder neu starten Sie den Upstream-Dienst.

# Beispiel für PHP-FPM
systemctl start phpX.X-fpm
# Wenn er bereits läuft und Sie einen Absturz vermuten, starten Sie ihn neu:
systemctl restart phpX.X-fpm

# Für benutzerdefinierte Anwendungen verwenden Sie deren spezifische Start-/Neustart-Befehle

Tipp: Stellen Sie sicher, dass Ihre Upstream-Dienste so konfiguriert sind, dass sie beim Systemstart automatisch starten. Bei systemd-Diensten verwenden Sie systemctl enable phpX.X-fpm.

2. Überlastung des Upstream-Servers / Ressourcenerschöpfung

Ursache: Der Upstream-Server ist überlastet, ihm gehen Speicher oder CPU aus, oder er erreicht Prozesslimits, wodurch er aufhört zu antworten oder neue Verbindungen ablehnt.

Symptome: Nginx-Fehlerprotokolle zeigen möglicherweise intermittierend connection refused oder upstream timed out, insbesondere unter Last. Systemüberwachungstools (top, htop, free -h) zeigen eine hohe Ressourcennutzung.

Lösungen:

Für PHP-FPM: Passen Sie die PHP-FPM-Pool-Einstellungen in seiner Konfigurationsdatei an (z. B. /etc/php/X.X/fpm/pool.d/www.conf).
- pm.max_children: Die maximale Anzahl von Prozessen, die gleichzeitig aktiv sein können.
- pm.start_servers: Die Anzahl der beim Start erstellten Prozesse.
- pm.min_spare_servers, pm.max_spare_servers: Steuern, wie viele Leerlaufprozesse vorgehalten werden.
ini ; Beispiel für dynamische Prozessverwaltung pm = dynamic pm.max_children = 50 pm.start_servers = 10 pm.min_spare_servers = 5 pm.max_spare_servers = 20
* Erhöhen Sie memory_limit in php.ini, wenn Skripte den Speicher erschöpfen.
* Für andere Anwendungen: Erhöhen Sie die Anzahl der Worker-Prozesse, Threads oder weisen Sie, wenn möglich, mehr Speicher zu. Überwachen Sie die spezifischen Metriken Ihrer Anwendung.
* Nginx Timeouts: Erhöhen Sie die Nginx-Direktiven proxy_connect_timeout, proxy_send_timeout und proxy_read_timeout in Ihrer Nginx-Konfiguration, aber bedenken Sie, dass dies den Fehler nur verzögert, wenn das Backend tatsächlich Probleme hat.

nginx http { ... proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; ... }

3. Falsche Upstream-Konfiguration in Nginx

Ursache: Nginx ist so konfiguriert, dass es sich mit der falschen IP-Adresse, dem falschen Port oder dem falschen Unix-Socket-Pfad für den Upstream-Server verbindet.

Symptome: Nginx-Fehlerprotokolle zeigen unmittelbar nach einer Anfrage connect() failed (111: Connection refused) an.

Lösung: Überprüfen Sie sorgfältig die Konfiguration Ihres Nginx-Serverblocks (/etc/nginx/sites-available/ihre_seite.conf).

Für HTTP/HTTPS Upstreams:

nginx location /app { proxy_pass http://127.0.0.1:8000; # Stellen Sie sicher, dass IP und Port korrekt sind proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
Für PHP-FPM über Unix-Socket:

nginx location ~ \.php$ { fastcgi_pass unix:/run/php/phpX.X-fpm.sock; # Überprüfen Sie, ob dieser Pfad exakt mit der PHP-FPM-Konfiguration übereinstimmt fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }
Für PHP-FPM über TCP/IP:

nginx location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; # IP und Port überprüfen fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }

Nachdem Sie Änderungen vorgenommen haben, testen Sie immer Ihre Nginx-Konfiguration und laden Sie Nginx neu/starten Sie es neu:

nginx -t
systemctl reload nginx # Oder neu starten, falls -t eine Notwendigkeit anzeigt

4. PHP-FPM `request_terminate_timeout` überschritten

Ursache: Ein PHP-Skript benötigt länger zur Ausführung als die Einstellung request_terminate_timeout in PHP-FPM. Nginx wartet auf die Antwort, aber PHP-FPM beendet das Skript, wodurch Nginx eine unvollständige Antwort erhält.

Symptome: Nginx-Fehlerprotokolle zeigen möglicherweise upstream timed out oder script timed out. PHP-FPM-Protokolle zeigen möglicherweise child XX exited on signal 9 (SIGKILL).

Lösung:
* Erhöhen Sie request_terminate_timeout: Suchen und passen Sie diese Direktive in Ihrer PHP-FPM-Pool-Konfiguration (www.conf) an. Die Einstellung auf 0 deaktiviert das Timeout, was jedoch im Allgemeinen nicht empfohlen wird, da lang laufende Skripte Ressourcen blockieren können.

```ini
request_terminate_timeout = 300 # Auf 5 Minuten (300 Sekunden) erhöhen
```

Erhöhen Sie fastcgi_read_timeout in Nginx: Dieses Nginx-Timeout sollte gleich oder größer als request_terminate_timeout von PHP-FPM sein.

nginx location ~ \.php$ { ... fastcgi_read_timeout 300s; # Muss >= request_terminate_timeout von PHP-FPM sein ... }

Warnung: Obwohl das Erhöhen von Timeouts den 502-Fehler beheben kann, kann es zugrunde liegende Leistungsprobleme maskieren. Die beste Langzeitlösung besteht darin, das langsame PHP-Skript zu optimieren.

5. Firewall-Probleme

Ursache: Eine Firewall (entweder auf dem Nginx-Server oder dem Upstream-Server, falls diese getrennt sind) blockiert Verbindungen zum Upstream-Port oder -Socket.

Lösung:
* Firewall-Status prüfen:

```bash
sudo ufw status # Für UFW (Ubuntu/Debian)
sudo firewall-cmd --list-all # Für firewalld (CentOS/RHEL)
sudo iptables -L # Für iptables
```

Notwendige Ports öffnen: Stellen Sie sicher, dass der Port, den Nginx zum Verbinden mit dem Upstream verwendet (z. B. 9000 für PHP-FPM über TCP/IP), geöffnet ist.

bash sudo ufw allow from 127.0.0.1 to any port 9000 # Lokalen Host den Zugriff auf 9000 erlauben sudo firewall-cmd --permanent --add-port=9000/tcp # Für firewalld sudo firewall-cmd --reload
* Deaktivieren Sie die Firewall zu Testzwecken nur in einer kontrollierten Umgebung vorübergehend und aktivieren Sie sie dann wieder und konfigurieren Sie sie korrekt.

6. SELinux- oder AppArmor-Interferenzen

Ursache: Sicherheitsverbesserungen wie SELinux (auf RHEL/CentOS) oder AppArmor (auf Ubuntu/Debian) verhindern möglicherweise, dass Nginx auf den Upstream-Socket zugreift oder Netzwerkverbindungen herstellt, selbst wenn Dateiberechtigungen und Firewalls korrekt konfiguriert sind.

Symptome: Protokolle zeigen möglicherweise permission denied oder ähnliche Meldungen an, insbesondere in /var/log/audit/audit.log (für SELinux).

Lösung:
* audit.log prüfen:

```bash
sudo grep nginx /var/log/audit/audit.log
```

SELinux vorübergehend in den permissiven Modus setzen: sudo setenforce 0. Wenn sich der Fehler behebt, ist SELinux der Übeltäter. Sie müssen dann die entsprechenden SELinux-Richtlinien generieren und anwenden (z. B. audit2allow). Denken Sie daran, ihn wieder auf erzwingend (sudo setenforce 1) zu setzen.
AppArmor-Status prüfen: sudo aa-status. Wenn AppArmor aktiv ist, müssen Sie möglicherweise das Nginx-Profil anpassen.

7. Große Anforderungs-/Antwortkörper (Proxy-Pufferung)

Ursache: Die Standardeinstellungen für die Proxy-Pufferung von Nginx sind möglicherweise zu klein für sehr große Anforderungs- oder Antwortkörper, was zu einem vorzeitigen Verbindungsabbruch führt.

Symptome: Nginx-Fehlerprotokolle zeigen möglicherweise upstream prematurely closed connection while reading response header from upstream oder upstream prematurely closed connection while reading response body from upstream an.

Lösung: Passen Sie die Nginx-Proxy-Pufferungsdirektiven in Ihrem http, server oder location Block an.

http {
    ...
    proxy_buffer_size   128k; # Größe des Puffers für den ersten Teil der Antwort
    proxy_buffers   4 256k; # Anzahl und Größe der Puffer für den Rest der Antwort
    proxy_busy_buffers_size   256k; # Maximalgröße von ausgelasteten Puffern
    proxy_temp_file_write_size 256k; # Größe für das Schreiben in temporäre Dateien, falls die Pufferung überläuft
    ...
}

Hinweis: Diese Einstellungen verbrauchen mehr Speicher. Passen Sie sie vorsichtig an die Ressourcen Ihres Servers und die typische Größe der Antworten Ihrer Anwendung an.

Allgemeine Tipps zur Fehlerbehebung

Alle relevanten Protokolle überprüfen: Überprüfen Sie neben den Nginx-Fehlerprotokollen auch die Nginx-Zugriffsprotokolle, die Protokolle der Upstream-Anwendung (PHP-FPM, Gunicorn, Node.js-App-Protokolle) und die Systemprotokolle (/var/log/syslog, dmesg).
Nginx neu starten: Starten Sie Nginx nach allen Konfigurationsänderungen immer neu, um sicherzustellen, dass diese wirksam werden: systemctl restart nginx.
Nginx-Konfiguration testen: Validieren Sie Ihre Nginx-Konfigurationssyntax, bevor Sie neu starten: nginx -t.
Problem isolieren: Versuchen Sie, Nginx zu umgehen und direkt auf die Upstream-Anwendung zuzugreifen. Wenn Ihre Node.js-App beispielsweise auf localhost:3000 läuft, verwenden Sie curl http://localhost:3000 von der Befehlszeile des Servers aus. Wenn dies ebenfalls fehlschlägt, liegt das Problem definitiv bei Ihrer Anwendung und nicht bei Nginx.
Festplattenspeicherplatz prüfen: Eine volle Festplatte kann verhindern, dass Anwendungen temporäre Dateien oder Protokolle schreiben, was zu Abstürzen oder Fehlern führen kann. Verwenden Sie df -h, um die Festplattenauslastung zu überprüfen.

Fazit

Nginx 502 Bad Gateway Fehler sind häufig, deuten jedoch fast immer auf ein Problem mit der Backend-Anwendung hin, mit der Nginx zu verbinden versucht, nicht auf Nginx selbst. Indem Sie systematisch Ihre Nginx-Fehlerprotokolle überprüfen, den Status des Upstream-Servers verifizieren, die Netzwerkkonnektivität bestätigen und dann allgemeine Konfigurations- oder Ressourcenprobleme beheben, können Sie diese Probleme effektiv diagnostizieren und beheben.

Denken Sie daran, die Fehlerbehebung methodisch anzugehen, indem Sie mit den grundlegendsten Prüfungen beginnen und schrittweise tiefer graben. Testen Sie immer Ihre Nginx-Konfiguration nach Änderungen und überwachen Sie die Integrität Ihrer Anwendung und Ihres Servers, um zukünftige Vorkommnisse zu vermeiden. Mit diesen Strategien sind Sie gut gerüstet, um den reibungslosen Betrieb Ihrer Dienste zu gewährleisten.