Jak opravit chybu „Nginx 502 Bad Gateway“ při proxyování k Node.js

Chyba NGINX 502 Bad Gateway před aplikací Node.js obvykle znamená jednu věc: NGINX přijal požadavek klienta, ale nemohl získat použitelnou odpověď od nadřazené aplikace, se kterou měl kontaktovat. Nejrychlejší opravou proto není restartovat vše ani pokaždé nevyvolávat časový limit. Nejprve ověřte, zda je služba Node.js dostupná ze stejného síťového umístění jako NGINX, a poté použijte protokol chyb NGINX k výběru dalšího kroku.

Tato příručka používá čtyři diagnostické kroky. Příkazy předpokládají hostitele Linux a aplikaci Node.js očekávanou na portu 3000. Nahraďte port, název hostitele, cesty a názvy služeb hodnotami ve vašem nasazení.

Co byste měli zkontrolovat před změnou NGINX?

Nejprve si položte tři otázky:

• Naslouchá proces Node.js skutečně na adrese a portu, ke kterému se NGINX snaží připojit?
• Jakou přesnou chybu v upstreamu zaznamenává protokol chyb NGINX pro neúspěšný požadavek?
• Běží NGINX a Node.js na stejném hostiteli, v oddělených kontejnerech nebo na oddělených počítačích?

Tyto odpovědi jsou důležité, protože stejná chyba 502 viditelná v prohlížeči může pocházet z velmi odlišných podmínek. Zastavený proces uzlu, nesprávný proxy_passport, nesprávné použití kontejneru 127.0.0.1, časový limit upstreamu a neplatná odpověď upstreamu nemají stejnou opravu.

NGINX dokumentuje proxy_passjako direktivu, která specifikuje protokol a adresu proxy serveru. Jeho upstream modul také zpřístupňuje proměnné jako $upstream_addr, $upstream_status, $upstream_connect_timea $upstream_response_time, které jsou užitečné, když potřebujete podrobnější produkční protokolování. Viz oficiální dokumentaci k proxy modulu NGINX a dokumentaci k upstream modulu NGINX .

Krok 1: Lze se k upstreamu NGINX dostat přímo?

Začněte obejitím reverzní proxy. Pokud je NGINX na stejném hostiteli jako Node.js a vaše konfigurace ukazuje na 127.0.0.1:3000, otestujte přesně tento cíl:

curl -i http://127.0.0.1:3000/health
ss -ltnp | grep ':3000'

V pořádku může vaše aplikace vrátit HTTP 200 a zobrazit posluchač na portu 3000. Pokud je připojení odmítnuto, zatím neupravujte časové limity NGINX. Na adrese, kterou se NGINX pokouší použít, není žádná naslouchací služba nebo služba naslouchá někde jinde.

Co když proces Node.js běží, ale chybí port?

Spuštěný proces nestačí. Aplikace musí dokončit spuštění serveru a úspěšně navázat naslouchací socket. Node.js dokumentuje server.listen()operaci, která spustí TCP nebo IPC server naslouchající připojením. Také uvádí, že EADDRINUSEk tomu dochází, když jiný server již vlastní požadovaný port. Projděte si oficiální dokumentaci k Node.js NET serveru a dokumentaci k Node.js HTTP .

Minimální testovací služba HTTP pro Node.js může vypadat takto:

import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200, { 'content-type': 'application/json' });
    return res.end(JSON.stringify({ status: 'ok' }));
  }

  res.writeHead(200, { 'content-type': 'text/plain' });
  res.end('Node.js is running');
});

server.listen(3000, '127.0.0.1', () => {
  console.log('Listening on http://127.0.0.1:3000');
});

Vazba na 127.0.0.1je vhodná, když NGINX a Node.js sdílejí stejného hostitele a žádný jiný počítač nepotřebuje přímý přístup k portu Node. Pokud jsou v oddělených kontejnerech, má tato adresa jiný význam, který je popsán níže.

Krok 2: Co vlastně říká chybový protokol NGINX?

Jakmile zjistíte, zda upstream reaguje přímo, zkontrolujte položku protokolu vytvořenou současně s chybou 502. Běžným umístěním v balíčcích Linuxu je /var/log/nginx/error.log, ale skutečná cesta je řízena direktivou error_loga může se lišit v závislosti na instalaci.

sudo tail -n 100 /var/log/nginx/error.log

V základní dokumentaci k NGINX se uvádí, že error_logdefinuje cíl a závažnost diagnostického protokolu. Dokumentace k příkazovému řádku také nabízí nginx -Ttestování a výpis aktivní konfigurace, což vám může pomoci najít neočekávanou cestu k protokolu nebo blok serveru. Viz dokumentace k základnímu protokolování NGINX a parametry příkazového řádku NGINX .

Použijte zprávu k upřesnění problému:

Krok 3: Odkazuje proxy_pass na adresu, kterou Node.js skutečně používá?

Porovnejte živý listener z kroku 1 s aktivní konfigurací NGINX. Konvenční nastavení na stejném hostiteli vypadá takto:

server {
    listen 80;
    server_name example.com;

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

NGINX oficiálně podporuje IP adresu, název hostitele, skupinu nadřazeného proudu nebo soket domény UNIX v proxy_pass. Kritické pravidlo je jednoduché: cíl musí být dosažitelný ze síťového kontextu workera NGINX.

Jsou NGINX a Node.js v samostatných kontejnerech Docker Compose?

Pokud ano, pak 127.0.0.1uvnitř kontejneru NGINX odkazuje na samotný kontejner NGINX, nikoli na kontejner Node.js. Dokumentace Docker Compose uvádí, že služby ve výchozí síti Compose jsou zjistitelné podle názvu služby. Také doporučuje používat pro komunikaci mezi službami port kontejneru, nikoli port publikovaný hostitelem.

Například pokud je služba Compose pojmenována appa Node naslouchá na portu kontejneru 3000, může NGINX použít:

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

Obě služby musí sdílet síť. Služba Node musí také naslouchat na rozhraní dostupném z dané kontejnerové sítě; aplikace se 0.0.0.0pro tento účel běžně vážou na rozhraní uvnitř kontejneru. Nemusíte nutně publikovat port 3000 na hostiteli pouze pro provoz NGINX-to-app. Ověřte topologii podle oficiální dokumentace k síti Docker Compose .

Měli byste použít localhost nebo 127.0.0.1?

Pokud oba procesy běží na stejném hostiteli, může kterýkoli z nich fungovat, ale nejsou vždy zaměnitelné v každém prostředí, protože localhostse mohou převést na IPv4, IPv6 nebo obojí. Použití přesné adresy zobrazené listenerem odstraní jednu proměnnou. Node.js dokumentuje, že pokud hostje argument vynechán, může naslouchat na nespecifikované adrese IPv6, ::pokud je k dispozici, nebo na nespecifikované adrese IPv4 0.0.0.0v opačném případě.

Pokud narazíte na neshodu, například když NGINX kontaktuje 127.0.0.1:3000aplikaci, zatímco je dostupná pouze prostřednictvím jiného názvu hostitele kontejneru, jiného portu nebo socketu UNIX, opravte adresu, místo abyste ji kompenzovali opakovanými pokusy.

Je delší časový limit skutečně správným řešením?

Časové limity měňte pouze tehdy, když logy ukazují časový limit a chápete, proč upstream potřebuje delší. NGINX dokumentuje výchozí hodnotu proxy_connect_timeout60 sekund a poznamenává, že obvykle nemůže překročit 75 sekund. Také dokumentuje výchozí hodnotu proxy_read_timeout60 sekund, měřeno mezi po sobě jdoucími čteními z upstreamu, nikoli v celé odpovědi.

location /reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 5s;
    proxy_read_timeout 120s;
}

Výše uvedený příklad není univerzálním doporučením. Nízký časový limit pro připojení může dávat smysl pro lokální upstream, který by se měl připojit téměř okamžitě, zatímco delší časový limit pro čtení může být opodstatněný pro legitimně dlouhý požadavek. Pokud je však aplikace pomalá kvůli blokované smyčce událostí, zablokování databáze, přetížené závislosti nebo zablokovanému požadavku, prodloužení časového limitu pouze skryje příznak.

Zkontrolujte přesnou sémantiku v oficiálních direktivách timeoutu proxy NGINX .

Co když chybu 502 nebo odpojení dostanou pouze připojení WebSocket?

Proxying WebSocket má další požadavky, protože hlavičky Upgradea Connectionjsou hlavičky typu hop-by-hop a nejsou automaticky přeposílány v běžné cestě reverzní proxy. Oficiální dokumentace WebSocketu NGINX ukazuje explicitní nastavení těchto hlaviček.

location /socket/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

NGINX také poznamenává, že nečinné proxyované připojení WebSocket se ukončí, pokud upstream neodešle žádná data během intervalu čtení; příkaz ping na úrovni aplikace může v případě potřeby udržet připojení aktivní. Aktuální chování a poznámky specifické pro verzi naleznete v oficiální dokumentaci k proxyování WebSocket NGINX .

Krok 4: Jak ověříte opravu, aniž byste způsobili nový výpadek?

Před opětovným načtením NGINX otestujte konfiguraci:

sudo nginx -t
sudo nginx -s reload

NGINX dokumentuje -tjako kontrolu syntaxe a odkazovaných souborů a -s reloadjako signál, který znovu načítá konfiguraci spuštěním nových workerů a elegantním vypnutím starých.

Pak znovu ověřte obě vrstvy:

curl -i http://127.0.0.1:3000/health
curl -I https://example.com/

Nezastavujte se u „načtení domovské stránky“. Znovu otestujte trasu, která původně selhala, včetně její metody HTTP a veškerého těla požadavku. Pokud se chyba 502 vyskytovala pouze při nahrávání, voláních API, velkých sestavách nebo WebSocketech, otestujte stejný vzorec provozu.

Co když přímé požadavky Node.js fungují, ale NGINX stále vrací 502?

Tento výsledek podstatně zužuje rozsah problému. Zkontrolujte tyto položky v tomto pořadí:

1. Potvrďte aktivní blok serveru. Spusťte sudo nginx -Ta ujistěte se, že očekávané funkce server_namea locationfunkce zpracovávají požadavek.
2. Potvrďte přesný cílový server. Adresa v adresáři proxy_passmusí odpovídat adrese dosažitelné z NGINX, nikoli pouze adrese fungující z vašeho notebooku nebo jiného kontejneru.
3. Zkontrolujte neshodu protokolů. Pokud upstream očekává HTTPS, ale NGINX používá http://, nebo naopak, opravte schéma a poté záměrně nakonfigurujte upstream TLS.
4. Hledejte resetování připojení aplikace. Zkontrolujte protokoly procesů Node.js ve stejném časovém razítku jako chyba NGINX. Havárie nebo přerušené připojení vyžaduje opravu na straně aplikace.
5. Zkontrolujte specializovaný provoz. WebSockety, streamované odpovědi, velké požadavky a neobvykle pomalé obslužné rutiny mohou vyžadovat odlišná nastavení proxy serveru od jednoduchého JSON API.

Pokud jsou NGINX a Node.js odděleny firewallem, službou Kubernetes, vyrovnávačem zátěže, sítí služeb nebo jiným proxy serverem, nemusí selhávajícím hopem být lokální připojení NGINX-Node. Otestujte každý hop samostatně, místo abyste předpokládali, že zdrojem selhání je viditelný server NGINX.

Měli byste nejdříve restartovat Node.js nebo NGINX?

Restart je vhodný, pokud máte důkazy o tom, že je proces zastaven, není v pořádku nebo má zastaralou konfiguraci. Není to nejlepší první diagnostický krok, protože může vymazat stopy a dočasně odstranit občasný problém.

Pokud port Node chybí, zkontrolujte protokoly správce procesů nebo kontejneru, opravte problém se spuštěním aplikace a poté spusťte službu. Pokud jste změnili pouze konfiguraci NGINX, použijte ji nginx -tpřed opětovným načtením. Pokud jste změnili kód Node.js nebo proměnné prostředí, restartujte službu Node pomocí supervizora, který vaše nasazení skutečně používá, například systemd, orchestrátor kontejnerů nebo jiný správce procesů.

V případě produkční verze Node.js ověřte také, zda se nacházíte na podporované řadě vydání. Od září 2026 oficiální stránka s vydáními Node.js uvádí Node.js 24 a 22 jako řady LTS a doporučuje, aby produkční aplikace používaly verze Active LTS nebo Maintenance LTS. Aktuální stav si ověřte na oficiální stránce s vydáními Node.js, místo abyste se spoléhali na starý tutoriál.

Kompaktní rozhodovací tabulka NGINX 502

Závěrečná samokontrola

Pravděpodobně jste odstranili hlavní příčinu, spíše než abyste pouze potlačili příznak, pokud platí všechny následující podmínky:

• Upstream Node.js reaguje přímo ze stejného síťového kontextu, jaký používá NGINX.
• Posluchač uzlu a proxy_passdohoda o protokolu, adrese a portu.
• Protokol chyb NGINX již nezaznamenává selhání připojení k nadřazenému serveru pro postiženou trasu.
• nginx -tuspěje před každým opětovným načtením konfigurace.
• Původní neúspěšný požadavek – nejen domovská stránka – nyní úspěšně odeslaný přes NGINX.
• Časové limity byly změněny pouze tehdy, když protokoly a naměřené chování aplikací změnu odůvodňovaly.
• Nasazení kontejnerů využívá síťování typu služba-služba, spíše než předpokládá 127.0.0.1překračování hranic kontejnerů.

Nejspolehlivějším vzorem pro řešení problémů je proto: otestovat uzel přímo, přečíst chybu NGINX, porovnat adresu upstreamu se skutečnou topologií sítě, poté ověřit a znovu načíst . Kód 502 je příznakem brány. Užitečnou otázkou vždy je, který směrovací uzel selhal a co o tomto selhání říká protokol.