504 Gateway Timeout NGINX: So beheben Sie es
Dieser Artikel ist eine Übersetzung des englischen Originals.
Jeder Blog scheint dieselbe „Lösung“ für 504 Gateway Timeout NGINX-Fehler zu kopieren und einzufügen: einfach alle Timeouts erhöhen. Schlechter Rat. Die meisten dieser Direktiven müssen überhaupt nicht angepasst werden – die eigentliche Lösung für 504 Gateway Timeout NGINX-Probleme besteht darin, zu verstehen, welche Ebene in einen Timeout läuft, und die EINE Direktive anzupassen, auf die es ankommt.
Das 504-Timeout-Problem verstehen
Ein 504 Gateway Timeout tritt auf, wenn NGINX als Proxy innerhalb des konfigurierten Timeout-Zeitraums keine Antwort vom Upstream-Server erhält. Der Standard-Timeout beträgt 60 Sekunden (intern 60000 ms).
Der Upstream, der den Timeout verursacht, könnte sein:
- Ein anderer HTTP-Server (Node.js, Python, Ruby, Go)
- Ein Caching-Proxy wie Varnish
- PHP-FPM oder ein beliebiger FastCGI-Prozess
- Ein beliebiges Backend, das HTTP spricht
Die entscheidende Erkenntnis: Sie müssen nur den Timeout erhöhen, der tatsächlich ausgelöst wird.
? Welche Direktive ist tatsächlich entscheidend?
Für das ngx_http_proxy_module (Proxying an HTTP-Backends) gibt es drei Timeout-Direktiven:
| Direktive | Standard | Was sie steuert |
|---|---|---|
proxy_connect_timeout |
60s | Zeit zum Aufbau der TCP-Verbindung |
proxy_send_timeout |
60s | Zeit zwischen aufeinanderfolgenden Schreibvorgängen an den Upstream |
proxy_read_timeout |
60s | Zeit zwischen aufeinanderfolgenden Lesevorgängen vom Upstream |
In 99 % der Fälle von 504 Gateway Timeout NGINX ist proxy_read_timeout der Übeltäter. Ihr Backend ist langsam beim Antworten, nicht langsam beim Annehmen von Verbindungen.
Dieselbe Logik gilt für FastCGI:
| Direktive | Standard | Was sie steuert |
|---|---|---|
fastcgi_connect_timeout |
60s | Zeit zum Aufbau der FastCGI-Verbindung |
fastcgi_send_timeout |
60s | Zeit zwischen aufeinanderfolgenden Schreibvorgängen |
fastcgi_read_timeout |
60s | Zeit zwischen aufeinanderfolgenden Lesevorgängen |
Für PHP-Anwendungen ist fastcgi_read_timeout fast immer die Direktive, die erhöht werden muss.
?️ Der richtige Weg, 504 Gateway Timeout NGINX-Fehler zu beheben
Erhöhen Sie nicht blind alle Timeouts. Befolgen Sie diesen diagnostischen Ansatz:
SCHRITT 1: Identifizieren Sie die Ebene, die den Timeout verursacht
Prüfen Sie Ihr NGINX-Fehlerprotokoll:
tail -f /var/log/nginx/error.log | grep -i timeout
Sie sehen Meldungen wie:
upstream timed out (110: Connection timed out) while reading response header from upstream
Das zeigt Ihnen, dass es sich um ein Read-Timeout-Problem handelt.
SCHRITT 2: Prüfen Sie Ihre Architektur
Wenn NGINX an ein HTTP-Backend proxyt (Varnish, Node.js, ein weiteres NGINX usw.):
location / {
proxy_pass http://127.0.0.1:6081;
proxy_read_timeout 120s; # Only directive that usually needs changing
}
Wenn NGINX direkt mit PHP-FPM spricht:
location ~ .php$ {
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_read_timeout 120s; # The critical one for PHP
}
SCHRITT 3: Vergessen Sie das eigentliche Backend nicht
Wenn Sie PHP ausführen, müssen Sie außerdem sicherstellen, dass PHP selbst nicht vor NGINX in einen Timeout läuft:
; In php.ini or PHP-FPM pool config
max_execution_time = 120
Speziell für PHP-FPM:
; In /etc/php-fpm.d/www.conf
request_terminate_timeout = 120
? Mehrschichtige Architekturen (das „NGINX-Sandwich“)
Produktionsumgebungen sehen oft so aus:
Client → NGINX (TLS) → Varnish → NGINX (Backend) → PHP-FPM
Dabei geht es nicht nur um Varnish – Sie könnten an jede HTTP-Anwendung proxien: Node.js, Python (Gunicorn/uWSGI), Ruby (Puma), Go, Java oder sogar eine weitere NGINX-Instanz.
Jede Ebene hat ihren eigenen Timeout. Die Kette sieht so aus:
- Front-NGINX (
proxy_read_timeout) → Timeout beim Warten auf Varnish/Backend - Varnish (
.first_byte_timeout) → Timeout beim Warten auf Backend-NGINX - Backend-NGINX (
fastcgi_read_timeout) → Timeout beim Warten auf PHP - PHP-FPM (
request_terminate_timeout) → beendet das PHP-Skript
Die Regel: Jede äußere Ebene sollte einen Timeout ≥ der inneren Ebene haben.
Varnish-Backend-Timeouts
Wenn Sie Varnish verwenden, konfigurieren Sie das Backend in Ihrem VCL:
vcl 4.1;
backend default {
.host = "127.0.0.1";
.port = "8080";
.first_byte_timeout = 120s; # Time to first response byte
}
Der .first_byte_timeout ist der entscheidende – er bestimmt, wie lange Varnish auf den Beginn der Antwort des Backends wartet.
? Vollständige funktionierende Beispiele
NGINX proxyt an Node.js/Python/Go
upstream app_backend {
server 127.0.0.1:3000;
}
server {
listen 443 ssl http2;
server_name example.com;
location / {
proxy_pass http://app_backend;
proxy_http_version 1.1;
# Increase only if your app has slow endpoints
proxy_read_timeout 120s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
NGINX mit PHP-FPM (ohne Varnish)
location ~ .php$ {
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# For slow PHP operations
fastcgi_read_timeout 120s;
}
WordPress-Admin mit verlängerten Timeouts
WordPress-Admin-Vorgänge (Importe, Plugin-Updates) benötigen oft mehr Zeit:
location ~ ^/wp-admin/.*.php$ {
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# Higher timeout for admin operations
fastcgi_read_timeout 300s;
fastcgi_param PHP_ADMIN_VALUE "memory_limit=512M n max_execution_time=300";
}
? Diagnosebefehle
Timeout-Fehler in NGINX finden
grep -i "timed out" /var/log/nginx/error.log | tail -20
PHP-FPM-Slow-Log prüfen
Aktivieren Sie es in Ihrer Pool-Konfiguration:
slowlog = /var/log/php-fpm/slow.log
request_slowlog_timeout = 5s
Überwachen Sie dann:
tail -f /var/log/php-fpm/slow.log
Konfiguration vor dem Neuladen validieren
nginx -t && systemctl reload nginx
⚠️ Häufige Fehler
Fehler 1: proxy_connect_timeout bei langsamen Antworten erhöhen
Dies betrifft nur den Verbindungsaufbau. Wenn Ihr Backend langsam bei der Verarbeitung ist (nicht langsam beim Annehmen von Verbindungen), hilft das nicht.
Fehler 2: Timeouts höher setzen als PHPs max_execution_time
Wenn PHP das Skript nach 30 s beendet, NGINX aber 120 s wartet, erhalten Sie einen 502 (Bad Gateway) oder eine leere Antwort, keinen 504.
Fehler 3: Zwischenebenen vergessen
In einem mehrschichtigen Setup gilt: Wenn Varnish einen Timeout von 60 s hat, NGINX aber 120 s, läuft Varnish zuerst in den Timeout und NGINX gibt 503/504 zurück.
Fehler 4: Überall denselben hohen Timeout verwenden
Setzen Sie proxy_read_timeout 600s nicht global. Verwenden Sie spezifische location-Blöcke für langsame Endpunkte. Siehe unseren Leitfaden zur NGINX location-Direktive, um bestimmte URLs gezielt anzusprechen.
Fehlermeldungen verstehen
| Meldung | Ursache | Behebung |
|---|---|---|
upstream timed out (110: Connection timed out) while reading |
proxy_read_timeout oder fastcgi_read_timeout zu niedrig |
Read-Timeout erhöhen |
upstream timed out (110: Connection timed out) while connecting |
proxy_connect_timeout zu niedrig ODER Backend nicht erreichbar |
Backend prüfen, Connect-Timeout erhöhen |
upstream prematurely closed connection |
Backend abgestürzt oder PHP-FPM hat den Prozess beendet | request_terminate_timeout |
Verwandt: Buffer-Tuning
Wenn Sie statt 504 Fehler 502-Fehler sehen, könnte Ihr Problem die proxy-Puffergröße statt Timeouts sein. Große Antwort-Header können pufferbedingte Fehler auslösen, die ähnlich aussehen.
Zusammenfassung der Best Practices
- Zuerst diagnostizieren: Prüfen Sie die Protokolle, um festzustellen, welcher Timeout ausgelöst wird
- Nur das erhöhen, was nötig ist: In der Regel nur
*_read_timeout - Die Kette abstimmen: Äußere Ebenen ≥ innere Ebenen
- Probleme nicht kaschieren: Wenn etwas 5 Minuten dauert, beheben Sie den Code, statt nur die Timeouts zu erhöhen
- Standortspezifische Überschreibungen verwenden: Hohe Timeouts nicht global anwenden
Für die meisten Setups löst das Setzen von proxy_read_timeout oder fastcgi_read_timeout auf 120 s das Problem 504 Gateway Timeout NGINX. Wenn Sie mehr benötigen, fragen Sie sich, warum – die Antwort könnte eine Code-Optimierung statt einer Konfigurationsänderung sein.
Tuning heute behebt das heutige Problem. Die 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).