SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

nginx Reverse Proxy konfigurieren: Anleitung für Ubuntu

Konfigurieren Sie einen nginx-Reverse-Proxy Zeile für Zeile: proxy_pass, vier wichtige Header, WebSockets, abschließende Slashes und Uploads unter Ubuntu 24.04.

Was eine nginx-Reverse-Proxy-Konfiguration bewirkt

Ein nginx-Reverse-Proxy nimmt die auf Port 80 und Port 443 eingehenden Anfragen entgegen und leitet jede davon an eine Anwendung weiter, die bereits auf einem lokalen Port lauscht. Anschließend gibt er die Antwort dieser Anwendung an den Browser zurück. Die Konfiguration besteht aus einem einzigen server-Block, und dieser Block ist kurz. Der größte Teil der Schwierigkeit steckt in fünf oder sechs Zeilen. Sie teilen der Anwendung mit, wer der tatsächliche Client war und welches Protokoll dieser Client verwendet hat.

Alle folgenden Schritte werden unter Ubuntu 24.04 von Grund auf mit dem nginx-Paket der Distribution aufgebaut. Ausgangspunkt ist eine Anwendung, die bereits auf 127.0.0.1:3000 antwortet. Wenn Sie sich noch nicht für einen Proxy entschieden haben, lesen Sie zuerst wie nginx im Vergleich zu Caddy und Traefik abschneidet. Danach sehen Sie Zeile für Zeile, wie die nginx-Lösung aussieht.

Führen Sie diese Konfigurationen auf Ihrem eigenen Server aus. Prüfen Sie jede Änderung vor dem Neuladen mit sudo nginx -t und lesen Sie die ausgegebene Meldung.

Wo nginx seine Konfiguration unter Ubuntu speichert

sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/

Die Hauptdatei ist /etc/nginx/nginx.conf. Sie legt globale Optionen in einem http { }-Block fest und bindet anschließend zwei Verzeichnisse ein: /etc/nginx/conf.d/*.conf und /etc/nginx/sites-enabled/*. Unter Ubuntu und Debian erstellen Sie für jede Site eine eigene Datei in /etc/nginx/sites-available/ und aktivieren sie mit einem Symlink nach /etc/nginx/sites-enabled/. Wenn Sie den Symlink löschen, wird die Site deaktiviert, die Datei bleibt jedoch erhalten.

Zwei später verwendete Direktiven funktionieren nur im http-Kontext, niemals innerhalb eines server-Blocks: map und upstream. Legen Sie sie in einer eigenen Datei unter /etc/nginx/conf.d/ ab, weil dieses Verzeichnis auf der http-Ebene eingebunden wird.

Das Paket liefert eine aktivierte Site namens default mit. Sie ist als default_server gekennzeichnet. Das bedeutet, dass sie jede Anfrage beantwortet, deren Host-Header keinem server_name in Ihrer Konfiguration entspricht. Solange sie aktiviert ist, landet eine Anfrage mit einem unbekannten Hostnamen auf dieser Site statt bei Ihrer Anwendung. Entfernen Sie den Symlink, sobald Ihre eigene Site funktioniert.

sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Der kleinste Server-Block für das Proxying einer Anwendung

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

Speichern Sie dies als /etc/nginx/sites-available/app.example.com, aktivieren Sie es anschließend und laden Sie die Konfiguration neu.

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/

listen 80; bindet IPv4 und listen [::]:80; bindet IPv6. Lassen Sie die zweite Zeile weg, wird jede IPv6-Verbindung zu Ihrem Server abgelehnt. Ein Dual-Stack-Browser, dessen DNS-Abfrage (Domain Name System) einen AAAA-Record zurückgibt, greift meist auf IPv4 zurück und kaschiert das Problem. Ein reiner IPv6-Besucher oder ein Client, der nur die erste erhaltene Adresse versucht, erhält jedoch eine Verbindungsablehnung, während alle Nutzer über IPv4 eine funktionierende Seite sehen. Der Fehlerbericht, den Sie erhalten, lautet dann: "Bei mir funktioniert es".

server_name wird mit dem Host-Header abgeglichen, den der Browser sendet. Mehrere Namen können durch Leerzeichen getrennt aufgelistet werden. Wenn kein Block übereinstimmt, verwendet nginx den Block, der default_server ist; deshalb musste die Standard-Seite entfernt werden.

location / ist ein Präfix-Abgleich für den Anfragepfad, und / passt auf jeden Pfad. proxy_pass ist die Adresse, zu der nginx eine Verbindung aufbaut. Binden Sie die Anwendung an 127.0.0.1, damit der einzige Zugang über nginx erfolgt. Wenn die Anwendung in einem Container läuft, veröffentlichen Sie sie als 127.0.0.1:3000:3000 und nicht als 3000:3000, da Docker eigene Regeln schreibt und Ports unter Umgehung von ufw veröffentlicht. Ein direkt veröffentlichter Port ist somit unabhängig von den ufw-Einstellungen aus dem Internet erreichbar. Docker dokumentiert seine DOCKER-USER-Chain als Ort, um diesen Datenverkehr zu filtern, aber die Bindung an 127.0.0.1 ist die einfachere Lösung.

Die Zeile curl sendet den korrekten Host-Header vom Server selbst, sodass Sie den Block testen können, bevor DNS auf irgendein Ziel verweist.

Was nginx standardmäßig an den Upstream sendet

proxy_pass blendet für Ihre Anwendung vier Punkte aus.

Das Paket nginx 1.24.0, das Ubuntu 24.04 ausliefert, verwendet standardmäßig HTTP/1.0 für die Verbindung zum Backend und sendet Connection: close. Dadurch wird für jede Anfrage eine neue Upstream-Verbindung geöffnet, und ein Protokoll-Upgrade ist nicht möglich. nginx 1.29.7, veröffentlicht im März 2026, hat diese Standardwerte geändert: Ab dieser Version verwendet nginx HTTP/1.1 zum Upstream, sendet keinen Connection-Header und verwendet wiederverwendbare Verbindungen, statt für jede Anfrage eine neue Verbindung zu öffnen. Auch dann benötigt ein WebSocket-Upgrade noch die weiter unten gezeigten Header.

Der Host-Header wird in den Wert aus proxy_pass umgeschrieben, also in 127.0.0.1:3000. Eine Anwendung, die absolute Links aus Host erstellt, erzeugt dadurch Links, die niemand außerhalb des Servers öffnen kann.

Die Verbindung zur Anwendung kommt von nginx. Daher sieht die Anwendung als Client-Adresse 127.0.0.1. Jede Protokollzeile und jedes Rate-Limit innerhalb der Anwendung erfasst dann den Proxy statt des Besuchers.

Die Anwendung kann nicht erkennen, dass der Browser HTTPS verwendet hat, weil die empfangene Verbindung unverschlüsseltes HTTP über eine Loopback-Adresse verwendet.

Vier Zeilen beheben all diese Probleme.

Die vier Header und welche Informationen jeder davon an das Backend übermittelt

location / {
    proxy_pass http://127.0.0.1:3000;

    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;
}

Host enthält den Namen, den der Besucher eingegeben hat. $host ist der Name aus der Anfrage, ohne Port und mit Kleinschreibung. Setzen Sie diesen Header, damit Ihre Anwendung korrekte absolute URLs erzeugt, zum Beispiel die Weiterleitung nach einer Anmeldung oder den Link in einer E-Mail zum Zurücksetzen des Passworts. Fehlt der Header, verwendet die Anwendung 127.0.0.1:3000 als eigenen Namen. Das standardmäßige proxy_redirect von nginx schreibt einen Location- oder Refresh-Header, der auf die proxy_pass-Adresse verweist, um. Deshalb führt eine einfache Weiterleitung nach der Anmeldung normalerweise weiterhin zum richtigen Ziel. Absolute URLs, die die Anwendung in ihre Seiten und E-Mails schreibt, etwa der Link zum Zurücksetzen des Passworts, verweisen jedoch auf 127.0.0.1:3000, eine Adresse, die der Browser des Besuchers nicht öffnen kann. Wenn Ihre Anwendung auch den Port benötigt, weil Sie sie auf 8080 bereitstellen, verwenden Sie $http_host. Dieser Header entspricht genau dem, den der Client gesendet hat.

X-Real-IP enthält einen Wert: $remote_addr, die Adresse, von der nginx die Verbindung angenommen hat. Anwendungen lesen diesen Header für ihre eigenen Access-Logs und ihre eigene Ratenbegrenzung.

X-Forwarded-For enthält eine Liste. $proxy_add_x_forwarded_for fügt $remote_addr an den Wert an, den der Client bereits in diesem Header angegeben hat. Der Wert ist daher durch Kommas getrennt, und der von nginx hinzugefügte Eintrag steht an letzter Stelle. Dieses Detail entscheidet darüber, ob dem Header vertraut werden kann: Ein Client kann jeden beliebigen X-Forwarded-For senden. Eine Anwendung, die den ersten Eintrag liest, kann daher jede beliebige Adresse erhalten. Wenn nginx der Edge-Server ist, schreiben Sie stattdessen $remote_addr und verwerfen Sie die Version des Clients. Wenn ein CDN oder ein anderer Proxy vorgeschaltet ist, verwenden Sie set_real_ip_from und real_ip_header aus dem realip-Modul, damit $remote_addr selbst zur tatsächlichen Client-Adresse wird.

X-Forwarded-Proto enthält http oder https. Frameworks lesen diesen Header, um zu entscheiden, ob Cookies als Secure markiert werden und ob eine Weiterleitung auf HTTPS erzwungen werden soll. Lassen Sie ihn auf einer TLS-Site weg, erkennt eine auf HTTPS erzwungene Anwendung http. Sie antwortet mit einer Weiterleitung auf die HTTPS-Adresse, erhält die nächste Anfrage über nginx, sieht weiterhin http und leitet erneut weiter. Der Browser bricht daraufhin ab und zeigt ERR_TOO_MANY_REDIRECTS an.

Wenn Sie diese vier Zeilen in jedem Location-Block wiederholen, laufen sie mit der Zeit auseinander. Legen Sie sie in einer Datei ab und binden Sie diese ein.

# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;
}

Bei der Vererbung gibt es hier eine wichtige Einschränkung. Eine Location übernimmt die proxy_set_header-Direktiven aus ihrem Server-Block nur dann, wenn sie selbst keine entsprechenden Direktiven definiert. Fügen Sie innerhalb der Location ein proxy_set_header hinzu, werden alle auf Server-Ebene definierten Header für diese Location verworfen. Halten Sie daher alle Header auf einer einzigen Ebene oder include-en Sie das Snippet in jeder Location ein, die als Proxy weiterleitet.

Warum verbindet sich meine WebSocket-Anwendung und trennt die Verbindung anschließend?

Das liegt daran, dass die Standardeinstellungen das Upgrade verhindern und das standardmäßige Lese-Timeout einen inaktiven Tunnel nach 60 Sekunden schließt. Ein WebSocket beginnt als HTTP-Anfrage mit Upgrade: websocket und Connection: Upgrade. Das sind Hop-by-Hop-Header. Ein Proxy soll sie daher verarbeiten und nicht weiterleiten. Außerdem verwendet das Upstream-Protokoll bei nginx 1.24.0 unter Ubuntu 24.04 standardmäßig HTTP/1.0. Dieses Protokoll unterstützt keinen Upgrade-Mechanismus. Beide Header müssen manuell wieder gesetzt werden.

Die map-Direktive gehört in den http-Kontext und in eine eigene Datei.

# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Anschließend folgt der location-Block.

location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Die map-Direktive ermöglicht es, mit einem location-Block beide Arten von Datenverkehr zu bedienen. Bei einer gewöhnlichen Anfrage ist $http_upgrade leer, daher wird $connection_upgrade zu close. Bei einer Upgrade-Anfrage enthält die Variable websocket. Dadurch lautet der an das Upstream gesendete Header Connection: upgrade. Wenn Sie proxy_set_header Connection "upgrade"; fest vorgeben, wird dieser Header auch bei jeder normalen Seitenanfrage gesendet. Einige Backends beantworten eine solche Anfrage mit 400.

proxy_http_version 1.1; ist ab nginx 1.29.7 der Standardwert. Bei diesen Versionen ändert die Zeile daher nichts und verursacht keine Probleme. Beim Paket mit 1.24.0 ist sie erforderlich. Die Zeilen Upgrade und Connection sind bei jeder Version erforderlich, weil nginx diese beiden Header nicht automatisch weiterleitet.

proxy_read_timeout verursacht Meldungen wie „Die Anwendung wird geladen und aktualisiert sich anschließend nicht mehr“. Der Standardwert beträgt 60 Sekunden. Gemessen wird der Abstand zwischen zwei Lesevorgängen vom Backend, nicht die Lebensdauer der Verbindung. Wenn ein WebSocket 60 Sekunden lang keine Daten überträgt, schließt nginx die Verbindung. Die Browserkonsole zeigt dann, dass der Socket mit dem Code 1006 geschlossen wurde. Anwendungen, die häufiger als einmal pro Minute eigene Heartbeats senden, bemerken das nicht. Anwendungen ohne Heartbeat fallen nach genau einer Minute aus. Bei Live-Editoren und Dashboards tritt das Problem zuerst auf. Ein häufiges Beispiel ist eine selbst gehostete n8n-Instanz hinter HTTPS.

Warum verändert ein abschließender Schrägstrich in proxy_pass meine URLs?

Die Regel lässt sich in einem Satz zusammenfassen. Wenn proxy_pass mit einer URI (Uniform Resource Identifier) endet, selbst mit einer einfachen /, entfernt nginx den Teil des Anfragepfads, der dem location-Präfix entspricht, und setzt diese URI an seine Stelle. Wenn proxy_pass beim Host und Port endet, wird der Anfragepfad unverändert weitergegeben.

location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

Eine Anfrage an /app/status erreicht das Backend als /status.

location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

Eine Anfrage an /app/status erreicht das Backend als /app/status.

Welche Form Sie benötigen, hängt von der Anwendung ab. Eine Anwendung mit einer Einstellung für Basispfad oder Unterverzeichnis benötigt die zweite Form. Die Einstellung muss dabei über /app informiert sein. Eine Anwendung, die Präfixe nicht kennt, benötigt die erste Form. Die erste Form hat einen sofort sichtbaren Nachteil: Das von der Anwendung zurückgegebene HTML enthält weiterhin absolute Pfade wie /static/main.css. Der Browser fordert diese am Root der Website an. Keine location passt darauf, und die Seite wird ohne Formatierung dargestellt. Im Netzwerk-Tab des Browsers werden diese Asset-Anfragen mit 404 beantwortet. Die Lösung ist die eigene Basispfad-Einstellung der Anwendung oder eine zweite location /static/, die auf dasselbe Backend verweist.

Eine Regex-location kann in proxy_pass keine URI enthalten. sudo nginx -t lehnt die Konfiguration ab und nennt den Grund: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.

Diese gesamte Problemklasse entfällt, wenn jede Anwendung einen eigenen Namen, app.example.com, erhält und über location / per Proxy weitergeleitet wird. Unterpfade sind den zusätzlichen Aufwand nur dann wert, wenn Sie keine DNS-Einträge hinzufügen können.

Wie schalte ich mehrere Backends hinter einem Namen?

Mit einem upstream-Block. Er gehört in den Kontext http. Schreiben Sie ihn daher in derselben Datei oberhalb des server-Blocks oder in /etc/nginx/conf.d/.

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

Die location benennt ihn anschließend: proxy_pass http://app_backend;.

Die Standardmethode ist Round Robin. least_conn sendet jede Anfrage an das Backend mit den wenigsten aktiven Verbindungen. Das eignet sich für Anfragen mit unterschiedlicher Dauer. ip_hash ordnet eine Clientadresse dauerhaft einem Backend zu. ip_hash ist erforderlich, wenn die Anwendung Sitzungen im eigenen Arbeitsspeicher speichert. Round Robin über zwei solche Backends meldet Benutzer andernfalls zufällig ab, sobald ihre Anfragen bei der Instanz landen, die sie zuvor nicht gesehen hat. Sitzungen in einem gemeinsamen Speicher abzulegen, ist die bessere Lösung.

max_fails=3 fail_timeout=30s bedeutet, dass drei fehlgeschlagene Versuche innerhalb von 30 Sekunden diesen Server für 30 Sekunden aus dem Pool nehmen. Wenn sich jeder Server im Block in diesem Zustand befindet, erhalten Clients den Status 502 und das Error-Log enthält no live upstreams while connecting to upstream.

keepalive 32 hält pro Worker-Prozess bis zu 32 inaktive Verbindungen zu den Backends offen. Dadurch entfällt bei den meisten Anfragen der TCP-Handshake. Bei Ubuntu 24.04 mit 1.24.0 aktiviert diese Zeile den Cache. Seit nginx 1.29.7 ist der Cache standardmäßig aktiviert. Der dokumentierte Standardwert ist jedoch keepalive 32 local;. Der Parameter local verhindert, dass gecachte Verbindungen zwischen verschiedenen locations gemeinsam verwendet werden. Bei 1.29.7 und später wiederholt ein einfaches keepalive 32; daher nicht lediglich den Standardwert. Wenn local fehlt, kann jede location, die an denselben Upstream-Server proxyt, eine Verbindung aus dem gemeinsamen Pool wiederverwenden. Das ist eine Änderung gegenüber dem Standardverhalten. Lassen Sie die Zeile bei diesen Versionen weg oder schreiben Sie keepalive 32 local;, um das Standardverhalten beizubehalten. Schreiben Sie die Anweisung ohne Parameter nur, wenn diese gemeinsame Nutzung gewünscht ist. Der Parameter local ist neu in 1.29.7. Das Paket 1.24.0 akzeptiert ihn daher nicht. Für HTTP-Backends empfiehlt nginx für den Pool proxy_http_version mit 1.1 (oder 2 bei nginx 1.29.4 und später) und einen gelöschten Connection-Header zum Backend. nginx dokumentiert außerdem persistente HTTP/1.0-Verbindungen. Dafür wird Connection: Keep-Alive an ein Backend gesendet, das diese Verbindungen unterstützt. nginx empfiehlt diese Methode jedoch nicht. Ab 1.29.7 sind beide Teile der empfohlenen Konfiguration Standardwerte. Fügen Sie bei 1.24.0 proxy_http_version 1.1; und proxy_set_header Connection ""; selbst zur location hinzu. Andernfalls sendet nginx weiterhin HTTP/1.0 mit Connection: close, und der Pool wird nie wiederverwendet. Wenn dieselbe location auch die WebSocket-Map verwendet, ändern Sie den leeren Fall von close in eine leere Zeichenfolge. Dann enthalten gewöhnliche Anfragen keinen Connection-Header, und die gepoolte Verbindung wird wiederverwendet.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

Namen in einem upstream-Block werden beim Start von nginx aufgelöst. Wenn Ihr Backend ein Container ist, der nach einem Neustart eine neue Adresse erhält, verwendet nginx weiterhin die alte Adresse, bis Sie nginx neu laden. nginx 1.27.3 und später kann solchen Änderungen ohne Reload folgen. Dazu dienen ein resolver, ein zone im upstream-Block und der Parameter resolve in jeder server-Zeile. Das Paket 1.24.0 ist jedoch älter und unterstützt diese Funktion nicht. In einem Docker-Netzwerk können Sie die Namensauflösung mit dem integrierten Resolver auf den Zeitpunkt der Anfrage verlagern.

resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;

Wenn Container so häufig hinzukommen und verschwinden, dass Sie nginx laufend anpassen müssen, ist ein Proxy die bessere Lösung, der Container-Labels ausliest. Traefik vor mehreren Docker-Compose-Anwendungen erstellt seine Routen aus den Containern selbst.

Warum schlagen Uploads mit 413 Request Entity Too Large fehl?

client_max_body_size ist standardmäßig auf 1 megabyte gesetzt. Einen größeren Request Body lehnt nginx mit 413 ab, und im Error-Log wird client intended to send too large body protokolliert. Erhöhen Sie den Wert im Server-Block oder in dem location-Block, in dem die Uploads verarbeitet werden.

client_max_body_size 512m;

Ein Wert von 0 deaktiviert die Prüfung vollständig. Mit 512m lehnt nginx Request Bodys oberhalb dieses Limits weiterhin ab. Ein 413, der nach dieser Änderung weiterhin auftritt, weist daher nicht auf das Backend als Ursache hin. Prüfen Sie den effektiven Wert von client_max_body_size im location-Block, der den Upload verarbeitet, sowie das Error-Log von nginx, bevor Sie das Upload-Limit der Anwendung prüfen.

Standardmäßig liest nginx den vollständigen Request Body ein, bevor es die Upstream-Verbindung öffnet. Größere Datenmengen schreibt nginx zunächst in eine temporäre Datei auf der Festplatte. Dadurch wird die Anwendung vor langsamen Clients geschützt, weil das Backend den Upload mit der vollen lokalen Geschwindigkeit erhält. Bei sehr großen Uploads können Sie stattdessen Streaming verwenden.

proxy_request_buffering off;

Bei HTTP/1.1-Uploads mit Chunked Transfer Encoding müssen Sie im Paket 1.24.0 außerdem proxy_http_version 1.1; in diesem location-Block setzen. Andernfalls puffert nginx den Body weiterhin. Das Backend erhält den Body dann während des Eingangs und muss damit umgehen können. Sobald nginx beginnt, den Body an das Upstream zu senden, kann es die Anfrage nicht erneut an ein anderes Upstream senden.

client_body_timeout gilt standardmäßig für 60 Sekunden zwischen zwei aufeinanderfolgenden Lesevorgängen des Bodys und nicht für den gesamten Upload. Ein langsamer, aber kontinuierlicher Upload wird dadurch nicht abgebrochen. Ein angehaltener Upload wird beendet.

Pufferung von Antworten und die Einstellung, die Live-Ausgaben beeinträchtigt

proxy_buffering ist standardmäßig aktiviert und normalerweise die richtige Einstellung. nginx liest die Antwort so schnell aus Ihrer Anwendung, wie diese sie schreiben kann, hält sie vor und liefert sie in der Geschwindigkeit eines langsamen Clients aus. Der Worker der Anwendung ist dadurch frühzeitig fertig, statt während des gesamten langsamen Downloads belegt zu bleiben.

Dadurch werden Streaming-Antworten beeinträchtigt. Server-Sent Events und die Live-Ausgabe von Logs zeigen dem Leser nichts an, bis ein Puffer gefüllt ist. Deaktivieren Sie die Pufferung nur an diesem Ort.

proxy_buffering off;

Wenn Sie die Anwendung kontrollieren, ist es besser, bei den Streaming-Antworten ausschließlich den Header X-Accel-Buffering: no zu senden. nginx wertet diesen Header für jede Antwort aus und deaktiviert die Pufferung nur für diese Antwort. Normale Seiten behalten dadurch den Vorteil der Pufferung.

Wenn das Fehlerprotokoll upstream sent too big header while reading response header from upstream meldet, haben die Antwort-Header nicht in einen einzelnen Puffer gepasst. proxy_buffer_size ist standardmäßig auf eine einzelne Speicherseite eingestellt, je nach Plattform auf 4 oder 8 Kilobyte. Lange Cookies oder große Authentifizierungs-Header können diesen Puffer überschreiten. Erhöhen Sie beide Werte.

proxy_buffer_size 16k;
proxy_buffers 8 16k;

Wo gehört TLS in diese Konfiguration?

Bei nginx, vor alle oben genannten Komponenten. TLS (Transport Layer Security) wird am Proxy terminiert. Die Verbindung von nginx zur Anwendung bleibt über die Loopback-Adresse unverschlüsselt. Kein anderer Host im Netzwerk kann sie mitlesen. Die Anwendung erkennt anhand von X-Forwarded-Proto, dass der Besucher HTTPS verwendet hat. Das ist der vierte der vier Header.

Tragen Sie Zertifikatspfade nicht manuell ein. Verweisen Sie mit dem DNS-Eintrag auf den Server, öffnen Sie die Firewall und lassen Sie Certbot diesen Server-Block bearbeiten. Certbot fügt die Zeile listen 443 ssl mit den Pfaden ssl_certificate sowie eine Weiterleitung von Port 80 hinzu. Ein Let's-Encrypt-Zertifikat für nginx mit Certbot ausstellen beschreibt die Ausstellung und den Erneuerungs-Timer.

sudo ufw allow 'Nginx Full'
sudo ufw status

Nginx Full ist ein Anwendungsprofil, das das nginx-Paket installiert. Es öffnet Port 80 und Port 443 gemeinsam. Port 80 muss für die HTTP-01-Erneuerungs-Challenge geöffnet bleiben, auch wenn jeder Besucher anschließend zu HTTPS weitergeleitet wird.

Konfiguration testen und anschließend neu laden

sudo nginx -t
sudo systemctl reload nginx

nginx -t analysiert jede eingebundene Datei und meldet entweder einen erfolgreichen Test oder gibt die Datei und die Zeile aus, an der die Verarbeitung beendet wurde. Lesen Sie diese Ausgabe, bevor Sie die Konfiguration neu laden. Ein Reload mit einer fehlerhaften Konfiguration wird nicht angewendet: nginx verwendet weiterhin die vorherige Konfiguration. Die Website bleibt dadurch erreichbar, während Ihre Änderung stillschweigend wirkungslos bleibt. systemctl restart verhält sich anders und problematischer, weil ein Neustart den laufenden Server zuerst beendet. Ein Konfigurationsfehler führt dann dazu, dass nginx überhaupt nicht mehr läuft. Verwenden Sie standardmäßig einen Reload. Nutzen Sie restart nur für seltene Änderungen, die dies erfordern.

sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'

Die Zeile ss zeigt, welcher Prozess welchen Port belegt. Damit können Sie bestätigen, dass die Anwendung tatsächlich dort auf Verbindungen wartet, wohin proxy_pass verweist.

Die Fehler, die tatsächlich auftreten

502 Bad Gateway mit connect() failed (111: Connection refused) while connecting to upstream im Fehlerprotokoll. Unter der in proxy_pass angegebenen Adresse lauscht kein Dienst. Die Anwendung ist beendet, an einen anderen Port gebunden oder an eine nur innerhalb des Containers erreichbare Adresse gebunden.

502 mit no live upstreams while connecting to upstream. Jeder Server im upstream-Block ist von max_fails derzeit als fehlgeschlagen markiert. Reparieren Sie die Backends. nginx versucht sie erneut, sobald fail_timeout abgelaufen ist.

504 Gateway Time-out mit upstream timed out (110: Connection timed out) while reading response header from upstream. Das Backend hat die Verbindung angenommen und anschließend für proxy_read_timeout Sekunden keine Daten gesendet. Das Erhöhen des Timeouts ist bei einem tatsächlich langsamen Bericht richtig, bei einer festhängenden Anwendung jedoch falsch.

Jeder Pfad liefert von der Anwendung 404 zurück. Die Regel für den abschließenden Schrägstrich hat den Pfad umgeschrieben. Vergleichen Sie den Pfad im Anwendungsprotokoll mit dem angeforderten Pfad.

Eine andere Website antwortet. server_name stimmt nicht mit dem Host-Header überein. Daher ist die Anfrage in den default_server-Block gefallen.

Die Seite wird geladen, anschließend friert die Oberfläche nach etwa einer Minute ein. Das ist der WebSocket-Fall: Die Upgrade-Verarbeitung fehlt oder proxy_read_timeout steht weiterhin auf 60 Sekunden.

FAQ

Warum gibt nginx nach dem Hinzufügen von proxy_pass den Fehler 502 Bad Gateway zurück?

nginx konnte keine Verbindung zu der in proxy_pass angegebenen Adresse herstellen. Das Fehlerprotokoll unter /var/log/nginx/error.log nennt die Ursache: connect() failed (111: Connection refused) while connecting to upstream bedeutet, dass dort kein Prozess Verbindungen annimmt, und no live upstreams bedeutet, dass jeder Server in einem upstream-Block als fehlgeschlagen markiert wurde. Führen Sie sudo ss -lntp | grep 3000 aus, um zu sehen, welcher Prozess den Port verwendet und an welche Adresse er gebunden ist. Eine Anwendung, die an eine nur im Container erreichbare Adresse oder an einen anderen als den angegebenen Port gebunden ist, verursacht diesen Fehler immer.

Warum trennt meine Anwendung hinter nginx nach etwa einer Minute die Verbindung?

Die Verbindung ist ein WebSocket, und proxy_read_timeout steht noch auf dem Standardwert von 60 Sekunden. Dieser Wert misst die Zeit zwischen zwei Lesevorgängen vom Backend. Ein inaktiver Socket wird von nginx geschlossen, und die Browserkonsole meldet den Schließcode 1006. Setzen Sie proxy_http_version 1.1 (der Standardwert seit nginx 1.29.7, jedoch nicht im Paket Ubuntu 24.04, das mit 1.24.0 ausgeliefert wird), leiten Sie Upgrade und Connection über einen map in $http_upgrade weiter und erhöhen Sie proxy_read_timeout auf einen Wert wie 3600s. Ohne den Header Upgrade findet das Upgrade überhaupt nicht statt. Die Anwendung fällt dann auf Polling zurück oder zeigt keine Live-Aktualisierungen an.

Ist der abschließende Schrägstrich in proxy_pass relevant?

Ja. Er ändert den Pfad, den das Backend erhält. Mit location /app/ und proxy_pass http://127.0.0.1:3000/ erreicht eine Anfrage an /app/status das Backend als /status, weil jeder URI-Teil nach Host und Port das Präfix des passenden location-Blocks ersetzt. Entfernen Sie den abschließenden Schrägstrich, erreicht dieselbe Anfrage das Backend als /app/status. Das Entfernen des Präfixes führt häufig dazu, dass die eigenen Asset-Links der Anwendung nicht mehr funktionieren. Diese bleiben absolut und liefern dann am Stammverzeichnis der Website den Fehler 404. Für eine Anwendung mit einer Einstellung für den Basispfad ist daher die Form besser geeignet, die den Pfad unverändert weiterleitet.

Warum protokolliert meine Anwendung 127.0.0.1 als IP-Adresse jedes Besuchers?

Die Verbindung, die die Anwendung erhält, kommt tatsächlich von nginx über die Loopback-Adresse. Die Adresse des Besuchers erreicht die Anwendung nur über einen von Ihnen gesetzten Header: proxy_set_header X-Real-IP $remote_addr; für einen einzelnen Wert und proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; für die angehängte Kette. Die Anwendung muss anschließend so konfiguriert werden, dass sie diesen Headern vertraut. Beachten Sie, dass ein Client seinen eigenen X-Forwarded-For senden kann. Wenn nginx der Edge-Server ist, überschreiben Sie den Wert daher mit $remote_addr, statt ihn anzuhängen.

Benötige ich TLS für die Verbindung zwischen nginx und meiner Anwendung?

Nicht, wenn die Anwendung auf demselben Server läuft und an 127.0.0.1 gebunden ist, da dieser Datenverkehr den Rechner nicht verlässt. Beenden Sie TLS in nginx, verwenden Sie proxy_pass für unverschlüsseltes HTTP über die Loopback-Schnittstelle und senden Sie X-Forwarded-Proto $scheme, damit die Anwendung weiß, dass der Besucher HTTPS verwendet hat. Befindet sich das Backend auf einem anderen Host und läuft die Verbindung über ein Netzwerk, das Sie nicht kontrollieren, benötigt dieser Abschnitt eine eigene Absicherung. Verwenden Sie dafür entweder HTTPS zum Backend oder einen privaten Tunnel zwischen den beiden Rechnern.

War dieser Artikel hilfreich?