DevOps Wissensdatenbank
DevOps Wissensdatenbank

Behebung von Nginx 504 Gateway Timeout und Client-Timeout-Problemen

Meistern Sie Nginx Timeouts, einschließlich des gefürchteten 504 Gateway Timeout, indem Sie lernen, kritische Proxy-Direktiven anzupassen. Dieser Leitfaden beschreibt detailliert, wie Sie `proxy_read_timeout` erhöhen, die Pufferung optimieren und Fehlerprotokolle verwenden, um Kommunikationsfehler zwischen Nginx und Upstream-Servern für eine robuste Verbindungsverarbeitung zu diagnostizieren.

60 Aufrufe

Behebung von Nginx 504 Gateway Timeout und Client Timeout Problemen

Nginx ist zwar für seine hohe Leistung und Stabilität bekannt, kann aber gelegentlich frustrierende Fehler aufweisen, insbesondere HTTP-Statuscodes, die auf eine Kommunikationsstörung hinweisen. Zu den häufigsten gehören die 504 Gateway Timeout und verschiedene clientseitige Timeouts. Diese Probleme ergeben sich fast immer aus einer Nichtübereinstimmung zwischen der Wartezeit von Nginx auf eine Antwort von einem Backend-Dienst (wie einem Anwendungsserver oder einem anderen Proxy) und der Wartezeit, die der Client (Browser oder Upstream-Dienst) für Nginx selbst bereit ist.

Dieser umfassende Leitfaden führt Sie durch die Diagnose der Ursachen dieser Timeouts und bietet konkrete Konfigurationsanpassungen zur Behebung von 504-Fehlern und zur Verbesserung der allgemeinen Verbindungsstabilität. Das Verständnis dieser Mechanismen ist entscheidend für die Aufrechterhaltung einer hohen Verfügbarkeit, insbesondere in Microservice-Architekturen oder bei der Arbeit mit langsam reagierenden Upstream-Anwendungen.

Verständnis des 504 Gateway Timeout Fehlers

Ein 504 Gateway Timeout Fehler tritt auf, wenn Nginx, das als Reverse-Proxy oder Gateway fungiert, keine rechtzeitige Antwort vom Upstream-Server erhält, an den es Anfragen weiterleitet. Einfach ausgedrückt: Nginx hat das Backend um eine Antwort gebeten, hat die konfigurierte Zeit gewartet und aufgegeben, weil keine Antwort einging.

Dies ist zu unterscheiden von einem 502 Bad Gateway (was eine ungültige Antwort vom Upstream impliziert) oder einem 503 Service Unavailable (was impliziert, dass der Upstream derzeit überlastet oder nicht verfügbar ist).

Wichtige Direktiven zur Steuerung von Upstream-Timeouts

Beim Weiterleiten von Anfragen verwendet Nginx mehrere kritische Direktiven, die sich hauptsächlich innerhalb der http, server oder location Blöcke oder speziell innerhalb eines upstream Blocks befinden. Die Anpassung dieser Werte ist die primäre Methode zur Lösung von 504-Fehlern.

1. proxy_connect_timeout

Dies legt das Timeout für den Aufbau einer Verbindung mit dem Upstream-Server fest. Wenn Nginx innerhalb dieses Zeitraums keine Verbindung herstellen kann, gibt es einen Timeout-Fehler zurück.

Standard: 60 Sekunden

proxy_connect_timeout 60s;

2. proxy_send_timeout

Dies legt das Timeout für die Zeit zwischen zwei aufeinanderfolgenden Schreibvorgängen an den Upstream-Server fest. Dies ist relevant beim Senden eines großen Anfragekörpers.

Standard: 60 Sekunden

proxy_send_timeout 60s;

3. proxy_read_timeout (Die häufigste Lösung für 504s)

Dies legt das Timeout für das Warten auf eine Antwort vom Upstream-Server fest, nachdem die Anfrage-Header gesendet wurden. Wenn die Backend-Anwendung zu lange zur Verarbeitung der Anfrage und zur Generierung eines Antwortkörpers benötigt, ist dies die Direktive, die erhöht werden muss.

Standard: 60 Sekunden

# Beispiel: Erhöhung des Lese-Timeouts auf 120 Sekunden für eine langsame API
proxy_read_timeout 120s;

Best Practice: Wenn Ihre Anwendung die Standard-60-Sekunden häufig überschreitet, erhöhen Sie diesen Wert vorsichtig. Ein sehr hoher Wert kann grundlegende Leistungsprobleme des Backends maskieren.

Behandlung von clientseitigen Timeouts

Während sich der 504 auf die Nginx-zu-Backend-Kommunikation bezieht, treten clientseitige Timeouts auf, wenn der Client (z. B. ein Browser, eine mobile App oder ein anderer Dienst, der eine Anfrage an Nginx stellt) aufgibt zu warten, bevor Nginx überhaupt die Kommunikation mit dem Backend abgeschlossen hat.

Wenn Sie clientseitige Timeouts bevor Nginx einen 504 protokolliert erleben, müssen Sie die Verbindung zwischen dem Client und Nginx untersuchen.

1. Clientseitiges Keepalive

Wenn der Client die Verbindung vorzeitig schließt, kann Nginx einen Fehler erhalten oder der Client wartet einfach auf Daten und erreicht ein Timeout.

Stellen Sie sicher, dass Ihre clientseitigen Verbindungseinstellungen (falls konfigurierbar) nicht zu aggressiv sind. Wenn der Client ein anderer Proxy oder Load Balancer ist, überprüfen Sie dessen Timeout-Einstellungen im Vergleich zu Nginx' send_timeout.

2. Nginx send_timeout

Diese Direktive steuert, wie lange Nginx auf die Bestätigung oder den Empfang von Daten durch den Client wartet (die Zeit zwischen zwei aufeinanderfolgenden Schreibvorgängen an den Client).

Standard: 60 Sekunden

# Setzen Sie dies, wenn Clients auslaufen, während Nginx die Antwort sendet
send_timeout 120s;

Optimierung der Pufferung für große Antworten

Manchmal treten Timeouts nicht auf, weil die Verarbeitung zu lange gedauert hat, sondern weil Nginx begonnen hat, die Upstream-Antwort zu puffern, und dann den Puffer-Schreibvorgang nicht abschließen konnte, bevor die Verbindung abgelaufen war. Dies ist besonders relevant, wenn sehr große Antworten verarbeitet werden.

Nginx verwendet Puffer, um Daten, die vom Upstream empfangen wurden, temporär zu speichern, bevor sie an den Client gesendet werden. Wenn die Antwort sehr groß ist, können diese Puffer überschritten werden, was zu komplexer Handhabung oder wahrgenommener Latenz führt.

Wichtige Pufferungsdirektiven

Diese werden normalerweise im location Block oder server Block gesetzt:

Direktive Zweck
proxy_buffers Legt die Anzahl und Größe der Puffer fest, die zum Lesen des Antwort-Headers vom Upstream verwendet werden. Format: number size;
proxy_buffer_size Legt die Größe des ersten Puffers fest, der zum Lesen des Antwort-Headers verwendet wird.
proxy_max_temp_file_size Wenn die Antwort die verfügbaren Puffer überschreitet, schreibt Nginx in temporäre Dateien. Dies legt die maximale Größe für diese temporären Dateien fest.

Beispielkonfiguration für hohe Volumina/große Antworten:

location /api/heavy_report {
    proxy_pass http://backend_app;

    # Lese-Timeout erhöhen
    proxy_read_timeout 180s;

    # Pufferung für potenziell große Antwortkörper abstimmen
    # 8 Puffer verwenden, jeweils bis zu 1 MB (1024k)
    proxy_buffers 8 1024k;
    proxy_buffer_size 256k;

    # Temporäre Dateien bis zu 500 MB zulassen, wenn Puffer überlaufen
    proxy_max_temp_file_size 500m;
}

Tipp zur Pufferung: Wenn Ihre Backend-Antwort wirklich riesig ist (z. B. mehrere GB), sollten Sie erwägen, statische Inhalte bereitzustellen oder Streaming direkt zu implementieren, da das Puffern extrem großer Antworten erhebliche Mengen an Arbeitsspeicher auf dem Nginx-Server beanspruchen kann.

Fehlerbehebungsschritte und Protokollanalyse

Die Behebung von Timeouts erfordert die genaue Bestimmung, wo die Verzögerung aufgetreten ist: Client -> Nginx oder Nginx -> Backend.

Schritt 1: Nginx-Fehlerprotokolle prüfen

Das Nginx-Fehlerprotokoll ist Ihre definitive Quelle, um festzustellen, ob Nginx beim Warten auf das Backend abgelaufen ist.

Suchen Sie nach Einträgen, die Phrasen enthalten wie:

  • upstream timed out (110: Connection timed out)
  • upstream prematurely closed connection while reading response header from upstream

Wenn Sie diese sehen, liegt das Problem bei proxy_read_timeout oder der Verarbeitungszeit des Backends.

Schritt 2: Protokolle der Backend-Anwendung prüfen

Wenn Nginx einen Timeout meldet (Protokolle zeigen 504 an), überprüfen Sie sofort die Protokolle des Upstream-Dienstes (z. B. PHP-FPM-Protokolle, Gunicorn-Protokolle, Java-Anwendungsserver-Protokolle). Sie müssen bestätigen, ob die Anfrage überhaupt das Backend erreicht hat und wie lange die Verarbeitung gedauert hat.

  • Wenn die Backend-Protokolle zeigen, dass die Anfrage länger als Ihr konfigurierter proxy_read_timeout gedauert hat, erhöhen Sie das Nginx-Timeout.
  • Wenn die Backend-Protokolle zeigen, dass die Anfrage schnell abgeschlossen wurde, liegt das Problem möglicherweise an der Netzwerklatenz zwischen Nginx und dem Backend oder an einem falsch konfigurierten Client-Timeout, das Nginx gegenübersteht.

Schritt 3: Verwenden Sie den X-Upstream-Response-Time Header (Optional)

Für detaillierte Diagnosen können Sie die genaue Zeit protokollieren, die das Upstream für die Antwort benötigt hat, indem Sie die Variable $upstream_response_time in Ihrem Zugriffsprotokollformat verwenden. Dies hilft, die tatsächliche Leistung des Backends zu bestätigen.

In Ihrer nginx.conf:

log_format proxy_detailed '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" $request_time $upstream_response_time';

access_log /var/log/nginx/access.log proxy_detailed;

Durch die Analyse von $upstream_response_time können Sie die genaue Dauer sehen, die Nginx gewartet hat, unabhängig von den eigenen Timeout-Einstellungen von Nginx.

Zusammenfassung und Anwenden von Änderungen

Die Behebung von Nginx-Timeout-Problemen beinhaltet im Allgemeinen ein Gleichgewicht zwischen den Erwartungen des Clients und den Verarbeitungsfähigkeiten des Backends. Denken Sie an die Beziehung:

  • 504 Timeout: Backend ist zu langsam oder die Netzwerkverbindung ist fehlgeschlagen, während Nginx gewartet hat (proxy_read_timeout).
  • Client Timeout: Client hat aufgegeben zu warten, bis Nginx antwortet (send_timeout oder Clienteinstellung).

Testen Sie nach jeder Konfigurationsänderung (z. B. Erhöhung von Timeouts oder Anpassung von Puffergrößen) immer die Konfigurationssyntax und laden Sie Nginx neu:

sudo nginx -t
sudo systemctl reload nginx

Überwachen Sie Ihre Protokolle nach der Anwendung von Korrekturen sorgfältig, da das blinde Erhöhen von Timeouts zugrunde liegende Engpässe in der Systemleistung maskieren kann, die optimiert und nicht durch Workarounds in der Konfiguration behoben werden müssen.