Nginx-Reverse-Proxy konfigurieren: Header, Timeouts, WebSocket

Falsche Client-IP, Weiterleitung auf HTTP, abbrechende WebSockets und 502/504 hinter einem Nginx-Reverse-Proxy: Header, Timeouts, Buffer, Keepalive und Diagnosereihenfolge.
Technische Zusammenfassung
Technologie
Nginx, ngx_http_proxy_module, ngx_http_realip_module, WebSocket, PHP-FPM, Docker
Thema
Anwendungen hinter Nginx korrekt veröffentlichen
Niveau
Mittel bis fortgeschritten
Voraussetzungen
  • Nginx auf einem Linux-Server installiert und Grundkenntnisse zum server-Block
  • Adresse und Port, auf denen die Backend-Anwendung lauscht
  • Berechtigung, die Konfiguration zu testen und neu zu laden
In diesem Beitrag8 Abschnitte

Sie haben die Anwendung hinter Nginx gestellt, die Website lädt. Einige Tage später kommen in den Logs alle Besucher von 127.0.0.1, die Rückleitung nach der Zahlung führt auf HTTP, die WebSocket-Verbindung bricht genau in der 60. Sekunde ab, und zu Spitzenzeiten kommt es zu 502-Fehlern. Fast alles davon ist die Folge eines Reverse Proxys, der mit Standardwerten belassen wurde. Nginx vor eine Anwendung in Node.js, Python, Java oder einem Container zu setzen, bündelt TLS-Terminierung, Komprimierung, statische Dateien und Zugriffskontrolle an einem Punkt; jede Direktive an diesem Punkt muss aber bewusst gesetzt werden. Im Folgenden erläutern wir ein in der Produktion genutztes Grundgerüst Direktive für Direktive und geben die Reihenfolge für die Diagnose von 502/504 an der Konsole vor.

Aufgaben eines Reverse Proxys

Der Client spricht nur mit dem Reverse Proxy; die dahinterliegenden Anwendungsserver sieht er nicht. In der Infrastruktur von Unternehmenswebsites übernimmt Nginx in dieser Rolle folgende Aufgaben:

  • TLS-Terminierung: Zertifikate und Protokolleinstellungen werden unabhängig von der Anwendung verwaltet.
  • Verbindungspufferung: Verhindert, dass langsame Clients die Worker der Anwendung blockieren; die Antwort wird schnell an Nginx übergeben, Nginx sendet sie an den Client.
  • Routing: Unter derselben Domain kann /api/ zu einem Dienst und / zu einem anderen führen.
  • Lastverteilung und Health: Verteilung auf mehrere Backends und vorübergehendes Herausnehmen fehlerhafter Server.
  • Policy-Punkt: Begrenzung der Anfragegröße, Rate Limit, IP-Beschränkung, Sicherheits-Header.

Jede dieser Aufgaben ist eine eigene Fehlerquelle. Die Wahl des Webservers ist eine separate Entscheidung; diese haben wir im Beitrag Nginx, Apache und IIS im Vergleich erörtert. Ab hier geht es um Nginx.

Grundlegende Proxy-Konfiguration

Das folgende Grundgerüst veröffentlicht eine Anwendung, die auf 127.0.0.1:3000 lauscht. Definieren Sie das Backend von Anfang an in einem upstream-Block; einen zweiten Server hinzuzufügen und Keepalive zu aktivieren, ist dann später eine Sache von einer Zeile.

upstream app_backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    listen 443 ssl;
    http2 on;
    server_name app.example.com;
    # Zeilen ssl_certificate und ssl_certificate_key hier

    client_max_body_size 20m;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        include /etc/nginx/snippets/proxy-headers.conf;
    }
}

Die Direktive http2 on; kam mit Nginx 1.25.1; in älteren Versionen wird die Syntax listen 443 ssl http2; verwendet. client_max_body_size beträgt standardmäßig 1 MB. Nachdem eine Anwendung mit Datei-Uploads hinter Nginx verlagert wurde, ist das meist die erste Beschwerde: 413 Request Entity Too Large. Gleichen Sie den Wert an das Upload-Limit der Anwendung an.

proxy_pass und die Schrägstrich-Regel

Hauptverdächtiger für unerklärliche 404-Fehler nach einer Migration ist der URI-Teil am Ende des proxy_pass-Werts:

Konfiguration Anfrage Pfad zum Backend
location /api/ { proxy_pass http://app; } /api/users /api/users
location /api/ { proxy_pass http://app/; } /api/users /users
location /api/ { proxy_pass http://app/v2/; } /api/users /v2/users

Die Regel lautet: Enthält proxy_pass einen URI (mindestens ein einzelnes /), wird das von location erfasste Präfix durch diesen URI ersetzt. In per Regex definierten locations kann proxy_pass mit URI nicht verwendet werden (nginx -t meldet einen Fehler); wird der URI mit rewrite … break geändert, wird der URI in proxy_pass ignoriert und der geänderte Pfad weitergegeben. In diesen Fällen ist es vorhersehbarer, proxy_pass ohne URI zu verwenden und den Pfad explizit umzuschreiben. Ein Zeichen, völlig anderes Verhalten.

Client-IP und Protokoll-Header

Die Anwendung erhält die TCP-Verbindung von Nginx. IP des Clients, verwendetes Protokoll und angefragte Domain erfährt sie nur aus Headern. Statt diese Header in jeden server-Block einzeln zu schreiben, bündeln Sie sie in einer einzigen Snippet-Datei:

# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host  $host;

Standardmäßig sendet Nginx dem Backend im Host-Header den Namen aus proxy_pass ($proxy_host); mandantenfähige Anwendungen und Frameworks, die absolute URLs erzeugen, leiten den Nutzer deshalb auf eine Adresse wie app_backend weiter. Fehlt X-Forwarded-Proto, hält die Anwendung die Anfrage für HTTP; sie markiert das Sitzungscookie nicht als Secure oder gerät in eine endlose HTTPS-Weiterleitungsschleife.

Die eigentliche Falle liegt in der Vererbungsregel: Definieren Sie in einer location auch nur ein einziges proxy_set_header, verlieren alle proxy_set_header-Definitionen des übergeordneten Blocks für diese location ihre Gültigkeit. nginx -t erkennt das nicht, denn die Konfiguration ist gültig. Das Snippet per include in jede location einzubinden, beseitigt die Falle. Legen Sie auch auf Anwendungsseite ausdrücklich fest, dass dem Proxy vertraut wird (in Express trust proxy, in Django SECURE_PROXY_SSL_HEADER, in Laravel die Middleware TrustProxies); andernfalls werden die Header ignoriert.

Echte IP hinter Cloudflare oder einem anderen Proxy

Steht vor Nginx Cloudflare, ein Load Balancer oder eine WAF, ist $remote_addr die Adresse dieses Geräts. Mit ngx_http_realip_module wird nur Headern aus vertrauenswürdigen Quellen geglaubt:

# im http-Block; alle Bereiche aus der Liste https://www.cloudflare.com/ips/ uebernehmen
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 2400:cb00::/32;
# ... weitere IPv4- und IPv6-Bereiche der Liste
real_ip_header CF-Connecting-IP;

Steht ein eigener Load Balancer davor, werden real_ip_header X-Forwarded-For; und real_ip_recursive on; verwendet; in diesem Fall müssen die Adressen aller vertrauenswürdigen Zwischen-Proxys mit set_real_ip_from definiert werden. set_real_ip_from 0.0.0.0/0 zu schreiben, erlaubt jedem IP-Spoofing per Header; diese Zeile, „damit es funktioniert“ geschrieben, begegnet uns in der Praxis häufig, und ab diesem Moment verlieren Rate Limit und IP-Beschränkung ihren Sinn. Die IP-Liste von Cloudflare kann sich ändern. Richten Sie eine Aufgabe ein, die diese Datei regelmäßig aktualisiert. Wie Cloudflare und die Cache-Schicht zusammenarbeiten, beschreibt der Leitfaden zu Cloudflare, WP Rocket und Redis.

Timeouts und Buffer-Einstellungen

Nginx hat drei Proxy-Timeouts, und keiner misst die gesamte Anfragedauer; jeder gilt für die Pause zwischen zwei Vorgängen:

Direktive Standard Was gemessen wird
proxy_connect_timeout 60s Dauer des TCP-Verbindungsaufbaus zum Backend (kann meist 75 Sekunden nicht überschreiten)
proxy_send_timeout 60s Zwischen zwei Schreibvorgängen zum Backend
proxy_read_timeout 60s Zwischen zwei Lesevorgängen vom Backend

Die Regel ist einfach: Halten Sie den Verbindungs-Timeout kurz (für einen Dienst auf demselben Server genügen einige Sekunden), und verlängern Sie den Lese-Timeout nur für lang laufende Endpunkte auf location-Ebene. Für einen Pfad /export/, der Berichte erzeugt, 300 Sekunden festzulegen, ist sicherer, als der gesamten Website 300 Sekunden zu geben; andernfalls halten hängende Anfragen Worker-Verbindungen lange fest. Die dauerhafte Lösung liegt in der Architektur: Stellen Sie lange Aufgaben in eine Warteschlange, und lassen Sie den Client den Status abfragen. Den Timeout zu vergrößern ist keine Therapie.

Bei den Buffern ist der Standard proxy_buffering on in den meisten Szenarien richtig. Drei Punkte müssen Sie manuell anpassen:

  • proxy_buffer_size: Wird für den Header-Teil der Antwort verwendet (standardmäßig eine Speicherseite, 4k oder 8k). Bei Anwendungen mit großen Cookies oder JWTs erscheint in den Logs upstream sent too big header, und der Client erhält 502; eine Erhöhung auf 16k–32k genügt meist.
  • proxy_buffers und proxy_busy_buffers_size: Body-Buffer. Reicht der Speicher nicht, wird die Antwort in eine temporäre Datei geschrieben; die Warnung an upstream response is buffered to a temporary file im Log zeigt das an.
  • Definieren Sie für Endpunkte mit Server-Sent Events oder Streaming in dieser location proxy_buffering off; oder sorgen Sie dafür, dass die Anwendung den Header X-Accel-Buffering: no sendet.

WebSocket und Upstream-Keepalive

WebSocket beginnt mit dem Upgrade-Mechanismus von HTTP/1.1. Upgrade und Connection sind Hop-by-Hop-Header; Nginx leitet sie nicht von selbst an das Backend weiter. Geben Sie sie nicht weiter, wird der Handshake nie abgeschlossen. Die im Dokument WebSocket proxying von nginx.org empfohlene Struktur:

# im http-Block
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# im server-Block
location /ws/ {
    proxy_pass http://app_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    include /etc/nginx/snippets/proxy-headers.conf;
    proxy_read_timeout 1h;
}

In dieser location steht $connection_upgrade statt Connection ""; wer beides verwechselt, beschädigt WebSocket stillschweigend. Für normale HTTP-Anfragen greift dagegen das Upstream-Keepalive: keepalive 32; ist die Obergrenze der Leerlaufverbindungen, die jeder Worker-Prozess zum Backend offen hält. Damit es funktioniert, sind proxy_http_version 1.1 und ein leerer Connection-Header nötig; standardmäßig spricht Nginx mit dem Backend HTTP/1.0 und öffnet bei jeder Anfrage eine neue Verbindung. Bei hohem Traffic sammeln sich ohne Keepalive viele TIME_WAIT-Sockets auf dem Server, und es kann zur Erschöpfung der ephemeren Ports kommen. Liegt die Zahl der timewait-Einträge in der Ausgabe von ss -s in den Tausenden, ist das der erste Ort zum Nachsehen.

Ist das Backend bei der containerbasierten Bereitstellung mit Docker über einen Dienstnamen definiert, löst Nginx diesen Namen nur beim Laden der Konfiguration auf; wird der Container neu erstellt und ändert sich seine IP, geht Nginx weiter an die alte Adresse. Das ist die klassische Ursache der Beschwerde „Container neu gestartet, Website liefert 502“. Laden Sie Nginx entweder neu, wenn sich das Backend ändert, oder nutzen Sie mit resolver 127.0.0.11 valid=10s; ein variablenbasiertes proxy_pass. Die Produktionseinstellungen des Container-Stacks beschreibt der Leitfaden zur Produktionsbereitstellung mit Docker Compose ausführlich.

Diagnose von 502- und 504-Fehlern

Die beiden Fehlercodes sagen Unterschiedliches: 502 Bad Gateway bedeutet, dass Nginx vom Backend keine gültige Antwort erhalten hat; 504 Gateway Timeout, dass die Antwort nicht innerhalb des Timeouts eintraf. Die Fehlerseite im Browser sagt Ihnen nichts. Die Diagnose beginnt mit error.log.

Meldung in error.log Code Mögliche Ursache und Prüfung
connect() failed (111: Connection refused) 502 Anwendung läuft nicht oder lauscht auf einem anderen Port bzw. einer anderen Adresse; mit ss -ltnp prüfen
connect() to unix:… failed (13: Permission denied) 502 Berechtigungen der Socket-Datei oder SELinux; im PHP-FPM-Pool listen.owner/listen.group
connect() failed (13: Permission denied), TCP 502 SELinux in der RHEL-Familie; setsebool -P httpd_can_network_connect 1
upstream prematurely closed connection 502 Anwendung ist mitten im Vorgang abgestürzt oder an das Speicherlimit gestoßen; Anwendungslogs
upstream sent too big header 502 proxy_buffer_size oder fastcgi_buffer_size zu klein
no live upstreams 502 Alle Server wegen max_fails vorübergehend deaktiviert
upstream timed out (110: Connection timed out) while reading response header 504 Langsame Abfrage oder Sperre; proxy_read_timeout zu erhöhen verbirgt nur das Symptom

Reihenfolge an der Konsole:

  1. Prüfen Sie mit nginx -t, ob die Konfiguration gültig ist; nginx -T gibt die zusammengeführte Konfiguration aus und zeigt, ob die erwartete Datei tatsächlich geladen wurde.
  2. Testen Sie das Backend unter Umgehung von Nginx direkt vom Server aus: curl -sv -H "Host: app.example.com" http://127.0.0.1:3000/. Tritt der Fehler auch hier auf, liegt das Problem nicht im Proxy.
  3. Ergänzen Sie das Zugriffslog um $upstream_addr, $upstream_status, $upstream_response_time und $request_time. Die Differenz der beiden Zeiten zeigt, ob die Zeit zwischen Nginx und Client oder in der Anwendung verbraucht wurde.
  4. Achten Sie auf 499-Codes: Der Client hat die Verbindung geschlossen, ohne auf die Antwort zu warten; meist ist der Timeout des vorgeschalteten CDN oder Load Balancers kürzer als der von Nginx.
  5. Richten Sie die Timeout-Kette aus: Von außen nach innen abnehmende Werte nach dem Muster CDN > Nginx > Anwendungsserver > Limit für Datenbankabfragen sorgen dafür, dass der Fehler in der Schicht nahe der Ursache und mit einer aussagekräftigen Meldung entsteht.

proxy_next_upstream versucht die Anfrage standardmäßig bei error timeout beim nächsten Server; seit Nginx 1.9.13 werden nicht idempotente Anfragen wie POST nach dem Senden an das Backend nicht erneut versucht. Dieses Verhalten mit non_idempotent zu erweitern, bringt bei Endpunkten, die Zahlungen oder Bestellungen anlegen, das Risiko doppelter Datensätze. Belassen Sie den Standard.

Auf Websites mit PHP-FPM läuft dieselbe Diagnoselogik über Entsprechungen wie fastcgi_pass und fastcgi_read_timeout; für 502/504 durch einen erschöpften Pool ist der Performance-Leitfaden zu PHP-FPM und MariaDB direkt anwendbar. Die offiziellen Definitionen aller Direktiven finden Sie in der Dokumentation zu ngx_http_proxy_module.

Checkliste vor dem Livegang

  • Host, X-Forwarded-For und X-Forwarded-Proto werden in jeder location weitergegeben; die Anwendung ist so eingestellt, dass sie dem Proxy vertraut.
  • Steht ein CDN oder Load Balancer davor, vertraut realip nur deren Bereichen.
  • client_max_body_size passt zum Upload-Limit der Anwendung.
  • Timeouts sind auf location-Ebene gesetzt und nehmen von der äußeren Schicht nach innen ab.
  • WebSocket-Pfade geben die Header Upgrade/Connection weiter, und der Lese-Timeout ist länger als das Ping-Intervall der Anwendung.
  • Upstream-Keepalive ist zusammen mit proxy_http_version 1.1 definiert.
  • Upstream-Zeiten und Statuscodes werden im Zugriffslog erfasst.

TLS-Protokoll- und Cipher-Einstellungen sind ein eigenes Thema; dazu wechseln Sie zum Leitfaden TLS-Konfiguration auf dem Webserver. In Strukturen, die viele Anwendungen hinter demselben Nginx bündeln, sind Konfigurationsstandard und Monitoring die eigentliche Arbeit; diesen Aufbau realisieren wir im Rahmen unserer Leistung Nginx-Webserver und Reverse Proxy.

Häufig gestellte Fragen

Was ändert der Schrägstrich am Ende der proxy_pass-Adresse?

Enthält proxy_pass einen URI-Teil (etwa eine Adresse, die auf http://app/ endet), wird das von location erfasste Präfix durch diesen URI ersetzt; die Anfrage /api/users geht als /users an das Backend. Ohne URI (http://app) wird der Pfad unverändert weitergegeben. Dieser Unterschied ist eine häufige Ursache unerwarteter 404-Fehler nach einer Migration.

Meine WebSocket-Verbindungen brechen nach genau 60 Sekunden ab – warum?

proxy_read_timeout beträgt standardmäßig 60 Sekunden und gilt für die Pause zwischen zwei Lesevorgängen. Sendet die Anwendung in dieser Zeit keine Daten, schließt Nginx die Verbindung. Verlängern Sie den Timeout für die betreffende location oder nutzen Sie in der Anwendung periodisches Ping/Pong; Letzteres hilft auch bei weiteren Proxys und Load Balancern dazwischen.

Warum erscheinen hinter Cloudflare in den Logs nur Cloudflare-IPs?

Da Nginx die Verbindung vom Edge-Server von Cloudflare erhält, zeigt $remote_addr dessen Adresse. Tragen Sie mit dem realip-Modul die von Cloudflare veröffentlichten IP-Bereiche in set_real_ip_from-Zeilen ein und definieren Sie real_ip_header CF-Connecting-IP; dann arbeiten Logs, Rate Limits und Zugriffsregeln mit der echten Client-IP.

Sollte man auch für PHP-FPM proxy_pass verwenden?

Nein. PHP-FPM spricht FastCGI; in Nginx wird mit fastcgi_pass verbunden, und für Einstellungen wie Timeouts und Buffer werden die Entsprechungen mit dem Präfix fastcgi_ verwendet. Die oben beschriebene Logik zu Timeouts, Buffern und Diagnose gilt unverändert; Client-Informationen werden jedoch statt mit proxy_set_header mit fastcgi_param übergeben.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge