Nginx 502 Bad Gateway, 더 이상 '임시방편'으로만 해결하지 마세요: 근본 원인 진단 가이드

"502 Bad Gateway" 에러 메시지를 마주하는 순간, 많은 개발자와 DevOps 엔지니어들은 당황합니다. 마치 시스템 전체가 멈춘 것처럼 보이기 때문이죠. 이 에러는 단순히 '어딘가 잘못되었다'는 추상적인 메시지일 뿐, 그 원인은 백엔드 애플리케이션의 메모리 부족일 수도 있고, 네트워크 타임아웃일 수도 있으며, 심지어 Nginx 설정의 사소한 오타일 수도 있습니다.

단순히 proxy_pass 지시어를 수정하거나, 서버를 재부팅하는 임시방편적인 대응은 재발을 막지 못합니다. 이 글은 Nginx 502 오류를 마주했을 때, 마치 과학 수사대처럼 체계적으로 원인을 추적하고, 재발을 원천 차단하는 '방법론' 자체를 습득하는 것을 목표로 합니다.

1. Nginx 502 오류, 왜 자꾸 마주치게 되는가? (문제 정의)

Nginx는 그 자체로 웹 서버이자, 클라이언트와 백엔드 서버(WAS, API 서버 등) 사이를 중재하는 '리버스 프록시' 역할을 수행합니다. 502 Bad Gateway는 클라이언트가 Nginx에게 요청을 보냈고, Nginx가 백엔드 서버에 요청을 전달했으나, 백엔드 서버로부터 유효하지 않거나 제때 응답을 받지 못했을 때 Nginx가 클라이언트에게 대신 전달하는 '중개 실패' 신호입니다.

쉽게 말해, Nginx는 "나한테는 요청이 왔는데, 뒤에 있는 친구(백엔드)가 말을 안 듣거나 이상한 소리를 해서, 너한테는 이 에러만 전달할게"라고 말하는 것과 같습니다.

이 에러가 발생하는 근본적인 원인은 크게 세 가지로 분류할 수 있습니다.

1. 시간 초과 (Timeout): 백엔드 처리가 너무 오래 걸림.
2. 자원 고갈 (Resource Exhaustion): 백엔드 서버가 동시 연결을 감당하지 못함.
3. 설정 불일치 (Misconfiguration): Nginx와 백엔드 간의 통신 방식이나 포트가 맞지 않음.

2. 1단계 진단: 502 오류의 작동 원리 이해하기

Nginx가 백엔드 서버와 통신할 때, 이 통신 과정에는 시간 제한(Timeout)이 걸려 있습니다. 이 시간 제한을 이해하는 것이 502 해결의 첫걸음입니다.

핵심 지시어 이해하기: 타임아웃 설정

Nginx 설정 파일(nginx.conf 또는 sites-available/default)에서 프록시 관련 타임아웃을 제어하는 세 가지 주요 지시어가 있습니다. 이 값들이 너무 짧게 설정되어 있으면, 실제로는 정상적인 처리 시간이 필요한 경우에도 502가 발생할 수 있습니다.

💡 실습 예시: 만약 백엔드 API 호출에 최대 120초가 걸릴 것으로 예상된다면, 다음과 같이 설정값을 늘려주어야 합니다.

location /api/slow_process {
    proxy_pass http://backend_upstream;
    proxy_connect_timeout 120s;
    proxy_read_timeout 120s; # 이 값을 늘리는 것이 핵심일 때가 많습니다.
}

3. 2단계 분석: 가장 흔한 3가지 근본 원인과 해결책

A. 원인 1: 백엔드 처리 시간 초과 (Timeout)

가장 흔한 원인입니다. API 요청이 복잡한 DB 쿼리나 무거운 계산을 포함하여 60초를 초과하는 경우, Nginx는 proxy_read_timeout에 의해 연결을 끊고 502를 반환합니다.

✅ 해결책:

1. (단기) proxy_read_timeout 값을 늘립니다. (최후의 수단)
2. (장기) 백엔드 로직을 비동기 처리(Async Job Queue)로 변경하여, Nginx는 즉시 "요청 접수 완료"만 받고 실제 처리는 별도의 워커가 담당하게 구조를 개선합니다.

B. 원인 2: 연결 풀 고갈 (Connection Pool Exhaustion)

백엔드 서버(예: Gunicorn, Tomcat)는 동시에 처리할 수 있는 워커(Worker) 또는 프로세스(Process)의 개수가 제한되어 있습니다. 만약 Nginx가 100개의 동시 요청을 보내려고 하는데, 백엔드 워커가 10개밖에 없다면, 나머지 90개 요청은 대기열에 쌓이거나 연결을 받지 못해 502가 발생합니다.

✅ 해결책: 백엔드 서버의 최대 동시 연결 수와 Nginx의 요청 처리량을 비교해야 합니다.

C. 원인 3: 백엔드 서비스 다운 또는 포트 충돌

가장 단순하지만 놓치기 쉬운 경우입니다. 백엔드 서비스 자체가 다운되었거나, Nginx가 바라보는 포트가 다른 프로세스에 의해 점유된 경우입니다.

✅ 진단 도구 활용: 네트워크 연결 확인 이 경우, netstat 명령어를 통해 해당 포트가 정상적으로 리스닝(Listening) 중인지 확인하는 것이 가장 빠릅니다.

# 예시: 8080 포트가 열려 있는지 확인
sudo netstat -tuln | grep 8080

🚀 심화 진단: 로그 분석과 성능 개선

위의 기본적인 점검으로 해결되지 않았다면, 다음 두 가지 영역을 점검해야 합니다.

1. Nginx 에러 로그 분석 (가장 중요)

Nginx의 에러 로그(error.log)에는 실패의 원인에 대한 구체적인 힌트가 담겨 있습니다. 다음과 같은 키워드를 검색해 보세요.

• upstream timed out: 백엔드 서버가 응답하지 않고 시간 초과가 발생했음을 의미합니다. (→ 백엔드 성능 문제)
• connection refused: 백엔드 서버가 해당 포트에서 아예 연결을 거부했음을 의미합니다. (→ 백엔드 서비스 다운 또는 방화벽 문제)

2. 로드 밸런싱 및 Keepalive 설정 검토

여러 대의 서버로 분산(Upstream)하는 경우, Nginx의 keepalive 설정이 적절한지 확인해야 합니다. 너무 짧은 keepalive 시간은 연결을 불안정하게 만들 수 있습니다.

결론적으로, 502 Bad Gateway 에러는 Nginx가 백엔드 서버와 통신하는 과정에서 문제가 발생했음을 의미하며, 원인은 대부분 '시간 초과(Timeout)' 또는 '연결 거부(Refused)'입니다.

💡 요약 체크리스트

1. [ ] Nginx 에러 로그에서 upstream timed out 검색.
2. [ ] 백엔드 서버가 정상적으로 실행 중인지 확인 (서비스 상태 점검).
3. [ ] netstat으로 포트 리스닝 상태 확인.
4. [ ] 필요하다면 Nginx의 proxy_read_timeout 값을 늘려 테스트.