Nginx 웹 서버를 프론트에 두고 백엔드로 PHP-FPM, Node.js, Python(Gunicorn) 등을 Reverse Proxy 형태로 연동해 사용할 때 가장 흔히 마주치는 에러가 502 Bad Gateway입니다.
이 가이드는 Nginx가 백엔드 애플리케이션 서버로부터 유효한 응답을 받지 못했을 때 발생하는 502 에러의 진단법과 트러블슈팅을 다룹니다.
1. 502 Bad Gateway 핵심 발생 원인
- 백엔드 프로세스 중단: PHP-FPM 또는 Node.js 데몬 프로세스가 꺼져 있는 경우
- 소켓/포트 설정 불일치: Nginx 설정의
proxy_pass/fastcgi_pass주소가 실제 백엔드 바인딩 주소와 다른 경우 - 권한 부족: UNIX Domain Socket 파일(
.sock) 사용 시 Nginx 권한(www-data)이 해당 파일에 접근하지 못하는 경우
2. 원인별 진단 및 해결 방법
[1단계] Nginx 에러 로그 확인
추측 대신 원인을 정확히 파악하기 위해 에러 로그 마지막 줄을 점검합니다.
Bash
sudo tail -n 30 /var/log/nginx/error.log
[2단계] 백엔드 애플리케이션 상태 확인 및 실행
백엔드 데몬이 정상 실행 중인지 확인합니다.
Bash
# PHP-FPM 상태 확인
sudo systemctl status php8.1-fpm
# Node.js (PM2 사용 시) 상태 확인
pm2 status
꺼져 있다면 sudo systemctl start php8.1-fpm 등으로 실행시킵니다.
[3단계] 소켓 파일 및 포트 바인딩 확인
Nginx 설정(/etc/nginx/sites-available/default)에 적힌 주소와 백엔드 소켓/포트가 일치하는지 점검합니다.
- PHP-FPM (Unix Socket) 예시: Nginx 설정:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;실제 해당 경로에.sock파일이 생성되어 존재하는지 점검합니다. - Node.js / Express (TCP Port) 예시: Nginx 설정:
proxy_pass [http://127.0.0.1:3000](http://127.0.0.1:3000);netstat -tlpn | grep 3000명령어로 3000번 포트가 LISTEN 중인지 확인합니다.