502 Bad Gateway 에러 해결하기

502 에러가 뜨는 상황

502 Bad Gateway는 Nginx가 백엔드 서버(Node.js, Python, Go 등)와 통신하지 못할 때 나타난다. 브라우저에는 "나쁜 게이트웨이" 또는 "일시적인 오류"라고 보인다.

배포 후 갑자기 이 에러가 나거나, 특정 시간대에만 계속 나타난다면 서버 자원 부족이나 프로세스 충돌을 의심해야 한다.

현재 상태 파악하기

먼저 어떤 포트에서 서버가 떠있는지 본다.

sudo ss -lntp | grep LISTEN

예상:

LISTEN 127.0.0.1:3000 (Node.js 앱)
LISTEN 127.0.0.1:5432 (PostgreSQL)

백엔드 서버가 떠있어야 Nginx가 연결할 수 있다. 없다면 프로세스를 시작해야 한다.

Nginx 로그 확인

Nginx가 왜 연결을 못 했는지 확인한다.

sudo tail -50 /var/log/nginx/error.log

흔한 메시지들:

• connect() failed: 백엔드 서버가 안 떠있음
• upstream timed out: 백엔드가 응답이 너무 느림
• too many open files: 동시 연결이 너무 많음

백엔드 서버 상태 확인

# Node.js 앱이 응답하는지 직접 테스트
curl http://localhost:3000

# Docker 컨테이너인 경우
docker ps | grep app_name
docker logs app_container_name

# 프로세스별 CPU/메모리 사용량
ps aux | grep node

# 에러 로그
tail -100 ~/app/logs/error.log

만약 백엔드가 응답하지 않으면 프로세스를 재시작해야 한다.

# systemd로 관리되는 경우
sudo systemctl restart myapp

# PM2로 관리되는 경우
pm2 restart myapp

# Docker의 경우
docker restart app_container_name

동시 연결 제한 확인

동시에 너무 많은 요청이 들어오면 502가 발생할 수 있다. 특히 캐시를 비우거나 배포 후에 트래픽이 몰릴 때 주의하자.

# 열려있는 파일 수 제한 확인
ulimit -n

# 너무 작으면 늘린다 (root)
ulimit -n 65536

또한 Nginx 설정에서 upstream 연결 수를 확인한다.

upstream backend {
    server 127.0.0.1:3000;
    keepalive 32;
}

배포 전 체크리스트

• 백엔드 서버가 정상적으로 응답하는가?
• Nginx 설정에서 upstream 주소가 맞는가?
• 방화벽이 포트를 차단하지 않는가?
• 디스크 공간이 충분한가?
• 파일 디스크립터 제한은 적절한가?

모두 확인한 후 배포하면 502 에러를 대부분 피할 수 있다.