웹사이트를 운영하다 보면 마주치는 수많은 에러 코드 중, 관리자의 등골을 가장 서늘하게 만드는 에러가 하나 있습니다. 하얀 바탕에 굵은 글씨로 덩그러니 적힌 **’502 Bad Gateway’**입니다.
접속자가 몰리는 이벤트 기간이나 중요한 업데이트 직후 이 에러가 발생하면, 비즈니스 수익과 직결되는 치명적인 장애가 됩니다. 구글 검색 엔진 역시 접속 불량인 사이트에 SEO(검색 엔진 최적화) 페널티를 부여하므로 신속한 조치가 필수적입니다. 오늘은 Nginx와 PHP-FPM(주로 워드프레스 환경) 조합에서 발생하는 502 Bad Gateway 에러의 근본적인 원인과 실무에서 즉시 적용할 수 있는 단계별 해결 방법을 완벽하게 정리해 드리겠습니다.
1. ‘502 Bad Gateway’ 에러의 진짜 의미는?
에러를 해결하려면 먼저 이 에러가 왜 발생하는지 구조를 이해해야 합니다.
최신 웹 서버 아키텍처는 대부분 프론트(앞단)에 Nginx를 두고, 백엔드(뒷단)에 PHP-FPM, Node.js, Tomcat 등을 두는 ‘리버스 프록시(Reverse Proxy)’ 구조를 사용합니다.
- Nginx (문지기): 사용자의 요청(트래픽)을 가장 먼저 받아 뒷단으로 넘겨줍니다.
- PHP-FPM (실무자): Nginx로부터 넘겨받은 요청(DB 조회, 연산 등)을 실제로 처리하여 다시 Nginx에게 돌려줍니다.
502 Bad Gateway 에러는 ‘문지기(Nginx)’는 정상적으로 살아있는데, ‘실무자(PHP-FPM)’가 죽어있거나 응답을 주지 않을 때 발생합니다. 즉, Nginx 자체의 문제라기보다는 그 뒤에 연결된 백엔드 애플리케이션에 문제가 생겼다는 명백한 신호입니다.
2. 에러가 발생하는 3가지 핵심 원인
실무에서 502 에러를 유발하는 범인은 십중팔구 아래 3가지 중 하나입니다.
- PHP-FPM 프로세스 중지: 서버 재부팅, 메모리 부족(OOM) 등으로 인해 PHP-FPM 데몬 자체가 아예 꺼져있는 경우입니다.
- 소켓(Socket) 통신 경로 불일치: Nginx는 A라는 문(경로)으로 데이터를 넘겨주려 하는데, PHP-FPM은 B라는 문에서 기다리고 있어 서로 연결(통신)이 어긋난 경우입니다.
- 타임아웃(Timeout) 및 자원 고갈: 동시 접속자가 너무 많거나, 무거운 DB 쿼리 연산으로 인해 PHP-FPM이 정해진 시간 내에 Nginx로 응답을 주지 못한 경우입니다.
3. Nginx / PHP-FPM 실전 해결 방법 (트러블슈팅)
원인을 알았으니, 이제 터미널(SSH)에 접속하여 순서대로 범인을 잡아낼 차례입니다. 우분투(Ubuntu) 환경을 기준으로 설명합니다.
[Step 1] PHP-FPM 서비스 상태 확인 및 재시작
가장 먼저 백엔드 프로세스가 살아있는지 확인해야 합니다. (PHP 버전은 본인 서버 환경에 맞게 숫자 8.1 등을 변경하세요.)
Bash
# 상태 확인
sudo systemctl status php8.1-fpm
만약 상태가 inactive (dead) 또는 failed로 나온다면, 데몬이 죽어있는 것입니다. 아래 명령어로 서비스를 재시작해 줍니다.
Bash
sudo systemctl restart php8.1-fpm
sudo systemctl restart nginx
단순한 일시적 오류였다면 이 명령어 두 줄로 사이트가 다시 정상적으로 열릴 것입니다.
[Step 2] 에러 로그(Log) 확인 (가장 중요)
재시작을 해도 여전히 502 에러가 뜬다면, Nginx가 남긴 에러 로그를 읽어 정확한 원인을 파악해야 합니다.
Bash
sudo tail -f /var/log/nginx/error.log
에러 로그를 보면 다음과 같은 핵심 단서들이 영어로 기록되어 있습니다.
connect() to unix:/run/php/php8.1-fpm.sock failed (2: No such file or directory)-> 소켓 경로 불일치 오류 (Step 3 참조)upstream timed out (110: Connection timed out)-> 타임아웃 오류 (Step 4 참조)
[Step 3] 소켓(Socket) 경로 일치시키기
에러 로그에 No such file이 떴다면, Nginx 설정과 PHP-FPM 설정의 통신 주소가 서로 다르게 세팅되어 있는 것입니다.
1. Nginx 설정 확인
Bash
sudo nano /etc/nginx/sites-available/default
파일 내에서 fastcgi_pass 항목이 어떻게 적혀있는지 확인합니다.
- 예시:
fastcgi_pass unix:/run/php/php8.1-fpm.sock;(유닉스 소켓 방식) 또는fastcgi_pass 127.0.0.1:9000;(TCP 방식)
2. PHP-FPM 설정 확인
Bash
sudo nano /etc/php/8.1/fpm/pool.d/www.conf
파일 내에서 listen = 항목을 찾습니다. 이 주소가 방금 확인한 Nginx의 fastcgi_pass 주소와 글자 하나 틀리지 않고 100% 동일해야 합니다. 다르게 적혀있다면 둘 중 하나를 수정하여 맞춰준 뒤, 두 서비스를 모두 재시작합니다.
[Step 4] 타임아웃 및 프로세스 제한(Max Children) 늘리기
트래픽이 몰렸을 때만 502 에러가 뜬다면, 서버가 감당할 수 있는 작업량(프로세스 수)을 늘려주고 기다려주는 시간(타임아웃)을 연장해야 합니다.
1. PHP-FPM 작업자 수 늘리기 www.conf 파일을 다시 열고 아래 설정값들을 서버의 RAM 용량에 맞게 상향 조정합니다. (1GB RAM 기준 권장값 예시)
Ini, TOML
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
2. Nginx 대기 시간 늘리기 Nginx 설정 파일(nginx.conf 또는 default)을 열고 location ~ \.php$ 블록 안에 아래 코드를 추가하여 대기 시간을 늘려줍니다.
Nginx
fastcgi_read_timeout 300;
fastcgi_send_timeout 300;
설정을 저장한 후 sudo nginx -t 로 문법 오류를 체크하고 서버를 재시작합니다.
결론: 당황하지 말고 ‘로그(Log)’부터 읽는 습관
‘502 Bad Gateway’ 에러는 겉보기에는 치명적인 고장 같지만, 사실 Nginx가 “내 뒤에 있는 친구가 응답이 없어요!”라고 친절하게 알려주는 아주 명확한 시스템 메시지입니다.
서버에 장애가 발생했을 때 인터넷 검색부터 하기보다는, tail -f /var/log/nginx/error.log 명령어를 쳐서 서버가 남긴 로그 기록을 먼저 읽어보는 습관을 들이는 것이 중요합니다. 이 트러블슈팅 가이드를 통해 트래픽 폭주 상황에서도 당황하지 않고 안정적으로 대처하는 훌륭한 시스템 엔지니어로 성장하시기를 응원합니다.
