Kako popraviti "Nginx 502 Bad Gateway" prilikom proxyja za Node.js

NGINX 502 Bad Gateway ispred Node.js aplikacije obično znači jedno: NGINX je prihvatio zahtjev klijenta, ali nije mogao dobiti upotrebljiv odgovor od uzvodne aplikacije s kojom je trebao kontaktirati. Stoga najbrže rješenje nije ponovno pokretanje svega ili svako istekanje vremena. Prvo provjerite je li Node.js usluga dostupna s iste mrežne lokacije kao i NGINX, a zatim upotrijebite NGINX zapisnik pogrešaka za odabir sljedećeg poteza.

Ovaj vodič koristi četiri dijagnostička koraka. Naredbe pretpostavljaju Linux host i Node.js aplikaciju koja se očekuje na portu 3000. Zamijenite port, naziv hosta, putanje i nazive usluga vrijednostima u vašem raspoređivanju.

Što biste trebali provjeriti prije promjene NGINX-a?

Prvo postavite tri pitanja:

• Sluša li Node.js proces doista adresu i port koji NGINX pokušava dosegnuti?
• Koju točno uzvodnu grešku NGINX zapisnik grešaka bilježi za neuspjeli zahtjev?
• Izvode li se NGINX i Node.js na istom hostu, u odvojenim kontejnerima ili na odvojenim računalima?

Ti odgovori su važni jer isti 502, vidljiv u pregledniku, može doći iz vrlo različitih uvjeta. Zaustavljeni Node proces, pogrešan proxy_passport, neispravno korištenje kontejnera 127.0.0.1, istek vremena uzvodnog pristupa i nevažeći odgovor uzvodnog pristupa nemaju isto rješenje.

NGINX dokumentira proxy_passkao direktivu koja specificira protokol i adresu proxy poslužitelja. Njegov uzvodni modul također izlaže varijable kao što su $upstream_addr, $upstream_status, $upstream_connect_timei $upstream_response_time, koje su korisne kada vam je potrebno detaljnije bilježenje produkcije. Pogledajte službenu dokumentaciju NGINX proxy modula i dokumentaciju NGINX uzvodnog modula .

Korak 1: Može li se izravno dosegnuti uzvodni NGINX?

Započnite zaobilaženjem obrnutog proxyja. Ako je NGINX na istom hostu kao i Node.js i vaša konfiguracija pokazuje na 127.0.0.1:3000, testirajte to točno odredište:

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

Ispravan rezultat može vratiti HTTP 200 iz vaše aplikacije i prikazati slušača na portu 3000. Ako je veza odbijena, nemojte još uređivati ​​NGINX timeoute. Na adresi koju NGINX pokušava koristiti nema usluge slušanja ili usluga sluša negdje drugdje.

Što ako se Node.js proces izvodi, ali nedostaje port?

Pokrenuti proces nije dovoljan. Aplikacija mora dovršiti pokretanje poslužitelja i uspješno se povezati s utičnicom za slušanje. Node.js dokumentira server.listen()operaciju koja pokreće TCP ili IPC poslužitelj koji osluškuje veze. Također napominje da se to EADDRINUSEdogađa kada drugi poslužitelj već posjeduje traženi port. Pregledajte službenu dokumentaciju Node.js net poslužitelja i Node.js HTTP dokumentaciju .

Minimalna Node.js HTTP testna usluga može izgledati ovako:

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

Povezivanje na 127.0.0.1je prikladno kada NGINX i Node.js dijele isti host i nijedno drugo računalo ne treba izravan pristup Node portu. Ako su u odvojenim spremnicima, ta adresa ima drugačije značenje, što je objašnjeno u nastavku.

Korak 2: Što zapravo kaže zapisnik grešaka NGINX-a?

Nakon što saznate odgovara li uzvodni sustav izravno, provjerite unos u dnevniku koji se generira istovremeno s 502. Uobičajena lokacija na Linux paketima je /var/log/nginx/error.log, ali stvarna putanja je kontrolirana direktivom error_logi može se razlikovati ovisno o instalaciji.

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

U osnovnoj dokumentaciji NGINX-a navodi se da error_logkontrolira odredište i ozbiljnost dijagnostičkog zapisnika. Dokumentacija naredbenog retka također omogućuje nginx -Ttestiranje i ispis aktivne konfiguracije, što vam može pomoći u pronalaženju neočekivane putanje zapisnika ili bloka poslužitelja. Pogledajte dokumentaciju o osnovnom zapisniku NGINX-a i parametre naredbenog retka NGINX-a .

Upotrijebite poruku za sužavanje problema:

Korak 3: Pokazuje li proxy_pass na adresu koju Node.js stvarno koristi?

Usporedite uživo slušač iz 1. koraka s aktivnom NGINX konfiguracijom. Konvencionalna postavka istog hosta izgleda ovako:

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 službeno podržava IP adresu, naziv hosta, uzvodnu grupu ili UNIX-domenski socket u proxy_pass. Ključno pravilo je jednostavno: odredište mora biti dostupno iz mrežnog konteksta NGINX radnika.

Jesu li NGINX i Node.js u odvojenim Docker Compose kontejnerima?

Ako jesu, 127.0.0.1unutar NGINX kontejnera odnosi se na sam NGINX kontejner, a ne na Node.js kontejner. Dokumentacija Docker Composea navodi da su servisi na zadanoj Compose mreži vidljivi po nazivu servisa. Također preporučuje korištenje porta kontejnera za komunikaciju između servisa, a ne porta koji je objavio host.

Na primjer, ako je usluga Compose imenovana appi Node osluškuje port kontejnera 3000, NGINX može koristiti:

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

Oba servisa moraju dijeliti mrežu. Servis Node također mora osluškivati ​​na sučelju dostupnom iz te kontejnerske mreže; aplikacije se obično vežu 0.0.0.0unutar kontejnera u tu svrhu. Ne morate nužno objaviti port 3000 na hostu samo za promet NGINX-a prema aplikaciji. Provjerite topologiju u odnosu na službenu dokumentaciju o umrežavanju Docker Composea .

Trebate li koristiti localhost ili 127.0.0.1?

Ako se oba procesa izvode na istom hostu, bilo koji od njih može raditi, ali nisu uvijek zamjenjivi u svakom okruženju jer localhostse mogu razlučiti na IPv4, IPv6 ili oboje. Korištenje točne adrese koju prikazuje slušač uklanja jednu varijablu. Node.js dokumentira da ako hostse argument izostavi, može slušati na neodređenoj IPv6 adresi ::kada je dostupna ili na neodređenoj IPv4 adresi 0.0.0.0u suprotnom.

Ako primijetite neusklađenost, poput kontaktiranja NGINX-a 127.0.0.1:3000dok je aplikacija dostupna samo putem drugog naziva glavnog računala spremnika, drugog porta ili UNIX utičnice, ispravite adresu umjesto da je kompenzirate ponovnim pokušajima.

Je li dulje vremensko ograničenje zapravo pravo rješenje?

Vremenska ograničenja mijenjajte samo kada zapisnici pokazuju vremensko ograničenje i kada razumijete zašto uzvodnom dijelu treba više. NGINX dokumentira zadanu vrijednost proxy_connect_timeoutod 60 sekundi i napominje da obično ne može premašiti 75 sekundi. Također dokumentira zadanu vrijednost proxy_read_timeoutod 60 sekundi, mjereno između uzastopnih čitanja iz uzvodnog dijela, a ne kroz cijeli odgovor.

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

Gornji primjer nije univerzalna preporuka. Kratko vrijeme isteka veze može imati smisla za lokalni uzvodni sustav koji bi se trebao povezati gotovo trenutno, dok dulje vrijeme isteka čitanja može biti opravdano za legitimno dugi zahtjev. Ali ako je aplikacija spora zbog blokirane petlje događaja, zastoja baze podataka, preopterećene ovisnosti ili zaglavljenog zahtjeva, povećanje vremena isteka samo skriva simptom.

Pregledajte točnu semantiku u službenim direktivama za timeout proxyja NGINX-a .

Što ako samo WebSocket veze dobiju grešku 502 ili se prekidaju?

WebSocket proxying ima dodatne zahtjeve jer su zaglavlja Upgradei Connectionhop-by-hop zaglavlja i ne prosljeđuju se automatski u uobičajenom putu obrnutog proxyja. Službena NGINX-ova WebSocket dokumentacija eksplicitno pokazuje postavljanje tih zaglavlja.

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

NGINX također napominje da se neaktivna proxyirana WebSocket veza zatvara ako uzvodni poslužitelj ne šalje podatke unutar intervala čekanja za čitanje; ping na razini aplikacije može održati vezu aktivnom gdje je to prikladno. Za trenutno ponašanje i bilješke specifične za verziju, koristite službenu dokumentaciju o proxyiranju NGINX WebSocketa .

Korak 4: Kako potvrditi ispravak bez stvaranja novog prekida?

Testirajte konfiguraciju prije ponovnog učitavanja NGINX-a:

sudo nginx -t
sudo nginx -s reload

NGINX dokumentira -tkao provjeru sintakse i referentnih datoteka te -s reloadkao signal koji ponovno učitava konfiguraciju pokretanjem novih radnika i elegantnim gašenjem starih.

Zatim ponovno provjerite oba sloja:

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

Nemojte stati na "početnoj stranici koja se učitava". Ponovno testirajte rutu koja je izvorno propala, uključujući njezinu HTTP metodu i tijelo zahtjeva. Ako se greška 502 pojavila samo pri prijenosima, API pozivima, velikim izvješćima ili WebSocketima, testirajte isti obrazac prometa.

Što ako izravni Node.js zahtjevi rade, ali NGINX i dalje vraća 502?

Taj rezultat znatno sužava problem. Provjerite ove stavke redom:

1. Potvrdite aktivni blok poslužitelja. Pokrenite sudo nginx -Ti provjerite da li očekivani server_namei locationobrađuju zahtjev.
2. Potvrdite točan uzvodni cilj. Adresa u proxy_passmora odgovarati onome što je dostupno s NGINX-a, a ne samo onome što radi s vašeg prijenosnog računala ili drugog spremnika.
3. Provjerite neusklađenost protokola. Ako uzvodni protokol očekuje HTTPS, ali NGINX koristi http://, ili obrnuto, ispravite shemu, a zatim namjerno konfigurirajte uzvodni TLS.
4. Potražite resetiranja veze aplikacije. Pregledajte zapisnike procesa Node.js u istom vremenskom žigu kao i NGINX greška. Pad sustava ili prekinuta veza zahtijeva ispravak na strani aplikacije.
5. Provjerite specijalizirani promet. WebSocketi, odgovori strujanja, veliki zahtjevi i neuobičajeno spori rukovatelji mogu zahtijevati drugačije postavke proxyja od jednostavnog JSON API-ja.

Ako su NGINX i Node.js odvojeni vatrozidom, Kubernetes uslugom, uravnoteživačem opterećenja, mrežom usluga ili nekim drugim proxyjem, neuspjeli skok možda nije lokalna NGINX-to-Node veza. Testirajte svaki skok zasebno umjesto da pretpostavljate da je vidljivi NGINX poslužitelj izvor kvara.

Trebate li prvo ponovno pokrenuti Node.js ili NGINX?

Ponovno pokretanje je prikladno kada imate dokaze da je proces zaustavljen, neispravan ili da ima zastarjelu konfiguraciju. To nije najbolja prva dijagnostička radnja jer može izbrisati tragove i privremeno ukloniti povremeni problem.

Ako nema Node porta, provjerite zapisnike upravitelja procesa ili spremnika, ispravite problem s pokretanjem aplikacije, a zatim pokrenite uslugu. Ako ste promijenili samo konfiguraciju NGINX-a, upotrijebite oznaku nginx -tprije ponovnog učitavanja. Ako ste promijenili Node.js kod ili varijable okruženja, ponovno pokrenite Node uslugu pomoću nadzornika koji vaše raspoređivanje zapravo koristi, kao što je systemd, orkestrator spremnika ili neki drugi upravitelj procesa.

Za produkcijski Node.js, također provjerite jeste li na podržanoj liniji izdanja. Od rujna 2026., službena stranica izdanja Node.js navodi Node.js 24 i 22 kao LTS linije i preporučuje da produkcijske aplikacije koriste Active LTS ili Maintenance LTS izdanja. Provjerite trenutni status na službenoj stranici izdanja Node.js umjesto da se oslanjate na stari vodič.

Kompaktna NGINX 502 tablica odluka

Završna samoprovjera

Vjerojatno ste riješili uzrok problema, umjesto da samo potisnete simptom, kada su svi sljedeći uvjeti istiniti:

• Node.js uzvodni dio odgovara izravno iz istog mrežnog konteksta koji koristi NGINX.
• Slušač čvora i proxy_passdogovaraju se o protokolu, adresi i portu.
• Zapisnik pogrešaka NGINX-a više ne bilježi kvarove uzvodne veze za pogođenu rutu.
• nginx -tuspijeva prije svakog ponovnog učitavanja konfiguracije.
• Izvorni neuspjeli zahtjev - ne samo početna stranica - sada se uspješno izvršava putem NGINX-a.
• Vremenska ograničenja su mijenjana samo kada su zapisnici i izmjereno ponašanje aplikacije opravdavali promjenu.
• Implementacije kontejnera koriste umrežavanje od usluge do usluge umjesto da pretpostavljaju 127.0.0.1prelazak granica kontejnera.

Najpouzdaniji obrazac za rješavanje problema je stoga: izravno testirati čvor, pročitati NGINX grešku, uskladiti uzvodnu adresu sa stvarnom topologijom mreže, zatim validirati i ponovno učitati . Greška 502 je simptom pristupnika. Korisno pitanje je uvijek koji je skok propao i što zapisnik kaže o tom neuspjehu.