Ako opraviť chybu „Nginx 502 Bad Gateway“ pri proxyovaní do Node.js

Chyba NGINX 502 Bad Gateway pred aplikáciou Node.js zvyčajne znamená jednu vec: NGINX prijal požiadavku klienta, ale nedokázal získať použiteľnú odpoveď od nadradenej aplikácie, s ktorou sa mal spojiť. Najrýchlejšou opravou preto nie je všetko reštartovať ani pri každom prekročení časového limitu. Najprv overte, či je služba Node.js dostupná z rovnakého sieťového umiestnenia ako NGINX, a potom použite protokol chýb NGINX na výber ďalšieho kroku.

Táto príručka používa štyri diagnostické kroky. Príkazy predpokladajú hostiteľa so systémom Linux a aplikáciu Node.js, ktorá sa očakáva na porte 3000. Nahraďte port, názov hostiteľa, cesty a názvy služieb hodnotami vo vašom nasadení.

Čo by ste mali skontrolovať pred zmenou NGINX?

Najprv si položte tri otázky:

• Načúva proces Node.js skutočne na adrese a porte, na ktorý sa NGINX snaží pripojiť?
• Akú presnú chybu v upstreame zaznamenáva protokol chýb NGINX pre neúspešnú požiadavku?
• Bežia NGINX a Node.js na rovnakom hostiteľovi, v samostatných kontajneroch alebo na samostatných počítačoch?

Tieto odpovede sú dôležité, pretože tá istá chyba 502 viditeľná v prehliadači môže pochádzať z veľmi odlišných podmienok. Zastavený proces uzla, nesprávny proxy_passport, nesprávne používanie kontajnera 127.0.0.1, časový limit upstreamu a neplatná odpoveď upstreamu nemajú rovnaké riešenie.

NGINX je dokumentovaný proxy_passako direktíva, ktorá špecifikuje protokol a adresu proxy servera. Jeho upstream modul tiež sprístupňuje premenné ako $upstream_addr, $upstream_status, $upstream_connect_timea $upstream_response_time, ktoré sú užitočné, keď potrebujete podrobnejšie produkčné protokolovanie. Pozrite si oficiálnu dokumentáciu k proxy modulu NGINX a dokumentáciu k upstream modulu NGINX .

Krok 1: Dá sa priamo dosiahnuť upstream NGINX?

Začnite obídením reverznej proxy. Ak je NGINX na rovnakom hostiteľovi ako Node.js a vaša konfigurácia ukazuje na 127.0.0.1:3000, otestujte presný cieľ:

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

V poriadku môže vaša aplikácia vrátiť HTTP 200 a zobraziť poslucháč na porte 3000. Ak je pripojenie odmietnuté, zatiaľ neupravujte časové limity NGINX. Na adrese, ktorú sa NGINX pokúša použiť, nie je žiadna počúvacia služba alebo služba počúva niekde inde.

Čo ak proces Node.js beží, ale chýba port?

Spustený proces nestačí. Aplikácia musí dokončiť spustenie servera a úspešne sa pripojiť k počúvajúcemu socketu. Node.js to dokumentuje server.listen()ako operáciu, ktorá spúšťa TCP alebo IPC server, ktorý počúva pripojenia. Taktiež sa v ňom uvádza, že EADDRINUSEk tomu dochádza, keď iný server už vlastní požadovaný port. Prečítajte si oficiálnu dokumentáciu k sieťovému serveru Node.js a dokumentáciu k HTTP Node.js.

Minimálna testovacia služba HTTP pre Node.js môže vyzerať 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');
});

Väzba na 127.0.0.1je vhodná, keď NGINX a Node.js zdieľajú toho istého hostiteľa a žiadny iný počítač nepotrebuje priamy prístup k portu Node. Ak sú v samostatných kontajneroch, táto adresa má iný význam, ktorý je uvedený nižšie.

Krok 2: Čo vlastne hovorí protokol chýb NGINX?

Keď zistíte, či upstream reaguje priamo, skontrolujte záznam v protokole vytvorený súčasne s chybou 502. Bežné umiestnenie v balíkoch Linuxu je /var/log/nginx/error.log, ale skutočná cesta je riadená direktívou error_loga môže sa líšiť v závislosti od inštalácie.

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

V základnej dokumentácii NGINX sa uvádza, že error_logriadi cieľ a závažnosť diagnostického protokolu. Dokumentácia príkazového riadka tiež umožňuje nginx -Ttestovať a vytvárať výpis aktívnej konfigurácie, čo vám môže pomôcť nájsť neočakávanú cestu k protokolu alebo blok servera. Pozrite si dokumentáciu k základnému protokolovaniu NGINX a parametre príkazového riadka NGINX .

Na zúženie problému použite správu:

Krok 3: Odkazuje proxy_pass na adresu, ktorú Node.js skutočne používa?

Porovnajte živý listener z kroku 1 s aktívnou konfiguráciou NGINX. Konvenčné nastavenie na rovnakom hostiteľovi vyzerá 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álne podporuje IP adresu, názov hostiteľa, skupinu nadradených používateľov alebo soket domény UNIX v proxy_pass. Kritické pravidlo je jednoduché: cieľ musí byť dosiahnuteľný zo sieťového kontextu pracovníka NGINX.

Sú NGINX a Node.js v samostatných kontajneroch Docker Compose?

Ak áno, 127.0.0.1vnútro kontajnera NGINX odkazuje na samotný kontajner NGINX, nie na kontajner Node.js. Dokumentácia Docker Compose uvádza, že služby v predvolenej sieti Compose sú objaviteľné podľa názvu služby. Taktiež odporúča používať na komunikáciu medzi službami port kontajnera namiesto portu publikovaného hostiteľom.

Napríklad, ak je služba Compose pomenovaná appa Node počúva na kontajnerovom porte 3000, NGINX môže použiť:

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

Obe služby musia zdieľať sieť. Služba Node musí tiež počúvať na rozhraní dostupnom z tejto kontajnerovej siete; aplikácie sa 0.0.0.0na tento účel bežne viažu na kontajner. Nie je nevyhnutné publikovať port 3000 na hostiteľovi len pre prevádzku medzi NGINX a aplikáciou. Overte topológiu podľa oficiálnej sieťovej dokumentácie Docker Compose .

Mali by ste použiť localhost alebo 127.0.0.1?

Ak oba procesy bežia na rovnakom hostiteľovi, ktorýkoľvek z nich môže fungovať, ale nie sú vždy zameniteľné v každom prostredí, pretože localhostsa môžu preložiť na IPv4, IPv6 alebo oba. Použitie presnej adresy zobrazenej listenerom odstráni jednu premennú. Node.js dokumentuje, že ak hostje argument vynechaný, môže počúvať na nešpecifikovanej adrese IPv6, ::ak je k dispozícii, alebo na nešpecifikovanej adrese IPv4 0.0.0.0v opačnom prípade.

Ak vidíte nezhodu, napríklad kontaktovanie NGINX, 127.0.0.1:3000zatiaľ čo aplikácia je dostupná iba prostredníctvom iného názvu hostiteľa kontajnera, iného portu alebo socketu UNIX, opravte adresu namiesto kompenzácie opakovanými pokusmi.

Je dlhší časový limit skutočne správnym riešením?

Časové limity zmeňte iba vtedy, keď protokoly ukazujú časový limit a rozumiete, prečo upstream potrebuje dlhší čas. NGINX dokumentuje predvolenú hodnotu proxy_connect_timeout60 sekúnd a poznamenáva, že zvyčajne nemôže presiahnuť 75 sekúnd. Taktiež dokumentuje predvolenú hodnotu proxy_read_timeout60 sekúnd, meranú medzi po sebe idúcimi čítaniami z upstreamu, a nie v celej odpovedi.

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

Vyššie uvedený príklad nie je univerzálnym odporúčaním. Nízky časový limit pripojenia môže mať zmysel pre lokálny upstream, ktorý by sa mal pripojiť takmer okamžite, zatiaľ čo dlhší časový limit čítania môže byť opodstatnený pre legitímne dlhú požiadavku. Ak je však aplikácia pomalá kvôli blokovanej slučke udalostí, zastaveniu databázy, preťaženej závislosti alebo zamrznutej požiadavke, zvýšenie časového limitu iba skryje príznak.

Skontrolujte presnú sémantiku v oficiálnych direktívach časového limitu proxy NGINX .

Čo ak sa chyba 502 alebo odpojenie dostanú iba cez pripojenia WebSocket?

Proxying cez WebSocket má ďalšie požiadavky, pretože hlavičky Upgradea Connectionsú hlavičky typu hop-by-hop a nie sú automaticky preposielané v bežnej ceste reverznej proxy. Oficiálna dokumentácia k WebSocketu od NGINX explicitne ukazuje nastavenie týchto hlavičiek.

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

NGINX tiež poznamenáva, že nečinné proxy pripojenie WebSocket sa ukončí, ak upstream neodošle žiadne dáta v rámci intervalu čítania; ping na úrovni aplikácie môže v prípade potreby udržať pripojenie aktívne. Aktuálne správanie a poznámky týkajúce sa konkrétnej verzie nájdete v oficiálnej dokumentácii k proxyovaniu WebSocket NGINX .

Krok 4: Ako overíte opravu bez toho, aby ste spôsobili nový výpadok?

Pred opätovným načítaním NGINX otestujte konfiguráciu:

sudo nginx -t
sudo nginx -s reload

NGINX dokumentuje -tako kontrolu syntaxe a referenčných súborov a -s reloadako signál, ktorý znovu načíta konfiguráciu spustením nových pracovníkov a elegantným vypnutím starých.

Potom znova overte obe vrstvy:

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

Nezastavujte sa pri „načítaní domovskej stránky“. Znovu otestujte trasu, ktorá pôvodne zlyhala, vrátane jej metódy HTTP a tela požiadavky. Ak sa chyba 502 vyskytla iba pri nahrávaní, volaniach API, veľkých prehľadoch alebo WebSocketoch, otestujte rovnaký vzorec prenosu.

Čo ak priame požiadavky Node.js fungujú, ale NGINX stále vracia 502?

Tento výsledok podstatne zužuje problém. Skontrolujte tieto položky v tomto poradí:

1. Potvrďte aktívny blok servera. Spustite ho sudo nginx -Ta uistite sa, že očakávaný server_namea locationspracováva požiadavku.
2. Potvrďte presný cieľ v upstreame. Adresa v bode proxy_passsa musí zhodovať s adresou dostupnou z NGINX, nielen s adresou fungujúcou z vášho notebooku alebo iného kontajnera.
3. Skontrolujte nesúlad protokolov. Ak upstream očakáva HTTPS, ale NGINX používa http://, alebo naopak, opravte schému a potom zámerne nakonfigurujte upstream TLS.
4. Hľadajte resetovania pripojenia aplikácie. Skontrolujte protokoly procesu Node.js v rovnakom časovom intervale ako chyba NGINX. Pád alebo prerušené pripojenie vyžaduje opravu na strane aplikácie.
5. Skontrolujte špecializovanú prevádzku. WebSockety, streamované odpovede, veľké požiadavky a nezvyčajne pomalé obslužné programy môžu vyžadovať odlišné nastavenia proxy od jednoduchého rozhrania JSON API.

Ak sú NGINX a Node.js oddelené firewallom, službou Kubernetes, vyrovnávačom záťaže, sieťou služieb alebo iným proxy serverom, zlyhávajúcim prechodom nemusí byť lokálne pripojenie NGINX-Node. Otestujte každý prechod samostatne, namiesto toho, aby ste predpokladali, že zdrojom zlyhania je viditeľný server NGINX.

Mali by ste najprv reštartovať Node.js alebo NGINX?

Reštart je vhodný, keď máte dôkazy o tom, že proces je zastavený, nefunkčný alebo má zastaranú konfiguráciu. Nie je to najlepší prvý diagnostický krok, pretože môže vymazať stopy a dočasne odstrániť občasný problém.

Ak chýba port Node, skontrolujte protokoly správcu procesov alebo kontajnerov, opravte problém so spustením aplikácie a potom spustite službu. Ak ste zmenili iba konfiguráciu NGINX, použite ju nginx -tpred opätovným načítaním. Ak ste zmenili kód Node.js alebo premenné prostredia, reštartujte službu Node pomocou supervízora, ktorý vaše nasadenie skutočne používa, ako je napríklad systemd, orchestrátor kontajnerov alebo iný správca procesov.

V prípade produkčného Node.js si overte aj, či sa nachádzate na podporovanom rade vydaní. Od septembra 2026 oficiálna stránka s vydaniami Node.js uvádza Node.js 24 a 22 ako rady LTS a odporúča, aby produkčné aplikácie používali vydania Active LTS alebo Maintenance LTS. Aktuálny stav si overte na oficiálnej stránke s vydaniami Node.js, namiesto toho, aby ste sa spoliehali na starý tutoriál.

Kompaktná rozhodovacia tabuľka NGINX 502

Záverečná samokontrola

Pravdepodobne ste odstránili hlavnú príčinu, a nie len potlačili príznak, keď sú splnené všetky nasledujúce podmienky:

• Upstream Node.js reaguje priamo z rovnakého sieťového kontextu, aký používa NGINX.
• Poslucháč uzla sa proxy_passdohodne na protokole, adrese a porte.
• Denník chýb NGINX už nezaznamenáva zlyhania pripojenia proti prúdu pre dotknutú trasu.
• nginx -tuspeje pred každým opätovným načítaním konfigurácie.
• Pôvodná neúspešná požiadavka – nielen domovská stránka – je teraz úspešná cez NGINX.
• Časové limity sa menili iba vtedy, keď protokoly a namerané správanie aplikácií zmenu odôvodňovali.
• Nasadenie kontajnerov využíva sieťovanie medzi službami, namiesto predpokladu 127.0.0.1prekročenia hraníc kontajnerov.

Najspoľahlivejší vzor riešenia problémov je preto: priamo otestovať uzol, prečítať chybu NGINX, porovnať adresu upstreamu so skutočnou topológiou siete, potom overiť a znova načítať . Kód 502 je príznakom brány. Užitočnou otázkou vždy je, ktorý skok zlyhal a čo o tomto zlyhaní hovorí protokol.