Fehlerbehebung bei häufigen Nginx-Fehlern: Ein praktischer Leitfaden

Die Fehlerbehebung bei häufigen Nginx-Fehlern wird viel einfacher, wenn Sie aufhören, den Statuscode als das gesamte Problem zu betrachten. Ein 502 könnte eine abgestürzte App, ein falscher Socket-Pfad oder ein Backend sein, das fehlerhafte Header zurückgegeben hat. Ein 403 könnte Dateiberechtigungen, eine fehlende Indexdatei oder eine Deny-Regel sein, die mehr abdeckt als erwartet.

Beginnen Sie mit Beweisen: dem Fehlerprotokoll, dem Zugriffsprotokoll, nginx -t und den Backend-Protokollen, wenn Nginx als Proxy für eine App fungiert. Raten allein anhand der Browserseite verschwendet Zeit.

Beginnen Sie mit den schnellen Überprüfungen

Führen Sie diese aus, bevor Sie die Konfiguration ändern:

sudo nginx -t
sudo systemctl status nginx --no-pager
sudo tail -n 80 /var/log/nginx/error.log
sudo tail -n 80 /var/log/nginx/access.log

nginx -t sagt Ihnen, ob die Konfiguration geparst werden kann. Der Dienststatus sagt Ihnen, ob Nginx läuft. Die Protokolle sagen Ihnen, was Nginx bei der Bearbeitung der Anfrage gesehen hat.

Wenn das Problem mit einer bestimmten URL zusammenhängt, reproduzieren Sie es mit curl, damit Sie Header und Status klar sehen können:

curl -I https://example.com/problem/path
curl -v https://example.com/problem/path

Wenn das Problem nur für einen bestimmten Hostnamen auftritt, fügen Sie ihn hinzu:

curl -I -H 'Host: app.example.com' http://127.0.0.1/

Das trennt das Nginx-Routing vom DNS-, CDN- und Load-Balancer-Verhalten.

Nginx startet oder lädt nicht neu

Ein Startfehler ist normalerweise ein Syntaxfehler, eine doppelte Direktive im falschen Kontext, eine fehlende Include-Datei oder ein Zertifikatspfadproblem.

Verwenden Sie:

sudo nginx -t
sudo journalctl -u nginx -n 100 --no-pager

Häufige Meldungen sind direkt:

• unknown directive bedeutet einen Tippfehler, ein nicht unterstütztes Modul oder eine Direktive, die in der falschen Nginx-Build-Version platziert wurde.
• directive is not allowed here bedeutet, dass die Direktive im falschen Kontext ist, z. B. das Platzieren einer http-nur-Direktive innerhalb von server.
• cannot load certificate bedeutet, dass der Pfad falsch ist, die Datei fehlt oder Berechtigungen Nginx am Lesen hindern.
• bind() to 0.0.0.0:80 failed bedeutet oft, dass ein anderer Prozess den Port bereits verwendet.

Überprüfen Sie Ports mit:

sudo ss -tulnp | grep ':80\|:443'

Laden Sie nicht neu, bis nginx -t bestanden ist. Ein fehlgeschlagenes Neuladen behält normalerweise den alten Worker-Prozess bei, aber ein fehlgeschlagener Neustart kann die Website lahmlegen.

(13: Permission denied) und 403 Forbidden

Permission denied erscheint im Fehlerprotokoll, wenn der Nginx-Worker-Benutzer eine Datei nicht lesen oder ein Verzeichnis nicht durchlaufen kann. Ein Browser kann 403 Forbidden anzeigen.

Finden Sie zuerst den Worker-Benutzer:

grep -R '^user ' /etc/nginx/nginx.conf

Auf Debian und Ubuntu ist es oft www-data. Auf RHEL-kompatiblen Systemen ist es oft nginx.

Für ein statisches Root wie /var/www/html benötigt Nginx die Ausführungsberechtigung für jedes übergeordnete Verzeichnis und die Leseberechtigung für die Datei:

sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

Vermeiden Sie reflexartiges Ausführen von chown -R www-data:www-data auf Anwendungsverzeichnissen. Es kann den Fehler verschwinden lassen, während dem Webserver Schreibzugriff gewährt wird, den er nicht benötigt. Ein sichereres Muster ist, die Berechtigungen für die Bereitstellung getrennt zu halten und Nginx nur Lesezugriff zu gewähren.

Wenn die Berechtigungen in Ordnung aussehen, überprüfen Sie, ob die Anfrage für ein Verzeichnis ohne Indexdatei erfolgt:

location / {
    root /var/www/html;
    index index.html index.htm;
}

Wenn /docs/ keine index.html hat und autoindex deaktiviert ist, gibt Nginx 403 zurück. Das ist korrektes Verhalten.

SELinux kann auch berechtigungsähnliche Fehler auf RHEL-Familien-Systemen verursachen. Wenn Dateiberechtigungen korrekt sind, Nginx aber immer noch nicht lesen oder als Proxy fungieren kann, überprüfen Sie die Audit-Protokolle, bevor Sie SELinux deaktivieren:

sudo ausearch -m avc -ts recent

(111: Connection refused) und 502 Bad Gateway

Connection refused bedeutet, dass Nginx versucht hat, eine Verbindung zu einem Upstream herzustellen, und das Ziel diese aktiv abgelehnt hat. Die App könnte ausgefallen sein, auf einer anderen Adresse lauschen oder einen Socket-Pfad verwenden, der nicht existiert.

Für diesen Proxy:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Überprüfen Sie:

sudo ss -tulnp | grep 3000
curl -I http://127.0.0.1:3000
sudo systemctl status your-app --no-pager

Wenn Nginx einen Unix-Socket verwendet, überprüfen Sie die Socket-Datei:

ls -l /run/gunicorn/app.sock

Der Worker-Benutzer muss den Socket lesen und beschreiben können.

Ein 502 Bad Gateway ist breiter gefasst. Nginx hat etwas im Upstream erreicht, aber die Antwort war ungültig, unvollständig, zu früh geschlossen oder nicht das, was Nginx erwartet hat. Überprüfen Sie die App-Protokolle zum gleichen Zeitstempel wie den Nginx-Fehler. Dieser Zeitstempel-Match ist wichtig; sonst jagen Sie der Ausnahme von gestern hinterher.

Für PHP-FPM überprüfen Sie, ob fastcgi_pass mit dem konfigurierten Pool-Socket oder -Port übereinstimmt. Zum Beispiel:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Überprüfen Sie dann:

sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock

504 Gateway Timeout

Ein 504 bedeutet, dass Nginx auf den Upstream gewartet hat und keine rechtzeitige Antwort erhalten hat. Das Erhöhen von Timeouts kann für Berichte, Importe oder langsame Admin-Operationen gültig sein, sollte aber nicht die einzige Lösung für einen öffentlichen Endpunkt sein, der bei jeder Anfrage langsam ist.

location /api/reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 180s;
}

Schauen Sie sich dann das Backend-Timing an. Fügen Sie Upstream-Timing zu Zugriffsprotokollen hinzu, falls Sie es nicht bereits haben:

log_format proxy_timing '$remote_addr "$request" $status '
                        'request_time=$request_time '
                        'upstream_time=$upstream_response_time';

Wenn $upstream_response_time hoch ist, liegt der Fokus wahrscheinlich auf der App oder Datenbank. Wenn Nginx Timeouts anzeigt, die App-Protokolle aber sagen, dass sie schnell geantwortet hat, überprüfen Sie Netzwerk-Hops, Container-Netzwerke, DNS-Auflösung innerhalb des Hosts oder einen Load Balancer zwischen Nginx und der App.

413 Request Entity Too Large

413 ist normalerweise unkompliziert: Der Anforderungskörper ist größer als von Nginx erlaubt. Uploads, große JSON-Payloads und Formularbeiträge können dies auslösen.

Setzen Sie client_max_body_size an der engsten sinnvollen Stelle:

server {
    server_name example.com;

    location /upload/ {
        client_max_body_size 100M;
        proxy_pass http://127.0.0.1:3000;
    }
}

Ein riesiges globales Limit zu setzen, ist selten eine gute Idee. Die meisten Routen benötigen es nicht, und größere erlaubte Körper erhöhen die Arbeit, die ein böswilliger Client Ihrem Stack aufzwingen kann.

SSL- und Zertifikatsfehler

TLS-Fehler sehen je nachdem, wo Sie sie bemerken, oft unterschiedlich aus. Nginx kann möglicherweise nicht neu laden, Browser können vor dem Zertifikat warnen oder Clients können einen Handshake nicht abschließen.

Überprüfen Sie Zertifikatsdaten:

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject -issuer

Überprüfen Sie, was der öffentliche Dienst präsentiert:

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Wenn diese beiden Befehle unterschiedliche Zertifikate anzeigen, könnte ein Load Balancer, CDN oder ein anderer Host den Verkehr bedienen.

400 Bad Request und Header-Probleme

400 bedeutet normalerweise, dass Nginx die Anforderungssyntax nicht akzeptiert hat. Bei echten Browsern ist es weniger häufig, aber Bots, alte Clients, ungewöhnliche Proxys oder überdimensionierte Header können es verursachen.

Achten Sie auf Meldungen wie client sent too large request header. Wenn ein legitimes SSO- oder Anwendungs-Cookie zu groß ist, müssen Sie möglicherweise die Header-Puffer-Einstellungen anpassen. Behandeln Sie dies als gezielte Lösung, nicht als erste Reaktion. Überdimensionierte Cookies werden oft besser in der Anwendung behoben.

Eine praktische Vorgehensweise

Wenn ein Nginx-Problem live ist, verwenden Sie eine wiederholbare Reihenfolge:

1. Bestätigen Sie die genaue URL, den Host, den Statuscode und die Zeit.
2. Überprüfen Sie nginx -t und den Dienststatus.
3. Ordnen Sie die Anfrage im Zugriffsprotokoll zu.
4. Ordnen Sie denselben Zeitstempel im Fehlerprotokoll zu.
5. Wenn als Proxy verwendet, überprüfen Sie den Upstream-Dienststatus und die Protokolle.
6. Testen Sie den Upstream direkt vom Nginx-Host aus.
7. Nehmen Sie die kleinste Konfigurationsänderung vor, die zu den Beweisen passt.
8. Führen Sie nginx -t aus, laden Sie neu und beobachten Sie die Protokolle während des erneuten Testens.

Die meisten Nginx-Probleme werden alltäglich, sobald Sie wissen, wo der Fehler aufgetreten ist: vor Nginx, innerhalb von Nginx, zwischen Nginx und dem Upstream oder innerhalb des Upstream-Dienstes.