Nginx 502 Bad Gateway 오류 해결 과정 (실제 원인별 해결 방법 정리)
Nginx 502 Bad Gateway 오류란 무엇인가
웹서버(Server)를 운영하다 보면 갑자기 사이트가 접속되지 않으면서
“502 Bad Gateway” 오류가 발생하는 경우가 있습니다.
이 오류는 단순한 문제가 아니라,
Nginx와 백엔드 서버 간 연결 문제에서 발생하는 대표적인 장애입니다.
이 글에서는 단순 설명이 아니라 실제로 많이 겪는 상황을 기준으로
Nginx 502 Bad Gateway 오류 해결 과정을 단계별로 정리합니다.
실제 문제 상황
웹사이트에 접속하면 다음과 같은 화면이 나타납니다.
- 502 Bad Gateway
- Nginx 에러 페이지 표시
- 서버(Server)는 살아 있는데 서비스만 죽은 상태
특징은:
- 서버는 켜져 있음
- ping 정상
- SSH 접속 가능
즉, 서버 자체 문제가 아니라 서비스 연결 문제입니다.
1. 백엔드 서버가 실행 안된 경우
가장 흔한 원인입니다.
실제 상황
Nginx는 정상 작동 중인데
Node.js, Python, PHP 등 백엔드 서버가 꺼져 있음
해결 방법
백엔드 서버(Server) 상태 확인
ps aux | grep node
또는
sudo systemctl status myapp
해결
백엔드 실행
node app.js
또는 서비스 재시작
sudo systemctl restart myapp
2. 포트 설정 불일치
Nginx와 백엔드 서버(Server)가 서로 다른 포트를 바라보는 경우입니다.
실제 상황
- Nginx → 3000 포트로 요청
- 백엔드 → 5000 포트 실행
→ 연결 실패 → 502 발생
해결 방법
Nginx 설정 확인
sudo nano /etc/nginx/sites-available/default
proxy_pass http://127.0.0.1:3000;
확인
백엔드 서버 포트와 동일하게 맞추기
3. 소켓(socket) 파일 문제
유닉스 소켓을 사용하는 경우 자주 발생합니다.
실제 상황
- PHP-FPM 사용
- socket 파일 경로 불일치
해결 방법
ls /run/php/
Nginx 설정 확인
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
경로가 다르면 수정 필요
4. Nginx 설정 오류
설정 파일이 잘못된 경우입니다.
확인 방법
sudo nginx -t
에러 예시
- syntax error
- invalid directive
해결 방법
설정 수정 후 재시작
sudo systemctl restart nginx
5. 권한 문제 (Permission denied)
파일 또는 소켓 접근 권한 문제입니다.
실제 상황
- Nginx는 www-data로 실행
- 백엔드 파일은 다른 사용자 권한
해결 방법
sudo chown -R www-data:www-data /var/www
또는 권한 변경
chmod 755 /var/www
6. 타임아웃 설정 문제
백엔드 응답이 느린 경우에도 502가 발생할 수 있습니다.
해결 방법
Nginx 설정 수정
proxy_read_timeout 60;
실제 해결 흐름 (경험 기준)
502 오류 발생 시 아래 순서로 확인하면 가장 빠르게 해결됩니다.
- 백엔드 서버 실행 여부 확인
- 포트 일치 여부 확인
- Nginx 설정 검사
- 로그 확인
- 권한 문제 확인
로그로 원인 찾는 방법
로그를 보면 거의 90% 해결됩니다.
Nginx 에러 로그
tail -f /var/log/nginx/error.log
자주 나오는 메시지
- connect() failed
- permission denied
- upstream timed out
초보자가 가장 많이 하는 실수
서버는 켜져 있는데 앱이 꺼져 있음
가장 흔한 케이스
포트 번호 착각
3000 / 8080 / 5000 혼동
설정 수정 후 재시작 안함
변경 사항 적용 안됨
502 오류 체크리스트
- 백엔드 서버 실행 중인가
- 포트가 일치하는가
- Nginx 설정이 맞는가
- 로그에 에러가 있는가
- 권한 문제가 없는가
핵심 요약
- 502 Bad Gateway는 Nginx와 백엔드 연결 문제이다
- 대부분 백엔드 서버 또는 설정 문제이다
- 로그 확인이 가장 빠른 해결 방법이다
- 단계적으로 확인하면 쉽게 해결된다
마무리
Nginx 502 Bad Gateway 오류는 서버(Server)를 운영하면서 반드시 한 번은 겪게 되는 문제입니다.
중요한 것은 당황하지 않고 연결 구조를 이해하고 하나씩 점검하는 것입니다.
이 과정을 한 번 경험하면 이후에는 502 오류를 훨씬 빠르게 해결할 수 있습니다.