Skip to main content

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:

  1. Front-NGINX (proxy_read_timeout) → Timeout beim Warten auf Varnish/Backend
  2. Varnish (.first_byte_timeout) → Timeout beim Warten auf Backend-NGINX
  3. Backend-NGINX (fastcgi_read_timeout) → Timeout beim Warten auf PHP
  4. 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

prüfen

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

  1. Zuerst diagnostizieren: Prüfen Sie die Protokolle, um festzustellen, welcher Timeout ausgelöst wird
  2. Nur das erhöhen, was nötig ist: In der Regel nur *_read_timeout
  3. Die Kette abstimmen: Äußere Ebenen ≥ innere Ebenen
  4. Probleme nicht kaschieren: Wenn etwas 5 Minuten dauert, beheben Sie den Code, statt nur die Timeouts zu erhöhen
  5. 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).