Nginx 502 Bad Gateway 오류, 원인부터 설정 최적화까지 완벽 해결 가이드

웹 서비스를 운영하다 보면 가장 당황스러운 순간 중 하나가 바로 '502 Bad Gateway' 에러를 마주하는 순간일 겁니다. 사용자는 "서버가 다운되었나?"라고 생각하지만, 실제로는 Nginx라는 게이트웨이가 백엔드 서비스와 통신하는 과정에서 문제가 발생했음을 의미합니다.

Nginx는 그 자체로 완벽한 웹 서버이지만, 백엔드(예: Python/Django, Node.js API)와 통신하는 '중개자' 역할을 수행하기 때문에, 이 통신 과정의 사소한 문제 하나가 치명적인 502 오류로 이어지곤 합니다.

이 글은 단순히 오류 코드를 검색하여 임시방편적인 해결책을 찾는 것을 넘어, 502 오류가 발생하는 모든 잠재적 원인(네트워크, 설정, 리소스)을 체계적으로 진단하고, 서비스 환경에 맞는 근본적인 해결책을 제시하는 DevOps 엔지니어 및 시스템 관리자를 위한 심층 가이드입니다.

1단계: 502 오류, 어디서부터 진단해야 할까? (기초 점검)

502 오류는 증상일 뿐, 원인은 다양합니다. 가장 먼저 해야 할 일은 '네트워크 연결'과 '서비스 활성화 여부'를 확인하는 것입니다.

1. 방화벽 및 네트워크 경로 점검

가장 흔하지만 간과하기 쉬운 부분입니다. Nginx가 백엔드 서버(예: 8000 포트)에 접근하는 경로에 방화벽(iptables, Security Group 등)이 막혀있을 수 있습니다.

✅ 진단 방법: Nginx가 실행되는 서버에서 백엔드 포트로의 연결 테스트를 수행합니다.

# 텔넷을 이용한 포트 연결성 확인
telnet [백엔드 서버 IP] [백엔드 포트]
# 예시: telnet 127.0.0.1 8000

만약 Connection refused가 뜬다면, 백엔드 서비스 자체가 해당 포트에서 리스닝하고 있지 않다는 의미입니다.

2. 백엔드 서비스의 활성화 및 로그 확인

Nginx가 요청을 받았을 때, 백엔드 프로세스(Gunicorn, Uvicorn 등)가 실제로 실행 중인지 확인해야 합니다.

# 프로세스 확인 (백엔드 프로세스 이름으로 변경)
ps aux | grep gunicorn
# 또는
systemctl status your_backend_service

만약 프로세스가 보이지 않거나, systemctl 상태가 failed라면, 서비스 시작 스크립트나 환경 변수 설정에 문제가 있는 것입니다. 가장 먼저 백엔드 서비스의 로그를 확인하여 502가 발생하기 직전의 에러 메시지를 찾는 것이 핵심입니다.

2단계: Nginx 설정 파일 심층 분석 및 최적화 (타임아웃 관리)

기초 점검에서 문제가 없다면, 문제는 대부분 Nginx가 백엔드로부터 응답을 기다리는 '시간' 문제일 가능성이 높습니다. Nginx는 기본적으로 매우 보수적인 타임아웃 설정을 가지고 있어, API 호출이 조금만 오래 걸려도 502를 반환할 수 있습니다.

nginx.conf 또는 해당 server 블록 내의 location 블록에 다음 세 가지 핵심 지시어를 반드시 점검하고, 필요에 따라 값을 늘려주어야 합니다.

💡 실무 팁: 만약 사용자가 대용량 파일을 업로드하거나, 복잡한 ML 모델 추론을 거치는 API라면, 기본값(보통 60초)으로는 부족합니다. proxy_read_timeout을 120초 이상으로 늘려주는 것만으로도 502 오류가 해결되는 경우가 많습니다.

Keepalive와 연결 유지

또한, proxy_http_version 1.1;과 함께 proxy_set_header Connection "";를 추가하여 HTTP Keepalive를 명시적으로 설정해주는 것이 연결 안정성에 도움이 됩니다.

3단계: 백엔드 서비스 관점에서의 문제 해결 (Worker와 리소스)

Nginx 설정이 완벽해도, 백엔드 서비스 자체가 병목 현상을 일으키면 502가 발생합니다. 특히 MSA 환경에서는 게이트웨이 역할을 하는 Nginx가 트래픽을 분산시키면서 백엔드 Worker 프로세스에 부하가 집중될 수 있습니다.

1. Worker 프로세스 제한과 Nginx 연결 제한의 관계

대부분의 백엔드 프레임워크(예: Python의 Gunicorn)는 --workers 옵션으로 Worker 프로세스 수를 제한합니다. 만약 Nginx가 동시에 100개의 요청을 보내려고 하는데, 백엔드 Worker가 4개만 존재한다면, 나머지 요청들은 대기열에 쌓이거나, Worker가 과부하로 인해 응답을 제때 하지 못해 Nginx의 타임아웃을 초과하게 됩니다.

✅ 해결책:

1. Worker 수 조정: 트래픽 예상량과 서버 코어 수에 맞춰 Worker 수를 적절히 설정합니다. (일반적으로 (2 * 코어 수) + 1을 권장합니다.)
2. 리소스 모니터링: top 또는 htop을 사용하여 CPU 및 메모리 사용률을 지속적으로 체크합니다. 메모리 누수(Memory Leak)가 발생하면 시스템 전체가 느려지며 502로 이어집니다.

2. 네트워크 연결 상태 심층 분석 (진단 도구 활용)

설정 변경으로 해결되지 않는 경우, 네트워크 레벨에서 패킷이 드롭되고 있을 수 있습니다. 이때는 시스템 레벨의 도구를 사용해야 합니다.

netstat 활용: 현재 열려있는 포트와 연결 상태를 확인합니다.

netstat -an | grep 8000
# ESTABLISHED 상태의 연결이 비정상적으로 많거나, TIME_WAIT 상태가 과도하면 리소스 문제가 있을 수 있습니다.

tcpdump 활용 (최종 수단): 실제 네트워크 패킷이 오가고 있는지 확인하는 가장 확실한 방법입니다. Nginx 서버와 백엔드 서버 양쪽에서 패킷 캡처를 시도하여, 요청(SYN)은 가지만 응답(SYN-ACK 또는 ACK)이 오지 않는지 확인합니다.

# 백엔드 서버에서 8000 포트로 들어오는 패킷 캡처 예시
sudo tcpdump -i eth0 port 8000 -nn -c 10

만약 요청 패킷 자체가 보이지 않는다면, 문제는 Nginx나 백엔드가 아닌, 중간 라우터나 방화벽에 있을 확률이 99%입니다.

🚀 AI 모델 서빙 환경 (FastAPI + Uvicorn) 특이 케이스 분석

최근 AI/ML API를 서빙하는 환경(예: FastAPI + Uvicorn)에서 502가 발생하는 경우, 일반적인 웹 요청보다 더 까다로운 경우가 많습니다.

특이점: 모델 추론(Inference) 과정은 CPU/GPU 자원을 매우 집중적으로 사용하며, 이 과정에서 CPU 자원 고갈이 발생할 수 있습니다.

해결책:

1. 워커 수 제한: Uvicorn이나 Gunicorn을 사용할 때, 너무 많은 워커(Worker)를 할당하면 모든 워커가 동시에 최대 부하를 받게 되어 시스템 전체가 마비될 수 있습니다. 적절한 워커 수를 설정하고, 필요하다면 CPU 사용률 모니터링을 통해 부하를 분산해야 합니다.
2. 비동기 처리 검토: 만약 요청이 순차적으로 처리되어야 하는 작업이라면, 비동기(Async) 처리가 적절한지 재검토하고, 필요하다면 메시지 큐(Redis/RabbitMQ)를 도입하여 요청을 분리 처리하는 것이 안정적입니다.

이러한 다층적인 점검(네트워크 → 서비스 설정 → 자원 할당)을 통해 500 에러의 근본 원인을 찾아 해결할 수 있습니다.