Kurze Antwort
Der Fehler 502 Bad Gateway bedeutet, dass Nginx keine gültige Antwort vom Backend-Dienst (PHP-FPM, Node.js, Gunicorn) erhalten kann. Prüfen Sie, ob der Backend-Prozess läuft, ob Sockets und Ports erreichbar sind und ob die Logs voller Fehler sind. In den meisten Fällen hilft ein Neustart des Backend-Dienstes oder eine Korrektur der Konfiguration.
So erkennen Sie das Problem
- Die Website zeigt eine weiße Seite mit dem Text 502 Bad Gateway
- Einige Seiten funktionieren, aber dynamische (PHP, API) liefern 502
- Im Nginx-Error-Log erscheint connect() failed
- Der Backend-Dienst (PHP-FPM, Node) ist abgestürzt oder startet neu
- 502 tritt sporadisch auf, besonders unter Last
Häufigste Ursachen
Backend-Dienst läuft nicht
PHP-FPM, Node.js, Gunicorn oder ein anderer Anwendungsserver ist abgestürzt oder wurde gestoppt. Nginx hat dann niemanden, an den es die Anfrage weiterleiten kann.
Falscher Socket oder Port in der Konfiguration
Nginx verweist auf einen nicht existierenden Unix-Socket oder einen Port, auf dem das Backend nicht lauscht. Der Fehler tritt auch nach Konfigurationsänderungen oder Upgrades auf.
Überlastetes Backend
Wenn PHP-FPM oder die Anwendung alle Ressourcen verbrauchen, können sie keine neuen Anfragen annehmen. Nginx gibt dann 502 oder 504 zurück.
Berechtigungen für den Socket
Der Nginx-Benutzer (z. B. www-data oder nginx) hat keine Zugriffsberechtigung auf den Unix-Socket. Das passiert oft nach Änderungen des Eigentümers oder der SELinux-Policy.
Backend stürzt wegen eines Codefehlers ab
Ein fataler Fehler in der Anwendung kann den Arbeitsprozess zum Absturz bringen. In den Logs sehen Sie einen Segfault oder PHP Fatal error.
Lösung Schritt für Schritt
- 1
Prüfen Sie den Status des Backend-Dienstes
Führen Sie
systemctl status php8.2-fpmaus (oder den entsprechenden Dienst:php-fpm,node,gunicorn). Wenn der Dienst inaktiv ist, versuchen Siesystemctl restart php8.2-fpm. Wenn er sofort wieder stoppt, lesen Sie die Logs. - 2
Sehen Sie das Nginx-Error-Log ein
Öffnen Sie
/var/log/nginx/error.log(oder den Pfad ausnginx -T). Suchen Sie nach Zeilen mitconnect() failedoderno live upstreams. Sie zeigen, ob Nginx keine Verbindung zum Socket oder Port herstellen kann. - 3
Prüfen Sie, ob das Backend lauscht
Für Unix-Socket:
ls -l /run/php/php8.2-fpm.sock. Für TCP-Port:ss -tlnp | grep 3000. Wenn keine Ausgabe erfolgt, lauscht das Backend nicht und das Problem liegt in seiner Konfiguration oder beim Start. - 4
Passen Sie den Pfad in der Nginx-Konfiguration an
In der Website-Datei (z. B.
/etc/nginx/sites-enabled/example.conf) prüfen Siefastcgi_passoderproxy_pass. Der Socket-Pfad oder Port muss dem entsprechen, was das Backend tatsächlich verwendet. Nach der Änderung führen Sienginx -tund dannsystemctl reload nginxaus. - 5
Prüfen Sie die Berechtigungen für den Socket
Der Socket sollte dem Benutzer gehören, unter dem das Backend läuft, und der Nginx-Benutzer muss Zugriff haben. Passen Sie bei Bedarf die Berechtigungen an (z. B.
chmod 660und die entsprechende Gruppe) und starten Sie beide Dienste neu. - 6
Verfolgen Sie die Anwendungslogs
Sehen Sie sich das PHP-Error-Log (
/var/log/php8.2-fpm.log),journalctl -u php8.2-fpm -n 50oder das Anwendungslog an. Wenn Sie fatale Fehler sehen, korrigieren Sie den Code oder die Konfiguration, bevor Sie weitere Neustarts durchführen. - 7
Testen Sie den Zugriff lokal auf dem Server
Führen Sie auf dem Server
curl -I -H 'Host: example.com' http://127.0.0.1undcurl -I http://127.0.0.1:3000aus (wenn die Anwendung auf diesem Port lauscht). Wenn es lokal funktioniert, aber von außen nicht, liegt das Problem im Netzwerk, in der Firewall oder in der Nginx-Konfiguration. - 8
Starten Sie die Dienste der Reihe nach neu
Starten Sie zuerst das Backend neu (
systemctl restart php8.2-fpm), dann Nginx (systemctl restart nginx). Laden Sie anschließend die Website neu. Wenn 502 weiterhin besteht, kehren Sie zu den Logs zurück.
Wenn nichts hilft
Wenn die Dienste aktiv sind, die Sockets erreichbar sind und die Logs keine offensichtlichen Fehler zeigen, prüfen Sie, ob das Problem im Netzwerk oder in SELinux liegt. Der Befehl getenforce zeigt, ob SELinux im Modus Enforcing ist; vorübergehend können Sie ihn zum Testen auf Permissive setzen (setenforce 0), aber setzen Sie ihn unbedingt wieder auf Enforcing (setenforce 1). Prüfen Sie auch, ob die Festplatte voll ist (df -h) und ob genügend Speicher vorhanden ist (free -m). Wenn 502 nur unter Last auftritt, erhöhen Sie die Anzahl der PHP-FPM-Prozesse oder worker_connections in Nginx. Für die Produktionsumgebung sollten Sie ein Monitoring in Betracht ziehen, das Sie benachrichtigt, bevor Benutzer den Fehler bemerken.
So beugen Sie vor
- Überwachen Sie regelmäßig den Betrieb der Backend-Dienste und richten Sie einen Alarm für Ausfälle ein
- Halten Sie die Nginx- und PHP-FPM-Konfiguration mit den tatsächlichen Sockets abgeglichen
- Überwachen Sie die Ressourcennutzung und erhöhen Sie die Limits rechtzeitig
- Testen Sie Konfigurationsänderungen mit `nginx -t` vor dem Reload
Wann Sie einen Profi rufen sollten
Wenn der Fehler wiederholt auftritt und Änderungen an der Konfiguration oder am Code erfordert, oder wenn Sie keinen Zugriff auf Logs und Root-Berechtigungen haben, ist es besser, den IT-Support anzurufen. Dieser kann die Ursache schnell isolieren und eine längere Ausfallzeit der Website verhindern.
IT-Infrastruktur-Wartung · Server, Netzwerke, Backup, Sicherheit und HelpdeskHäufige Fragen
Ist 502 dasselbe wie 504?
Nein. 502 bedeutet, dass das Backend eine ungültige Antwort zurückgegeben hat oder Nginx keine Verbindung herstellen konnte, während 504 bedeutet, dass das Backend zu lange geschwiegen hat. In der Praxis werden sie oft ähnlich behoben, indem man den Backend-Dienst und die Logs prüft.
Warum tritt 502 nur auf einigen Seiten auf?
Statische Dateien werden von Nginx direkt ausgeliefert und funktionieren daher. Dynamische Seiten hängen vom Backend ab und melden daher 502. Das bestätigt, dass das Problem im Anwendungsserver und nicht in Nginx liegt.
Kann ich nur PHP-FPM neu starten?
Ja, wenn das Problem in PHP-FPM liegt, reicht `systemctl restart php8.2-fpm`. Starten Sie Nginx nur neu, wenn Sie seine Konfiguration geändert haben oder das Problem weiterhin besteht.