Skip to main content

NGINX Timeout-Direktiven: Vollständiger Konfigurationsleitfaden

Dieser Artikel ist eine Übersetzung des englischen Originals.


Das Verständnis der NGINX timeout-Konfiguration ist entscheidend für den stabilen Betrieb von Produktionsservern. Falsch konfigurierte Timeouts führen entweder zu vorzeitigen Verbindungsabbrüchen (was zu 504-Fehlern führt) oder zu Ressourcenerschöpfung durch zu lange offen gehaltene Verbindungen. Dieser Leitfaden behandelt jede NGINX timeout-Direktive, erklärt, wann Sie welche einsetzen, und bietet produktionsreife Konfigurationen.

Die vier wesentlichen NGINX Timeout-Direktiven

NGINX verfügt über Dutzende timeoutbezogener Direktiven, aber vier Kern-Direktiven decken die meisten Anwendungsfälle ab:

Direktive Standard Zweck
proxy_read_timeout 60s Zeit, die auf eine Upstream-Antwort gewartet wird
client_body_timeout 60s Zeit zwischen dem Senden von Request-Body-Chunks durch den Client
keepalive_timeout 75s Wie lange Leerlaufverbindungen offen bleiben
send_timeout 60s Zeit zwischen dem Senden von Response-Chunks an den Client

Jede NGINX timeout-Direktive wirkt an einem anderen Punkt im Request-Lebenszyklus. Zu verstehen, wann welche gilt, verhindert sowohl vorzeitige Verbindungsabbrüche als auch Ressourcenverschwendung.

proxy_read_timeout: Der Verursacher von 504-Fehlern

Wenn NGINX als Reverse Proxy fungiert, ist proxy_read_timeout die kritischste NGINX timeout-Einstellung. Sie legt fest, wie lange NGINX auf das Senden von Antwortdaten durch den Upstream-Server wartet. Die offizielle NGINX proxy_read_timeout-Dokumentation finden Sie als maßgebliche Referenz.

Standardverhalten

Der Standardwert für proxy_read_timeout beträgt 60 Sekunden. Wenn Ihr Backend länger für die Verarbeitung einer Anfrage benötigt, sehen Sie dies in Ihrem Fehlerprotokoll:

upstream timed out (110: Connection timed out) while reading response header from upstream

Und Clients erhalten eine 504 Gateway Timeout-Antwort.

Wann proxy_read_timeout erhöht werden sollte

Erhöhen Sie diesen NGINX timeout-Wert, wenn:

  • Sie lang laufende API-Operationen ausführen
  • Sie große Datei-Uploads oder -Exporte verarbeiten
  • Sie langsame Datenbankabfragen ausführen
  • Sie die Berichterstellung oder PDF-Erstellung handhaben

Konfiguration

location / {
    proxy_pass http://backend;

    # Increase for slow operations
    proxy_read_timeout 120s;
}

Für standortspezifische Anpassung (empfohlen gegenüber globalen Änderungen):

# Normal endpoints keep the 60s default
location / {
    proxy_pass http://backend;
}

# Langsame Admin-Operationen erhalten mehr Zeit
location /admin/reports {
    proxy_pass http://backend;
    proxy_read_timeout 300s;
}

Verwandte Upstream-Timeouts

Zwei begleitende Direktiven vervollständigen das NGINX-TimeoutTrio für Upstreams:

proxy_connect_timeout 60s;  # Time to establish TCP connection
proxy_send_timeout 60s;     # Time between writes to upstream
proxy_read_timeout 60s;     # Time between reads from upstream

In der Praxis muss nur proxy_read_timeout angepasst werden. Der Verbindungsaufbau (proxy_connect_timeout) dauert selten mehr als ein paar Sekunden, und Request-Bodies werden üblicherweise schnell gesendet (proxy_send_timeout).

Eine umfassende Fehlerbehebung bei Upstream-Timeout-Problemen finden Sie in unserem speziellen Leitfaden zu 504 Gateway Timeout NGINX errors.

client_body_timeout: Timeouts bei Datei-Uploads

Die Direktive client_body_timeout steuert, wie lange NGINX zwischen dem Empfang von Teilen des Request-Bodys vom Client wartet. Dieser NGINX-Timeout ist entscheidend für Datei-Uploads.

So funktioniert client_body_timeout

Dieser NGINX-Timeout misst nicht die gesamte Upload-Dauer. Stattdessen misst er die Lücke zwischen aufeinanderfolgenden Datenpaketen. Ein langsamer Client, der eine große Datei über eine schlechte Verbindung hochlädt, kann diesen Timeout auslösen, obwohl noch Daten eintreffen.

Laut dem NGINX-Quellcode gilt der Timeout für jeden Lesevorgang auf der Client-Verbindung:

ngx_add_timer(c->read, clcf->client_body_timeout);

Standardwert

Der Standardwert für client_body_timeout beträgt 60 Sekunden. Für die meisten Webanwendungen ist dies ausreichend.

Wann client_body_timeout erhöht werden sollte

Erhöhen Sie diesen NGINX-Timeout für:

  • Große Datei-Uploads (Video, Backups, Bilder)
  • Mobile Nutzer mit schlechten Verbindungen
  • API-Endpunkte, die große Payloads akzeptieren

Konfiguration

# For a file upload location
location /upload {
    client_max_body_size 100M;
    client_body_timeout 300s;

    proxy_pass http://upload_backend;
    proxy_read_timeout 300s;
}

Hinweis: Bei der Verarbeitung von Uploads müssen Sie in der Regel sowohl client_body_timeout (NGINX empfängt vom Client) als auch proxy_read_timeout (NGINX wartet auf die Verarbeitung des Uploads durch das Backend) erhöhen.

Zusammenhang mit client_max_body_size

Der client_body_timeout wirkt zusammen mit client_max_body_size, um das Upload-Verhalten zu steuern. Ein Request, der client_max_body_size überschreitet, wird sofort mit einem 413-Fehler abgelehnt, bevor client_body_timeout greifen kann.

keepalive_timeout: Verbindungspersistenz

Die Direktive keepalive_timeout bestimmt, wie lange NGINX inaktive Client-Verbindungen offen hält. Dieser NGINX-Timeout gleicht die Effizienz der Verbindungswiederverwendung gegen den Ressourcenverbrauch ab.

HTTP Keep-Alive erklärt

HTTP/1.1 führte persistente Verbindungen (Keep-Alive) ein, um den Overhead des Aufbaus neuer TCP-Verbindungen für jede Anfrage zu vermeiden. Ein Browser, der eine Seite mit 50 Ressourcen lädt, kann eine Verbindung wiederverwenden, anstatt 50 zu öffnen.

Standardwert

NGINX verwendet standardmäßig 75 Sekunden für keepalive_timeout. Die Standard-Distributionskonfiguration setzt ihn oft auf 65 Sekunden:

keepalive_timeout 65;

Syntaxoptionen

Die Direktive akzeptiert einen oder zwei Parameter:

# Single value: server-side timeout only
keepalive_timeout 65s;

# Zwei Werte: Server-Timeout und Keep-Alive-Header-Wert
keepalive_timeout 65s 60s;

Der zweite Parameter legt den Antwortheader Keep-Alive: timeout=60 fest. Damit teilen Sie dem Browser mit, wie lange die Verbindung offen gehalten werden soll. Wenn Sie ihn etwas niedriger als den Serverwert setzen, vermeiden Sie Race Conditions, bei denen der Client die Verbindung für aktiv hält, während der Server sie bereits geschlossen hat.

Produktionskonfiguration

Für Produktionsserver:

http {
    # Keep connections open for 65 seconds
    keepalive_timeout 65s 60s;

    # Enable keepalive to upstream servers too
    upstream backend {
        server 127.0.0.1:8000;
        keepalive 32;  # Connection pool size
    }

    server {
        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
        }
    }
}

Details zum Upstream-Verbindungspooling finden Sie in unserem Leitfaden zu NGINX upstream keepalive.

Wann Sie keepalive_timeout anpassen sollten

Erhöhen Sie diesen NGINX timeout, wenn:

  • Sie Anwendungen bereitstellen, bei denen Nutzer häufig Anfragen stellen (SPAs, Echtzeit-Dashboards)
  • Sie hinter einem CDN betrieben werden (CDN-Verbindungen sind wertvoll, wenn sie offen bleiben)

Verringern Sie ihn, wenn:

  • Sie einen Server mit hohem Traffic und Verbindungslimits betreiben
  • DER Arbeitsspeicher knapp ist (jede Verbindung belegt Kernel-Speicher)

Überlegungen zu HTTP/2 und HTTP/3

Bei HTTP/2 und HTTP/3 ändert sich die Bedeutung von keepalive_timeout. Diese Protokolle multiplexen mehrere Anfragen über eine einzige Verbindung. Dadurch wird die Wiederverwendung von Verbindungen noch wertvoller. Erwägen Sie längere Timeouts für HTTP/2+-Traffic:

http2_idle_timeout 180s;  # HTTP/2 specific

send_timeout: Schutz vor langsamen Clients

Die Direktive send_timeout steuert, wie lange NGINX beim Senden der Antwort an den Client zwischen Schreibvorgängen wartet.

So funktioniert send_timeout

Wie bei client_body_timeout misst dieser NGINX timeout die Abstände zwischen Vorgängen, nicht die gesamte Übertragungszeit. Wenn ein Client aufhört, Antwortdaten zu lesen, schließt NGINX die Verbindung nach send_timeout Sekunden ohne Aktivität.

Standardwert

Der Standardwert ist 60 Sekunden, was für die meisten Szenarien passt.

Wann Sie send_timeout anpassen sollten

Erhöhen Sie ihn für:

  • SEHR große Dateidownloads
  • Streaming-Antworten
  • Clients mit extrem langsamen Verbindungen

Verringern Sie ihn für:

  • API-Server, bei denen langsame Clients Ressourcen verschwenden
  • Seiten mit hohem Traffic, die eine schnelle Verbindungsfreigabe benötigen

Konfigurationsbeispiel

# For large file downloads
location /downloads {
    send_timeout 300s;

    # Also increase proxy timeout if proxying
    proxy_read_timeout 300s;
}

FastCGI-, uWSGI- und gRPC-Timeouts

Wenn NGINX mit FastCGI- (PHP-FPM), uWSGI- oder gRPC-Backends kommuniziert, gibt es entsprechende Timeout-Direktiven.

FastCGI-Timeouts (PHP-FPM)

location ~ .php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;

    fastcgi_connect_timeout 60s;
    fastcgi_send_timeout 60s;
    fastcgi_read_timeout 60s;  # Usually the one to increase

    include fastcgi_params;
}

Bei PHP-Anwendungen ist fastcgi_read_timeout fast immer der NGINX timeout, der angepasst werden muss.

Informationen zu persistenten FastCGI-Verbindungen finden Sie in unserem Leitfaden zu NGINX FastCGI keepalive.

uWSGI-Timeouts (Python)

location / {
    uwsgi_pass unix:/tmp/uwsgi.sock;

    uwsgi_connect_timeout 60s;
    uwsgi_send_timeout 60s;
    uwsgi_read_timeout 60s;

    include uwsgi_params;
}

gRPC-Timeouts

location /grpc.ServiceName {
    grpc_pass grpc://backend;

    grpc_connect_timeout 60s;
    grpc_send_timeout 60s;
    grpc_read_timeout 60s;
}

Diagnose von NGINX-Timeout-Problemen

Wenn Nutzer Timeout-Fehler melden, verwenden Sie diese Diagnoseansätze.

NGINX-Fehlerprotokoll prüfen

Das Fehlerprotokoll zeigt, welcher Timeout ausgelöst wurde:

grep -i "timed out" /var/log/nginx/error.log | tail -20

Häufige Meldungen:

Meldung Ursache
upstream timed out ... while reading response header proxy_read_timeout zu niedrig
upstream timed out ... while connecting proxy_connect_timeout zu niedrig oder Backend nicht erreichbar
client timed out client_body_timeout oder send_timeout

Aktive Timeout-Konfiguration anzeigen

Geben Sie die effektive Konfiguration aus, um alle NGINX timeout-Werte zu sehen:

nginx -T 2>/dev/null | grep -E 'timeout|keepalive'

Antwortzeit des Backends testen

Wenn Upstream-Timeouts auftreten, messen Sie die tatsächliche Antwortzeit des Backends:

curl -w "Time: %{time_total}sn" -o /dev/null -s http://127.0.0.1:8000/slow-endpoint

Wenn das Backend 90 Sekunden benötigt, proxy_read_timeout aber 60 Sekunden beträgt, erhalten Sie 504-Fehler.

Auf Timeout-Muster achten

Beobachten Sie Timeout-Fehler in Echtzeit:

tail -f /var/log/nginx/error.log | grep -i timeout

Empfehlungen für die Produktionskonfiguration

Allgemeine Webanwendung

http {
    # Client timeouts
    client_body_timeout 60s;
    client_header_timeout 60s;
    send_timeout 60s;

    # Keep-alive
    keepalive_timeout 65s 60s;
    keepalive_requests 100;

    upstream app {
        server 127.0.0.1:8000;
        keepalive 32;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_pass http://app;
            proxy_http_version 1.1;
            proxy_set_header Connection "";

            # Upstream timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }

        # Longer timeout for admin operations
        location /admin {
            proxy_pass http://app;
            proxy_read_timeout 180s;
        }
    }
}

API-Server mit hohem Traffic

Für API-Server, die viele Anfragen verarbeiten:

http {
    # Aggressive client timeouts
    client_body_timeout 30s;
    send_timeout 30s;

    # Shorter keepalive
    keepalive_timeout 30s;
    keepalive_requests 1000;

    upstream api {
        server 127.0.0.1:8000;
        keepalive 64;
    }

    server {
        location /api {
            proxy_pass http://api;
            proxy_read_timeout 30s;
        }
    }
}

Datei-Upload-Server

Für Server, die große Uploads verarbeiten:

server {
    client_max_body_size 500M;

    location /upload {
        # Extended timeouts for uploads
        client_body_timeout 600s;
        proxy_read_timeout 600s;

        proxy_pass http://upload_backend;
        proxy_request_buffering off;  # Stream directly to backend
    }
}

Häufige Timeout-Fehler

Fehler 1: Alle Timeouts blind erhöhen

Setzen Sie nicht jeden NGINX timeout „nur für den Fall“ auf 300 Sekunden. Das verschwendet Ressourcen und verdeckt zugrunde liegende Performance-Probleme.

Fehler 2: Die Backend-Timeout-Kette vergessen

Wenn NGINX proxy_read_timeout 120s hat, PHP-FPM aber request_terminate_timeout = 30, stirbt PHP zuerst. Stellen Sie sicher, dass die Kette konsistent ist:

NGINX proxy_read_timeout >= Backend process timeout

Für PHP:

; In php.ini
max_execution_time = 120

; In php-fpm pool config
request_terminate_timeout = 120

Fehler 3: Globale Timeouts für bestimmte Endpunkte verwenden

Statt:

# Bad: global long timeout
proxy_read_timeout 300s;

Verwenden Sie standortspezifische Überschreibungen:

# Good: targeted long timeout
location /reports/generate {
    proxy_read_timeout 300s;
}

Fehler 4: Zwischengeschaltete Proxies ignorieren

In mehrschichtigen Architekturen (NGINX zu Varnish zu Backend) hat jede Schicht Timeouts. Die äußere Schicht sollte gleiche oder längere Timeouts als die inneren Schichten haben.

Beispiele für mehrschichtige Architekturen finden Sie in unserem 504 Gateway Timeout-Leitfaden.

Schnellreferenztabelle für Timeouts

Direktive Standard Gilt für Erhöhen für
proxy_read_timeout 60s Upstream-Antwort Langsame Backends, lange Vorgänge
proxy_connect_timeout 60s Upstream-TCP-Verbindung Selten erforderlich
proxy_send_timeout 60s Senden an Upstream Große Anfrage-Bodys
client_body_timeout 60s Anfrage-Body des Clients Datei-Uploads
client_header_timeout 60s Anfrage-Header des Clients Langsame Clients
send_timeout 60s Senden an Client Große Downloads, langsame Clients
keepalive_timeout 75s Leerlaufende Verbindungen SPAs, CDN-Verbindungen
fastcgi_read_timeout 60s FastCGI-Antwort Langsame PHP-Skripte
uwsgi_read_timeout 60s uWSGI-Antwort Langsame Python-Anwendungen
grpc_read_timeout 60s gRPC-Antwort Langsame gRPC-Dienste

Zusammenfassung

Eine effektive NGINX timeout-Konfiguration erfordert das Verständnis dafür, was jede Direktive steuert:

  1. proxy_read_timeout behandelt Upstream-Verzögerungen und ist die Hauptursache für 504-Fehler
  2. client_body_timeout verwaltet Upload-Timeouts von langsamen Clients
  3. keepalive_timeout gleicht Verbindungswiederverwendung gegen Ressourcenverbrauch ab
  4. send_timeout schützt vor langsamen oder hängenden Clients

Beginnen Sie mit den Standardwerten, überwachen Sie Ihre Fehlerprotokolle und passen Sie bestimmte Timeouts basierend auf tatsächlichen Problemen an, statt präventiv alles hochzusetzen. Speziell zur Fehlerbehebung bei 504-Fehlern finden Sie in unserem Begleitleitfaden zu Behebung von NGINX 504 Gateway Timeout-Fehlern weitere Informationen.

Tuning heute behebt das heutige Problem. Eine Regression von morgen macht es stillschweigend zunichte. GetPageSpeed Amplify führt geplante gixy-Scans auf jedem Host aus und verknüpft die Ergebnisse mit Live-Laufzeitmetriken von NGINX. Drop-in-kompatibel mit dem veralteten nginx-amplify-agent (EOL Januar 2026).