Kā novērst kļūdu "Nginx 502 Bad Gateway", veicot starpniekservera darbību ar Node.js

NGINX 502 nepareiza vārteja Node.js lietojumprogrammas priekšā parasti nozīmē vienu lietu: NGINX pieņēma klienta pieprasījumu, bet nevarēja saņemt izmantojamu atbildi no augšupējās lietojumprogrammas, ar kuru tam bija jāsazinās. Tāpēc ātrākais risinājums nav visu restartēt vai izraisīt kļūdu katrā taimauta gadījumā. Vispirms pārbaudiet, vai Node.js pakalpojums ir sasniedzams no tās pašas tīkla vietas kā NGINX, un pēc tam izmantojiet NGINX kļūdu žurnālu, lai izvēlētos nākamo darbību.

Šajā rokasgrāmatā ir izmantotas četras diagnostikas darbības. Komandas pieņem, ka 3000. portā ir Linux resursdators un Node.js lietotne. Aizstājiet portu, resursdatora nosaukumu, ceļus un pakalpojumu nosaukumus ar vērtībām savā izvietojumā.

Kas jāpārbauda pirms NGINX maiņas?

Vispirms uzdodiet trīs jautājumus:

• Vai Node.js process faktiski klausās adresē un portā, ko NGINX mēģina sasniegt?
• Kādu precīzu augšupējo kļūdu NGINX kļūdu žurnālā ieraksta neveiksmīgam pieprasījumam?
• Vai NGINX un Node.js darbojas vienā un tajā pašā resursdatorā, atsevišķos konteineros vai atsevišķās ierīcēs?

Šīs atbildes ir svarīgas, jo viens un tas pats pārlūkprogrammā redzamais 502 var rasties ļoti dažādu apstākļu dēļ. Apturētam mezgla procesam, nepareizam proxy_passportam, nepareizi izmantotam konteineram 127.0.0.1, augšupsaites taimautam un nederīgai augšupsaites atbildei nav vienāda labojuma.

NGINX dokumentē proxy_passkā direktīvu, kas norāda starpniekservera protokolu un adresi. Tā augšupējais modulis arī atklāj tādus mainīgos kā $upstream_addr, $upstream_status, $upstream_connect_timeun $upstream_response_time, kas ir noderīgi, ja nepieciešama detalizētāka ražošanas reģistrēšana. Skatiet oficiālo NGINX starpniekservera moduļa dokumentāciju un NGINX augšupējā moduļa dokumentāciju .

1. darbība: vai NGINX augšupējo plūsmu var sasniegt tieši?

Sāciet, apejot apgriezto starpniekserveri. Ja NGINX atrodas tajā pašā resursdatorā, kur Node.js, un jūsu konfigurācija norāda uz 127.0.0.1:3000, pārbaudiet šo precīzo galamērķi:

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

Veselīgs rezultāts var atgriezt HTTP 200 no jūsu lietojumprogrammas un parādīt klausītāju 3000. portā. Ja savienojums tiek atteikts, vēl nemediģējiet NGINX taimautus. Adresē, kuru NGINX mēģina izmantot, nav klausīšanās pakalpojuma vai pakalpojums klausās kaut kur citur.

Ko darīt, ja Node.js process darbojas, bet trūkst porta?

Ar vienu darbojošos procesu vien nepietiek. Lietojumprogrammai ir jābūt pabeigtai servera startēšanai un veiksmīgi piesaistītai klausīšanās ligzdai. Node.js dokumentē server.listen()kā darbību, kas sāk TCP vai IPC serveri, kas klausās savienojumus. Tajā arī norādīts, ka tas EADDRINUSEnotiek, ja pieprasītais ports jau pieder citam serverim. Pārskatiet oficiālo Node.js tīkla servera dokumentāciju un Node.js HTTP dokumentāciju .

Minimāls Node.js HTTP testa pakalpojums var izskatīties šādi:

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

Saistīšana ar 127.0.0.1ir piemērota, ja NGINX un Node.js koplieto vienu un to pašu resursdatoru un nevienai citai iekārtai nav nepieciešama tieša piekļuve Node portam. Ja tie atrodas atsevišķos konteineros, šai adresei ir cita nozīme, kas ir aplūkota tālāk.

2. darbība. Ko patiesībā saka NGINX kļūdu žurnāls?

Kad esat noskaidrojis, vai augšupējais serveris reaģē tieši, pārbaudiet žurnāla ierakstu, kas izveidots vienlaikus ar 502. Bieži sastopama atrašanās vieta Linux pakotnēs ir /var/log/nginx/error.log, bet faktisko ceļu kontrolē direktīva error_logun var atšķirties atkarībā no instalācijas.

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

NGINX pamata dokumentācijā ir norādīts, ka tā error_logkontrolē diagnostikas žurnāla galamērķi un nopietnību. Tās komandrindas dokumentācija nodrošina arī nginx -Taktīvās konfigurācijas pārbaudi un izmešanu, kas var palīdzēt atrast negaidītu žurnāla ceļu vai servera bloku. Skatiet NGINX pamata reģistrēšanas dokumentāciju un NGINX komandrindas parametrus .

Izmantojiet ziņojumu, lai sašaurinātu problēmas loku:

3. solis: Vai proxy_pass norāda uz adresi, kuru Node.js patiesībā izmanto?

Salīdziniet 1. darbībā iegūto tiešraides klausītāju ar aktīvo NGINX konfigurāciju. Parastā viena resursdatora iestatīšana izskatās šādi:

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āli atbalsta IP adresi, resursdatora nosaukumu, augšupējo grupu vai UNIX domēna ligzdu proxy_pass. Svarīgākais noteikums ir vienkāršs: galamērķim jābūt sasniedzamam no NGINX darbinieka tīkla konteksta.

Vai NGINX un Node.js atrodas atsevišķos Docker Compose konteineros?

Ja tā ir, tad 127.0.0.1NGINX konteinera iekšpusē tas attiecas uz pašu NGINX konteineru, nevis Node.js konteineru. Docker Compose dokumentācijā ir norādīts, ka pakalpojumus noklusējuma Compose tīklā var atklāt pēc pakalpojuma nosaukuma. Tā arī iesaka pakalpojumu savstarpējai saziņai izmantot konteinera portu, nevis resursdatora publicētu portu.

Piemēram, ja pakalpojumam Compose ir piešķirts nosaukums appun Node klausās konteinera portā 3000, NGINX var izmantot:

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

Abiem pakalpojumiem ir jākoplieto tīkls. Nozvejas pakalpojumam ir arī jāuzklausa saskarne, kas sasniedzama no šī konteinera tīkla; 0.0.0.0šim nolūkam lietojumprogrammas parasti izveido savienojumu ar konteinera iekšpusi. Jums nav obligāti jāpublicē 3000. ports resursdatorā tikai NGINX un lietotnes datplūsmai. Pārbaudiet topoloģiju, izmantojot oficiālo Docker Compose tīkla dokumentāciju .

Vai jums vajadzētu izmantot localhost vai 127.0.0.1?

Ja abi procesi darbojas vienā un tajā pašā resursdatorā, jebkurš no tiem var darboties, taču tie ne vienmēr ir savstarpēji aizvietojami katrā vidē, jo localhostvar atrisināt ar IPv4, IPv6 vai abiem. Izmantojot precīzu klausītāja parādīto adresi, tiek noņemts viens mainīgais. Node.js dokumentē, ka, ja arguments hosttiek izlaists, tas var klausīties nenorādītajā IPv6 adresē, ::ja tā ir pieejama, vai pretējā gadījumā nenorādītajā IPv4 adresē 0.0.0.0.

Ja redzat neatbilstību, piemēram, NGINX sazinās, 127.0.0.1:3000kamēr lietojumprogramma ir pieejama tikai caur citu konteinera resursdatora nosaukumu, citu portu vai UNIX ligzdu, izlabojiet adresi, nevis kompensējiet to ar atkārtotiem mēģinājumiem.

Vai ilgāks pārtraukums tiešām ir pareizais risinājums?

Mainiet taimautus tikai tad, ja žurnālos tiek parādīts taimauts un jūs saprotat, kāpēc augšupējam avotam ir nepieciešams ilgāks laiks. NGINX dokumentē noklusējuma vērtību proxy_connect_timeout60 sekundes un norāda, ka tā parasti nedrīkst pārsniegt 75 sekundes. Tā arī dokumentē noklusējuma vērtību proxy_read_timeout60 sekundes, kas tiek mērītas starp secīgiem lasījumiem no augšupējā avota, nevis visā atbildē.

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

Iepriekš minētais piemērs nav universāls ieteikums. Zems savienojuma taimauts var būt lietderīgs lokālam augšupējam avotam, kuram vajadzētu izveidot savienojumu gandrīz nekavējoties, savukārt ilgāks lasīšanas taimauts var būt pamatots pietiekami ilgam pieprasījumam. Taču, ja lietojumprogramma ir lēna bloķēta notikumu cikla, datubāzes apstāšanās, pārslogotas atkarības vai apturēta pieprasījuma dēļ, taimauta palielināšana tikai slēpj simptomu.

Pārskatiet precīzu semantiku oficiālajās NGINX starpniekservera taimauta direktīvās .

Ko darīt, ja tikai WebSocket savienojumi saņem 502 kļūdu vai atvienojas?

WebSocket starpniekservera izmantošanai ir papildu prasības, jo Upgradegalvenes Connectionir “hop-by-hop” galvenes un netiek automātiski pārsūtītas parastajā reversā starpniekservera ceļā. NGINX oficiālajā WebSocket dokumentācijā ir skaidri parādīta šo galvenes iestatīšana.

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

NGINX arī norāda, ka dīkstāvē esošs starpniekservera WebSocket savienojums tiek slēgts, ja augšupsaites savienojums nolasīšanas taimauta intervālā nesūta datus; lietojumprogrammas līmeņa ping var uzturēt savienojumu aktīvu, ja tas ir nepieciešams. Lai iegūtu informāciju par pašreizējo darbību un versijām raksturīgām piezīmēm, izmantojiet oficiālo NGINX WebSocket starpniekservera dokumentāciju .

4. darbība. Kā validēt labojumu, neradot jaunu darbības pārtraukumu?

Pirms NGINX atkārtotas ielādes pārbaudiet konfigurāciju:

sudo nginx -t
sudo nginx -s reload

NGINX dokumentē -tkā sintakses un atsauces failu pārbaudi un -s reloadkā signālu, kas atkārtoti ielādē konfigurāciju, startējot jaunus darbiniekus un graciozi izslēdzot vecos.

Pēc tam vēlreiz pārbaudiet abus slāņus:

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

Neapstājieties pie “sākumslapas ielādes”. Vēlreiz pārbaudiet maršrutu, kas sākotnēji neizdevās, tostarp tā HTTP metodi un jebkuru pieprasījuma pamattekstu. Ja 502. kļūme radās tikai augšupielādēs, API izsaukumos, lielos pārskatos vai WebSockets, pārbaudiet to pašu datplūsmas modeli.

Ko darīt, ja tiešie Node.js pieprasījumi darbojas, bet NGINX joprojām atgriež 502?

Šis rezultāts ievērojami sašaurina problēmu. Pārbaudiet šos vienumus šādā secībā:

1. Apstipriniet aktīvā servera bloķēšanu. Palaidiet sudo nginx -Tun pārliecinieties, vai paredzētie server_nameun locationapstrādā pieprasījumu.
2. Apstipriniet precīzu augšupējo mērķi. Adresei proxy_passir jāatbilst tam, kas ir sasniedzams no NGINX, nevis tikai tam, kas darbojas no jūsu klēpjdatora vai cita konteinera.
3. Pārbaudiet protokola neatbilstību. Ja augšupējais serveris sagaida HTTPS, bet NGINX izmanto http://, vai otrādi, izlabojiet shēmu un pēc tam apzināti konfigurējiet augšupējā servera TLS.
4. Meklējiet lietojumprogrammu savienojuma atiestatīšanu. Pārbaudiet Node.js procesa žurnālus tajā pašā laika zīmogā, kurā ir NGINX kļūda. Avārijas vai pārtraukta savienojuma gadījumā ir nepieciešams labojums lietojumprogrammas pusē.
5. Pārbaudiet specializēto datplūsmu. WebSockets, straumēšanas atbildes, lieli pieprasījumi un neparasti lēni apstrādātāji var pieprasīt atšķirīgus starpniekservera iestatījumus nekā vienkārša JSON API.

Ja NGINX un Node.js atdala ugunsmūris, Kubernetes pakalpojums, slodzes līdzsvarotājs, pakalpojumu tīkls vai cits starpniekserveris, kļūmes cēlonis, iespējams, nav lokālais NGINX-Node savienojums. Pārbaudiet katru lēcienu atsevišķi, nevis pieņemot, ka redzamais NGINX serveris ir kļūmes avots.

Vai vispirms vajadzētu restartēt Node.js vai NGINX?

Restartēšana ir piemērota, ja ir pierādījumi, ka process ir apturēts, nedarbojas pareizi vai darbojas ar novecojušu konfigurāciju. Tā nav labākā pirmā diagnostikas darbība, jo tā var dzēst pavedienus un īslaicīgi novērst periodisku problēmu.

Ja Node porta nav, pārbaudiet procesa pārvaldnieka vai konteinera žurnālus, novērsiet lietojumprogrammas startēšanas problēmu un pēc tam startējiet pakalpojumu. Ja mainījāt tikai NGINX konfigurāciju, izmantojiet to nginx -tpirms atkārtotas ielādes. Ja mainījāt Node.js kodu vai vides mainīgos, restartējiet Node pakalpojumu, izmantojot jūsu izvietošanas faktiski izmantoto pārvaldnieku, piemēram, systemd, konteinera orķestratoru vai citu procesa pārvaldnieku.

Ražošanas Node.js gadījumā pārliecinieties arī, vai izmantojat atbalstītu laidienu līniju. Sākot ar 2026. gada septembri, oficiālajā Node.js laidienu lapā Node.js 24. un 22. versija ir norādīta kā LTS līnijas, un ražošanas lietojumprogrammām ieteicams izmantot aktīvās LTS vai uzturēšanas LTS laidienus. Pārbaudiet pašreizējo statusu oficiālajā Node.js laidienu lapā, nevis paļaujieties uz vecu pamācību.

Kompakta NGINX 502 lēmumu pieņemšanas tabula

Galīgā pašpārbaude

Jūs, iespējams, esat novērsis pamatcēloni, nevis tikai apspiedis simptomu, ja ir patiesi visi šie nosacījumi:

• Node.js augšupējais slānis atbild tieši no tā paša tīkla konteksta, ko izmanto NGINX.
• Mezgla klausītājs proxy_passvienojas par protokolu, adresi un portu.
• NGINX kļūdu žurnālā vairs netiek reģistrētas augšupējās savienojuma kļūmes attiecīgajā maršrutā.
• nginx -tizdodas pirms katras konfigurācijas atkārtotas ielādes.
• Sākotnējais neveiksmīgais pieprasījums — ne tikai sākumlapa — tagad tiek izpildīts, izmantojot NGINX.
• Taimauti tika mainīti tikai tad, ja žurnāli un izmērītā lietojumprogrammu darbība attaisnoja izmaiņas.
• Konteineru izvietošana izmanto pakalpojumu savstarpēju tīklošanu, nevis pieņem, ka tā 127.0.0.1šķērso konteineru robežas.

Tāpēc visuzticamākais problēmu novēršanas modelis ir šāds: tieši pārbaudiet mezglu, nolasiet NGINX kļūdu, salīdziniet augšupējo adresi ar faktisko tīkla topoloģiju, pēc tam validējiet un ielādējiet atkārtoti . 502 ir vārtejas simptoms. Noderīgs jautājums vienmēr ir, kurš lēciens neizdevās un ko žurnāls saka par šo kļūmi.