Konfiguracja nginx jako reverse proxy krok po kroku
Dowiedz się, jak poprawnie skonfigurować nginx jako reverse proxy. Artykuł wyjaśnia użycie proxy_pass, przekazywanie nagłówków, obsługę websockets oraz limitów dla przesyłanych plików.
Działanie reverse proxy w nginx
Reverse proxy w nginx przyjmuje żądania docierające na port 80 oraz 443 i przekazuje każde z nich do aplikacji nasłuchującej na lokalnym porcie, a następnie zwraca odpowiedź aplikacji do przeglądarki. Konfiguracja składa się z pojedynczego bloku server i jest krótka. Większość trudności sprowadza się do pięciu lub sześciu linii, które informują aplikację o tym, kim był rzeczywisty klient oraz jakiego protokołu użył.
Poniższa treść bazuje na czystej instalacji Ubuntu 24.04, z wykorzystaniem pakietu nginx z repozytoriów dystrybucji. Punktem wyjścia jest aplikacja, która odpowiada już na 127.0.0.1:3000. Jeśli wybór proxy nie został jeszcze dokonany, warto najpierw zapoznać się z porównaniem porównanie nginx z Caddy i Traefik. Poniżej przedstawiono strukturę konfiguracji nginx, linia po linii.
Wprowadź te konfiguracje na własnym serwerze. Każda zmiana musi zostać przetestowana za pomocą sudo nginx -t przed przeładowaniem; należy również przeanalizować komunikaty zwracane przez to polecenie.
Gdzie nginx przechowuje konfigurację w systemie Ubuntu
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/Główny plik to /etc/nginx/nginx.conf. Określa on opcje globalne wewnątrz bloku http { }, a następnie wczytuje dwa katalogi: /etc/nginx/conf.d/*.conf oraz /etc/nginx/sites-enabled/*. W systemach Ubuntu i Debian dla każdej witryny tworzy się osobny plik w /etc/nginx/sites-available/ i aktywuje go za pomocą dowiązania symbolicznego w /etc/nginx/sites-enabled/. Usunięcie dowiązania wyłącza witrynę, zachowując jednocześnie plik konfiguracyjny.
Dwie dyrektywy używane w dalszej części działają wyłącznie w kontekście http, nigdy wewnątrz bloku server: map oraz upstream. Należy umieścić je w osobnym pliku w katalogu /etc/nginx/conf.d/, ponieważ zawartość tego katalogu jest dołączana na poziomie http.
Pakiet dostarcza domyślnie włączoną witrynę o nazwie default. Jest ona oznaczona jako default_server, co oznacza, że odpowiada na każde żądanie, którego nagłówek Host nie pasuje do żadnego server_name w konfiguracji. Dopóki pozostaje ona włączona, żądania niedopasowane do zdefiniowanych nazw trafiają na tę stronę zamiast do Twojej aplikacji. Po poprawnej konfiguracji własnej witryny należy usunąć to dowiązanie symboliczne.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxNajmniejszy blok serwera przekazujący ruch do jednej aplikacji
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}Zapisz to jako /etc/nginx/sites-available/app.example.com, a następnie włącz i załaduj konfigurację.
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; wiąże adres IPv4, a listen [::]:80; wiąże adres IPv6. Pomiń drugą linię, a każde połączenie IPv6 do serwera zostanie odrzucone. Przeglądarka typu dual-stack, której zapytanie DNS (domain name system) zwraca rekord AAAA, zazwyczaj przełącza się na IPv4 i maskuje problem. Jednak użytkownik korzystający wyłącznie z IPv6 lub klient próbujący użyć tylko pierwszego otrzymanego adresu, otrzyma błąd odmowy połączenia, podczas gdy użytkownicy IPv4 będą widzieć działającą witrynę. Zgłoszenie błędu, które otrzymasz, będzie brzmiało: „u mnie działa”.
server_name jest dopasowywane do nagłówka Host wysyłanego przez przeglądarkę. Można wymienić kilka nazw, oddzielając je spacjami. Jeśli żaden blok nie pasuje, nginx używa bloku, który jest default_server, dlatego domyślna witryna musiała zostać usunięta.
location / to dopasowanie prefiksu ścieżki żądania, a / pasuje do każdej ścieżki. proxy_pass to adres, z którym nginx nawiązuje połączenie. Utrzymuj aplikację powiązaną z 127.0.0.1, aby jedyna droga dostępu prowadziła przez nginx. Jeśli aplikacja działa w kontenerze, publikuj ją jako 127.0.0.1:3000:3000, a nie jako 3000:3000, ponieważ Docker tworzy własne reguły i publikuje porty z pominięciem ufw, więc bezpośrednio opublikowany port jest dostępny z Internetu niezależnie od ustawień ufw. Dokumentacja Dockera wskazuje łańcuch DOCKER-USER jako miejsce filtrowania tego ruchu, ale powiązanie z 127.0.0.1 jest prostszym rozwiązaniem.
Linia curl wysyła poprawny nagłówek Host bezpośrednio z serwera, dzięki czemu można przetestować blok przed skierowaniem ruchu DNS.
Co nginx wysyła do backendu przy braku dodatkowej konfiguracji
proxy_pass samodzielnie ukrywa przed aplikacją cztery elementy.
Pakiet nginx 1.24.0, który dostarcza Ubuntu 24.04, domyślnie komunikuje się z backendem przy użyciu HTTP/1.0 i wysyła Connection: close, co powoduje, że każde żądanie otwiera nowe połączenie upstream i uniemożliwia aktualizację protokołu. Wersja nginx 1.29.7, wydana w marcu 2026, zmieniła te ustawienia domyślne: od tej wersji nginx używa protokołu HTTP/1.1 w komunikacji upstream, nie wysyła nagłówka Connection i ponownie wykorzystuje połączenia z puli zamiast otwierać nowe dla każdego żądania. Nawet w tym przypadku aktualizacja do WebSocket nadal wymaga nagłówków przedstawionych w dalszej części.
Nagłówek Host jest nadpisywany wartością z proxy_pass, czyli 127.0.0.1:3000. Aplikacja, która tworzy linki bezwzględne na podstawie Host, generuje teraz odnośniki, których nikt spoza serwera nie może otworzyć.
Połączenie docierające do aplikacji pochodzi z nginx, więc aplikacja widzi adres klienta jako 127.0.0.1. Każdy wpis w dzienniku i każdy limit szybkości (rate limit) wewnątrz aplikacji rejestruje zatem proxy zamiast odwiedzającego.
Aplikacja nie jest w stanie rozpoznać, że przeglądarka użyła HTTPS, ponieważ otrzymane połączenie to zwykłe HTTP na adresie pętli zwrotnej (loopback).
Cztery linie rozwiązują wszystkie te problemy.
Cztery nagłówki do ustawienia i informacje, które przekazują do backendu
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 zawiera nazwę wpisaną przez użytkownika. $host to nazwa z żądania, z usuniętym portem i zamienionymi na małe literami. Ustawienie tego nagłówka pozwala aplikacji na poprawne generowanie bezwzględnych adresów URL: przekierowań po logowaniu czy linków w wiadomościach e-mail z resetem hasła. Brak tego nagłówka powoduje, że aplikacja przyjmuje 127.0.0.1:3000 jako własną nazwę. Domyślne ustawienie proxy_redirect w nginx nadpisuje nagłówek Location lub Refresh wskazujący na adres proxy_pass, więc zwykłe przekierowanie po logowaniu zazwyczaj działa poprawnie. Jednak bezwzględne adresy URL, które aplikacja umieszcza na stronach i w wiadomościach e-mail, takie jak link do resetu hasła, wskazują na 127.0.0.1:3000 – adres, którego przeglądarka użytkownika nie może otworzyć. Jeśli aplikacja wymaga również numeru portu, ponieważ działa na 8080, należy użyć $http_host, który przekazuje nagłówek dokładnie w takiej formie, w jakiej wysłał go klient.
X-Real-IP zawiera jedną wartość: $remote_addr, czyli adres, z którego nginx przyjął połączenie. Aplikacje odczytują go na potrzeby własnych logów dostępu oraz mechanizmów ograniczania liczby żądań (rate limiting).
X-Forwarded-For zawiera listę. $proxy_add_x_forwarded_for dołącza $remote_addr do wartości, którą klient już umieścił w tym nagłówku, dzięki czemu wartość jest rozdzielona przecinkami, a wpis dodany przez nginx znajduje się na końcu. Ten szczegół decyduje o tym, czy nagłówek jest wiarygodny: klient może wysłać dowolny nagłówek X-Forwarded-For, więc aplikacja odczytująca pierwszy wpis może otrzymać dowolny adres. Gdy nginx pełni rolę serwera brzegowego, należy użyć $remote_addr i odrzucić wersję przesłaną przez klienta. Jeśli przed nginx znajduje się CDN lub inne proxy, należy użyć set_real_ip_from oraz real_ip_header z modułu realip, aby $remote_addr stało się rzeczywistym adresem klienta.
X-Forwarded-Proto zawiera http lub https. Frameworki odczytują tę wartość, aby zdecydować, czy oznaczyć pliki cookie jako Secure oraz czy wymusić przekierowanie na HTTPS. Pominięcie tego nagłówka w witrynie z TLS powoduje, że aplikacja skonfigurowana do wymuszania HTTPS widzi http, odpowiada przekierowaniem na adres HTTPS, otrzymuje kolejne żądanie przez nginx, nadal widzi http i ponownie wysyła przekierowanie. Przeglądarka przerywa działanie i wyświetla ERR_TOO_MANY_REDIRECTS.
Powtarzanie tych czterech linii w każdej lokalizacji prowadzi do rozbieżności w konfiguracji. Należy umieścić je w jednym pliku i dołączać go za pomocą dyrektywy include.
# /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;
}Dziedziczenie w tym przypadku posiada pułapkę. Lokalizacja dziedziczy dyrektywy proxy_set_header z bloku serwera tylko wtedy, gdy sama nie definiuje żadnej z nich. Dodanie choć jednego wpisu proxy_set_header wewnątrz lokalizacji powoduje, że wszystkie nagłówki zdefiniowane na poziomie serwera są dla tej lokalizacji pomijane. Dlatego należy utrzymywać je na jednym poziomie lub używać include dla fragmentu konfiguracji w każdej lokalizacji, która przekazuje ruch (proxy).
Dlaczego aplikacja WebSocket łączy się, a następnie rozłącza?
Domyślne ustawienia zabraniają aktualizacji protokołu, a domyślny limit czasu odczytu zamyka bezczynny tunel po 60 sekundach. WebSocket rozpoczyna się jako żądanie HTTP zawierające Upgrade: websocket oraz Connection: Upgrade. Są to nagłówki typu hop-by-hop, co oznacza, że proxy powinno je przetworzyć, zamiast przekazywać dalej. W nginx 1.24.0 dostępnym w Ubuntu 24.04 domyślny protokół upstream to HTTP/1.0, który nie posiada mechanizmu aktualizacji. Oba elementy muszą zostać przywrócone ręcznie.
Mapę należy umieścić w kontekście http, w osobnym pliku.
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}Następnie należy skonfigurować blok location.
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;
}Mapa istnieje po to, aby jedna lokalizacja mogła obsługiwać oba rodzaje ruchu. W przypadku zwykłego żądania $http_upgrade jest puste, więc $connection_upgrade przyjmuje wartość close. W przypadku żądania aktualizacji zawiera ono websocket, więc nagłówek wysyłany do upstream to Connection: upgrade. Sztywne wpisanie proxy_set_header Connection "upgrade"; powoduje wysyłanie tego nagłówka również przy każdym zwykłym żądaniu strony, na co niektóre backendy odpowiadają błędem 400.
proxy_http_version 1.1; jest wartością domyślną od wersji nginx 1.29.7, więc w tych wersjach linia ta nic nie zmienia i nie powoduje problemów. W pakiecie 1.24.0 jest ona wymagana. Linie Upgrade oraz Connection są wymagane w każdej wersji, ponieważ nginx nigdy nie przekazuje tych dwóch nagłówków automatycznie.
proxy_read_timeout jest przyczyną zgłoszeń typu „ładuje się, a potem przestaje aktualizować”. Domyślnie wynosi 60 sekund i mierzy przerwę między dwoma odczytami z backendu, a nie czas trwania połączenia. WebSocket, który pozostaje nieaktywny przez 60 sekund, jest zamykany przez nginx, a konsola przeglądarki wykazuje zamknięcie gniazda z kodem 1006. Aplikacje wysyłające własny sygnał heartbeat częściej niż raz na minutę nigdy tego nie zauważą. Aplikacje, które tego nie robią, są rozłączane po minucie. Problem ten najpierw pojawia się w edytorach czasu rzeczywistego i dashboardach, a samodzielnie hostowana instancja n8n za HTTPS jest tego częstym przykładem.
Dlaczego ukośnik na końcu w proxy_pass zmienia adresy URL?
Zasada jest jednowierszowa. Jeśli proxy_pass kończy się identyfikatorem URI (nawet samym /), nginx usuwa część ścieżki żądania, która pasowała do prefiksu location, i wstawia w to miejsce wspomniany URI. Jeśli proxy_pass kończy się na hoście i porcie, ścieżka żądania jest przekazywana bez zmian.
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}Żądanie dla /app/status dociera do backendu jako /status.
location /app/ {
proxy_pass http://127.0.0.1:3000;
}Żądanie dla /app/status dociera do backendu jako /app/status.
Wybór formy zależy od aplikacji. Aplikacja z ustawieniem ścieżki bazowej lub podkatalogu wymaga drugiej formy, przy czym w ustawieniach należy wskazać /app. Aplikacja, która nie posiada wiedzy o prefiksach, wymaga pierwszej formy. Pierwsza forma wiąże się z natychmiastowym skutkiem: kod HTML zwracany przez aplikację nadal zawiera ścieżki bezwzględne, takie jak /static/main.css, przeglądarka szuka ich w katalogu głównym witryny, nie znajduje dopasowania lokalizacji, a strona renderuje się bez stylów. Zakładka sieci w narzędziach deweloperskich przeglądarki wykazuje błędy 404 dla tych zasobów. Rozwiązaniem jest konfiguracja ścieżki bazowej w samej aplikacji lub dodanie drugiej dyrektywy location /static/ wskazującej na ten sam backend.
Lokalizacja oparta na wyrażeniu regularnym nie może zawierać URI w proxy_pass. sudo nginx -t odrzuca taką konfigurację i podaje przyczynę: "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.
Cała ta klasa problemów znika, gdy każda aplikacja otrzymuje własną nazwę, app.example.com, obsługiwaną przez proxy z location /. Ścieżki podrzędne są warte zachodu tylko wtedy, gdy nie ma możliwości dodania rekordów DNS.
Jak umieścić więcej niż jeden backend pod jedną nazwą?
Należy użyć bloku upstream. Należy on do kontekstu http, więc należy go umieścić powyżej bloku server w tym samym pliku lub w /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;
}Następnie dyrektywa location wskazuje go za pomocą: proxy_pass http://app_backend;.
Domyślną metodą jest round robin. least_conn kieruje każde żądanie do backendu z najmniejszą liczbą aktywnych połączeń, co sprawdza się przy żądaniach o różnym czasie przetwarzania. ip_hash przypisuje jeden adres klienta do jednego backendu. ip_hash jest wymagane, gdy aplikacja przechowuje sesje w pamięci lokalnej, ponieważ round robin między dwoma takimi backendami powoduje losowe wylogowywanie użytkowników, gdy żądania trafiają do instancji, która nie posiada ich sesji. Lepszym rozwiązaniem jest przeniesienie sesji do współdzielonej pamięci.
max_fails=3 fail_timeout=30s oznacza, że trzy nieudane próby w ciągu 30 sekund wyłączają serwer na 30 sekund. Gdy każdy serwer w bloku znajduje się w tym stanie, klienci otrzymują błąd 502, a dziennik błędów zawiera no live upstreams while connecting to upstream.
keepalive 32 utrzymuje do 32 bezczynnych połączeń z backendami otwartych dla każdego procesu roboczego, co eliminuje konieczność wykonywania handshake'u TCP dla większości żądań. W wersji 1.24.0 dostępnej w Ubuntu 24.04 ta linia aktywuje pamięć podręczną. Od wersji nginx 1.29.7 pamięć podręczna jest włączona domyślnie, ale udokumentowana wartość domyślna to keepalive 32 local;, a parametr local zapobiega współdzieleniu połączeń z pamięci podręcznej między różnymi lokalizacjami. Zatem w wersji 1.29.7 i nowszych, samo keepalive 32; nie tylko przywraca wartość domyślną: poprzez pominięcie local pozwala każdej lokalizacji proxy do tego samego serwera upstream na ponowne wykorzystanie puli połączeń, co stanowi zmianę względem domyślnego zachowania. W tych wersjach należy pominąć tę linię lub wpisać keepalive 32 local;, aby zachować ustawienia domyślne, a wpisać ją samodzielnie tylko wtedy, gdy wymagane jest współdzielenie. Parametr local jest nowy w wersji 1.29.7, więc pakiet 1.24.0 go nie obsługuje. Dla backendów HTTP zalecana przez nginx konfiguracja puli to proxy_http_version ustawione na 1.1 (lub 2 w nginx 1.29.4 i nowszych) z wyczyszczonym nagłówkiem Connection przesyłanym do upstreamu. nginx dokumentuje również trwałe połączenia HTTP/1.0, tworzone przez wysyłanie Connection: Keep-Alive do backendu, który je obsługuje, ale metoda ta nie jest zalecana. Od wersji 1.29.7 obie części zalecanej konfiguracji są ustawieniami domyślnymi. W wersji 1.24.0 należy samodzielnie dodać proxy_http_version 1.1; oraz proxy_set_header Connection ""; do sekcji location, w przeciwnym razie nginx będzie wysyłać HTTP/1.0 z Connection: close i pula połączeń nigdy nie zostanie ponownie wykorzystana. Jeśli ta sama lokalizacja używa również mapy WebSocket, należy zmienić pusty przypadek z close na pusty ciąg znaków, aby zwykłe żądania nie zawierały nagłówka Connection, co umożliwi ponowne wykorzystanie połączenia z puli.
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}Nazwy wewnątrz bloku upstream są rozwiązywane podczas uruchamiania nginx. Jeśli backend jest kontenerem, który otrzymuje nowy adres po restarcie, nginx używa starego adresu do momentu przeładowania konfiguracji. nginx 1.27.3 i nowsze potrafią śledzić takie zmiany bez przeładowania dzięki resolver, zone w bloku upstream oraz parametrowi resolve w każdej linii server, jednak pakiet 1.24.0 jest starszy. Wewnątrz sieci Docker można przenieść rozwiązywanie nazw na moment żądania za pomocą wbudowanego mechanizmu resolver.
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;Gdy kontenery pojawiają się i znikają na tyle często, że edytowanie konfiguracji nginx staje się uciążliwe, lepszym narzędziem jest proxy odczytujące etykiety kontenerów. Traefik przed kilkoma aplikacjami Docker Compose buduje swoje trasy bezpośrednio na podstawie kontenerów.
Dlaczego przesyłanie plików kończy się błędem 413 Request Entity Too Large?
client_max_body_size domyślnie wynosi 1 megabajt. Żądanie o większym rozmiarze treści jest odrzucane przez nginx z kodem 413, a dziennik błędów rejestruje client intended to send too large body. Należy zwiększyć tę wartość w bloku server lub w lokalizacji, w której odbywa się przesyłanie plików.
client_max_body_size 512m;Wartość 0 całkowicie wyłącza sprawdzanie. Przy 512m nginx nadal odrzuca treści żądań powyżej tego limitu, więc błąd 413, który pojawia się mimo tej zmiany, nie wskazuje na backend jako źródło problemu. Przed sprawdzeniem limitu przesyłania w samej aplikacji należy zweryfikować efektywne client_max_body_size w lokalizacji obsługującej przesyłanie oraz sprawdzić dziennik błędów nginx.
Domyślnie nginx odczytuje całą treść żądania przed otwarciem połączenia z upstreamem, zapisując większe dane w pliku tymczasowym na dysku. Chroni to aplikację przed wolnymi klientami, ponieważ backend otrzymuje przesyłane dane z pełną lokalną prędkością. W przypadku bardzo dużych plików można zastosować strumieniowanie.
proxy_request_buffering off;Dla przesyłania w trybie chunked w protokole HTTP/1.1 w pakiecie 1.24.0 należy również ustawić proxy_http_version 1.1; w danej lokalizacji, w przeciwnym razie nginx nadal będzie buforować treść żądania. Backend otrzymuje wtedy dane w miarę ich napływania i musi być w stanie je obsłużyć. Gdy nginx rozpocznie wysyłanie treści do upstreamu, nie może ponowić żądania do innego upstreamu.
client_body_timeout, domyślnie 60 sekund, ma zastosowanie między dwoma kolejnymi odczytami treści, a nie do całego procesu przesyłania. Wolne, ale stabilne przesyłanie nie zostanie przerwane. Zatrzymane przesyłanie zostanie zerwane.
Buforowanie odpowiedzi i ustawienie powodujące przerwanie strumieniowania danych wyjściowych
proxy_buffering jest domyślnie włączone i zazwyczaj jest to pożądane zachowanie. Nginx odczytuje odpowiedź z aplikacji tak szybko, jak aplikacja jest w stanie ją wygenerować, przechowuje ją, a następnie przekazuje do wolnego klienta w tempie dostosowanym do jego możliwości. Proces roboczy aplikacji kończy pracę szybciej, zamiast pozostawać zajętym przez cały czas trwania powolnego pobierania.
Powoduje to jednak przerwanie odpowiedzi strumieniowych. Zdarzenia przesyłane przez serwer (Server-sent events) oraz strumieniowe dane wyjściowe dzienników nie są widoczne dla odbiorcy, dopóki bufor nie zostanie zapełniony. W takiej lokalizacji należy wyłączyć buforowanie.
proxy_buffering off;Jeśli masz kontrolę nad aplikacją, lepszym rozwiązaniem jest wysłanie nagłówka X-Accel-Buffering: no wyłącznie w odpowiedziach strumieniowych. Nginx odczytuje ten nagłówek dla każdej odpowiedzi i wyłącza buforowanie tylko dla niej, dzięki czemu zwykłe strony zachowują korzyści z tego mechanizmu.
Gdy dziennik błędów zawiera komunikat upstream sent too big header while reading response header from upstream, oznacza to, że nagłówki odpowiedzi nie zmieściły się w jednym buforze. proxy_buffer_size domyślnie przyjmuje wartość pojedynczej strony pamięci, czyli 4 lub 8 kilobajtów w zależności od platformy, a długie pliki cookie lub rozbudowane nagłówki uwierzytelniania powodują przepełnienie tego obszaru. Należy zwiększyć obie te wartości.
proxy_buffer_size 16k;
proxy_buffers 8 16k;Gdzie w tej konfiguracji umieścić TLS?
W Nginx, przed wszystkimi powyższymi elementami. TLS (transport layer security) kończy się na proxy, a połączenie między Nginx a aplikacją pozostaje zwykłym HTTP przez adres loopback, gdzie nikt inny w sieci nie może go odczytać. Aplikacja dowiaduje się, że użytkownik użył HTTPS, z X-Forwarded-Proto, czwartego z czterech nagłówków.
Nie należy ręcznie wpisywać ścieżek do certyfikatów. Należy skierować rekord DNS na serwer, otworzyć zaporę sieciową i pozwolić Certbot na edycję tego samego bloku serwera: dodaje on linię listen 443 ssl ze ścieżkami ssl_certificate oraz przekierowanie z portu 80. Wystawianie certyfikatu Let's Encrypt dla Nginx za pomocą Certbot opisuje proces wystawiania oraz harmonogram odnawiania.
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full to profil aplikacji instalowany przez pakiet Nginx, który otwiera port 80 oraz port 443 jednocześnie. Port 80 musi pozostać otwarty dla wyzwania HTTP-01 podczas odnawiania, nawet po przekierowaniu wszystkich użytkowników na HTTPS.
Testowanie konfiguracji i przeładowanie
sudo nginx -t
sudo systemctl reload nginxnginx -t analizuje wszystkie dołączone pliki i zgłasza powodzenie testu lub wskazuje plik oraz linię, w której wystąpił błąd. Należy zapoznać się z tym komunikatem przed przeładowaniem. Przeładowanie z błędną konfiguracją nie przynosi zmian: Nginx kontynuuje pracę z poprzednimi ustawieniami, dzięki czemu serwis pozostaje dostępny, mimo że wprowadzona zmiana nie została zastosowana. systemctl restart działa inaczej i jest bardziej ryzykowne, ponieważ restart najpierw zatrzymuje działający serwer, więc błąd w konfiguracji spowoduje całkowite wyłączenie Nginx. Zaleca się domyślne stosowanie przeładowania, a restart pozostawienie dla rzadkich przypadków, w których jest on wymagany.
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'Polecenie ss wyświetla procesy przypisane do poszczególnych portów, co pozwala potwierdzić, czy aplikacja faktycznie nasłuchuje tam, gdzie wskazuje proxy_pass.
Awarie, z którymi faktycznie się zetkniesz
502 Bad Gateway, z connect() failed (111: Connection refused) while connecting to upstream w dzienniku błędów. Pod adresem w proxy_pass nikt nie nasłuchuje. Aplikacja jest zatrzymana, przypisana do innego portu lub powiązana z adresem wewnętrznym kontenera, do którego host nie ma dostępu.
502 z no live upstreams while connecting to upstream. Każdy serwer w bloku upstream jest obecnie oznaczony przez max_fails jako niedziałający. Napraw backendy. Nginx ponowi próbę połączenia, gdy wygaśnie fail_timeout.
504 Gateway Time-out, z upstream timed out (110: Connection timed out) while reading response header from upstream. Backend zaakceptował połączenie, a następnie nie wysłał żadnych danych przez proxy_read_timeout sekund. Zwiększenie limitu czasu jest właściwe dla faktycznie wolno generowanego raportu, ale błędne w przypadku zawieszonej aplikacji.
Każda ścieżka zwraca 404 z poziomu aplikacji. Reguła dotycząca końcowego ukośnika nadpisała ścieżkę. Porównaj ścieżkę zapisaną w logach aplikacji ze ścieżką, o którą wysłano żądanie.
Odpowiada inna witryna. server_name nie pasuje do nagłówka Host, więc żądanie zostało przekierowane do bloku default_server.
Strona ładuje się, a następnie interfejs zawiesza się po około minucie. To przypadek związany z WebSocket: brakuje obsługi Upgrade lub proxy_read_timeout nadal wynosi 60 sekund.
FAQ
Dlaczego nginx zwraca 502 Bad Gateway po dodaniu proxy_pass?
nginx nie może nawiązać połączenia z adresem wskazanym w proxy_pass. Dziennik błędów w /var/log/nginx/error.log wskazuje przyczynę: connect() failed (111: Connection refused) while connecting to upstream oznacza, że pod wskazanym adresem żadna usługa nie nasłuchuje, natomiast no live upstreams oznacza, że wszystkie serwery w bloku upstream zostały oznaczone jako niedziałające. Uruchom sudo ss -lntp | grep 3000, aby sprawdzić, który proces zajmuje port i do jakiego adresu jest przypisany. Aplikacja powiązana z adresem wewnętrznym kontenera lub innym portem niż zdefiniowany w konfiguracji zawsze wywoła ten błąd.
Dlaczego aplikacja rozłącza się po około minucie pracy za nginx?
Połączenie jest typu WebSocket, a wartość proxy_read_timeout wynosi domyślnie 60 sekund, co określa czas bezczynności między odczytami z backendu. Nieaktywne gniazdo jest zamykane przez nginx, a konsola przeglądarki zgłasza kod zamknięcia 1006. Ustaw proxy_http_version 1.1 (wartość domyślna od nginx 1.29.7, nieobecna w pakiecie 1.24.0 dostępnym w Ubuntu 24.04), przekaż nagłówki Upgrade oraz Connection za pomocą map w $http_upgrade i zwiększ proxy_read_timeout do wartości takiej jak 3600s. Bez nagłówka Upgrade proces aktualizacji połączenia nie nastąpi, co spowoduje, że aplikacja przełączy się na odpytywanie (polling) lub przestanie wyświetlać aktualizacje w czasie rzeczywistym.
Czy końcowy ukośnik w proxy_pass ma znaczenie?
Tak, zmienia on ścieżkę otrzymywaną przez backend. W przypadku location /app/ oraz proxy_pass http://127.0.0.1:3000/, żądanie dla /app/status dociera do backendu jako /status, ponieważ każdy identyfikator URI po hoście i porcie zastępuje dopasowany prefiks lokalizacji. Usunięcie końcowego ukośnika spowoduje, że to samo żądanie dotrze jako /app/status. Usunięcie prefiksu często powoduje błędy w linkach do zasobów aplikacji, które pozostają bezwzględne i zwracają błąd 404 w katalogu głównym, dlatego aplikację z ustawioną ścieżką bazową lepiej obsługiwać w sposób przekazujący pełną ścieżkę.
Dlaczego aplikacja loguje 127.0.0.1 jako adres IP każdego odwiedzającego?
Ponieważ połączenie docierające do aplikacji faktycznie pochodzi z nginx na adresie pętli zwrotnej (loopback). Adres odwiedzającego dociera do aplikacji tylko w nagłówku, który należy ustawić: proxy_set_header X-Real-IP $remote_addr; dla pojedynczej wartości oraz proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; dla dołączanego łańcucha. Aplikacja musi zostać skonfigurowana tak, aby ufała tym nagłówkom. Należy pamiętać, że klient może wysłać własny nagłówek X-Forwarded-For, dlatego gdy nginx pełni rolę serwera brzegowego, należy go nadpisać za pomocą $remote_addr zamiast dopisywać wartość.
Czy połączenie między nginx a aplikacją wymaga TLS?
Nie, jeśli aplikacja działa na tym samym serwerze i jest powiązana z 127.0.0.1, ponieważ ruch ten nie opuszcza maszyny. Terminację TLS należy wykonać na nginx, utrzymać proxy_pass jako zwykłe HTTP wewnątrz pętli zwrotnej i wysłać X-Forwarded-Proto $scheme, aby aplikacja wiedziała, że odwiedzający użył HTTPS. Jeśli backend znajduje się na innym hoście w sieci, nad którą nie sprawuje się kontroli, ten odcinek wymaga własnego zabezpieczenia, poprzez HTTPS do backendu lub prywatny tunel między obiema maszynami.