NGINX Reverse Proxy

6 Kernkonzepte

Die wichtigsten NGINX Reverse Proxy Konfigurationen: proxy_pass · proxy_set_header · proxy_cache · WebSocket · Timeouts & Buffering · Sicherheit NGINX als Reverse Proxy ist die Standardlösung für die Auslieferung von Webanwendungen. Diese Cheatsheet enthält alle wichtigen Direktiven für eine optimale Proxy-Konfiguration.

Grundlegende Proxy-Konfiguration – proxy_pass & Header

proxy_pass · proxy_set_header · proxy_http_version

location / { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

proxy_pass ist die zentrale Direktive für den Reverse Proxy. Sie leitet Anfragen an ein Backend weiter. Die proxy_set_header-Direktiven setzen wichtige Header für das Backend.

Wichtige proxy_set_header Variablen

Variable	Bedeutung
$host	Host-Header der Anfrage
$remote_addr	IP-Adresse des Clients
$proxy_add_x_forwarded_for	Client-IP + X-Forwarded-For-Kette
$scheme	Protokoll (http/https)
$http_upgrade	Upgrade-Header (für WebSocket)
$request_uri	Vollständige URI mit Query-String

Beispiele

# Standard Proxy für Node.js/Express

location /api/ {

proxy_pass http://localhost:3000/; # Trailing Slash wichtig!

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 mit Pfadweiterleitung (ohne Trailing Slash)

location /app {

proxy_pass http://localhost:8080; # Kein Slash → /app wird weitergeleitet

proxy_set_header Host $host;

}

Tipp: Der Trailing Slash bei proxy_pass entscheidet, ob der location-Pfad an den Backend-Pfad angehängt wird. Mit Slash wird er ersetzt, ohne Slash wird er angefügt.

Header & Variablen – X-Forwarded-*, Host, Connection

proxy_set_header · X-Forwarded-* · add_header

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;

Header und Variablen sind entscheidend, damit das Backend die richtige Client-IP, das Protokoll und den Hostnamen erkennt – besonders wichtig hinter einem Proxy.

Beispiele

# Vollständige Header-Konfiguration

location / {

proxy_pass http://backend;

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;

proxy_set_header X-Forwarded-Port $server_port;

}

# Response-Header hinzufügen (add_header)

location / {

proxy_pass http://backend;

add_header X-Frame-Options "SAMEORIGIN" always;

add_header X-Content-Type-Options "nosniff" always;

add_header Referrer-Policy "no-referrer" always;

}

Tipp: In vielen Backends (z.B. Django, Express) müssen Sie trust proxy aktivieren, damit die X-Forwarded-* Header akzeptiert werden. In Express: app.set('trust proxy', true).

Caching – proxy_cache für bessere Performance

proxy_cache · proxy_cache_key · proxy_cache_valid

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m; location / { proxy_cache my_cache; proxy_cache_valid 200 302 60m; proxy_cache_valid 404 1m; }

proxy_cache ermöglicht das Caching von Antworten des Backends. Das reduziert die Last auf dem Backend und verbessert die Antwortzeiten erheblich.

Cache-Konfigurationsparameter

Direktive	Beschreibung
proxy_cache_path	Cache-Verzeichnis, Größe, Zone
proxy_cache	Aktiviert den Cache für eine Zone
proxy_cache_key	Schlüssel für Cache-Eintrag (z.B. $scheme$host$request_uri)
proxy_cache_valid	Gültigkeitsdauer für HTTP-Statuscodes
proxy_cache_min_uses	Mindestanzahl Anfragen vor Caching
proxy_cache_bypass	Bedingungen für Cache-Bypass

Beispiele

# Cache für API-Antworten

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/ {

proxy_cache api_cache;

proxy_cache_key $scheme$host$request_uri;

proxy_cache_valid 200 202 10m;

proxy_cache_valid 404 1m;

proxy_cache_bypass $http_cache_control;

proxy_pass http://backend;

}

# Cache für statische Assets

location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {

proxy_cache static_cache;

proxy_cache_valid 200 30d;

proxy_pass http://backend;

}

Tipp: Die proxy_cache_path-Direktive muss im http-Block definiert werden. Die Cache-Größe (max_size) sollte an den verfügbaren Speicherplatz angepasst werden.

WebSocket Proxy – Upgrade-Header richtig setzen

Upgrade · Connection · proxy_http_version 1.1

location /ws/ { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; }

WebSocket-Proxy erfordert spezielle Header, damit die Verbindung von HTTP auf das WebSocket-Protokoll aktualisiert wird. proxy_http_version 1.1 ist zwingend erforderlich.

Beispiele

# WebSocket Proxy für Node.js (Socket.io)

location /socket.io/ {

proxy_pass http://backend:3000;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

}

# WebSocket mit Timeout (lange Verbindungen)

location /ws/ {

proxy_pass http://backend;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

proxy_read_timeout 3600s; # 1 Stunde Timeout

proxy_send_timeout 3600s;

}

Tipp: WebSocket-Verbindungen benötigen längere Timeouts. Erhöhen Sie proxy_read_timeout und proxy_send_timeout für stabile Verbindungen – besonders bei Chats oder Live-Anwendungen.

Performance & Timeouts – Buffering, Keepalive, Zeitlimits

proxy_buffering · proxy_read_timeout · keepalive

proxy_buffering on; proxy_buffer_size 16k; proxy_buffers 8 16k; proxy_read_timeout 60s;

Performance und Timeouts beeinflussen die Geschwindigkeit und Stabilität des Proxys. Buffering verbessert die Performance bei großen Antworten, während Timeouts hängende Verbindungen verhindern.

Beispiele

# Optimierte Performance-Konfiguration

location / {

proxy_pass http://backend;

proxy_buffering on; # Buffering aktivieren

proxy_buffer_size 16k;

proxy_buffers 8 16k;

proxy_busy_buffers_size 64k;

proxy_read_timeout 120s;

proxy_connect_timeout 10s;

proxy_send_timeout 60s;

}

# Keepalive-Verbindungen zum Backend

upstream backend {

server localhost:3000;

keepalive 32; # 32 Keepalive-Verbindungen

}

# Gzip für Proxy-Antworten

gzip on;

gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

gzip_min_length 1000;

Tipp: Bei großen Antworten (z.B. Datei-Downloads) kann proxy_buffering off die Performance verbessern, da der Proxy die Antwort sofort an den Client weiterleitet.

Sicherheit – Rate Limiting, IP-Blockierung, Header

limit_req · allow/deny · add_header

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s; location /api/ { limit_req zone=api_limit burst=20 nodelay; proxy_pass http://backend; }

Sicherheitskonfigurationen schützen den Proxy vor Missbrauch – durch Rate Limiting, IP-Blockierung, Header und SSL-Zwangsverschlüsselung.

Beispiele

# Rate Limiting (10 Anfragen pro Sekunde)

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

location /api/ {

limit_req zone=api_limit burst=20 nodelay;

proxy_pass http://backend;

}

# IP-Blockierung (allow / deny)

location /admin/ {

allow 192.168.1.0/24;

allow 10.0.0.0/8;

deny all;

proxy_pass http://backend;

}

# Sicherheits-Header für Proxy-Antworten

location / {

proxy_pass http://backend;

add_header X-Frame-Options "DENY" always;

add_header X-Content-Type-Options "nosniff" always;

add_header Referrer-Policy "strict-origin-when-cross-origin" always;

add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;

}

# SSL-Zwangsverschlüsselung (HSTS)

server {

listen 443 ssl;

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

}

Tipp: Kombinieren Sie Rate Limiting mit limit_req_status 429 um einen passenden HTTP-Statuscode für zu viele Anfragen zurückzugeben.

Reverse Proxy Parameter im Überblick

proxy_pass Ziel-Backend
http://localhost:3000

proxy_set_header Header setzen
Host, X-Real-IP, X-Forwarded-*

proxy_cache Caching
Antworten cachen

proxy_read_timeout Timeout
Verbindungslimits

Upgrade WebSocket
http_upgrade

limit_req Rate Limiting
Anfragen pro Sekunde

Quick Summary

proxy_pass

Weiterleitung

proxy_set_header

Header setzen

proxy_cache

Caching

Upgrade

WebSocket

timeout

Timeouts

limit_req

Rate Limiting

proxy_pass http://localhost:3000 · proxy_set_header Host $host · proxy_cache my_cache