Nginx 502 Bad Gateway 발생 원인 정리

 

502는 보통 Nginx → Backend(업스트림) 사이에서 통신이 안 될 때 뜨는 에러임.
즉, Nginx 자체 문제라기보다는 뒤에 있는 서버/컨테이너가 제대로 응답을 못 줬다는 신호임.

 

 

---

업스트림 서버(백엔드) 자체가 죽어있는 경우

• Nginx는 살아있는데, API / Socket 서버가 다운됨
• Docker라면 컨테이너 stop 상태
• PM2/Node라면 프로세스 죽어있음
• Nginx 입장에서 뒤 서버가 아예 없으니까 502 발생함

 

확인 방법

 

docker ps pm2 status systemctl status backend

 

---

업스트림 포트가 열려있지 않음

• Nginx는 http://api:3000으로 보내는데
  백엔드는 실제로 3000이 아니라 다른 포트에서 떠있는 경우
• 또는 방화벽 / 보안 정책으로 포트가 막혀있음

확인 방법

 

 

---

백엔드 응답 속도가 너무 느림 (timeout)

• API 처리 시간이 길어서 Nginx가 기다리다 포기
• 그때 502가 발생함
• 주로 DB lock, deadlock, I/O 대기, 대용량 연산 등에서 자주 발생

해결
Nginx 쪽 timeout 늘리기

 

 

 

서버 자원 부족 (CPU 100%, Memory OOM)

 

• 백엔드 CPU 100% → 응답을 아예 못 함
• 메모리 부족 → Node / Java / Spring 서버가 OOMKilled
• 프로세스는 살아있어도 응답이 안 되면 502로 돌아옴

 

DNS 또는 업스트림 이름 해석 문제

 

• Nginx upstream을 server api:3000; 이렇게 쓰는데
  도커 내부 DNS가 순간적으로 name resolution 실패하면 502 발생
• Swarm/K8s 환경에서 자주 나오는 케이스

해결

• IP 고정 사용 
• 업스트림에 여러 노드 등록해서 Failover 구성

 

 

Nginx 설정 오류 (conf 문법 오류 X → routing 오류 O)

• conf 문법은 OK인데, upstream 블록이 잘못된 포트를 가리키는 경우
• 또는 location 매칭이 잘못되어 백엔드 없이 처리되는 경우도 있음

확인

 

nginx -T nginx -t

 

 

 

 

SSL 관련 프록시 설정 문제

HTTPS → Nginx → HTTP Backend
이런 구조에서 proxy_set_header가 누락되면 백엔드가 요청을 이해 못하고 502 돌려주는 경우 있음.

예:

 

proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme;

 

 

 

업스트림 서버의 Keep-Alive 문제

• 백엔드가 keep-alive를 비정상적으로 끊어버림
• 연결이 순간적으로 reset되면 Nginx가 502 반환

Node.js 환경에서 자주 발생함
특히 socket 서버나 long-polling할 때 종종 뜸.

 

 

 

파일 다운로드/업로드 시 버퍼 문제

• 대용량 업로드/다운로드에서
  Nginx 버퍼보다 큰 파일이 들어오면 upstream prematurely closed connection 로그 발생 → 502로 이어짐

 

관련 설정

client_max_body_size proxy_buffering proxy_buffers

 

 

🔍 502가 뜰 때 가장 먼저 보는 체크리스트

1) nginx 오류 로그 확인

 

/var/log/nginx/error.log

2) 백엔드 로그 확인

502는 거의 항상 백엔드에서 사인 나옴.

3) 실제 업스트림 포트 열려 있는지 확인

 

curl -v http://127.0.0.1:3000

4) 도커 스웜/쿠버 환경이면 노드 문제도 체크

Overlay 네트워크 단절 → 502 폭탄.