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:
- proxy_read_timeout behandelt Upstream-Verzögerungen und ist die Hauptursache für 504-Fehler
- client_body_timeout verwaltet Upload-Timeouts von langsamen Clients
- keepalive_timeout gleicht Verbindungswiederverwendung gegen Ressourcenverbrauch ab
- 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).