Hogyan javítsuk ki az „Nginx 502 Bad Gateway” hibát Node.js proxy használatakor

Egy Node.js alkalmazás előtti NGINX 502 Bad Gateway hiba általában egy dolgot jelent: az NGINX elfogadta a kliens kérését, de nem kapott használható választ a hozzá tartozó upstream alkalmazástól, amellyel kapcsolatba kellett volna lépnie. A leggyorsabb megoldás ezért az, hogy nem kell mindent újraindítani, vagy minden időtúllépéskor hibát jelezni. Először is ellenőrizzük, hogy a Node.js szolgáltatás elérhető-e ugyanarról a hálózati helyről, mint az NGINX, majd az NGINX hibanapló segítségével válasszuk ki a következő lépést.

Ez az útmutató négy diagnosztikai lépést használ. A parancsok feltételezik, hogy egy Linux gazdagép és egy Node.js alkalmazás várhatóan a 3000-es porton fut. Cserélje le a portot, a gazdagépnevet, az elérési utakat és a szolgáltatásneveket a telepítésben szereplő értékekkel.

Mit kell ellenőrizni az NGINX cseréje előtt?

Először három kérdést tegyél fel:

• A Node.js folyamat valóban figyeli az NGINX által elérni kívánt címet és portot?
• Pontosan milyen upstream hibát rögzít az NGINX hibanapló a sikertelen kéréshez?
• Az NGINX és a Node.js ugyanazon a hoston, külön konténerekben vagy külön gépeken fut?

Ezek a válaszok azért fontosak, mert ugyanaz a böngésző által látható 502-es hiba nagyon különböző körülményekből származhat. A leállított Node folyamat, a rossz proxy_passport, a helytelenül használt konténer 127.0.0.1, az upstream időtúllépés és az érvénytelen upstream válasz nem ugyanazt a megoldást kínálja.

Az NGINX dokumentációja proxy_passdirektívaként határozza meg a proxy szerver protokollját és címét. Az upstream modulja olyan változókat is elérhetővé tesz, mint a $upstream_addr, $upstream_status, $upstream_connect_timeés $upstream_response_time, amelyek hasznosak, ha részletesebb éles naplózásra van szükség. Lásd a hivatalos NGINX proxy modul dokumentációját és az NGINX upstream modul dokumentációját .

1. lépés: Elérhető-e közvetlenül az NGINX upstreamje?

Kezd azzal, hogy megkerülöd a fordított proxyt. Ha az NGINX ugyanazon a gépen van, mint a Node.js, és a konfigurációd a következőre mutat 127.0.0.1:3000: , teszteld le pontosan ezt a célállomást:

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

Egy kifogástalan eredmény esetén az alkalmazás HTTP 200-as értéket adhat vissza, és egy figyelőt jeleníthet meg a 3000-es porton. Ha a kapcsolat elutasításra kerül, még ne szerkessze az NGINX időtúllépéseit. Nincs figyelő szolgáltatás azon a címen, amelyet az NGINX használni próbál, vagy a szolgáltatás máshol figyel.

Mi van, ha a Node.js folyamat fut, de a port hiányzik?

Egy futó folyamat nem elég. Az alkalmazásnak be kell fejeznie a szerverindítást, és sikeresen hozzá kell rendelnie egy figyelő sockethez. A Node.js server.listen()azt a műveletet dokumentálja, amely elindít egy TCP vagy IPC szervert, amely kapcsolatokat figyel. Azt is megjegyzi, hogy ez EADDRINUSEakkor történik, ha egy másik szerver már birtokolja a kért portot. Tekintse át a hivatalos Node.js hálózati szerver dokumentációját és a Node.js HTTP dokumentációját .

Egy minimális Node.js HTTP tesztszolgáltatás így nézhet ki:

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

A kötés 127.0.0.1akkor helyénvaló, ha az NGINX és a Node.js ugyanazt a hosztot használja, és egyetlen más gépnek sem kell közvetlen hozzáférése a Node porthoz. Ha külön konténerekben vannak, akkor a címnek más jelentése van, amelyet alább tárgyalunk.

2. lépés: Mit ír valójában az NGINX hibanapló?

Miután megtudta, hogy a upstream közvetlenül válaszol-e, vizsgálja meg az 502-es utasítással egy időben létrejövő naplóbejegyzést. A Linux csomagokon egy gyakori hely a /var/log/nginx/error.log, de a tényleges elérési utat az utasítás vezérli, error_logés telepítésenként eltérő lehet.

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

Az NGINX alapvető dokumentációja kimondja, hogy ez error_logszabályozza a diagnosztikai napló célhelyét és súlyosságát. A parancssori dokumentáció lehetővé teszi nginx -Taz aktív konfiguráció tesztelését és kiíratását is, ami segíthet a váratlan naplóútvonalak vagy kiszolgálóblokkok megtalálásában. Lásd az NGINX alapvető naplózási dokumentációját és az NGINX parancssori paramétereket .

Az üzenet segítségével szűkítheti le a problémát:

3. lépés: A proxy_pass a Node.js által valójában használt címre mutat?

Hasonlítsa össze az 1. lépésben kapott élő figyelőt az aktív NGINX konfigurációval. Egy hagyományos, azonos gépet használó beállítás így néz ki:

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

Az NGINX hivatalosan támogatja az IP-címet, a hosztnevet, a upstream csoportot vagy a UNIX-tartomány socketjét proxy_pass. A kritikus szabály egyszerű: a célnak elérhetőnek kell lennie az NGINX munkavégző hálózati kontextusából.

Az NGINX és a Node.js külön Docker Compose konténerekben vannak?

Ha igen, akkor 127.0.0.1az NGINX konténeren belüli kifejezés magára az NGINX konténerre vonatkozik, nem a Node.js konténerre. A Docker Compose dokumentációja szerint az alapértelmezett Compose hálózaton lévő szolgáltatások a szolgáltatásnév alapján deríthetők fel. Azt is javasolja, hogy a szolgáltatások közötti kommunikációhoz a konténerportot használják a gazdagép által közzétett port helyett.

Például, ha a Compose szolgáltatás neve meg van adva app, és a Node a 3000-es konténerporton figyel, az NGINX a következőket használhatja:

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

Mindkét szolgáltatásnak meg kell osztania egy hálózatot. A Node szolgáltatásnak is figyelnie kell egy, a konténerhálózatból elérhető interfészen; az alkalmazások általában 0.0.0.0a konténeren belüli interfészekhez kötődnek erre a célra. Nem feltétlenül kell közzétenni a 3000-es portot a gazdagépen csak az NGINX-alkalmazás forgalomhoz. Ellenőrizze a topológiát a hivatalos Docker Compose hálózati dokumentáció alapján .

A localhost-ot vagy a 127.0.0.1-et érdemesebb használni?

Ha mindkét folyamat ugyanazon a gépen fut, bármelyik működhet, de nem mindig felcserélhetők minden környezetben, mivel localhostképesek IPv4-re, IPv6-ra vagy mindkettőre feloldani. A figyelő által mutatott pontos cím használata eltávolít egy változót. A Node.js dokumentálja, hogy ha az hostargumentumot elhagyjuk, akkor a nem meghatározott IPv6-címen figyelhet, ::ha elérhető, vagy a nem meghatározott IPv4-címen, 0.0.0.0egyébként.

Ha eltérést tapasztal, például NGINX-kapcsolatot, 127.0.0.1:3000miközben az alkalmazás csak egy másik konténer-hosztnéven, másik porton vagy UNIX-socketen keresztül érhető el, akkor a cím javításával kompenzálja a problémát az újrapróbálkozásokkal.

Valóban a hosszabb várakozási idő a megfelelő megoldás?

Csak akkor módosítsa az időtúllépéseket, ha a naplók időtúllépést mutatnak, és megérti, hogy miért van szüksége a felsőbb szintűnek hosszabb időre. Az NGINX alapértelmezettként proxy_connect_timeout60 másodpercet dokumentál, és megjegyzi, hogy ez általában nem haladhatja meg a 75 másodpercet. Az alapértelmezett érték proxy_read_timeout60 másodperc, amelyet az upstreamről érkező egymást követő olvasások között mérnek, nem pedig a teljes válaszon.

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

A fenti példa nem általános ajánlás. Egy alacsony csatlakozási időkorlátnak lehet értelme egy helyi upstream esetében, amelynek szinte azonnal csatlakoznia kellene, míg egy hosszabb olvasási időkorlát indokolt lehet egy jogosan hosszú kérés esetén. De ha az alkalmazás lassú egy blokkolt eseményhurok, egy adatbázis-leállás, egy túlterhelt függőség vagy egy lefagyott kérés miatt, az időkorlát növelése csak elrejti a tünetet.

Tekintse át a pontos szemantikát a hivatalos NGINX proxy időtúllépési direktívákban .

Mi van, ha csak a WebSocket kapcsolatok kapnak 502-es hibát vagy lekapcsolódnak?

A WebSocket proxyzásnak további követelményei vannak, mivel az Upgradeés Connectiona fejlécek hop-by-hop fejlécek, és nem kerülnek automatikusan továbbításra a szokásos fordított proxy útvonalon. Az NGINX hivatalos WebSocket dokumentációja explicit módon bemutatja ezen fejlécek beállítását.

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

Az NGINX azt is megjegyzi, hogy egy tétlen proxyzott WebSocket-kapcsolat lezárul, ha a upstream nem küld adatot az olvasási időkorláton belül; egy alkalmazásszintű ping adott esetben aktívan tarthatja a kapcsolatot. Az aktuális viselkedésért és a verzióspecifikus megjegyzésekért tekintse meg a hivatalos NGINX WebSocket proxy dokumentációt .

4. lépés: Hogyan validálható a javítás új leállás létrehozása nélkül?

A konfiguráció tesztelése az NGINX újraindítása előtt:

sudo nginx -t
sudo nginx -s reload

Az NGINX dokumentációi -tszintaxis- és hivatkozott fájl-ellenőrzésként, valamint -s reloada konfiguráció újratöltését jelző jelként szolgálnak új munkavégzők indításával és a régiek szabályos leállításával.

Ezután ellenőrizze újra mindkét réteget:

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

Ne állj meg a „kezdőlap betöltődik” üzenetnél. Teszteld újra az eredetileg hibás útvonalat, beleértve a HTTP-metódusát és a kérés törzsét is. Ha az 502-es hiba csak feltöltéskor, API-híváskor, nagyméretű jelentéseknél vagy WebSockets-nél fordult elő, teszteld ugyanazt a forgalmi mintát.

Mi van, ha a közvetlen Node.js kérések működnek, de az NGINX továbbra is 502-es hibát ad vissza?

Ez az eredmény jelentősen leszűkíti a problémát. Ellenőrizze a következő elemeket sorrendben:

1. Erősítse meg az aktív szerver blokkolását. Futtassa a(z) kiszolgálót, sudo nginx -Tés győződjön meg arról, hogy a várt server_nameés locationa kiszolgáló kezeli a kérést.
2. Erősítse meg a pontos upstream célt. A címnek proxy_passmeg kell egyeznie azzal, ami elérhető az NGINX-ből, nem csupán azzal, ami a laptopjáról vagy egy másik konténerből működik.
3. Protokollaltérések ellenőrzése. Ha a upstream HTTPS-t vár, de az NGINX protokoll használatával működik http://, vagy fordítva, akkor javítsa ki a sémát, majd konfigurálja szándékosan a upstream TLS-t.
4. Keresse az alkalmazáskapcsolatok visszaállításait. Vizsgálja meg a Node.js folyamatnaplókat az NGINX hiba időbélyegével megegyező időpontban. Összeomlás vagy megszakított kapcsolat esetén alkalmazásoldali javításra van szükség.
5. Ellenőrizd a speciális forgalmat. A websocketek, a streamelt válaszok, a nagy kérések és a szokatlanul lassú kezelők eltérő proxy beállításokat igényelhetnek, mint egy egyszerű JSON API.

Ha az NGINX és a Node.js között tűzfal, Kubernetes szolgáltatás, terheléselosztó, szolgáltatásháló vagy más proxy található, akkor a hibás ugrás nem feltétlenül a helyi NGINX-Node kapcsolat. Teszteld az egyes ugrásokat külön-külön, ahelyett, hogy a látható NGINX-kiszolgálót feltételeznéd a hiba forrásaként.

Először a Node.js-t vagy az NGINX-et érdemes újraindítani?

Az újraindítás akkor helyénvaló, ha bizonyíték van arra, hogy egy folyamat leállt, nem megfelelő állapotban van, vagy elavult konfigurációt futtat. Ez nem a legjobb első diagnosztikai intézkedés, mert törölheti a nyomokat, és ideiglenesen megszüntetheti az időszakos problémákat.

Ha a Node port hiányzik, vizsgálja meg a folyamatkezelőt vagy a konténernaplókat, javítsa ki az alkalmazásindítási problémát, majd indítsa el a szolgáltatást. Ha csak az NGINX konfigurációját módosította, használja ezt nginx -taz újratöltés előtt. Ha a Node.js kódot vagy a környezeti változókat módosította, indítsa újra a Node szolgáltatást a telepítés által ténylegesen használt felügyelővel, például a systemd-vel, egy konténer-vezéreltővel vagy egy másik folyamatkezelővel.

Éles Node.js esetén azt is ellenőrizd, hogy támogatott kiadási soron vagy-e. 2026 szeptemberétől a hivatalos Node.js kiadási oldal a Node.js 24-es és 22-es verzióját LTS sorként sorolja fel, és az éles alkalmazások számára az Active LTS vagy a Maintenance LTS kiadások használatát javasolja. A jelenlegi állapotot a hivatalos Node.js kiadási oldalon ellenőrizheted, ahelyett , hogy egy régi oktatóanyagra hagyatkoznál.

Kompakt NGINX 502 döntési tábla

Végső önellenőrzés

Valószínűleg a kiváltó okot szüntette meg, ahelyett, hogy csupán a tünetet elnyomta volna, ha a következők mindegyike igaz:

• A Node.js upstream közvetlenül ugyanabból a hálózati kontextusból válaszol, mint amit az NGINX használ.
• A csomópont-figyelő és proxy_passa protokoll, a cím és a port egyeztetése.
• Az NGINX hibanaplója már nem rögzíti az érintett útvonal upstream kapcsolati hibáit.
• nginx -tminden konfiguráció újratöltése előtt sikeres.
• Az eredeti sikertelen kérés – nem csak a kezdőlap – mostantól sikeresen teljesíthető az NGINX-en keresztül.
• Az időtúllépéseket csak akkor módosították, ha a naplók és a mért alkalmazásviselkedés indokolta a módosítást.
• A konténertelepítések szolgáltatás-szolgáltatás hálózatépítést használnak ahelyett, hogy feltételeznék, 127.0.0.1hogy átlépik a konténerhatárokat.

A legmegbízhatóbb hibaelhárítási minta tehát a következő: tesztelje közvetlenül a csomópontot, olvassa be az NGINX hibát, illessze a upstream címet a tényleges hálózati topológiához, majd érvényesítse és töltse újra . Az 502-es hiba átjáróra utal. A hasznos kérdés mindig az, hogy melyik ugrás hibásodott meg, és mit ír a napló a hibáról.