Fehlerbehebung bei Nginx: Häufige Befehlszeilenlösungen für Webserver-Probleme

Wenn Nginx ausfällt, geht es in den ersten Minuten meist darum, das Problem einzugrenzen. Ist der Dienst gestoppt? Ist eine Konfigurationsänderung fehlgeschlagen? Nutzt ein anderer Prozess bereits Port 80? Läuft Nginx einwandfrei, aber die Upstream-Anwendung ist ausgefallen? Die Befehlszeile liefert schnelle Antworten, wenn Sie die Prüfungen in der richtigen Reihenfolge durchführen.

Ich beginne gerne mit den am wenigsten destruktiven Befehlen: Status prüfen, Konfiguration testen, Protokolle lesen und erst dann neu laden oder neu starten. Ein Neustart kann nützliche Beweise verbergen. Behandeln Sie ihn daher nur als Lösung, wenn Sie wissen, was Sie beheben.

Wichtige Nginx-Verwaltungsbefehle

Der erste Schritt bei der Fehlerbehebung besteht oft darin, den Status des Nginx-Dienstes selbst zu überprüfen. Abhängig von Ihrem Betriebssystem interagieren Sie normalerweise entweder mit systemd oder service (SysVinit).

1. Überprüfen des Nginx-Dienststatus

Zu wissen, ob Nginx läuft, gestoppt ist oder ausfällt, ist entscheidend. Der Befehl status liefert diese Übersicht.

Verwendung von systemd (Üblich auf modernen Linux-Distributionen wie Ubuntu 16.04+, CentOS 7+):

sudo systemctl status nginx

Erwartete Ausgabe (Aktiv/Läuft):

● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2023-10-24 10:00:00 UTC; 1h ago
     Docs: man:nginx(8)
 Main PID: 1234 (nginx)
    Tasks: 2 (limit: 4915)
   CGroup: /system.slice/nginx.service
           ├─1234 nginx: master process /usr/sbin/nginx -g daemon on;
           └─1235 nginx: worker process

Wenn die Ausgabe Active: inactive (dead) oder Active: failed anzeigt, wissen Sie, dass Nginx derzeit keinen Datenverkehr bedient. Das sagt Ihnen nicht, warum. Der nächste Hinweis ist normalerweise ein Konfigurationstest oder das System-Journal.

sudo journalctl -u nginx -n 80 --no-pager

Dies zeigt die letzten Dienstprotokolle, einschließlich Startfehler von systemd. Achten Sie auf Meldungen über unbekannte Direktiven, fehlende Zertifikatsdateien, Bind-Fehler oder Berechtigungsfehler.

2. Starten, Stoppen und Neuladen von Nginx

Sobald Sie den Status identifiziert haben, müssen Sie ihn verwalten. Verwenden Sie die folgenden Befehle nach Bedarf:

Aktion	Befehl (mit `systemctl`)
Stoppen des Dienstes	`sudo systemctl stop nginx`
Starten des Dienstes	`sudo systemctl start nginx`
Neustarten des Dienstes	`sudo systemctl restart nginx` (Stoppt und startet dann neu)
Neuladen der Konfiguration	`sudo systemctl reload nginx` (Wendet neue Konfigurationen an, ohne Verbindungen zu trennen)

Bewährte Methode: Verwenden Sie reload anstelle von restart Wenn Sie Konfigurationsänderungen vornehmen (z. B. Aktualisieren von virtuellen Hosts oder SSL-Zertifikaten), verwenden Sie immer reload. Dadurch werden Änderungen elegant übernommen, während bestehende Verbindungen ohne Unterbrechung fortgesetzt werden. Verwenden Sie restart nur, wenn reload fehlschlägt oder wenn Sie die Worker-Prozesse vollständig zurücksetzen müssen.

Führen Sie vor jedem Neuladen Folgendes aus:

sudo nginx -t && sudo systemctl reload nginx

Dieses Einzeiler-Muster verhindert den häufigsten Fehler: das Neuladen einer defekten Konfiguration und das Herunterfahren eines funktionierenden Servers. Wenn nginx -t fehlschlägt, wird der Neuladebefehl nicht ausgeführt.

Validieren von Konfigurationsdateien

Die häufigste Ursache für Startfehler oder unerwartetes Verhalten von Nginx ist ein Syntaxfehler in den Konfigurationsdateien (nginx.conf oder Dateien, die in /etc/nginx/sites-available/ eingebunden sind). Nginx bietet ein hervorragendes integriertes Testdienstprogramm.

3. Testen der Konfigurationssyntax

Das Flag -t testet die Konfigurationsdateien auf Syntaxfehler und prüft, ob die Pfade der Konfigurationsdateien gültig sind.

sudo nginx -t

Beispiel für eine erfolgreiche Ausgabe:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Beispiel für eine Fehlerausgabe:

Wenn ein Fehler vorliegt, zeigt Nginx auf die genaue Datei und Zeilennummer. Zum Beispiel ein fehlendes Semikolon:

nginx: [emerg] unknown directive "server_name example.com" in /etc/nginx/sites-enabled/default:15
nginx: configuration file /etc/nginx/nginx.conf test failed

Diese sofortige Rückmeldung ermöglicht es Ihnen, direkt zur Zeile 15 der angegebenen Datei zu springen, um den Tippfehler zu korrigieren.

Manchmal ist die gemeldete Zeile nur die Stelle, an der Nginx das Problem schließlich bemerkt hat. Eine fehlende } oder ; kann ein paar Zeilen früher sein. Wenn der Fehler auf eine normal aussehende Direktive zeigt, überprüfen Sie den Block darüber.

4. Anzeigen der aktiven Konfiguration

Um genau zu sehen, was Nginx derzeit ausführt (besonders nützlich nach mehreren Konfigurationszusammenführungen oder komplexen Includes), verwenden Sie das Flag -T (Großbuchstabe T):

sudo nginx -T

Dies gibt die gesamte aktive Konfiguration aus, die zum Vergleich oder zur detaillierten Überprüfung in eine Datei umgeleitet werden kann:

sudo nginx -T > current_nginx_config.txt

Seien Sie vorsichtig beim Teilen der Ausgabe von nginx -T. Sie kann interne Hostnamen, Zertifikatspfade, Proxy-Header und manchmal Geheimnisse enthalten, die als Header übergeben werden. Für die Incident-Arbeit ist sie hervorragend. Für Tickets oder Chats sollten Sie sie zuerst schwärzen.

Überprüfen von Ports und Listenern

Wenn Nginx nicht startet und die Protokolle bind() to 0.0.0.0:80 failed erwähnen, lauscht möglicherweise bereits ein anderer Prozess auf dem Port.

sudo ss -ltnp | grep -E ':80|:443'

Die typische Ausgabe zeigt die lokale Adresse, den Port und den Prozessnamen. Wenn Apache, Caddy, ein Container-Proxy oder ein alter Nginx-Prozess den Port belegt, kann Nginx nicht daran binden.

Sie können das öffentliche Verhalten auch vom Server selbst aus bestätigen:

curl -I http://127.0.0.1
curl -Ik https://127.0.0.1

-I ruft nur Header ab. -k ignoriert die Zertifikatsvalidierung, was nützlich ist, wenn Sie Localhost gegen ein für einen Domainnamen ausgestelltes Zertifikat testen. Testen Sie von einem anderen Rechner aus auch den echten Hostnamen:

curl -I https://example.com

Wenn Localhost funktioniert, der öffentliche Hostname jedoch fehlschlägt, überprüfen Sie Firewall-Regeln, Cloud-Sicherheitsgruppen, DNS, Load Balancer oder CDN-Konfiguration.

DNS ist eine separate Überprüfung wert, da es einen gesunden Nginx-Server von außen defekt erscheinen lassen kann:

dig +short example.com
dig +short www.example.com

Stellen Sie sicher, dass die zurückgegebene Adresse der Server oder Load Balancer ist, den Sie erwarten. Wenn Sie die Website kürzlich verschoben haben, kann veraltetes DNS einige Benutzer zum alten Host leiten, während Ihre eigenen Tests den neuen treffen.

Überwachung und Protokollanalyse

Wenn Nginx erfolgreich startet, aber falsche Seiten ausliefert oder 5xx-Fehler zurückgibt, werden die Protokolle zur primären Informationsquelle.

5. Auffinden wichtiger Protokolldateien

Standardmäßig befinden sich Nginx-Protokolle normalerweise in /var/log/nginx/. Die beiden wesentlichen Dateien sind:

access.log: Zeichnet jede vom Server verarbeitete Anfrage auf, einschließlich IP, Anfragezeit, Statuscode und angeforderter Ressource.
error.log: Zeichnet Warnungen, Hinweise und kritische Fehler auf, die während des Betriebs oder der Anfrageverarbeitung auftreten.

6. Echtzeit-Protokollüberwachung mit `tail`

Um Fehler zu überwachen, während sie auftreten, verwenden Sie den Befehl tail mit der Option Follow (-f) für das Fehlerprotokoll.

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

Dies ist unschätzbar wertvoll, wenn Sie einen neu bereitgestellten Anwendungsendpunkt testen, da Sie sofort sehen können, ob Nginx oder die Upstream-Anwendung Fehler wirft.

Folgen Sie bei einem stark ausgelasteten Server nur neuen Fehlerzeilen und behalten Sie die Zeitstempel im Blick:

sudo tail -n 50 -f /var/log/nginx/error.log

Reproduzieren Sie dann die fehlgeschlagene Anfrage in einem anderen Terminal:

curl -I https://example.com/failing/path

Dieser einfache Zwei-Terminal-Workflow ist oft schneller als das Herumklicken in einem Browser, da jede Anfrage und jeder Protokolleintrag direkt zugeordnet werden können.

7. Analysieren von Zugriffsprotokoll-Statuscodes

Bei Problemen mit hohem Datenverkehr kann das schnelle Durchsuchen des Zugriffsprotokolls nach Statuscodes Probleme aufdecken:

4xx-Codes (Client-Fehler): Deuten oft auf defekte Links, fehlende Dateien (404) oder Berechtigungsprobleme hin.
5xx-Codes (Server-Fehler): Zeigen an, dass Nginx selbst die Anfrage nicht erfüllen konnte, oft aufgrund von Upstream-Verbindungszeitüberschreitungen (502/504) oder internen Serververarbeitungsfehlern (500).

Verwenden Sie grep, um nach bestimmten Codes zu filtern. Zum Beispiel, um alle 502 Bad Gateway-Fehler zu finden:

sudo grep ' 502 ' /var/log/nginx/access.log | tail -n 20

Eine schnelle Statuscode-Zählung kann zeigen, ob Sie es mit einer einzigen fehlerhaften URL oder einem größeren Vorfall zu tun haben:

sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head

Häufige Muster:

404-Spitzen deuten oft auf einen fehlerhaften Bereitstellungspfad, fehlende statische Dateien oder geänderte Routen hin.
403 deutet oft auf Dateiberechtigungen, Verzeichnisberechtigungen oder eine absichtliche Zugriffsregel hin.
502 bedeutet normalerweise, dass Nginx keine gültige Antwort vom Upstream-Dienst erhalten konnte.
504 bedeutet normalerweise, dass der Upstream-Dienst die Verbindung akzeptiert, aber nicht rechtzeitig geantwortet hat.

Überprüfen Sie bei Upstream-Fehlern auch den Anwendungsdienst:

sudo systemctl status myapp
sudo journalctl -u myapp -n 100 --no-pager

Ersetzen Sie myapp durch den tatsächlichen Dienstnamen. Nginx kann nur das proxyen, was lebendig und erreichbar ist.

Erweiterte Diagnose: Ausführlichkeit und Prozess-ID

8. Erzwingen der Debug-Protokollierung (Vorsicht geboten)

In sehr kniffligen Situationen kann die Erhöhung der Protokollierungsstufe detailliertere Informationen über die Anfrageverarbeitung liefern. Dies geschieht durch Ändern der Direktive error_log in Ihrer Konfiguration auf debug.

Warnung: Die Debug-Protokollierung erzeugt sehr schnell massive Datenmengen und sollte nur vorübergehend für die aktive Fehlerbehebung verwendet werden, da sie die Leistung erheblich beeinträchtigt.

Nachdem Sie die Direktive geändert haben, müssen Sie Nginx mit reload oder restart neu laden, damit die Änderung wirksam wird.

9. Finden der Nginx-Master-Prozess-ID (PID)

Die Prozess-ID (PID) ist nützlich, um bestimmte Signale an den laufenden Master-Prozess zu senden (z. B. für ein ordnungsgemäßes Herunterfahren oder ein ordnungsgemäßes Neuladen außerhalb von systemctl). Die PID wird normalerweise in einer Datei gespeichert, normalerweise /var/run/nginx.pid.

cat /var/run/nginx.pid
# Beispielausgabe: 1234

Sie können dann bei Bedarf den Befehl kill verwenden (z. B. sudo kill -HUP 1234, um ein Neuladen über die PID zu erzwingen):

Die meisten Betreiber sollten systemctl reload nginx bevorzugen, da es über den Dienstmanager läuft und einfacher zu prüfen ist. Signale sind immer noch auf minimalistischen Systemen, Containern oder älteren Hosts nützlich, auf denen systemd den Prozess nicht verwaltet.

Häufige Befehlszeilen-Fixes nach Symptom

Wenn Nginx nach einer Konfigurationsbearbeitung fehlschlägt:

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

Korrigieren Sie die gemeldete Datei und Zeile, testen Sie dann erneut, bevor Sie neu laden.

Wenn HTTPS nach der Zertifikatserneuerung fehlschlägt:

sudo nginx -t
sudo ls -l /etc/letsencrypt/live/example.com/
sudo openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject

Dies bestätigt, dass die Zertifikatsdatei existiert, und zeigt den Betreff und die Gültigkeitsdaten an.

Wenn statische Dateien 403 zurückgeben:

namei -l /var/www/example.com/index.html

namei -l gibt die Berechtigungen für jedes Verzeichnis im Pfad aus. Nginx benötigt die Ausführungsberechtigung für übergeordnete Verzeichnisse und die Leseberechtigung für Dateien.

Wenn ein Reverse-Proxy 502 zurückgibt:

sudo grep 'connect() failed' /var/log/nginx/error.log | tail
sudo ss -ltnp | grep 3000
curl -I http://127.0.0.1:3000

Dies prüft, ob der Upstream lauscht und ob er lokal antwortet.

Wenn es sich bei dem Upstream um einen Unix-Socket anstelle eines TCP-Ports handelt, überprüfen Sie den Socket-Pfad und die Berechtigungen:

sudo ls -l /run/myapp/myapp.sock
sudo grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d

Der Nginx-Worker-Benutzer benötigt die Berechtigung, auf den Socket zuzugreifen. Auf vielen Systemen ist dieser Benutzer www-data oder nginx, aber bestätigen Sie dies in nginx.conf, bevor Sie den Besitzer oder die Gruppen ändern.

Vergleichen Sie bei intermittierenden Fehlern erfolgreiche und fehlgeschlagene Anfragen im Zugriffsprotokoll. Eine kleine Stichprobe reicht oft aus:

sudo grep ' 504 ' /var/log/nginx/access.log | tail -n 20
sudo grep ' 200 ' /var/log/nginx/access.log | tail -n 20

Achten Sie auf Muster in Pfaden, Upstream-Antwortzeitfeldern, falls Ihr Protokollformat diese enthält, oder einer bestimmten Client-IP, die schwere Anfragen auslöst.

Workflow zur Fehlerbehebung

Wenn Sie auf ein Nginx-Problem stoßen, führen Sie diese Reihenfolge aus:

Status prüfen: sudo systemctl status nginx.
Konfiguration testen: Wenn der Start fehlgeschlagen ist, führen Sie sudo nginx -t aus. Korrigieren Sie die gemeldeten Fehler.
Neustarten/Neuladen: Wenn die Konfiguration geändert wurde, verwenden Sie sudo systemctl reload nginx.
Protokolle überwachen: Wenn es läuft, aber defekt ist, verwenden Sie sudo tail -f /var/log/nginx/error.log, während Sie das Problem reproduzieren.
Zugriff analysieren: Überprüfen Sie access.log auf Statuscodes, die die Art des Fehlers anzeigen (4xx vs. 5xx).

Diese Reihenfolge verhindert, dass Sie raten müssen. Der Status sagt Ihnen, ob Nginx läuft, Konfigurationstests sagen Ihnen, ob es laden kann, Protokolle sagen Ihnen, was bei echten Anfragen passiert ist, und lokale curl-Prüfungen trennen Nginx-Probleme von Upstream- oder Netzwerkproblemen.

Führen Sie während der Arbeit eine kurze Vorfallnotiz: ausgeführter Befehl, gesehenes Ergebnis und vorgenommene Änderung. Dies verhindert wiederholte Prüfungen und erleichtert die Übergabe erheblich.