Erste Schritte
Grundkonfiguration
Die Nginx-Konfiguration nutzt eine hierarchische Blockstruktur. worker_processes legt die Prozessanzahl fest. Der http-Block enthält server-Blöcke, die location-Blöcke enthalten. Vor jedem Reload immer mit nginx -t testen.
# /etc/nginx/nginx.conf
worker_processes auto;
events {
worker_connections 1024;
}
http {
server {
listen 80;
server_name example.com;
location / {
root /var/www/html;
index index.html;
}
}
}
# Test config: nginx -t
# Reload: nginx -s reload
# Start: systemctl start nginxDirektiven & Kontexte
Kontexte schachteln: main > events/http/mail > server > location. Einfache Direktiven enden mit Semikolon; Block-Direktiven nutzen geschweifte Klammern. Manche Direktiven sind nur in bestimmten Kontexten gültig.
# Contexts are hierarchical blocks
# Global context (main) - outside any block
user nginx;
worker_processes auto;
# events context
events {
worker_connections 1024;
}
# http context
http {
# server context
server {
listen 80;
# location context
location / {
root /var/www/html;
}
}
}
# Directives: simple (name value;) or block (name { ... })Testen & Neu laden
nginx -t prüft die Syntax UND versucht, referenzierte Dateien zu öffnen (Zertifikate, Logs). Vor jedem Reload ausführen. reload sendet SIGHUP — Worker beenden aktuelle Requests und laden dann neu. restart verursacht eine kurze Ausfallzeit.
# test configuration for syntax errors
nginx -t
# test and print full config
nginx -T
# reload config without dropping connections
nginx -s reload
# stop gracefully (finishes current requests)
nginx -s quit
# stop immediately
nginx -s stop
# reopen log files (after log rotation)
nginx -s reopen
# systemd alternative
systemctl reload nginx
systemctl restart nginxMain- vs. HTTP-Kontext
worker_processes und events leben im main-Kontext. Routing, Proxying, Caching und Server-Blöcke leben in http. SSL, Logging und gzip lassen sich in http setzen und werden von server/location geerbt.
# main context - global settings
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;
events {
worker_connections 4096;
}
http {
# all HTTP-related config lives here
include /etc/nginx/mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
include /etc/nginx/conf.d/*.conf;
}Include-Dateien
Includes halten die Konfiguration modular. Das conf.d-Glob (*.conf) ist die moderne Konvention. sites-enabled mit Symlinks ist das Debian/Ubuntu-Muster. mime.types mappt Dateiendungen auf Content-Type.
# main config: /etc/nginx/nginx.conf
http {
include /etc/nginx/mime.types;
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}
# /etc/nginx/conf.d/default.conf
server {
listen 80;
server_name example.com;
root /var/www/html;
}
# Disable a site: remove the file from sites-enabled/
# Available sites kept in sites-available/, symlinked into enabled/Kommandozeilen-Operationen
nginx -V zeigt Compile-Zeit-Optionen inklusive der eingebauten Module. -g setzt Direktiven, die die Konfiguration überschreiben. -c ist nützlich, um alternative Konfigurationen zu testen, ohne die Standarddatei anzufassen.
# start nginx (if not managed by systemd)
nginx
# specify a custom config file
nginx -c /path/to/nginx.conf
# set a global directive from command line
nginx -g "worker_processes 4;"
# test config
nginx -t
# print version and build configuration
nginx -V
# send signal to master process
nginx -s reload
nginx -s stopServer-Blöcke
Einfacher Server-Block
Ein server-Block definiert einen virtuellen Host. listen setzt den Port. server_name matcht den Host-Header. root setzt das Dokumentenverzeichnis. index legt fest, welche Dateien bei Verzeichnis-Requests ausgeliefert werden.
server {
listen 80;
server_name example.com www.example.com;
root /var/www/example;
index index.html index.htm;
location / {
try_files $uri $uri/ =404;
}
}Mehrere Server-Namen
Nginx matcht server_name exakt, dann per Wildcard (*.foo.com), dann per Regex. Der erste passende server-Block behandelt den Request. Für verschiedene Apps auf demselben Port getrennte Blöcke verwenden.
server {
listen 80;
server_name example.com www.example.com;
# ...
}
server {
listen 80;
server_name api.example.com;
# ...
}
# Wildcard: matches any single-level subdomain
server_name *.example.com;
# Regex (starts with ~)
server_name ~^www\d+\.example\.com$;Default-Server
default_server behandelt Requests, deren Host-Header auf keinen server_name passt. Der Unterstrich ist eine Konvention (ungültiger Hostname, matched nie echten Traffic). return 444 schließt die Verbindung ohne Antwort.
# mark a server block as default for the port
server {
listen 80 default_server;
server_name _;
return 444; # drop connection (no response)
}
# handles all requests that don't match another server_name
# _ is an invalid hostname, used as catch-all convention
# useful to block requests with no matching Host headerlisten-Direktive
listen kann sich an eine bestimmte Adresse, IPv6, einen UNIX-Socket binden oder den default_server setzen. Der Parameter ssl aktiviert TLS für diesen Listener. In einem server-Block sind mehrere listen-Direktiven erlaubt.
# listen on port 80
listen 80;
# IPv6
listen [::]:80;
# HTTPS (ssl flag)
listen 443 ssl;
listen [::]:443 ssl;
# specific address
listen 127.0.0.1:8080;
# default server for this port
listen 80 default_server;
# listen on UNIX socket
listen unix:/var/run/nginx.sock;Server-Name-Matching
Die Match-Priorität ist exakt > führende Wildcard > nachgestellte Wildcard > Regex. Regexes werden in Konfigurationsreihenfolge geprüft, der erste Treffer gewinnt. Hash-Bucket-Size erhöhen, wenn Servernamen lang oder zahlreich sind.
# Order of precedence (highest to lowest):
# 1. Exact name: example.com
# 2. Longest wildcard starting with *: *.example.com
# 3. Longest wildcard ending with *: www.*
# 4. First matching regex (in config order): ~^www\d+\.
# If nothing matches, the default_server handles it
# Tune hash sizes for many server names
http {
server_names_hash_bucket_size 64;
server_names_hash_max_size 512;
}Catch-all-Server
Ein Catch-all verhindert, dass Requests mit beliebigen Host-Headern deine Apps erreichen. return 301 leitet auf einen bekannten Host um. return 444 verwirft die Verbindung — nützlich gegen Scanner, die deine IP direkt treffen.
# catch all requests regardless of host header
server {
listen 80 default_server;
server_name _; # invalid name, never matches real host
return 301 https://$host$request_uri;
}
# or drop the connection silently
server {
listen 80 default_server;
server_name _;
return 444;
}
# redirect unknown subdomains to main site
server {
listen 80 default_server;
return 301 https://example.com;
}Location-Blöcke
Location-Modifikatoren
Modifikatoren ändern das Matching-Verhalten: = (exakt), ^~ (Präfix, Regex überspringen), ~ (Regex, groß-/kleinschreibungsabhängig), ~* (Regex, unabhängig von Groß-/Kleinschreibung), keiner (Präfix). Regex eignet sich am besten für Dateiendungen; Präfix für Pfadbäume.
# exact match - fastest, stops search if matched
location = /favicon.ico {
log_not_found off;
}
# prefix match with ^~ - skips regex if longest prefix matches
location ^~ /static/ {
root /var/www;
}
# case-sensitive regex
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
}
# case-insensitive regex
location ~* \.(jpg|jpeg|png|gif|ico)$ {
expires 30d;
}
# prefix match (no modifier)
location / {
try_files $uri $uri/ /index.php;
}Location-Priorität
Nginx wertet exakt (=) zuerst aus, dann Präfix-Matches (der längste gewinnt), dann Regex in Konfigurationsreihenfolge. ^~ lässt ein Präfix-Match die Regex-Auswertung überspringen. Wer diese Reihenfolge versteht, vermeidet Überraschungen bei überlappenden Locations.
# Priority order (highest to lowest):
# 1. = exact match
# 2. ^~ prefix match (skips regex if matched)
# 3. ~ ~* regex (first match in config order)
# 4. (none) prefix match (longest wins)
location = /api {
# exact, highest priority
}
location ^~ /assets/ {
# prefix, beats regex
}
location ~ \.php$ {
# regex
}
location /api/ {
# prefix, lowest of these
}Root vs. Alias
root hängt die URI an seinen Wert an; alias ersetzt das gematchte Präfix. root verwenden, wenn die Location auf ein Unterverzeichnis eines Baums mapt. alias verwenden, wenn der URI-Pfad vom Dateisystempfad abweicht. alias mit Regex braucht einen $1-Capture.
# root: appends the full URI to the path
# request /img/cat.png -> /var/www/img/cat.png
location /img/ {
root /var/www;
}
# alias: replaces the matched location part
# request /img/cat.png -> /data/images/cat.png
location /img/ {
alias /data/images/;
}
# alias with regex requires capturing the path
location ~ ^/img/(.*)$ {
alias /data/images/$1;
}try_files
try_files prüft jedes Argument der Reihe nach; das letzte ist der Fallback (keine Dateiprüfung). $uri prüft die Datei, $uri/ das Verzeichnis. Der Fallback kann eine URI, =code oder @named sein. Essenziell für SPAs und CMS-Routing.
# try files in order, fall back to last option
location / {
try_files $uri $uri/ /index.html;
}
# serve index.php if file/dir not found (pretty URLs)
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# return 404 if nothing matches
location / {
try_files $uri =404;
}
# named location as fallback
location / {
try_files $uri $uri/ @drupal;
}Benannte Locations
Benannte Locations (@name) sind nur intern — sie werden nie direkt von einem Request-URI getroffen. Sie sind Ziele für try_files, error_page und rewrite. Ideal, um einen Konfigurationsblock (etwa einen Fallback-Handler) über mehrere Locations zu teilen.
# named locations start with @, can't be reached externally
# used as try_files fallback or rewrite target
location / {
try_files $uri $uri/ @app;
}
location @app {
fastcgi_pass unix:/run/php.sock;
# ... fastcgi config
}
# useful for organizing common error logic
location @error_page {
return 500 "Internal Server Error";
}
# can also be used with error_page
error_page 404 @fallback;
location @fallback {
proxy_pass http://backend;
}Verschachtelte Locations
Locations dürfen verschachteln. Innere Locations erben Direktiven der äußeren und können sie überschreiben. Nützlich, um einen Pfad innerhalb eines breiteren Präfixes Sonderbehandlung zu geben (z. B. größere Body-Größe für Uploads oder statische Dateien aus einem Unterpfad).
location /api {
# /api/users, /api/posts handled here
proxy_pass http://backend;
location /api/upload {
# override for upload endpoint
client_max_body_size 50M;
proxy_pass http://upload_backend;
}
location ~ ^/api/static/(.*)$ {
# regex inside prefix location
root /var/www;
}
}Reverse-Proxy
Einfaches proxy_pass
proxy_pass leitet Requests an einen Upstream-Server weiter. Ein nachgestellter Slash auf proxy_pass bewirkt, dass das gematchte Location-Präfix ersetzt wird. Ohne nachgestellten Slash wird der Original-URI unverändert durchgereicht.
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://localhost:3000;
}
}
# proxy_pass with URI replacement (trailing slash matters)
location /api/ {
proxy_pass http://backend/; # /api/foo -> /foo
}
# without trailing slash, URI is preserved
location /api/ {
proxy_pass http://backend; # /api/foo -> /api/foo
}Proxy-Header
Standardmäßig reicht nginx weder Client-IP noch Original-Host durch. X-Real-IP und X-Forwarded-For setzen, damit das Backend den echten Client erkennt. X-Forwarded-Proto nennt das Original-Schema — kritisch für HTTPS-Redirect-Logik.
location / {
proxy_pass http://backend;
# preserve original host
proxy_set_header Host $host;
# real client IP (not nginx's)
proxy_set_header X-Real-IP $remote_addr;
# forwarded-for chain
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# scheme (http or https)
proxy_set_header X-Forwarded-Proto $scheme;
# original host
proxy_set_header X-Forwarded-Host $host;
}Upstream-Proxy
Ein upstream-Block definiert einen benannten Serverpool, auf den proxy_pass verweisen kann. Das ermöglicht Lastverteilung, Health Checks und Keepalive-Verbindungen. Upstream-Variablen sind nützlich, um zu loggen, welches Backend jeden Request behandelt hat.
# define a named pool of backend servers
upstream backend {
server 10.0.0.1:8080;
server 10.0.0.2:8080;
server 10.0.0.3:8080;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
# useful upstream variables:
# $upstream_addr, $upstream_status,
# $upstream_response_time, $upstream_cache_statusProxy-Timeouts
proxy_connect_timeout ist das TCP-Handshake-Limit; read/send-Timeouts gelten für Leerlaufphasen während der Datenübertragung. read_timeout für langsame Endpunkte erhöhen (Exports, AI-Inferenz). upstream keepalive wiederverwendet Verbindungen und senkt die Latenz.
location / {
proxy_pass http://backend;
# connect timeout (TCP handshake to upstream)
proxy_connect_timeout 5s;
# time between reads from upstream (response)
proxy_read_timeout 60s;
# time between writes to upstream (request body)
proxy_send_timeout 60s;
# for slow backends (large uploads/downloads)
proxy_read_timeout 300s;
}
# keepalive connections to upstream
upstream backend {
server 10.0.0.1:8080;
keepalive 32;
}Proxy-Buffering
Buffering speichert die Upstream-Antwort im Speicher/auf Platte, bevor sie an den Client geht — effizient bei langsamen Clients, bricht aber Streaming. Bei SSE, WebSocket oder chunked Streaming abschalten. buffer_size ist der erste Teil (Header); buffers halten den Rest.
location / {
proxy_pass http://backend;
# enable buffering (default on)
proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 8 4k;
# busy buffers during streaming
proxy_busy_buffers_size 16k;
# disable for streaming/SSE
proxy_buffering off;
proxy_cache off;
}
# Server-Sent Events or streaming responses
location /events {
proxy_pass http://backend;
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
}WebSocket-Upgrade
WebSocket braucht HTTP/1.1 plus Upgrade- und Connection-Header. Der map-Block wandelt den Upgrade-Header in den korrekten Connection-Wert um (upgrade vs. close). Ein langes proxy_read_timeout verhindert, dass im Leerlauf hängende WebSockets geschlossen werden.
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
location /ws {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# keepalive for long-lived connections
proxy_read_timeout 3600s;
}
}Lastverteilung
upstream-Block
Ein upstream-Block definiert Backend-Server. Standard-Lastverteilung ist Round-Robin. max_fails und fail_timeout konfigurieren passive Health Checks: Nach max_fails Fehlern innerhalb von fail_timeout gilt der Server für fail_timeout Sekunden als down.
upstream backend {
server backend1.example.com weight=5;
server backend2.example.com;
server backend3.example.com max_fails=3 fail_timeout=30s;
}
server {
location / {
proxy_pass http://backend;
}
}
# default algorithm: round-robin
# max_fails: failed attempts before marking server down
# fail_timeout: window for counting fails AND downtime durationLoad-Balancing-Methoden
Round-Robin verteilt gleichmäßig; least_conn sendet an den am wenigsten belasteten Server; ip_hash hält einen Client auf demselben Server (Sticky Sessions via IP); hash verteilt nach einem eigenen Schlüssel. Der Parameter consistent minimiert die Umverteilung beim Hinzufügen/Entfernen von Servern.
# round-robin (default) - even distribution
upstream backend {
server s1.example.com;
server s2.example.com;
}
# least connections - fewest active connections
upstream backend {
least_conn;
server s1.example.com;
server s2.example.com;
}
# ip_hash - sticky by client IP (session persistence)
upstream backend {
ip_hash;
server s1.example.com;
server s2.example.com;
}
# generic hash (key-based, e.g., by URI or header)
upstream backend {
hash $request_uri consistent;
server s1.example.com;
server s2.example.com;
}Gewichtetes Round-Robin
weight steuert die Traffic-Verteilung anteilig. Standardgewicht ist 1. Stärkeren Servern höhere Gewichte geben, damit sie einen größeren Anteil übernehmen. Gewichte funktionieren mit Round-Robin, least_conn und ip_hash.
upstream backend {
server s1.example.com weight=3; # 3x traffic
server s2.example.com weight=2; # 2x traffic
server s3.example.com weight=1; # 1x traffic (default)
}
# total weight = 6
# s1 gets 3/6 = 50%, s2 gets 2/6 = 33%, s3 gets 1/6 = 17%
# useful when servers have different capacity
# e.g., a 4-core server gets weight=4, a 2-core gets weight=2Health Checks
Open-Source-Nginx nutzt passive Health Checks (max_fails/fail_timeout) auf Basis echter Request-Fehler. NGINX Plus ergänzt aktive Health Checks, die periodisch eine URI pollen. Ein Server muss 'passes' Checks hintereinander bestehen, um wieder als gesund zu gelten.
upstream backend {
server s1.example.com max_fails=3 fail_timeout=30s;
server s2.example.com max_fails=3 fail_timeout=30s;
# passive health check (default behavior):
# 3 failures within 30s marks the server down
# it stays down for fail_timeout (30s) before retry
}
# NGINX Plus active health check
upstream backend {
server s1.example.com;
server s2.example.com;
health_check interval=10s fails=3 passes=2;
health_check uri=/health;
}Session-Persistenz
ip_hash liefert Sticky Sessions per Client-IP, bricht aber, wenn sich die IP ändert (Mobilfunknetze). Die hash-Direktive mit consistent minimiert die Schlüssel-Umverteilung bei Pool-Änderungen. sticky cookie (Plus) setzt ein Cookie, um einen Client an einen Server zu heften.
# ip_hash: routes by client IP (uses first 3 IPv4 octets)
upstream backend {
ip_hash;
server s1.example.com:8080;
server s2.example.com:8080;
}
# sticky cookie (NGINX Plus only)
upstream backend {
sticky cookie srv_id expires=1h domain=.example.com path=/;
server s1.example.com;
server s2.example.com;
}
# hash with consistent parameter for minimal redistribution
upstream backend {
hash $http_x_session_id consistent;
server s1.example.com;
server s2.example.com;
}Backup-Server
Mit dem Parameter backup markierte Server bekommen nur Traffic, wenn alle primären Server ausfallen. Übliches Muster: Primäre servern die App; ein Backup liefert eine statische Wartungsseite. Backup-Server sind von der normalen Lastverteilung ausgeschlossen.
upstream backend {
server s1.example.com;
server s2.example.com;
# used only when all primaries are down
server s3.example.com backup;
server s4.example.com backup;
}
# backup servers receive traffic ONLY when all
# non-backup servers are unavailable
# useful for a maintenance page or DR fallback
upstream backend {
server primary.example.com;
server standby.example.com backup;
}SSL/TLS-Konfiguration
Einfacher HTTPS-Server
Der Parameter ssl auf listen aktiviert TLS. ssl_certificate zeigt auf die Zertifikatskette (Serverzertifikat + Intermediates); ssl_certificate_key auf den privaten Schlüssel. Immer fullchain.pem verwenden, damit Clients die Kette verifizieren können.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/certs/example.com.crt;
ssl_certificate_key /etc/ssl/private/example.com.key;
root /var/www/html;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}SSL-Zertifikat einrichten
Let's Encrypt legt Zertifikate unter /etc/letsencrypt/live/<domain>/ ab. fullchain.pem enthält die Intermediates; privkey.pem ist der private Schlüssel. Nginx unterstützt mehrere Zertifikatstypen pro Server und wählt nach Client-Fähigkeit.
# Let's Encrypt paths
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# multiple cert types (RSA + ECDSA) on one server
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.rsa.crt;
ssl_certificate_key /etc/ssl/example.com.rsa.key;
ssl_certificate /etc/ssl/example.com.ecdsa.crt;
ssl_certificate_key /etc/ssl/example.com.ecdsa.key;
}HTTP-zu-HTTPS-Redirect
Das sauberste Muster ist ein eigener Port-80-Server, der umleitet. $host erhält den Original-Hostnamen. if ($scheme) in einem kombinierten Block funktioniert, aber der Ansatz mit separatem Server ist zu bevorzugen und vermeidet die 'If is evil'-Fallen.
# redirect all HTTP traffic to HTTPS
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
# single server block handling both
server {
listen 80;
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.crt;
ssl_certificate_key /etc/ssl/example.com.key;
if ($scheme != "https") {
return 301 https://$host$request_uri;
}
}SSL-Protokolle & Ciphers
Alte Protokolle deaktivieren (SSLv3, TLSv1.0/1.1). TLS 1.3 ist am schnellsten und sichersten. Den Mozilla SSL Configuration Generator für ein getestetes Profil verwenden. shared:SSL-Cache beschleunigt die Session-Wiederaufnahme über Worker hinweg.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.crt;
ssl_certificate_key /etc/ssl/example.com.key;
# modern configuration (Mozilla SSL Config Generator)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;
# session settings
ssl_session_tickets off;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:50m;
}HSTS
HSTS sagt Browsern, die Domain immer über HTTPS zu laden, und verhindert SSL-Stripping-Angriffe. max-age ist in Sekunden (31536000 = 1 Jahr). includeSubDomains deckt alle Subdomains ab. preload meldet die Seite an eine eingebaute Browser-Liste — praktisch irreversibel, vorsichtig einsetzen.
server {
listen 443 ssl;
server_name example.com;
# HSTS: force HTTPS for 1 year (include subdomains)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# preload list (be very careful — requires permanent HTTPS)
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
}
# Preload commits your domain to a browser-baked HTTPS-only list.
# Only enable preload after verifying all subdomains work on HTTPS.OCSP-Stapling
OCSP-Stapling lässt nginx den Widerrufsstatus des Zertifikats holen und mitliefern und spart dem Client den Round-Trip zum OCSP-Responder. ssl_trusted_certificate wird benötigt, um die OCSP-Antwort zu verifizieren. Ein Resolver ist nötig, damit nginx den OCSP-Server erreicht.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/example.com/privkey.pem;
ssl_stapling on;
ssl_stapling_verify on;
# trust chain for verification
ssl_trusted_certificate /etc/ssl/example.com/chain.pem;
# DNS resolver needed for OCSP requests
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
}Statische Dateien ausliefern
Statische Dateien ausliefern
root definiert das Dokumentenverzeichnis; nginx mappt den Request-URI auf einen Dateipfad. try_files prüft die Datei, dann das Verzeichnis, dann 404. root auf Server-Ebene gesetzt, erben alle Locations, aber pro Location lässt sich überschreiben.
server {
listen 80;
server_name example.com;
root /var/www/html;
location / {
try_files $uri $uri/ =404;
}
}
# root set at server level is inherited by all locations
# request /images/logo.png -> /var/www/html/images/logo.png
# request /css/style.css -> /var/www/html/css/style.cssindex-Direktive
index listet Dateien, die versucht werden, wenn der Request ein Verzeichnis anfragt. Die erste existierende wird ausgeliefert. Existiert keine und ist autoindex aus, liefert nginx 403. Die Reihenfolge zählt — bevorzugte Dateien zuerst listen.
server {
listen 80;
root /var/www/html;
# try these files in order when request targets a directory
index index.html index.htm index.php;
location / {
try_files $uri $uri/ =404;
}
}
# request / -> tries /var/www/html/index.html, then index.htm
# request /about/ -> tries /var/www/html/about/index.html
# if no index file found and autoindex off -> 403 Forbiddentry_files für SPA
SPAs routen clientseitig, also müssen unbekannte Pfade index.html ausliefern. try_files $uri $uri/ /index.html macht genau das. Gehashte Assets ein Jahr mit immutable cachen, da ihre inhaltsadressierten Dateinamen bei Inhaltsänderung eine neue URL garantieren.
# Single Page Application (React, Vue, Angular)
server {
listen 80;
root /var/www/spa;
location / {
# serve static files, fall back to index.html for client routing
try_files $uri $uri/ /index.html;
}
# cache static assets aggressively (filename usually hashed)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}Autoindex (Verzeichnisliste)
autoindex erzeugt eine HTML-Verzeichnisliste. Nützlich für Datei-Download-Seiten. exact_size ausschalten für Lesbarkeit und localtime einschalten für korrekte Zeitstempel. Nie für Verzeichnisse mit sensiblen Dateien aktivieren — immer mit Zugriffskontrolle kombinieren.
location /files/ {
autoindex on;
autoindex_exact_size off; # human-readable sizes (KB, MB)
autoindex_localtime on; # show local time instead of UTC
root /var/www;
}
# /files/ -> directory listing
# /files/doc.pdf -> downloads the file
# /files/sub/ -> listing of subdirectory
# disable for security on sensitive directories
location /private/ {
autoindex off;
deny all;
}Expires-Header
expires setzt das Cache-Control-max-age. immutable sagt Browsern, dass sich die Datei nie ändert (Revalidierung überspringen). Für gehashte Assets (file.abc123.js) ist 1y + immutable ideal. HTML sollte immer revalidieren, damit Nutzer Updates sofort bekommen.
# cache static assets for a year
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
# never cache HTML (always revalidate)
location ~* \.html$ {
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# short cache for API responses
location /api/ {
add_header Cache-Control "no-cache";
}Logging für statische Inhalte deaktivieren
Static-Asset- und favicon/robots-Requests verstopfen die Access-Logs. access_log off stoppt das Logging; log_not_found off unterdrückt 404-Logeinträge. So bleiben Logs auf sinnvollen Traffic fokussiert und die Platten-I/O auf stark frequentierten Seiten sinkt.
# don't log requests for static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
access_log off;
log_not_found off;
expires 1y;
}
# don't log favicon requests (often 404 from browsers)
location = /favicon.ico {
log_not_found off;
access_log off;
}
# don't log robots.txt
location = /robots.txt {
log_not_found off;
access_log off;
}Gzip-Kompression
Gzip aktivieren
gzip komprimiert Antworten und spart Bandbreite. gzip_vary ergänzt 'Vary: Accept-Encoding' für Caches. gzip_proxied any komprimiert auch für proxied Requests. comp_level 6 balanciert CPU und Größe. min_length 256 überspringt winzige Antworten (Overhead übersteigt den Gewinn).
http {
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_min_length 256;
gzip_types
text/plain
text/css
text/xml
application/json
application/javascript
application/xml+rss
application/atom+xml
image/svg+xml;
}Gzip-Typen
gzip_types listet die zu komprimierenden MIME-Typen. text/html wird standardmäßig immer komprimiert. Bereits komprimierte Binärformate (Bilder, Video, Archive) nicht komprimieren — das verschwendet CPU ohne Größengewinn und kann die Ausgabe sogar vergrößern.
http {
gzip on;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/javascript
application/x-javascript
application/json
application/xml
application/xml+rss
application/rss+xml
application/atom+xml
image/svg+xml
font/ttf
font/otf
application/vnd.ms-fontobject;
# text/html is always compressed (implicitly, cannot disable)
# DON'T compress already-compressed: jpg, png, gif, mp4, zip, gz
}Gzip-Kompressionsstufe
comp_level tauscht CPU gegen Kompression. 6 ist der Sweet Spot — 9 kostet weit mehr CPU für <2 % kleinere Ausgabe. min_length vermeidet die Kompression winziger Antworten, wo der Gzip-Header-Overhead die Ersparnis übersteigt. gzip_disable schließt das alte IE6 aus, dessen Gzip-Unterstützung defekt ist.
http {
gzip on;
gzip_comp_level 6; # 1-9, higher = more compression, more CPU
# level 1: fast, low compression
# level 6: good balance (recommended default)
# level 9: slow, marginal size gain
# minimum response size to compress (bytes)
gzip_min_length 256;
# disable gzip for old browsers
gzip_disable "MSIE [1-6]\.";
}gzip_static
gzip_static liefert vorab erzeugte .gz-Dateien aus und eliminiert die CPU-Kosten der Laufzeitkompression. Der Build-Schritt erzeugt .gz-Dateien neben den Originalen. Nginx liefert .gz an Clients mit Accept-Encoding: gzip, sonst das Original. Ideal für statische Asset-Pipelines.
# serve pre-compressed .gz files (no runtime compression cost)
# requires ngx_http_gzip_static_module
location / {
gzip_static on;
# on: serve .gz if it exists
# always: serve .gz even without Accept-Encoding header
root /var/www/html;
}
# pre-compress files at build time:
# find /var/www/html -type f ( -name "*.css" -o -name "*.js" \
# -o -name "*.html" ) -exec gzip -k -9 {} \;
# creates file.css.gz, file.js.gz alongside the originalsBrotli
Brotli schlägt gzip bei Textinhalten, besonders auf höheren Kompressionsstufen. Es erfordert das Drittanbieter-Modul ngx_brotli. brotli_static liefert vorab erzeugte .br-Dateien aus. Moderne Browser melden 'br' in Accept-Encoding, also wählt nginx das beste verfügbare.
# requires ngx_brotli module (not built-in)
http {
brotli on;
brotli_comp_level 6;
brotli_types
text/plain
text/css
application/javascript
application/json
image/svg+xml;
# serve pre-compressed .br files
brotli_static on;
}
# Brotli typically 10-20% smaller than gzip for text
# supported by all modern browsers (not IE)
# nginx can serve both .br and .gz; picks based on Accept-EncodingGzip für proxied Requests
Standardmäßig komprimiert nginx proxied Antworten nicht (um doppelte Kompression bereits komprimierter Upstreams zu vermeiden). gzip_proxied any aktiviert sie für alle proxied Requests. gzip_vary stellt sicher, dass Caches getrennte Versionen für komprimierte/unkomprimierte Clients speichern.
http {
gzip on;
gzip_proxied any;
# gzip_proxied controls compression for proxied requests:
# off: never compress proxied requests
# expired: compress if response has Expires header
# no-cache: compress if Cache-Control: no-cache
# no-store: compress if Cache-Control: no-store
# private: compress if Cache-Control: private
# no_last_modified: compress if no Last-Modified header
# no_etag: compress if no ETag header
# auth: compress if Authorization header present
# any: compress all proxied requests
gzip_vary on; # add "Vary: Accept-Encoding" header
}Caching
Proxy-Cache
proxy_cache speichert Upstream-Antworten auf Platte. keys_zone definiert eine geteilte Speicherzone für Cache-Schlüssel (10m ≈ 80.000 Schlüssel). max_size begrenzt die Plattennutzung; inactive entfernt Einträge, die in dieser Zeit nicht gelesen wurden. use_temp_path=off schreibt direkt in den Cache — schneller.
http {
# define cache zone on disk
proxy_cache_path /var/cache/nginx levels=1:2
keys_zone=api_cache:10m
max_size=1g
inactive=60m
use_temp_path=off;
server {
location /api/ {
proxy_pass http://backend;
proxy_cache api_cache;
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
}
}
}Cache-Zone
levels=1:2 erzeugt aus dem MD5-Hash des Cache-Schlüssels einen zweistufigen Verzeichnisbaum, um zu viele Dateien in einem Verzeichnis zu vermeiden. Getrennte Zonen pro Inhaltstyp erlauben es, max_size und inactive unabhängig zu tunen — statisch länger, API kurz gecacht.
http {
proxy_cache_path /var/cache/nginx
levels=1:2 # directory hierarchy depth
keys_zone=my_cache:10m # zone name + shared memory size
max_size=1g # max disk size for cache
inactive=60m # remove if not accessed in 60min
use_temp_path=off; # write directly (faster, no temp copy)
# multiple zones for different content types
proxy_cache_path /var/cache/static levels=1:2
keys_zone=static:10m max_size=500m inactive=24h;
proxy_cache_path /var/cache/api levels=1:2
keys_zone=api:10m max_size=200m inactive=10m;
}Cache-Schlüssel
Der Cache-Schlüssel bestimmt die Eindeutigkeit des Caches. Der Standardschlüssel kann über virtuelle Hosts hinweg kollidieren — $host einschließen. Für nutzerbezogene Inhalte einen Nutzerbezeichner einschließen. proxy_cache_bypass überspringt den Cache (speichert trotzdem); proxy_no_cache speichert die Antwort nicht.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# default key: $scheme$proxy_host$request_uri
proxy_cache_key "$scheme$request_method$host$request_uri";
# include user-specific data to avoid cross-user leaks
proxy_cache_key "$scheme$host$request_uri$http_x_user_id";
# bypass cache for authenticated users
proxy_cache_bypass $http_authorization;
proxy_no_cache $http_authorization;
}Cache-Gültigkeit
proxy_cache_valid setzt TTLs pro Statuscode. 0s oder das Weglassen eines Status verhindert dessen Caching. proxy_cache_lock serialisiert gleichzeitige Cache-Misses für denselben Schlüssel — nur ein Request trifft den Upstream; die restlichen warten auf die gecachte Antwort.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# cache by response status code
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid 500 502 503 504 0s; # don't cache errors
# fallback for any other status
proxy_cache_valid any 1m;
# cache lock: collapse concurrent misses into one upstream call
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
}Cache umgehen
proxy_cache_bypass überspringt das Lesen des Caches (geht zum Upstream), kann die Antwort aber trotzdem speichern. proxy_no_cache überspringt das Speichern. Der X-Cache-Status-Header ist beim Debuggen unbezahlbar — HIT heißt aus dem Cache ausgeliefert, MISS heißt vom Upstream geholt.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# bypass cache (always go to upstream)
proxy_cache_bypass $http_authorization $arg_nocache;
# don't store in cache
proxy_no_cache $http_authorization;
# add header showing cache status for debugging
add_header X-Cache-Status $upstream_cache_status;
}
# $upstream_cache_status values:
# MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, HITBrowser-Caching
Browser-Caching senkt die Latenz wiederkehrender Besuche. immutable überspringt die Revalidierung komplett (nur sicher bei inhaltsadressierten Dateinamen). no-cache heißt jedes Mal revalidieren (Conditional-GET bleibt erlaubt). no-store heißt nie speichern. Mit ETags paaren für effiziente 304-Antworten.
# cache static assets in the browser
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# HTML - revalidate always
location ~* \.html$ {
add_header Cache-Control "no-cache, must-revalidate";
etag on;
}
# API responses - never cache
location /api/ {
add_header Cache-Control "no-store";
}
# public: any cache (browser, CDN) may store
# private: only the browser may store
# immutable: file never changes, skip revalidation
# no-store: never cacheURL-Rewrite
return-Direktive
return ist der einfachste Weg umzuleiten oder zu antworten. Er stoppt die Verarbeitung sofort. 301 für permanente, 302 für temporäre Redirects verwenden. Ein Statuscode mit Body (200, 418) oder eine Umleitung auf eine URL ist möglich. Für Redirects return statt rewrite bevorzugen.
# simplest redirect/rewrite - return stops processing
server {
location /old {
return 301 /new;
}
location /external {
return 301 https://example.com$request_uri;
}
location /api {
return 200 "OK\n";
}
location /teapot {
return 418 "I'm a teapot";
}
}
# return is preferred over rewrite for simple redirectsrewrite-Direktive
rewrite matcht den URI gegen einen Regex und ersetzt ihn. last wertet das Location-Matching mit dem neuen URI neu aus (wie ein Neustart). break stoppt das Rewriting, bleibt aber in der aktuellen Location. redirect/permanent senden dem Browser eine Umleitung.
# rewrite regex replacement [flag]
server {
# rewrite /old/* to /new/* preserving the captured part
rewrite ^/old/(.*)$ /new/$1 permanent;
# rewrite old blog URLs to new structure
rewrite ^/blog/(\d{4})/(\d{2})/(.*)$ /articles/$1/$2/$3 last;
# capture with named groups
rewrite ^/download/(.*)$ /assets/$1 last;
}
# flags:
# last: re-search locations with the new URI
# break: stop rewrite, continue in current location
# redirect: 302 temporary redirect
# permanent: 301 permanent redirectRewrite-Flags
last vs. break ist der verwirrendste Teil. last startet die Location-Suche neu (nützlich, wenn das Rewrite auf eine andere Location zielt). break stoppt das Rewriting, bleibt aber (nützlich, wenn das Rewrite nur einen internen Pfad anpasst). redirect/permanent ändern die URL im Browser.
location / {
# last: restart location matching with new URI
rewrite ^/api/(.*)$ /backend/$1 last;
# break: stop processing rewrites, stay in current location
rewrite ^/static/(.*)$ /assets/$1 break;
# redirect: 302 temporary redirect (browser URL changes)
rewrite ^/old/(.*)$ /new/$1 redirect;
# permanent: 301 permanent redirect (browser URL changes)
rewrite ^/old/(.*)$ /new/$1 permanent;
}
# avoid rewrite inside if blocks - use location + try_files insteadBenannte Captures
Benannte Captures (?<name>pattern) erzeugen Variablen ($name), die klarer sind als positionale $1, $2. Sie funktionieren in Location-Regex wie in rewrite. Die Captures stehen in proxy_pass, fastcgi_param, add_header und log_format innerhalb dieser Location zur Verfügung.
# named captures in regex locations
location ~ ^/users/(?<username>[a-z]+)/?$ {
proxy_pass http://backend/users/$username;
}
# named captures in rewrite
location / {
rewrite ^/articles/(?<year>\d{4})/(?<slug>[a-z-]+)/?$
/blog?year=$year&slug=$slug last;
}
# named captures become variables: $year, $slug, $username
# accessible in proxy_pass, fastcgi_pass, headers, etc.
# safer than $1, $2 positional captures for readabilitymap-Direktive
map baut eine Lookup-Tabelle von einer Variable auf eine andere, lazy ausgewertet. Sie ist weit effizienter und lesbarer als Ketten von if-Anweisungen. Der default-Zweig behandelt ungetroffene Werte. Regex-Matches (mit ~ vorangestellt) werden der Reihe nach geprüft.
# map creates a new variable based on another variable's value
map $http_host $backend {
default "http://default.backend";
"a.com" "http://a.backend";
"b.com" "http://b.backend";
"~^.*\.app\.com$" "http://app.backend";
}
server {
server_name a.com b.com;
location / {
proxy_pass $backend;
}
}
# map is evaluated lazily and cached per request
# more efficient than if/else chainsif-Direktive (Vorsicht)
if hat überraschendes Verhalten innerhalb von Location-Blöcken — es kann Konfigurationen unvorhersehbar umschreiben. Die einzigen universell sicheren Verwendungen sind return und rewrite. Für Dateiexistenz-Checks try_files verwenden. Für komplexe Logik map oder getrennte Location-Blöcke. Siehe das Wiki: 'If Is Evil'.
# "if is evil" — use sparingly! Only safe for:
# return / rewrite, and with these checks:
# -f, -d, -e, -x (file/dir/exists/executable)
# =, !=, ~, ~* (string/regex comparison)
location / {
if ($request_method = POST) {
return 405;
}
if ($http_user_agent ~* "bot") {
return 403;
}
# BAD: don't do this inside if
# if (-f $request_filename) { ... }
# use try_files instead
try_files $uri $uri/ /index.html;
}Redirects
Permanenter Redirect (301)
301 heißt 'dauerhaft verschoben' — Browser und Suchmaschinen cachen ihn, also nur für wirklich permanente Änderungen einsetzen. Redirects zuerst mit 302 testen, um einen Fehler nicht einzubetonieren. 301 übergibt Link-Equity (SEO) an die neue URL.
# 301 - permanent redirect (cached by browsers indefinitely)
server {
listen 80;
server_name old-domain.com;
# redirect entire site to a new domain
return 301 https://new-domain.com$request_uri;
}
location /old-page {
return 301 /new-page;
}
# 301 caches indefinitely in browsers — test with 302 first!
# Search engines treat 301 as a permanent move and update indexes.Temporärer Redirect (302)
302 wandelt beim Redirect POST in GET um (historisches Verhalten). 307 und 308 erhalten die Methode — wichtig beim erneuten Absenden von POSTs. 303 konvertiert explizit zu GET (nützlich nach Formularabsenden, um Doppelsenden beim Refresh zu verhindern). Danach wählen, ob die Methode erhalten bleiben soll.
# 302 - temporary redirect (not cached by default)
location /maintenance {
return 302 /maintenance.html;
}
# 307 - temporary, preserves HTTP method (POST stays POST)
location /api/v1 {
return 307 /api/v2;
}
# 308 - permanent, preserves HTTP method
location /api/v1 {
return 308 /api/v2;
}
# 303 - see other (always uses GET for the new request)
location /form-submit {
return 303 /success;
}www auf non-www umleiten
Eine kanonische Form wählen (www oder non-www) und die andere umleiten. Zwei Server-Blöcke ist das sauberste Muster: Der nicht-kanonische leitet nur um. $request_uri erhält Pfad und Query-String. Dasselbe gilt für HTTPS-Redirects.
# www to non-www
server {
listen 80;
server_name www.example.com;
return 301 https://example.com$request_uri;
}
server {
listen 80;
server_name example.com;
# ... main site config
}
# non-www to www (reverse direction)
server {
listen 80;
server_name example.com;
return 301 https://www.example.com$request_uri;
}HTTP auf HTTPS umleiten
$host erhält den Original-Hostnamen, der Redirect funktioniert also für jeden server_name. $request_uri erhält Pfad und Query. Bei Nicht-Standard-Ports :port an $host anhängen. Ein eigener Port-80-Server-Block ist sauberer als if-Checks pro Location.
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
# with a non-standard HTTPS port
server {
listen 8080;
return 301 https://$host:8443$request_uri;
}
# redirect only a specific path
location /secure {
if ($scheme = http) {
return 301 https://$host$request_uri;
}
}Auf eine andere Domain umleiten
Bei Domainmigrationen erhält $request_uri den vollständigen Pfad und die Query, damit Links nicht brechen. rewrite mit einem Capture verwenden, wenn sich die Pfadstruktur ändert. 301 ist bei permanenten Migrationen richtig — er überträgt das SEO-Ranking auf die neue Domain.
# domain migration — preserve all paths
server {
listen 80;
server_name old.com www.old.com;
return 301 https://new.com$request_uri;
}
# preserve path and query string
location /docs/ {
return 301 https://docs.new.com$request_uri;
}
# with path rewrite using capture groups
location /old-blog/ {
rewrite ^/old-blog/(.*)$ https://blog.new.com/$1 permanent;
}Pfadbasierter Redirect
Pfad-Redirects sind nützlich für URL-Aufräumarbeiten (Slash am Ende entfernen, Dateiendungen entfernen) und Inhaltszüge. Regex-Locations mit Captures ($1) ermöglichen flexibles Pfad-Rewriting. Query-Parameter-basierte Redirects lesen mit $arg_name einzelne Query-Parameter.
# redirect specific paths
location /promo/2023 {
return 301 /promo/2024;
}
# remove trailing slash
location ~ ^/(.*)/$ {
return 301 /$1;
}
# remove .html extension
location ~ ^/(.*)\.html$ {
return 301 /$1;
}
# redirect based on query parameter
location /download {
if ($arg_version = "1") {
return 301 /download?v=2;
}
}FastCGI (PHP-FPM)
PHP-FPM-Grundeinrichtung
fastcgi_pass sendet PHP-Requests an PHP-FPM über einen UNIX-Socket (schneller, nur lokal) oder TCP-Port. include fastcgi_params setzt die Standard-CGI-Variablen. SCRIPT_FILENAME sagt PHP, welche Datei auszuführen ist — Dokumentenverzeichnis plus Skriptpfad.
server {
listen 80;
server_name example.com;
root /var/www/laravel/public;
index index.php;
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
# or: fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}FastCGI-Params
fastcgi_params setzt Umgebungsvariablen, die an PHP durchgereicht werden. SCRIPT_FILENAME ist am kritischsten — ohne ihn findet PHP das Skript nicht. Eigene Params (APP_ENV, DB_HOST) erlauben es, Konfiguration zu injizieren, ohne die App zu ändern. PATH_INFO ermöglicht saubere URLs in manchen Frameworks.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
# standard CGI parameters
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
# custom application parameters
fastcgi_param APP_ENV production;
fastcgi_param DB_HOST db.internal;
# flag for HTTPS (so PHP knows the original scheme)
fastcgi_param HTTPS $https_flag;
}FastCGI-Cache
fastcgi_cache speichert PHP-Antworten und entlastet cachebare Seiten dramatisch. fastcgi_cache_use_stale liefert eine veraltete gecachte Antwort, wenn das Backend fehlschlägt oder in den Timeout läuft — mehr Resilienz. Vorsicht: keine nutzer- oder authentifizierungsbezogenen Inhalte cachen.
http {
fastcgi_cache_path /var/cache/nginx/php
levels=1:2
keys_zone=phpcache:100m
max_size=1g
inactive=60m;
server {
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_cache phpcache;
fastcgi_cache_valid 200 10m;
fastcgi_cache_key $scheme$host$request_uri;
fastcgi_cache_use_stale error timeout invalid_header;
}
}
}FastCGI-Buffers
Buffers halten die PHP-Antwort, bevor sie an den Client geht. Kleine Buffer veranlassen nginx, bei großen Antworten auf Platte zu schreiben (langsam). Bei 'upstream sent too big header'-Fehlern fastcgi_buffer_size erhöhen. Bei großen API-Antworten größere/weniger Buffer verwenden.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
# buffer settings
fastcgi_buffering on;
fastcgi_buffer_size 16k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;
# for large responses (e.g., PHP generating big JSON)
fastcgi_buffers 64 16k;
fastcgi_buffer_size 32k;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}FastCGI-Timeouts
fastcgi_read_timeout ist die Zeit, die nginx auf die PHP-Ausgabe wartet. Langlebige Skripte (Datenimporte, Berichte, AI-Aufrufe) brauchen höhere Werte. Sicherstellen, dass PHPs max_execution_time mindestens so hoch ist, sonst läuft PHP zuerst in den Timeout.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_connect_timeout 5s;
fastcgi_read_timeout 300s; # for long-running scripts
fastcgi_send_timeout 300s;
# increase for very slow PHP scripts (imports, exports, reports)
fastcgi_read_timeout 600s;
}
# also adjust max_execution_time in php.ini to match
# otherwise PHP kills the script before nginx times outtry_files mit PHP
try_files $uri $uri/ /index.php?$args ist das Standardmuster für PHP-Frameworks (WordPress, Laravel, Drupal). Es liefert echte Dateien/Verzeichnisse aus, sonst routet es zu index.php mit Query-String. $args erhält die Original-Query-Parameter.
# WordPress-style pretty URLs
server {
root /var/www/wordpress;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
# deny access to sensitive files
location ~* /wp-config.php {
deny all;
}
}WebSocket-Proxy
WebSocket-Proxy
WebSocket verlangt HTTP/1.1 plus Upgrade- und Connection-Header. Der map-Block wandelt den Upgrade-Header des Clients in den korrekten Connection-Wert um: 'upgrade' für WebSocket, 'close' für normales HTTP. Der lange read_timeout hält WebSocket-Verbindungen im Leerlauf offen.
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name ws.example.com;
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s; # 1 hour
proxy_send_timeout 3600s;
}
}Upgrade-Header
HTTP/1.1 ist für WebSocket Pflicht (HTTP/2 handhabt Multiplexing anders). Connection ließe sich hart auf 'upgrade' kodieren, aber der map-Variablen-Ansatz behandelt auch Nicht-WebSocket-Requests in derselben Location. Host durchreichen, damit das Backend den Origin-Header validieren kann.
location /ws {
proxy_pass http://backend;
# HTTP/1.1 is required for the Upgrade mechanism
proxy_http_version 1.1;
# pass the Upgrade header through
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# preserve host for origin checks on the backend
proxy_set_header Host $host;
# real client IP
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}WebSocket-Timeout
Der Standard proxy_read_timeout (60s) schließt WebSocket-Verbindungen im Leerlauf. Hoch setzen (86400s = 24h), um Verbindungen zwischen Nachrichten offen zu halten. proxy_buffering off sorgt dafür, dass Nachrichten den Client sofort erreichen, statt gebündelt zu werden.
location /ws {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# WebSocket connections are long-lived
# default 60s would close them during idle periods
proxy_read_timeout 86400s; # 24 hours
proxy_send_timeout 86400s;
# disable buffering for real-time messages
proxy_buffering off;
}Socket.io-Proxy
Socket.io startet mit HTTP-Long-Polling und wechselt dann — falls verfügbar — zu WebSocket. Beide Transporte laufen über dasselbe proxy_pass, eine Location behandelt also alles. X-Forwarded-Proto durchreichen, damit socket.io weiß, dass HTTPS vorgeschaltet ist, und korrekte URLs baut.
server {
listen 80;
server_name socket.example.com;
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 86400s;
# socket.io needs these for correct client IP and scheme
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# socket.io uses both polling (HTTP) and WebSocket transports
# both are handled by the proxy_pass aboveMehrere WebSocket-Pfade
Verschiedene WebSocket-Dienste lassen sich per Pfad an verschiedene Backends routen. Jede Location braucht dieselben Upgrade-Header. Der map-Block wird einmal auf http-Ebene definiert und geteilt. read_timeout pro Dienst tunen — Chat ist oft aktiv; Benachrichtigungen können Stunden idle sein.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
# chat application
location /ws/chat/ {
proxy_pass http://chat_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
}
# notifications service
location /ws/notify/ {
proxy_pass http://notify_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400s;
}
}WSS (Secure WebSocket)
WSS ist WebSocket über TLS. Nginx terminiert das TLS (handhabt das Zertifikat) und proxied ein klares WebSocket zum Backend. Das Backend braucht keine TLS-Konfiguration. Das ist das Standard-Produktionssetup — Browser verlangen WSS für HTTPS-Seiten (Mixed-Content-Regeln).
server {
listen 443 ssl;
server_name ws.example.com;
ssl_certificate /etc/ssl/ws.example.com.crt;
ssl_certificate_key /etc/ssl/ws.example.com.key;
location / {
proxy_pass http://backend:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 86400s;
}
}
# browser connects with wss://ws.example.com
# nginx terminates TLS, proxies plain WebSocket to the backendSicherheits-Header
X-Frame-Options
X-Frame-Options verhindert, dass deine Seite in iframes eingebettet wird, und blockiert Clickjacking-Angriffe. SAMEORIGIN erlaubt eigenen Seiten, sich selbst zu framen. Der moderne Ersatz ist CSP frame-ancestors, der flexibler ist. always stellt sicher, dass der Header auch bei Fehlern gesendet wird.
# prevent clickjacking (your site embedded in an iframe)
add_header X-Frame-Options "SAMEORIGIN" always;
# options:
# DENY - no framing at all
# SAMEORIGIN - only same-site can frame
# ALLOW-FROM - deprecated, use CSP frame-ancestors instead
# modern equivalent via Content-Security-Policy
add_header Content-Security-Policy "frame-ancestors 'self'" always;X-Content-Type-Options
nosniff sagt Browsern, dem Content-Type-Header zu vertrauen und den Inhalt nicht zu erraten. Ohne ihn könnte ein Browser ein hochgeladenes Bild als HTML ausführen, wenn es HTML-Inhalt erschnüffelt. Ein Header mit kleinem Aufwand und hohem Nutzen — immer aktivieren.
# prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;
# forces the browser to respect the declared Content-Type
# prevents XSS via uploaded files (e.g., an image containing HTML
# being executed as a script)
# related: block Adobe Flash / PDF cross-domain policies
add_header X-Permitted-Cross-Domain-Policies "none" always;Content-Security-Policy
CSP ist die mächtigste Verteidigung gegen XSS — sie listet erlaubte Quellen für Skripte, Styles, Bilder usw. auf. Mit Report-Only beginnen, um Verstöße zu finden, ohne etwas zu zerstören, dann erzwingen. 'self' heißt gleiche Herkunft; 'unsafe-inline' erlaubt Inline-Skripte/-Styles (für viele Apps nötig).
# strict CSP — restricts where resources can load from
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" always;
# report-only mode (logs violations without blocking)
add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;X-XSS-Protection
X-XSS-Protection aktivierte den eingebauten Reflected-XSS-Filter des Browsers. Moderne Browser haben dieses Feature zugunsten von CSP entfernt. mode=block verhinderte die Bereinigung (die neue Schwachstellen schaffen konnte) und blockierte die Seite einfach. Für Legacy-Browser harmlos — aber CSP ist die echte Verteidigung.
# legacy XSS auditor (older browsers)
add_header X-XSS-Protection "1; mode=block" always;
# values:
# 0 - disable the filter
# 1 - enable (sanitize)
# 1; mode=block - enable and block the page entirely
# NOTE: deprecated in modern browsers (Chrome, Edge, Safari removed it)
# CSP is the modern replacement, but this doesn't hurt to include
# for legacy browser supportReferrer-Policy
Referrer-Policy steuert, wie viel URL-Information über den Referer-Header entweicht, wenn Nutzer Links klicken. strict-origin-when-cross-origin (der Browser-Standard) sendet die volle URL für same-origin-Requests, nur die Origin für cross-origin und nichts beim Abstieg zu HTTP.
# control what the Referer header contains
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# options:
# no-referrer - never send Referer
# no-referrer-when-downgrade - default; no Referer on HTTPS->HTTP
# same-origin - only same-site
# origin - send only scheme+host
# strict-origin - origin, but not on downgrade
# origin-when-cross-origin - full for same, origin for cross
# strict-origin-when-cross-origin - recommended default
# unsafe-url - send full URL (not recommended)Permissions-Policy
Permissions-Policy erlaubt es, Browserfunktionen (Kamera, Mikrofon, Geolokalisierung usw.) zu deaktivieren, selbst wenn die Seite sie anfordert. Ein leeres () deaktiviert die Funktion vollständig. Das begrenzt den Schadensradius eines XSS — ein kompromittiertes Skript kann die Kamera nicht einschalten, wenn die Richtlinie es verbietet.
# control which browser features the page can use
# (formerly Feature-Policy)
add_header Permissions-Policy "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=()" always;
# allow only for same origin
add_header Permissions-Policy "geolocation=(self), microphone=(self)" always;
# allow for specific origins
add_header Permissions-Policy "camera=(self https://trusted.com)" always;Zugriffskontrolle
Allow/Deny nach IP
allow/deny-Regeln werden der Reihe nach ausgewertet; der erste Treffer gewinnt. Das abschließende deny all blockt alles, was nicht explizit erlaubt ist. Nützlich, um Admin-Panels auf Firmen-IPs zu beschränken. Regeln können CIDR-Bereiche oder Einzel-IPs nutzen und unterstützen IPv4 und IPv6.
location /admin {
allow 192.168.1.0/24; # internal network
allow 10.0.0.0/8; # VPN range
allow 203.0.113.5; # specific IP
deny all;
proxy_pass http://backend;
}
# rules are checked in order — first match wins
# if no rule matches, access is allowed by defaultDeny All
deny all blockt jeden; mit allow paaren ergibt sich eine Whitelist. Umgekehrt — bestimmte IPs deny, alle allow — ist eine Blacklist. Whitelists sind sicherer (standardmäßig verweigern). Ohne explizites allow/deny ist Zugriff erlaubt, also geschützte Bereiche immer mit deny all abschließen.
# deny all access to a location
location /private {
deny all;
return 403;
}
# deny specific IPs, allow everyone else
location / {
deny 192.168.1.100; # block one IP
deny 203.0.113.0/24; # block a range
allow all;
}
# deny a range, allow the rest
location /api {
deny 10.0.0.0/8;
allow all;
proxy_pass http://backend;
}Subnetz erlauben
Private IP-Bereiche (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) sind im Internet nicht routbar, ihr Erlauben schränkt den Zugang also auf interne Netze ein. Bei IPv6 ist ::1 localhost. Mit einem VPN kombinieren für sicheren Fernzugriff auf interne Tools.
# allow only local/private networks
location /internal {
allow 192.168.0.0/16; # private class B
allow 172.16.0.0/12; # private class B range
allow 10.0.0.0/8; # private class A
deny all;
root /var/www/internal;
}
# IPv6
location / {
allow 2001:db8::/32; # example IPv6 range
allow ::1; # IPv6 localhost
deny all;
}Geo-Modul
geo ist für IP-Lookups über einen Radix-Baum optimiert — weit schneller als eine lange allow/deny-Liste. Es setzt eine Variable (hier $allowed_ip) basierend auf der Client-IP. Die 'ranges'-Form unterstützt Start-End-IP-Bereiche. Die Variable in if() oder map für flexible Zugriffskontrolle verwenden.
# map IPs to values (binary search, very fast)
geo $allowed_ip {
default 0;
192.168.0.0/24 1;
10.0.0.0/8 1;
203.0.113.5 1;
}
server {
location /admin {
if ($allowed_ip = 0) {
return 403;
}
proxy_pass http://backend;
}
}
# geo with IP ranges (uses 'ranges' directive)
geo $country_code {
ranges;
default ZZ;
10.0.0.0-10.255.255.255 US;
}Limit nach IP (limit_req)
limit_req_zone definiert eine Rate pro IP über $binary_remote_addr (kompakt). limit_req wendet sie an. burst erlaubt kurze Spitzen (bis zu 20 einreihen). nodelay liefert die Spitze sofort statt zu drosseln — gut für APIs. Ohne nodelay werden überzählige Requests verzögert, nicht abgewiesen.
http {
# define rate limit zone (10 requests/sec per IP)
limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;
server {
location /api/ {
limit_req zone=mylimit burst=20 nodelay;
proxy_pass http://backend;
}
}
}
# $binary_remote_addr uses binary form (more memory-efficient)
# 10m zone stores ~160,000 unique IP addresses
# rate=10r/s: 10 requests per second per IP
# burst=20: allow 20 requests to queue
# nodelay: serve the burst immediately (no artificial delay)Länderblockierung (GeoIP)
Das GeoIP-Modul mappt Client-IPs auf Ländercodes über eine MaxMind-Datenbank. Kombiniert mit map lassen sich ganze Länder blockieren oder erlauben. Hinweis: MaxMinds kostenloses GeoLite2 erfordert das Drittanbieter-Modul maxminddb (das alte GeoIP-Modul nutzt das ältere .dat-Format). Die Genauigkeit ist nicht 100 % — nur für grobe Filterung.
# requires the GeoIP module and a MaxMind database
geoip_country /usr/share/GeoIP/GeoIP.dat;
map $geoip_country_code $allowed_country {
default yes;
CN no;
RU no;
KP no;
}
server {
location / {
if ($allowed_country = no) {
return 403;
}
proxy_pass http://backend;
}
}
# GeoIP2 (maxminddb module) for the newer GeoLite2 format
# maxminddb /etc/nginx/geoip2/GeoLite2-Country.mmdb;
# $geoip2_country_code source=$remote_addr country iso_code;Authentifizierung
Basic-Auth einrichten
auth_basic löst den nativen Nutzername/Passwort-Dialog des Browsers aus. Der Realm-String ('Admin Area') wird dem Nutzer angezeigt. auth_basic_user_file zeigt auf eine htpasswd-Datei. auth_basic off deaktiviert die Auth in einer Unter-Location, die öffentlich bleiben soll.
location /admin {
auth_basic "Admin Area";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://backend;
}
location /public {
# disable auth inherited from parent location
auth_basic off;
}
# create users with htpasswd (apache2-utils / httpd-tools):
# htpasswd -c /etc/nginx/.htpasswd user1 (create file)
# htpasswd /etc/nginx/.htpasswd user2 (append, no -c)htpasswd-Datei
Die htpasswd-Datei speichert Nutzername:Hash-Paare. bcrypt (-B) ist der stärkste Hash; MD5 (-m, Standard) akzeptabel; SHA1 (-s) schwach; PLAIN unsicher. Dateiberechtigungen einschränken, sodass nur nginx sie lesen kann — die Datei enthält Passwort-Hashes, die nicht entweichen dürfen.
# /etc/nginx/.htpasswd format:
# user1:$apr1$qHR...$hashedpassword
# user2:{PLAIN}plaintext (insecure!)
# user3:{SHA}base64sha1hash
# generate with htpasswd:
# -c create new file (overwrites!)
# -B bcrypt (most secure, recommended)
# -m MD5 (default, APR1)
# -s SHA1
# bcrypt (recommended)
# htpasswd -B /etc/nginx/.htpasswd user1
# protect the file permissions
chown root:nginx /etc/nginx/.htpasswd
chmod 640 /etc/nginx/.htpasswdAuth für bestimmte Location
auth_basic wird an verschachtelte Locations vererbt. Um einen Unterpfad öffentlich zu machen, auth_basic off setzen. Nützlich, wenn fast ganz /admin Auth braucht, aber /admin/health (ein Health-Check-Endpunkt) ohne Anmeldeinformationen für Monitoring-Tools erreichbar sein soll.
server {
# no auth at server level
location /admin {
auth_basic "Admin";
auth_basic_user_file /etc/nginx/.htpasswd;
}
location /admin/api {
# inherits auth from /admin
proxy_pass http://admin_api;
}
location /admin/public {
# explicitly disable inherited auth
auth_basic off;
proxy_pass http://public_api;
}
}Allow/Deny mit Auth
satisfy any heißt: Entweder der IP-Check ODER die Authentifizierung genügt für Zugang — bequem für interne Nutzer (ohne Passwort), während externe weiterhin ein Passwort brauchen. satisfy all verlangt beides — die restriktivste Option, für höchstsensible Bereiche.
# satisfy: ALL (default) or ANY
location / {
# allow corporate IPs without password
# require password from outside the corporate network
satisfy any;
allow 192.168.0.0/16;
deny all;
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://backend;
}
# satisfy all: must pass BOTH IP check AND auth
# satisfy any: pass EITHER IP check OR authAuth-Request-Modul
auth_request sendet vor dem Haupt-Request einen internen Subrequest an einen Auth-Dienst. Der Dienst validiert das Token (JWT, Session-Cookie usw.) und liefert 2xx (erlauben) oder 401/403 (ablehnen). internal verhindert externen Zugriff auf /auth. So ist die Auth von deiner App entkoppelt.
# delegate authentication to a subrequest (OAuth, JWT, etc.)
location / {
auth_request /auth;
proxy_pass http://backend;
}
location = /auth {
internal; # can't be called directly
proxy_pass http://auth-service/validate;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
# auth-service returns:
# 2xx -> allow (continue to backend)
# 401/403 -> deny (return to client)
# other -> errorJWT-Auth
JWT-Validierung lässt sich prozess-intern mit njs (nginx JavaScript-Modul) bei niedriger Latenz erledigen oder an einen externen Dienst via auth_request delegieren. njs führt eine Untermenge von JavaScript innerhalb von nginx aus — schnell, aber begrenzt. Der auth_request-Ansatz ist flexibler und sprachagnostisch.
# requires the njs (nginx JavaScript) module
js_import auth.js;
location /api/ {
js_content auth.validateJwt;
proxy_pass http://backend;
}
# auth.js defines the validateJwt function:
# function validateJwt(r) {
# var token = r.headersIn.Authorization;
# if (!token || !verifyJwt(token)) {
# r.return(401);
# return;
# }
# }
# alternative: use auth_request with an external JWT validator service
# more portable than njs, but adds a network hop per requestLogging
Access Log
access_log zeichnet jeden Request auf. log_format legt fest, welche Felder erfasst werden. Das 'combined'-Standardformat ist Apache-kompatibel. Bei stark frequentierten Seiten reduziert buffer+flush die Platten-I/O durch gebündelte Schreibvorgänge. syslog sendet Logs an einen zentralen Server zur Aggregation.
http {
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
access_log /var/log/nginx/access.log main;
# or use the built-in 'combined' format
access_log /var/log/nginx/access.log combined;
}
# disable access log
access_log off;
# log to syslog
access_log syslog:server=localhost,facility=local7 main;
# buffer writes (reduce I/O)
access_log /var/log/nginx/access.log main buffer=32k flush=5s;Error Log
error_log erfasst nginx-Fehler und Upstream-Probleme. Das Level filtert die Schwere — warn ist ein guter Standard. debug ist sehr geschwätzig (nur zur Fehleranalyse) und verlangt einen Debug-Build. memory: puffert Logs im RAM — nützlich zum Diagnostizieren von Startup-Problemen, die Platten-Logging nicht erfassen kann.
# error log location and severity level
error_log /var/log/nginx/error.log warn;
# levels (low to high severity):
# debug, info, notice, warn, error, crit, alert, emerg
# debug requires nginx built with --with-debug
error_log /var/log/nginx/error.log debug;
# log to memory (for debugging, lost on restart)
error_log memory:32m debug;
# disable (NOT recommended — hides real errors)
error_log /dev/null crit;Log-Formate
Eigene Log-Formate erfassen, was dir wichtig ist. request_time ist die Gesamtverarbeitungszeit; upstream_response_time isoliert das Backend. escape=json erzeugt gültiges JSON für Log-Aggregatoren (ELK, Loki, Datadog). Ohne escape=json können Sonderzeichen in URIs das JSON-Parsing brechen.
http {
# combined (Apache-compatible, the default)
log_format combined '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
# main with upstream timing
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'rt=$request_time uct="$upstream_connect_time" '
'urt="$upstream_response_time"';
# JSON format for log aggregation (ELK, Loki, etc.)
log_format json escape=json
'{"time":"$time_iso8601",'
'"remote":"$remote_addr",'
'"method":"$request_method",'
'"uri":"$request_uri",'
'"status":$status,'
'"bytes":$body_bytes_sent,'
'"ua":"$http_user_agent"}';
}Bedingtes Logging
Der if=-Parameter loggt bedingt auf Basis einer Variable. map $status erlaubt, nur Fehler (4xx/5xx) zu loggen — weniger Rauschen und Plattennutzung auf stark frequentierten Seiten. Die Variable muss 0/leer sein, um Logging zu überspringen, und ungleich 0, um zu loggen.
http {
# don't log successful 2xx/3xx, only errors
map $status $loggable {
~^[23] 0;
default 1;
}
server {
access_log /var/log/nginx/access.log main if=$loggable;
}
}
# skip logging for static assets
map $request_uri $log_skip {
default 1;
~*\.(jpg|png|gif|css|js)$ 0;
}
access_log /var/log/nginx/access.log main if=$log_skip;Log-Rotation
logrotate benennt alte Logs um und komprimiert sie. postrotate sendet USR1 an nginx, das seine Logdateien neu öffnet — ohne das schreibt nginx weiter in die umbenannte Datei. sharedscripts führt postrotate einmal (nicht pro Datei) aus. delaycompress komprimiert erst bei der zweiten Rotation, das jüngste Log bleibt unkomprimiert.
# logrotate config: /etc/logrotate.d/nginx
/var/log/nginx/*.log {
daily
missingok
rotate 14
compress
delaycompress
notifempty
create 0640 www-data adm
sharedscripts
postrotate
if [ -f /var/run/nginx.pid ]; then
kill -USR1 $(cat /var/run/nginx.pid)
fi
endscript
}
# USR1 signal tells nginx to reopen log files
# without dropping connections
# nginx -s reopen does the same thingLogging deaktivieren
access_log für Health-Checks und statische Assets zu deaktivieren senkt Log-Rauschen und Platten-I/O deutlich. log_not_found off unterdrückt 404-Logeinträge (praktisch für favicon.ico). error_log immer mindestens auf 'error' aktiviert halten — stille Fehlschläge sind schwer zu diagnostizieren.
# disable access log entirely
access_log off;
# disable for a specific location
location /health {
access_log off;
return 200 "ok\n";
}
# disable for static assets
location ~* \.(jpg|png|gif|ico|css|js)$ {
access_log off;
log_not_found off;
}
# only log errors (reduce error log verbosity)
error_log /var/log/nginx/error.log error;Rate Limiting
limit_req_zone
limit_req_zone definiert ein Ratelimit, verschlüsselt über eine Variable (meist die Client-IP). Die Zonengröße (10m) bestimmt, wie viele eindeutige Schlüssel verfolgt werden können. rate ist die erlaubte Request-Frequenz. Zonen im http-Kontext definieren und im location-Kontext mit limit_req anwenden.
http {
# 10 requests per second per IP
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
# 1 request per second per IP (for login)
limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
# 100 requests per minute per IP
limit_req_zone $binary_remote_addr zone=general:10m rate=100r/m;
}
# $binary_remote_addr uses binary form (more memory-efficient than text)
# 10m zone stores ~160,000 unique IP addresses
# rate can be per second (r/s) or per minute (r/m)limit_req
limit_req wendet eine Zone auf eine Location an. burst erlaubt kurze Spitzen (bis zu N überzählige Requests einreihen). nodelay bedient die Spitze mit voller Geschwindigkeit, statt sie zu strecken — gut für APIs, wo Latenz zählt. Ohne burst wird jeder Request oberhalb der Rate sofort abgewiesen.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
proxy_pass http://backend;
}
location /login {
limit_req zone=api burst=5 nodelay;
proxy_pass http://backend;
}
}
}
# burst: max number of requests allowed to queue
# nodelay: serve the burst immediately (no artificial throttling)
# without burst: requests exceeding the rate get 503 immediatelylimit_conn
limit_conn begrenzt gleichzeitige Verbindungen, nicht die Request-Rate. Nützlich, um zu verhindern, dass eine einzelne IP hunderte gleichzeitige Downloads öffnet. Kombiniert mit limit_req (Rate) gibt es sowohl Spitzen- als auch Nebenläufigkeitsschutz. limit_conn_zone folgt demselben zonenbasierten Schlüsselmuster.
http {
# limit concurrent connections per IP
limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;
# limit total connections per server name
limit_conn_zone $server_name zone=conn_per_server:10m;
server {
limit_conn conn_per_ip 10;
limit_conn conn_per_server 1000;
location /download {
limit_conn conn_per_ip 1; # one download at a time per IP
proxy_pass http://backend;
}
}
}Burst-Queue
burst ist die Queue-Größe für überzählige Requests. nodelay bedient die ganze Spitze sofort (gut für APIs). delay=N bedient N sofort und drosselt den Rest auf die konfigurierte Rate (glatter). Ohne nodelay werden alle überzähligen Requests verzögert, bis sie der Rate entsprechen, und die Last gleichmäßig verteilt.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
# burst=20: allow 20 requests to queue
# nodelay: serve them immediately (no artificial delay)
limit_req zone=api burst=20 nodelay;
# delay: first 10 immediate, next 10 delayed, rest rejected
limit_req zone=api burst=20 delay=10;
proxy_pass http://backend;
}
}
}
# without burst: requests over rate get 503 immediately
# with burst: excess requests queue (default delayed)
# nodelay: queue served at full speed (allows spikes)
# delay=N: first N immediate, rest throttled to the rateRatelimit nach IP
Getrennte Zonen pro Endpunkt-Typ mit passenden Raten definieren. API-Endpunkte vertragen höhere Raten; Auth-Endpunkte (Login, Passwort-Reset) brauchen strenge Limits gegen Brute Force; Uploads sehr niedrige Raten gegen Missbrauch. burst gibt eine kleine Toleranz für legitime Spitzen.
http {
# different limits for different endpoints
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=auth:10m rate=1r/s;
limit_req_zone $binary_remote_addr zone=upload:10m rate=2r/m;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
}
location /login {
limit_req zone=auth burst=5 nodelay;
}
location /upload {
limit_req zone=upload burst=3 nodelay;
client_max_body_size 100M;
}
}
}Eigene Ratelimit-Antwort
Standardmäßig erhalten ratelimitierte Requests 503 (Service Unavailable). 429 (Too Many Requests) ist semantisch korrekter und wird von den meisten APIs erwartet. Mit error_page einen JSON-Body zurückgeben, der das Limit erklärt. Einen Retry-After-Header einschließen, damit Clients wissen, wann sie es erneut versuchen.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_status 429; # default is 503
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
# custom error response
error_page 429 = @rate_limited;
}
location @rate_limited {
default_type application/json;
return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
}
}
}
# also available: limit_conn_status 429;Performance-Tuning
worker_processes
worker_processes sollte der CPU-Kernzahl entsprechen — auto macht das automatisch. Jeder Worker ist ein single-threaded-Prozess, der viele Verbindungen über die Event-Loop behandelt. worker_cpu_affinity heftet Worker an bestimmte Kerne und verbessert die Cache-Lokalität. Auto-Affinity überlässt es dem OS-Scheduler.
# main context
worker_processes auto; # one per CPU core (recommended)
# or set an explicit count
worker_processes 4;
# each worker handles connections independently
# 'auto' uses the number of available CPU cores
# CPU affinity (pin workers to specific cores)
worker_processes auto;
worker_cpu_affinity auto;
# or manual bitmask (one mask per worker)
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;worker_connections
worker_connections gilt pro Worker; die Gesamtkapazität ist worker_processes * worker_connections. Begrenzt auch das OS-File-Descriptor-Limit (worker_rlimit_nofile). Beide Limits erhöhen — das von nginx und das des OS (limits.conf oder systemd-LimitNOFILE). multi_accept nimmt alle wartenden Verbindungen auf einmal.
events {
# connections per worker process
worker_connections 4096;
# accept multiple connections at once under high load
multi_accept on;
}
# total max connections = worker_processes * worker_connections
# but also bounded by worker_rlimit_nofile (file descriptor limit)
# main context — raise the FD limit
worker_rlimit_nofile 65535;
# also raise system limits (outside nginx):
# /etc/security/limits.conf:
# * soft nofile 65535
# * hard nofile 65535keepalive_timeout
Client-Keepalive wiederverwendet Verbindungen für mehrere Requests und senkt die Latenz. keepalive_timeout ist, wie lange eine ungenutzte Verbindung offen bleibt. Upstream-Keepalive (die keepalive-Direktive in upstream) cache-Verbindungen zu Backends — Connection auf leer setzen, damit nginx kein 'close' sendet.
http {
# keep-alive timeout (client side)
keepalive_timeout 65s;
keepalive_requests 1000; # max requests per connection
# upstream keepalive (reuse connections to backends)
upstream backend {
server 10.0.0.1:8080;
keepalive 32; # cache of 32 idle upstream connections
}
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection ""; # clear to enable keepalive
}
}sendfile & tcp_nopush
sendfile nutzt einen Zero-Copy-Pfad auf Kernel-Ebene, um Dateien zu senden, und umgeht User-Space-Buffer — viel schneller für statische Dateien. tcp_nopush ergänzt sendfile und sendet Header und Dateianfang in einem Paket. tcp_nodelay deaktiviert Nagle für niedrige Latenz. aio threads verlagert Platten-I/O aus der Event-Loop.
http {
# use kernel sendfile() for static files (zero-copy)
sendfile on;
# send headers + start of file in one TCP packet
tcp_nopush on;
# disable Nagle's algorithm (send small packets immediately)
tcp_nodelay on;
# for static file serving
location /static/ {
sendfile on;
tcp_nopush on;
aio threads; # asynchronous I/O via thread pool
root /var/www;
}
}
# sendfile: zero-copy file transfer (kernel space, no user-space copy)
# tcp_nopush: coalesce headers + file data into one packet
# tcp_nodelay: don't wait to batch small packets (low latency)Buffer-Größen
Buffer an den eigenen Traffic anpassen. client_max_body_size begrenzt die Upload-Größe (Standard 1M — zu klein für Dateiuploads). Proxy-/FastCGI-Buffer halten Upstream-Antworten; zu kleine Buffer laufen auf Platte über. large_client_header_buffers behandeln lange URLs/Cookies. Auf 'buffer overflow'-Fehler achten.
http {
# client body buffer (in-memory before writing to disk)
client_body_buffer_size 16k;
client_max_body_size 50m;
# client header buffers
client_header_buffer_size 1k;
large_client_header_buffers 4 8k;
# proxy buffers (responses from upstream)
proxy_buffer_size 4k;
proxy_buffers 8 4k;
proxy_busy_buffers_size 16k;
# fastcgi buffers (responses from PHP-FPM, etc.)
fastcgi_buffer_size 4k;
fastcgi_buffers 8 4k;
}
# if a request body exceeds client_body_buffer_size,
# nginx writes it to a temp file (slower)Open-File-Cache
open_file_cache cache-t Datei-Deskriptoren und Metadaten und vermeidet wiederholte open()/stat()-Syscalls für beliebte Dateien. Das beschleunigt das Ausliefern statischer Dateien deutlich. valid steuert, wie oft nginx die Datei neu prüft (erwischt Updates). min_uses vermeidet das Cachen von Einmal-Requests. Auch Cache-Fehler cachen, um wiederholte fehlgeschlagene Opens zu vermeiden.
http {
open_file_cache max=10000 inactive=20s;
open_file_cache_valid 30s;
open_file_cache_min_uses 2;
open_file_cache_errors on;
server {
root /var/www/html;
location / {
open_file_cache max=10000 inactive=20s;
open_file_cache_valid 30s;
try_files $uri $uri/ =404;
}
}
}
# caches file descriptors, sizes, modification times
# reduces stat() and open() syscalls for popular files
# max=10000: cache up to 10000 files
# inactive=20s: remove if not accessed in 20 seconds
# min_uses=2: only cache files accessed 2+ times
# valid=30s: re-validate cache every 30sDocker-Deployment
Nginx in Docker
Das offizielle nginx-Image liefert standardmäßig /usr/share/nginx/html aus und liest die Konfiguration aus /etc/nginx. Konfiguration und Inhalte als Volumes mounten. :ro (read-only) verhindert, dass der Container Host-Dateien verändert. nginx -s reload übernimmt Konfigurationsänderungen, ohne den Container neu zu erzeugen.
# run the official nginx image
docker run -d --name nginx \
-p 80:80 -p 443:443 \
-v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
-v /var/www/html:/usr/share/nginx/html:ro \
-v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \
nginx:latest
# interactive shell into the running container
docker exec -it nginx sh
# reload config without restarting the container
docker exec nginx nginx -s reload
# view logs
docker logs nginx
docker logs -f nginxDocker Compose
Docker Compose orchestriert nginx mit seinen Backends. expose macht einen Port für verbundene Dienste verfügbar (nicht für den Host). depends_on stellt sicher, dass das Backend zuerst startet. restart: unless-stopped übersteht Reboots, respektiert aber manuelles Stoppen. Logs mit Schreibrechten mounten (ohne :ro), damit nginx sie schreiben kann.
version: '3.8'
services:
nginx:
image: nginx:latest
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./conf.d:/etc/nginx/conf.d:ro
- ./html:/usr/share/nginx/html:ro
- ./certs:/etc/nginx/certs:ro
- ./logs:/var/log/nginx
depends_on:
- backend
restart: unless-stopped
backend:
image: myapp:latest
expose:
- "3000"Eigenes nginx-Image
Konfiguration ins Image backen macht Deployments unveränderlich und reproduzierbar — keine Laufzeit-Volume-Mounts nötig. Die Alpine-Variante hält das Image winzig (~7 MB Basis). Ideal für Kubernetes oder CI/CD, wo man ein in sich geschlossenes Artefakt will. Zur Aktualisierung der Konfiguration neu bauen.
# Dockerfile
FROM nginx:alpine
# copy custom config
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/
# copy static files
COPY html/ /usr/share/nginx/html/
# copy SSL certificates
COPY certs/ /etc/nginx/certs/
# build and run
# docker build -t mynginx .
# docker run -d -p 80:80 mynginx
# alpine is ~7MB; the image stays small
# bake config in for immutable deploymentsVolume-Mounts
Volume-Mounts erlauben Iterationen an der Konfiguration, ohne das Image neu zu bauen — ideal für die Entwicklung. Ein Verzeichnis zu mounten ist robust; eine einzelne Datei zu mounten kann brechen, wenn die Host-Datei fehlt (Docker erzeugt dann ein Verzeichnis). Benannte Volumes überstehen Container-Neuerzeugungen und werden von Docker verwaltet.
# mount config and content as volumes (dev workflow)
docker run -d --name nginx \
-p 80:80 \
-v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
-v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
-v $(pwd)/html:/usr/share/nginx/html:ro \
-v $(pwd)/logs:/var/log/nginx \
nginx:alpine
# read-only mounts (:ro) for security
# logs need write access (no :ro)
# use named volumes for persistent data:
# -v nginx_logs:/var/log/nginx
# IMPORTANT: mounting a single file (nginx.conf) requires
# the file to exist on the host, or Docker creates a directoryReverse-Proxy in Docker
In Docker Compose lösen sich Dienste gegenseitig über den Dienstnamen auf (app1, app2). nginx' upstream kann diese Namen direkt referenzieren — keine IP-Adressen nötig. So wird nginx ein mächtiger Load Balancer für Container-Apps. Das Standard-Compose-Netzwerk nutzen oder für Isolation ein eigenes definieren.
# nginx as reverse proxy for other containers
version: '3.8'
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- app1
- app2
restart: unless-stopped
app1:
image: myapp:latest
app2:
image: myapp:latest
# nginx.conf:
# upstream apps {
# server app1:3000;
# server app2:3000;
# }
# server {
# listen 80;
# location / { proxy_pass http://apps; }
# }Health Check
Health Checks zeigen Docker (und Orchestratoren wie Swarm), ob nginx wirklich ausliefert, nicht nur läuft. wget --spider prüft den HTTP-Status, ohne den Body zu laden. start_period verzögert den ersten Check, damit nginx booten kann. In Kubernetes stattdessen eine Readiness-/Liveness-Probe statt des Docker-HEALTHCHECK verwenden.
# Dockerfile with a health check
FROM nginx:alpine
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1
COPY nginx.conf /etc/nginx/nginx.conf
# docker-compose health check
version: '3.8'
services:
nginx:
image: nginx:alpine
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
# start_period gives nginx time to boot before checking
# a failed health check marks the container unhealthyVerwandte Nginx-Snippets
Copy-paste ready code for common tasks.
Server Block
Configure a virtual host with root, index, and try_files.
Reverse Proxy
Forward requests to upstream HTTP services.
Load Balancing
Distribute traffic across multiple upstream servers.
HTTPS & SSL
Terminate TLS with certificates and HTTP/2.
Location Rules
Match request URIs with prefix, regex, and exact locations.
Rewrite & Redirect
Rewrite URIs and issue HTTP redirects.
Gzip Compression
Compress text responses to reduce bandwidth.
Proxy Caching
Cache upstream responses to reduce backend load.
Was this helpful?