Sådan rettes "Nginx 502 Bad Gateway" ved proxy til Node.js

En NGINX 502 Bad Gateway foran en Node.js-applikation betyder normalt én ting: NGINX accepterede klientanmodningen, men kunne ikke få et brugbart svar fra den upstream-applikation, den skulle kontakte. Den hurtigste løsning er derfor ikke at genstarte alt eller hæve hver timeout. Bevis først, om Node.js-tjenesten kan nås fra samme netværksplacering som NGINX, og brug derefter NGINX-fejlloggen til at vælge det næste skridt.

Denne vejledning bruger fire diagnosticeringstrin. Kommandoerne antager, at en Linux-vært og en Node.js-app forventes på port 3000. Erstat port, værtsnavn, stier og servicenavne med værdierne i din implementering.

Hvad skal du kontrollere, før du ændrer NGINX?

Stil først tre spørgsmål:

• Lytter Node.js-processen faktisk på den adresse og port, som NGINX forsøger at nå?
• Hvilken præcis upstream-fejl registrerer NGINX-fejlloggen for den mislykkede anmodning?
• Kører NGINX og Node.js på den samme vært, i separate containere eller på separate maskiner?

Disse svar er vigtige, fordi den samme browser-synlige 502 kan komme fra meget forskellige forhold. En stoppet nodeproces, den forkerte proxy_passport, en container der bruges 127.0.0.1forkert, en upstream timeout og et ugyldigt upstream-svar har ikke den samme løsning.

NGINX dokumenterer proxy_passsom den direktiv, der specificerer protokollen og adressen på den proxy-baserede server. Dens upstream-modul eksponerer også variabler som $upstream_addr, $upstream_status, $upstream_connect_timeog $upstream_response_time, som er nyttige, når du har brug for mere detaljeret produktionslogning. Se den officielle dokumentation til NGINX proxy-modulet og NGINX upstream-modulet .

Trin 1: Kan NGINX's upstream nås direkte?

Start med at omgå den reverse proxy. Hvis NGINX er på samme vært som Node.js, og din konfiguration peger på 127.0.0.1:3000, skal du teste den præcise destination:

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

Et korrekt resultat kan returnere HTTP 200 fra din applikation og vise en lytter på port 3000. Hvis forbindelsen afvises, må du ikke redigere NGINX timeouts endnu. Der er ingen lyttetjeneste på den adresse, som NGINX forsøger at bruge, eller tjenesten lytter et andet sted.

Hvad hvis Node.js-processen kører, men porten mangler?

En kørende proces er ikke nok. Applikationen skal have gennemført sin serveropstart og bundet en lyttesocket. Node.js dokumenteres server.listen()som den handling, der starter en TCP- eller IPC-server, der lytter efter forbindelser. Den bemærker også, at dette EADDRINUSEsker, når en anden server allerede ejer den anmodede port. Gennemgå den officielle Node.js net-serverdokumentation og Node.js HTTP-dokumentation .

En minimal Node.js HTTP-testtjeneste kan se sådan ud:

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

Binding til 127.0.0.1er passende, når NGINX og Node.js deler den samme vært, og ingen anden maskine har brug for direkte adgang til Node-porten. Hvis de er i separate containere, har den adresse en anden betydning, som er beskrevet nedenfor.

Trin 2: Hvad siger NGINX-fejlloggen egentlig?

Når du ved, om upstreamen reagerer direkte, skal du kontrollere logposten, der genereres samtidig med 502. En almindelig placering på Linux-pakker er /var/log/nginx/error.log, men den faktiske sti styres af error_logdirektivet og kan variere afhængigt af installationen.

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

NGINX's kernedokumentation angiver, at det error_logstyrer den diagnostiske logdestination og alvorlighedsgrad. Dens kommandolinjedokumentation giver også mulighed nginx -Tfor at teste og dumpe den aktive konfiguration, hvilket kan hjælpe dig med at finde en uventet logsti eller serverblok. Se NGINX's kernelogføringsdokumentation og NGINX-kommandolinjeparametre .

Brug beskeden til at indsnævre problemet:

Trin 3: Peger proxy_pass på den adresse, som Node.js rent faktisk bruger?

Sammenlign live-lytteren fra trin 1 med den aktive NGINX-konfiguration. En konventionel same-host-opsætning ser sådan ud:

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 understøtter officielt en IP-adresse, et værtsnavn, en upstream-gruppe eller en UNIX-domænesocket i proxy_pass. Den kritiske regel er enkel: destinationen skal kunne nås fra NGINX-arbejderens netværkskontekst.

Er NGINX og Node.js i separate Docker Compose-containere?

Hvis de er det, 127.0.0.1refererer "inside the NGINX container" til selve NGINX containeren, ikke Node.js containeren. Docker Compose-dokumentationen angiver, at tjenester på standard Compose-netværket kan findes via tjenestenavn. Den anbefaler også at bruge containerporten til tjeneste-til-tjeneste-kommunikation i stedet for en værtspubliceret port.

Hvis for eksempel Compose-tjenesten er navngivet app, og Node lytter på containerport 3000, kan NGINX bruge:

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

Begge tjenester skal dele et netværk. Node-tjenesten skal også lytte på en grænseflade, der kan nås fra det pågældende containernetværk; applikationer binder normalt til 0.0.0.0containeren til dette formål. Du behøver ikke nødvendigvis at udgive port 3000 til værten kun for NGINX-til-app-trafik. Bekræft topologien i forhold til den officielle Docker Compose-netværksdokumentation .

Skal du bruge localhost eller 127.0.0.1?

Hvis begge processer kører på den samme vært, kan begge fungere, men de er ikke altid udskiftelige i alle miljøer, fordi localhostde kan opløses til IPv4, IPv6 eller begge. Brug af den nøjagtige adresse vist af lytteren fjerner én variabel. Node.js dokumenterer, at hvis argumentet hostudelades, kan den lytte på den uspecificerede IPv6-adresse, ::når den er tilgængelig, eller den uspecificerede IPv4-adresse 0.0.0.0ellers.

Hvis du ser en uoverensstemmelse, f.eks. at NGINX kontakter, 127.0.0.1:3000mens applikationen kun er tilgængelig via et andet containerværtsnavn, en anden port eller en UNIX-socket, skal du rette adressen i stedet for at kompensere med nye forsøg.

Er en længere timeout virkelig den rigtige løsning?

Skift kun timeouts, når loggene viser en timeout, og du forstår, hvorfor upstream-systemet har brug for længere tid. NGINX dokumenterer en standard proxy_connect_timeoutpå 60 sekunder og bemærker, at den normalt ikke kan overstige 75 sekunder. Den dokumenterer også en standard proxy_read_timeoutpå 60 sekunder, målt mellem successive læsninger fra upstream-systemet i stedet for på tværs af hele responsen.

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

Eksemplet ovenfor er ikke en universel anbefaling. En lav forbindelsestimeout kan give mening for en lokal upstream, der burde oprette forbindelse næsten øjeblikkeligt, mens en længere læsetimeout kan være berettiget for en legitimt lang anmodning. Men hvis applikationen er langsom på grund af en blokeret hændelsesløkke, en databasestop, en overbelastet afhængighed eller en hængende anmodning, skjuler en forøgelse af timeouten kun symptomet.

Gennemgå den nøjagtige semantik i de officielle NGINX proxy timeout-direktiver .

Hvad hvis kun WebSocket-forbindelser får en 502 eller afbryder forbindelsen?

WebSocket-proxying har yderligere krav, fordi ` Upgradeand`- Connectionheaderne er hop-by-hop-headere og ikke automatisk videresendes i den almindelige reverse-proxy-sti. NGINX's officielle WebSocket-dokumentation viser eksplicit indstilling af disse headere.

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

NGINX bemærker også, at en inaktiv proxy-WebSocket-forbindelse lukkes, hvis upstream-forbindelsen ikke sender data inden for læse-timeout-intervallet; en ping på applikationsniveau kan holde forbindelsen aktiv, hvor det er relevant. For aktuel adfærd og versionsspecifikke noter, brug den officielle NGINX WebSocket proxy-dokumentation .

Trin 4: Hvordan validerer du rettelsen uden at skabe et nyt strømafbrydelse?

Test konfigurationen før du genindlæser NGINX:

sudo nginx -t
sudo nginx -s reload

NGINX-dokumenter -tsom en syntaks- og referenced-file-check og -s reloadsom det signal, der genindlæser konfigurationen ved at starte nye workers og elegant lukke gamle ned.

Bekræft derefter begge lag igen:

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

Stop ikke ved "startsiden indlæses". Test den rute, der oprindeligt mislykkedes, igen, inklusive dens HTTP-metode og eventuel anmodningstekst. Hvis 502 kun opstod ved uploads, API-kald, store rapporter eller WebSockets, skal du teste det samme trafikmønster.

Hvad hvis direkte Node.js-anmodninger virker, men NGINX stadig returnerer 502?

Det resultat indsnævrer problemet betydeligt. Tjek disse punkter i rækkefølge:

1. Bekræft den aktive serverblok. Kør sudo nginx -Tog sørg for, at de forventede server_nameog locationhåndterer anmodningen.
2. Bekræft det nøjagtige upstream-mål. Adressen proxy_passskal matche det, der kan nås fra NGINX, ikke blot det, der fungerer fra din bærbare computer eller en anden container.
3. Kontroller protokoluoverensstemmelse. Hvis upstream forventer HTTPS, men NGINX bruger http://, eller omvendt, skal du rette skemaet og derefter konfigurere upstream TLS med vilje.
4. Se efter nulstillinger af programforbindelser. Undersøg Node.js-proceslogfilerne med samme tidsstempel som NGINX-fejlen. Et nedbrud eller en afbrudt forbindelse kræver en rettelse på programsiden.
5. Tjek specialiseret trafik. WebSockets, streamingsvar, store anmodninger og usædvanligt langsomme handlere kan kræve forskellige proxyindstillinger fra en simpel JSON API.

Hvis NGINX og Node.js er adskilt af en firewall, Kubernetes-tjeneste, load balancer, service mesh eller en anden proxy, er det fejlende hop muligvis ikke den lokale NGINX-til-Node-forbindelse. Test hvert hop uafhængigt i stedet for at antage, at den synlige NGINX-server er kilden til fejlen.

Skal du genstarte Node.js eller NGINX først?

En genstart er passende, når du har bevis for, at en proces er stoppet, usund eller kører en forældet konfiguration. Det er ikke den bedste første diagnosticeringshandling, fordi det kan slette spor og midlertidigt få et periodisk problem til at forsvinde.

Hvis Node-porten mangler, skal du kontrollere din proceshåndtering eller containerlogfiler, rette problemet med applikationens opstart, og derefter starte tjenesten. Hvis du kun har ændret NGINX-konfigurationen, skal du bruge den, nginx -tfør du genindlæser. Hvis du har ændret Node.js-kode eller miljøvariabler, skal du genstarte Node-tjenesten ved hjælp af den supervisor, din implementering rent faktisk bruger, f.eks. systemd, en containerorchestrator eller en anden proceshåndtering.

For Node.js produktionsversion skal du også bekræfte, at du er på en understøttet udgivelseslinje. Fra september 2026 viser den officielle Node.js-udgivelsesside Node.js 24 og 22 som LTS-linjer og anbefaler, at produktionsapplikationer bruger Active LTS- eller Maintenance LTS-udgivelser. Tjek den aktuelle status på den officielle Node.js-udgivelsesside i stedet for at stole på en gammel vejledning.

En kompakt NGINX 502 beslutningstabel

Sidste selvtjek

Du har sandsynligvis fundet den grundlæggende årsag i stedet for blot at undertrykke symptomet, når alle følgende er sande:

• Node.js upstream reagerer direkte fra den samme netværkskontekst, som NGINX bruger.
• Node-lytteren bliver proxy_passenige om protokol, adresse og port.
• NGINX-fejlloggen registrerer ikke længere upstream-forbindelsesfejl for den berørte rute.
• nginx -tlykkes før hver genindlæsning af konfigurationen.
• Den oprindelige mislykkede anmodning – ikke kun hjemmesiden – lykkes nu via NGINX.
• Timeouts blev kun ændret, når logfiler og målt applikationsadfærd berettigede ændringen.
• Containerimplementeringer bruger service-to-service-netværk i stedet for at antage, 127.0.0.1at de krydser containergrænser.

Det mest pålidelige fejlfindingsmønster er derfor: test noden direkte, læs NGINX-fejlen, match upstream-adressen med den faktiske netværkstopologi, valider og genindlæs derefter . En 502 er et gateway-symptom. Det nyttige spørgsmål er altid, hvilket hop der mislykkedes, og hvad loggen siger om den fejl.