Kuinka korjata "Nginx 502 Bad Gateway" -virhe, kun välityspalvelimena käytetään Node.js:ää

Node.js-sovelluksen edessä oleva NGINX 502 Bad Gateway -virhe tarkoittaa yleensä yhtä asiaa: NGINX hyväksyi asiakaspyynnön, mutta ei saanut käyttökelpoista vastausta ylävirran sovellukselta, johon sen piti ottaa yhteyttä. Nopein ratkaisu ei siis ole käynnistää kaikkea uudelleen tai nostaa virhettä jokaisen aikakatkaisun jälkeen. Varmista ensin, onko Node.js-palvelu tavoitettavissa samasta verkkosijainnista kuin NGINX, ja valitse sitten seuraava siirto NGINX-virhelokin perusteella.

Tässä oppaassa käytetään neljää diagnostiikkavaihetta. Komennot olettavat Linux-isännän ja Node.js-sovelluksen olevan portissa 3000. Korvaa portti, isäntänimi, polut ja palvelunimet käyttöönottosi arvoilla.

Mitä sinun pitäisi tarkistaa ennen NGINX:n vaihtamista?

Kysy ensin kolme kysymystä:

• Kuunteleeko Node.js-prosessi todella osoitetta ja porttia, johon NGINX yrittää päästä?
• Minkä tarkalleen ottaen ylävirran virheen NGINX-virhelokiin kirjataan epäonnistuneelle pyynnölle?
• Toimiiko NGINX ja Node.js samalla isännöintipalvelimella, erillisissä säilöissä vai erillisillä koneilla?

Näillä vastauksilla on merkitystä, koska sama selaimessa näkyvä 502-virhe voi tulla hyvin erilaisista olosuhteista. Pysähtyneellä Node-prosessilla, väärällä proxy_passportilla, väärin käytetyllä säilöllä 127.0.0.1, ylävirran aikakatkaisulla ja virheellisellä ylävirran vastauksella ei ole samaa korjausta.

NGINX-dokumentaatio proxy_passon direktiivi, joka määrittää välityspalvelimen protokollan ja osoitteen. Sen ylävirran moduuli paljastaa myös muuttujia, kuten $upstream_addr, $upstream_status, $upstream_connect_timeja $upstream_response_time, jotka ovat hyödyllisiä, kun tarvitset yksityiskohtaisempaa tuotantolokia. Katso NGINX-välityspalvelimen moduulin virallinen dokumentaatio ja NGINX-ylävirran moduulin dokumentaatio .

Vaihe 1: Voidaanko NGINX:n ylävirtaan tavoittaa suoraan?

Aloita ohittamalla käänteinen välityspalvelin. Jos NGINX on samalla isännöllä kuin Node.js ja kokoonpanosi osoittaa kohteeseen 127.0.0.1:3000, testaa tarkkaa kohdetta:

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

Terveellinen tulos saattaa palauttaa sovelluksestasi HTTP 200 -osoitteen ja näyttää kuuntelijan portissa 3000. Jos yhteys evätään, älä vielä muokkaa NGINX-aikakatkaisuja. NGINX:n käyttämässä osoitteessa ei ole kuuntelupalvelua tai palvelu kuuntelee jossain muualla.

Entä jos Node.js-prosessi on käynnissä, mutta portti puuttuu?

Pelkkä käynnissä oleva prosessi ei riitä. Sovelluksen on täytynyt käynnistää palvelin ja muodostaa kuuntelusoketti onnistuneesti. Node.js dokumentoi server.listen()operaation, joka käynnistää TCP- tai IPC-palvelimen kuuntelemaan yhteyksiä. Se huomauttaa myös, että tämä EADDRINUSEtapahtuu, kun toinen palvelin omistaa jo pyydetyn portin. Tutustu Node.js:n viralliseen verkkopalvelimen dokumentaatioon ja Node.js:n HTTP-dokumentaatioon .

Minimalistinen Node.js HTTP-testauspalvelu voi näyttää tältä:

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

Sidontaa osoitteeseen (link to) 127.0.0.1kannattaa käyttää, kun NGINX ja Node.js jakavat saman isännän eikä mikään muu kone tarvitse suoraa pääsyä Node-porttiin. Jos ne ovat erillisissä säilöissä, osoitteella on eri merkitys, jota käsitellään alla.

Vaihe 2: Mitä NGINX-virheloki oikeastaan ​​sanoo?

Kun tiedät, vastaako ylävirta suoraan, tarkista 502-koodin kanssa samanaikaisesti tuotettua lokimerkintää. Yleinen sijainti Linux-paketeissa on /var/log/nginx/error.log, mutta varsinaista polkua ohjaa direktiivi error_logja se voi vaihdella asennuksen mukaan.

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

NGINX:n ydindokumentaatio määrää, että se error_loghallitsee diagnostiikkalokin kohdetta ja vakavuutta. Sen komentorividokumentaatio tarjoaa myös nginx -Tmahdollisuuden testata ja vedostaa aktiivisen kokoonpanon, mikä voi auttaa sinua löytämään odottamattoman lokipolun tai palvelinlohkon. Katso NGINX:n ydinlokitiedostojen dokumentaatio ja NGINX:n komentoriviparametrit .

Käytä viestiä ongelman rajaamiseen:

Vaihe 3: Osoittaako proxy_pass siihen osoitteeseen, jota Node.js todella käyttää?

Vertaa vaiheen 1 live-kuuntelijaa aktiiviseen NGINX-kokoonpanoon. Perinteinen saman isännän kokoonpano näyttää tältä:

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 tukee virallisesti IP-osoitetta, isäntänimeä, ylävirran ryhmää tai UNIX-toimialueen sokettia proxy_pass. Kriittinen sääntö on yksinkertainen: kohteen on oltava tavoitettavissa NGINX-työntekijän verkkokontekstista.

Ovatko NGINX ja Node.js erillisissä Docker Compose -konteissa?

Jos näin on, 127.0.0.1NGINX-kontin sisällä oleva merkinnällä viitataan itse NGINX-konttiin, ei Node.js-konttiin. Docker Composen dokumentaatiossa todetaan, että oletusarvoisen Compose-verkon palvelut ovat löydettävissä palvelun nimen perusteella. Se suosittelee myös konttiportin käyttöä palveluiden väliseen viestintään isännän julkaiseman portin sijaan.

Jos esimerkiksi Compose-palvelu on nimetty appja Node kuuntelee konttiporttia 3000, NGINX voi käyttää:

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

Molempien palveluiden on jaettava verkko. Node-palvelun on myös kuunneltava rajapintaa, johon kyseinen konttiverkko on käytettävissä; sovellukset sitoutuvat yleensä kontin sisäisiin yhteyksiin tätä tarkoitusta varten. Sinun ei välttämättä tarvitse julkaista porttia 3000 isännälle vain NGINX:n ja sovelluksen välistä liikennettä varten. Tarkista topologia Docker Composen virallista verkkodokumentaatiota0.0.0.0 vasten .

Pitäisikö sinun käyttää localhostia vai 127.0.0.1:tä?

Jos molemmat prosessit toimivat samalla isännöllä, kumpi tahansa voi toimia, mutta ne eivät ole aina keskenään vaihdettavissa kaikissa ympäristöissä, koska localhostne voivat ratkaista IPv4:n, IPv6:n tai molemmat. Kuuntelijan näyttämän tarkan osoitteen käyttäminen poistaa yhden muuttujan. Node.js dokumentoi, että jos argumentti hostjätetään pois, se voi kuunnella määrittelemätöntä IPv6-osoitetta, ::kun se on saatavilla, tai muussa tapauksessa määrittelemätöntä IPv4-osoitetta 0.0.0.0.

Jos huomaat ristiriidan, kuten NGINX-yhteyden muodostamisen, 127.0.0.1:3000vaikka sovellus on käytettävissä vain toisen säilön isäntänimen, eri portin tai UNIX-socketin kautta, korjaa osoite uudelleenyritysten sijaan.

Onko pidempi tauko todella oikea ratkaisu?

Muuta aikakatkaisuja vain, kun lokit näyttävät aikakatkaisun ja ymmärrät, miksi ylävirran aikakatkaisu tarvitsee pidemmän ajan. NGINX dokumentoi oletusarvoksi proxy_connect_timeout60 sekuntia ja huomauttaa, että se ei yleensä voi ylittää 75 sekuntia. Se dokumentoi myös oletusarvoksi proxy_read_timeout60 sekuntia, mitattuna ylävirran peräkkäisten lukukertojen välillä eikä koko vastauksen osalta.

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

Yllä oleva esimerkki ei ole yleismaailmallinen suositus. Lyhyt yhteyden aikakatkaisu voi olla järkevää paikalliselle ylävirtaan, jonka pitäisi muodostaa yhteys lähes välittömästi, kun taas pidempi lukuaikakatkaisu voi olla perusteltua pitkän pyynnön yhteydessä. Mutta jos sovellus on hidas estyneen tapahtumasilmukan, tietokannan kaatumisen, ylikuormitetun riippuvuuden tai jumiutuneen pyynnön vuoksi, aikakatkaisun pidentäminen vain piilottaa oireen.

Tarkista tarkka semantiikka virallisista NGINX-välityspalvelimen aikakatkaisudirektiiveistä .

Entä jos vain WebSocket-yhteydet saavat 502-virheen tai katkaisevat yhteyden?

WebSocket-välityspalvelimella on lisävaatimuksia, koska Upgradeja Connection-otsikot ovat hop-by-hop-otsikoita, eikä niitä lähetetä automaattisesti eteenpäin tavallisessa käänteisen välityspalvelimen polussa. NGINX:n virallinen WebSocket-dokumentaatio osoittaa näiden otsikoiden asettamisen eksplisiittisesti.

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

NGINX huomauttaa myös, että käyttämätön välityspalvelimella varustettu WebSocket-yhteys suljetaan, jos ylävirta ei lähetä dataa lukuaikakatkaisun aikana; sovellustason ping voi pitää yhteyden aktiivisena tarvittaessa. Katso ajankohtaiset tiedot ja versiokohtaiset tiedot NGINX WebSocket -välityspalvelimen virallisesta dokumentaatiosta .

Vaihe 4: Miten korjauksen validointi tehdään ilman uuden käyttökatkoksen luomista?

Testaa kokoonpano ennen NGINX:n uudelleenkäynnistystä:

sudo nginx -t
sudo nginx -s reload

NGINX-dokumentit -ttoimivat syntaksi- ja viitattujen tiedostojen tarkistuksena sekä -s reloadsignaalina, joka lataa kokoonpanon uudelleen käynnistämällä uusia työprosesseja ja sulkemalla vanhoja hallitusti.

Tarkista sitten molemmat kerrokset uudelleen:

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

Älä pysähdy kohtaan ”kotisivu latautuu”. Testaa uudelleen alun perin epäonnistunut reitti, mukaan lukien sen HTTP-metodi ja mahdollinen pyynnön runko. Jos 502-virhe ilmeni vain latauksissa, API-kutsuissa, suurissa raporteissa tai WebSockets-yhteyksissä, testaa samaa liikennekuviota.

Mitä jos suorat Node.js-pyynnöt toimivat, mutta NGINX palauttaa silti 502:n?

Tämä tulos rajaa ongelmaa huomattavasti. Tarkista nämä kohdat järjestyksessä:

1. Vahvista aktiivisen palvelimen esto. Suorita sudo nginx -Tja varmista, että odotetut server_nameja locationkäsittelevät pyynnön.
2. Vahvista tarkka ylävirran kohde. Osoitteen proxy_passon vastattava sitä, mihin NGINX:stä päästään, ei pelkästään sitä, mikä toimii kannettavallasi tai toisella säilöllä.
3. Tarkista protokollan epäsuhta. Jos yläpuolinen reititin odottaa HTTPS:ää, mutta NGINX käyttää http://, tai päinvastoin, korjaa protokolla ja määritä sitten yläpuolinen TLS tarkoituksella.
4. Etsi sovellusyhteyden nollauksia. Tarkista Node.js-prosessilokit samalta aikaleimalta kuin NGINX-virhe. Kaatuminen tai keskeytetty yhteys vaatii sovelluspuolen korjauksen.
5. Tarkista erikoistunut liikenne. WebSocketit, suoratoistovastaukset, suuret pyynnöt ja epätavallisen hitaat käsittelijät voivat tarvita erilaisia ​​välityspalvelinasetuksia kuin yksinkertainen JSON-rajapinta.

Jos NGINX ja Node.js ovat erillään palomuurin, Kubernetes-palvelun, kuormituksen tasaajan, palveluverkon tai muun välityspalvelimen avulla, epäonnistuva hyppy ei välttämättä ole paikallinen NGINX:n ja Node:n välinen yhteys. Testaa kutakin hyppyä erikseen sen sijaan, että olettaisit näkyvän NGINX-palvelimen olevan virheen lähde.

Pitäisikö sinun käynnistää Node.js vai NGINX ensin uudelleen?

Uudelleenkäynnistys on sopiva, kun on todisteita siitä, että prosessi on pysähtynyt, toimintahäiriöinen tai käyttää vanhentunutta kokoonpanoa. Se ei ole paras ensimmäinen diagnostiikkatoimenpide, koska se voi poistaa vihjeitä ja poistaa ajoittaisen ongelman tilapäisesti.

Jos Node-portti puuttuu, tarkista prosessinhallinta- tai säilölokit, korjaa sovelluksen käynnistysongelma ja käynnistä sitten palvelu. Jos muutit vain NGINX-kokoonpanoa, käytä sitä nginx -tennen uudelleenlatausta. Jos muutit Node.js-koodia tai ympäristömuuttujia, käynnistä Node-palvelu uudelleen käyttämällä käyttöönottosi tosiasiallisesti käyttämää valvojaa, kuten systemd:tä, säilöorkestroijaa tai toista prosessinhallintaa.

Varmista myös tuotantoympäristössä olevan Node.js:n osalta, että olet tuetulla julkaisulinjalla. Syyskuusta 2026 lähtien Node.js:n virallinen julkaisusivu listaa Node.js 24:n ja 22:n LTS-linjoiksi ja suosittelee tuotantosovelluksille aktiivisen LTS:n tai ylläpidon LTS-julkaisujen käyttöä. Tarkista nykyinen tila Node.js:n viralliselta julkaisusivulta sen sijaan, että luottaisit vanhaan tutoriaaliin.

Kompakti NGINX 502 -päätöstaulukko

Lopputarkastus

Olet luultavasti korjannut perimmäisen syyn pelkän oireen tukahduttamisen sijaan, kun kaikki seuraavat kohdat pitävät paikkansa:

• Node.js vastaa suoraan samasta verkkokontekstista, jota NGINX käyttää.
• Solmun kuuntelija ja proxy_passsopivat protokollasta, osoitteesta ja portista.
• NGINX-virhelokiin ei enää kirjata ylävirran yhteysvirheitä kyseiselle reitille.
• nginx -tonnistuu ennen jokaista kokoonpanon uudelleenlatausta.
• Alkuperäinen epäonnistunut pyyntö – ei vain kotisivu – onnistuu nyt NGINX:n kautta.
• Aikakatkaisuja muutettiin vain, kun lokit ja mitattu sovelluksen toiminta oikeuttivat muutoksen.
• Konttien käyttöönotot käyttävät palveluiden välistä verkkoa sen sijaan, että oletettaisiin 127.0.0.1konttien rajojen ylittävän.

Luotettavin vianmääritysmalli on siis seuraava: testaa solmu suoraan, lue NGINX-virhe, yhdistä ylävirran osoite todelliseen verkkotopologiaan, vahvista ja lataa uudelleen . 502-virhe on yhdyskäytävän oire. Hyödyllinen kysymys on aina, mikä hyppy epäonnistui ja mitä loki kertoo kyseisestä epäonnistumisesta.