Nginx 502/504 에러 원인과 해결법 총정리 – 실무 트러블슈팅 프로세스
서비스 운영하다 보면 한 번쯤은 꼭 마주치게 되는 에러가 있죠. 바로 Nginx의 502 Bad Gateway와 504 Gateway Timeout이에요. 저도 한밤중에 모니터링 알림이 울려서 부랴부랴 서버에 접속했던 기억이 있는데, 처음엔 로그를 어디서 봐야 하는지조차 헤맸어요. 😅
이 두 에러는 비슷해 보이지만 원인이 다르고, 해결 방법도 달라요. 오늘은 제가 실제로 겪으면서 정리한 로그 분석 순서와 타임아웃 설정 변경 프로세스를 처음부터 끝까지 공유해볼게요!
502 vs 504, 뭐가 다른 건가요? 🤔
둘 다 Nginx가 뒤쪽 서버(업스트림)와 통신하다 생기는 에러인데요, 핵심 차이를 먼저 알아야 정확한 진단이 가능해요.
| 구분 | 502 Bad Gateway | 504 Gateway Timeout |
|---|---|---|
| 의미 | 업스트림이 잘못된 응답을 보냄 | 업스트림이 시간 내 응답하지 않음 |
| 주요 원인 | 백엔드 프로세스 죽음, 소켓 오류 | 처리 시간 초과, 과부하 |
| 체감 증상 | 페이지가 즉시 에러 표시 | 한참 로딩 후 에러 표시 |
| 핵심 확인 | 업스트림 서비스 상태 점검 | 타임아웃 설정값 점검 |
쉽게 기억하는 팁이에요. 502는 "백엔드가 죽었거나 이상한 답을 보낸 것", 504는 "백엔드가 너무 오래 생각하고 있는 것"이라고 보시면 돼요.
1단계: 로그부터 확인하세요 🔍
에러가 발생하면 감으로 설정을 바꾸기 전에 반드시 로그를 먼저 확인해야 해요. Nginx에서 확인해야 할 로그는 크게 두 가지예요.
에러 로그 (error.log)
sudo tail -f /var/log/nginx/error.log
실시간으로 에러 로그를 추적할 수 있어요. 에러 발생 시점에 어떤 메시지가 찍히는지 주의 깊게 살펴보세요.
로그에서 자주 보이는 메시지별 의미를 정리해봤어요.
| 로그 메시지 | 에러 | 의미 |
|---|---|---|
| connect() failed (111: Connection refused) | 502 | 업스트림 서비스가 꺼져 있음 |
| upstream prematurely closed connection | 502 | 백엔드가 응답 도중 연결을 끊음 |
| upstream timed out (110: Connection timed out) | 504 | 업스트림 응답 대기 시간 초과 |
| no live upstreams while connecting | 502 | 모든 업스트림 서버가 다운됨 |
액세스 로그 (access.log)
sudo cat /var/log/nginx/access.log | grep " 502 \| 504 "
502와 504 응답이 발생한 요청만 필터링해서 볼 수 있어요. 특정 URL이나 시간대에 집중되는지 패턴을 파악하는 데 유용해요.
Nginx 로그만 보고 끝내면 안 돼요! 반드시 업스트림 서비스(PHP-FPM, Node.js, Gunicorn 등)의 자체 로그도 함께 확인해야 정확한 원인을 찾을 수 있어요.
2단계: 업스트림 서비스 상태 점검 🩺
로그에서 원인의 방향이 잡혔다면, 이제 백엔드 서비스를 직접 확인할 차례예요.
- 프로세스 생존 확인 — systemctl status php-fpm 또는 pm2 status 등으로 백엔드가 살아있는지 확인해요.
- 포트/소켓 연결 테스트 — curl -v http://127.0.0.1:8080으로 업스트림에 직접 요청을 보내봐요. Nginx를 거치지 않고 백엔드 응답을 확인할 수 있어요.
- 리소스 확인 — top, free -h, df -h로 CPU, 메모리, 디스크 상태를 점검해요. 리소스 부족으로 백엔드가 응답을 못 하는 경우가 꽤 많아요.
3단계: Nginx 타임아웃 설정 변경 ⚙️
504 에러가 반복된다면, Nginx의 타임아웃 값이 백엔드 처리 시간보다 짧게 설정되어 있을 가능성이 높아요. 핵심 설정 세 가지를 알아볼게요.
📝 핵심 타임아웃 설정
proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; send_timeout 60s;
| 설정값 | 역할 | 권장값 |
|---|---|---|
| proxy_connect_timeout | 업스트림 연결 수립 대기 시간 | 5~15s |
| proxy_send_timeout | 업스트림에 요청 전송 대기 시간 | 60s |
| proxy_read_timeout | 업스트림 응답 대기 시간 (504 핵심!) | 60~300s |
| send_timeout | 클라이언트에 응답 전송 대기 시간 | 60s |
설정 파일 위치는 보통 /etc/nginx/nginx.conf 또는 /etc/nginx/sites-available/ 내 해당 사이트 설정 파일이에요. proxy_read_timeout이 504 에러와 가장 직접적으로 연관되니 이 값을 먼저 조절해보세요.
설정을 변경한 뒤에는 반드시 문법 검사와 리로드를 해주세요.
sudo nginx -t && sudo systemctl reload nginx
restart가 아닌 reload를 사용하면 서비스 중단 없이 설정을 적용할 수 있어요.
타임아웃을 무작정 높이는 건 위험해요! 300s 이상으로 설정하면 느린 요청이 커넥션을 오래 점유해서 전체 서버 성능이 저하될 수 있어요. 근본 원인(느린 쿼리, 무거운 API 등)을 먼저 해결하는 게 우선이에요.
실전 트러블슈팅 플로우차트 🗺️
제가 실무에서 에러를 만났을 때 따르는 순서를 정리해봤어요. 이 흐름대로 하면 대부분의 경우 원인을 찾을 수 있어요.
트러블슈팅 5단계 📝
- 에러 확인 — 502인지 504인지 정확히 구분하기
- Nginx error.log 확인 — 어떤 메시지가 찍혔는지 파악
- 업스트림 서비스 점검 — 프로세스 상태, 직접 요청 테스트
- 서버 리소스 확인 — CPU, 메모리, 디스크 여유 점검
- 설정 조정 — 타임아웃 값 변경 후 reload, 모니터링
마무리: 핵심 내용 요약 📝
502와 504 에러는 원인이 다르기 때문에 접근 방법도 달라야 해요.
- 502 Bad Gateway: 업스트림 서비스가 죽었거나 비정상 응답을 보내는 경우. 백엔드 프로세스 상태를 먼저 점검하세요.
- 504 Gateway Timeout: 업스트림이 시간 내 응답하지 못하는 경우. proxy_read_timeout 조정과 함께 백엔드 성능 최적화가 필요해요.
- 로그가 최우선: 설정을 바꾸기 전에 error.log와 업스트림 로그를 반드시 먼저 확인하세요.
- 타임아웃은 신중하게: 무작정 올리지 말고, 근본 원인을 먼저 해결한 뒤 적정값으로 설정하세요.
서버 운영은 경험이 쌓일수록 대응이 빨라지더라고요. 혹시 다른 에러 코드나 특이한 상황을 겪으신 적 있다면 댓글로 공유해주세요. 같이 해결해봐요~ 😊