502 Bad Gateway: 원인과 해결 방법

오류의 의미

502는 정상적으로 작동하는 서버가 보내는 응답입니다. 앞단의 웹 서버(nginx, Apache, 로드 밸런서 또는 Cloudflare 같은 CDN)가 요청을 받아 뒤에 있는 애플리케이션(PHP-FPM, Node.js나 Python 프로세스, 백엔드 서버)에 전달했지만 사용할 수 있는 응답을 받지 못한 것입니다. 연결이 거부되었거나, 끊어졌거나, 엉뚱한 데이터가 돌아왔습니다. “Gateway”는 앞단의 서버를, “bad”는 뒤에서 돌아온 응답을 가리킵니다.

따라서 502는 두 가지를 동시에 알려 줍니다. 앞단은 살아 있고 뒤쪽은 다운되었거나 고장 났다는 것입니다. 덕분에 원인을 찾는 범위가 크게 좁혀집니다.

흔한 원인

1. 애플리케이션 프로세스가 실행 중이 아닙니다. PHP-FPM이 비정상 종료되었거나 중지되었고, Node.js 프로세스가 죽었거나, 컨테이너가 종료되었습니다. 앞단이 아예 연결할 수 없습니다.
2. 애플리케이션이 과부하 상태입니다. 모든 PHP-FPM 워커가 사용 중이고, 대기열이 가득 차서 새 연결이 거부됩니다. 트래픽이 급증하거나 느린 데이터베이스 쿼리가 모든 워커를 막은 뒤에 자주 발생합니다.
3. 설정의 소켓 또는 포트가 잘못되었습니다. 업데이트나 PHP 버전 변경 후 nginx는 여전히 php8.2-fpm.sock을 가리키는데 새 풀은 php8.4-fpm.sock에서 대기하는 경우입니다.
4. 시간 제한이 너무 짧게 설정되었습니다. 백엔드는 응답하지만 앞단이 기다려 주는 시간보다 늦게 응답합니다. 어떤 환경에서는 이를 502로, 다른 환경에서는 504 Gateway Timeout으로 보고합니다.
5. 백엔드가 너무 큰 헤더나 잘못된 응답을 보냅니다. 쿠키에 많은 내용을 담는 프레임워크에서 전형적으로 나타나며, 이때 nginx는 “upstream sent too big header”를 기록합니다.
6. CDN이 서버에 연결하지 못합니다. Cloudflare를 앞에 두었을 때 Cloudflare 로고가 있는 502 페이지가 보이면, Cloudflare가 원본 서버에서 아무것도 받지 못했다는 뜻입니다. 방화벽, 이전 후 잘못된 IP, 또는 서버가 단순히 다운된 경우입니다.

방문자인 경우

다른 사람의 사이트에서 발생한 502는 해결할 수 없습니다. 1분 후에 한 번 새로 고침해 보세요. 계속되면 사이트 소유자가 조치해야 합니다. 직접 운영하는 사이트라면 계속 읽어 주세요.

직접 운영하는 사이트라면: 먼저 확인할 것

모든 사람에게 다운인가요? 웹사이트 다운 확인 도구를 실행하세요. 외부에서 본 상태 코드와, CDN이 응답했는지 원본 서버가 응답했는지 보여 줍니다.

공유 호스팅이나 사이트 빌더인가요? 그런 환경의 502는 거의 항상 호스팅 업체의 문제입니다(공유 노드의 과부하된 PHP 풀). 아래의 호스팅 업체에 보낼 메시지로 바로 넘어가세요.

직접 운영하는 서버: SSH로 로그인해서 웹 서버에 무엇이 잘못되었는지 물어보세요.

# nginx: 마지막 오류, 가장 최근 항목이 맨 아래
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

대표적인 로그 줄과 그 의미:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM이 실행 중이 아니거나 소켓 경로가 잘못되었습니다.
• connect() failed (111: Connection refused) while connecting to upstream: 백엔드 포트가 대기 중이 아닙니다.
• upstream prematurely closed connection: 응답하는 도중 백엔드 프로세스가 비정상 종료되었습니다. 대개 PHP 치명적 오류나 메모리 부족입니다.
• upstream sent too big header: 버퍼를 늘립니다(아래 참조).
• (11: Resource temporarily unavailable): 모든 PHP-FPM 워커가 사용 중입니다.

직접 운영하는 서버에서의 해결 방법

1. 중지된 서비스 시작

# 사용 중인 PHP-FPM 버전 찾기
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# systemd로 관리되는 Node.js 또는 Python 앱
sudo systemctl restart myapp

서비스가 시작되지 않으면 이유는 journalctl -u php8.3-fpm -n 50에 있습니다. 가장 흔한 원인은 가득 찬 디스크(df -h)이고, 두 번째는 풀 설정의 구문 오류(sudo php-fpm8.3 -t)입니다.

2. 소켓 또는 포트 수정

nginx가 연결하는 대상과 PHP-FPM이 대기하는 대상을 비교하세요.

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

두 값은 일치해야 합니다. 변경 후에는 다시 불러오기 전에 항상 설정을 테스트하세요.

sudo nginx -t && sudo systemctl reload nginx

mod_proxy_fcgi를 통해 Apache와 PHP-FPM을 사용하는 경우에도 SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost" 줄에 같은 확인이 적용됩니다. sudo apachectl configtest로 테스트하세요.

3. PHP-FPM에 여유 확보

오류 로그에 워커가 사용 중이라거나 server reached pm.max_children이라고 나오면 풀 파일(/etc/php/8.3/fpm/pool.d/www.conf)에서 한도를 올립니다.

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

워커마다 메모리가 필요합니다(WordPress의 경우 흔히 30~80 MB). 숫자를 올리기 전에 free -m을 확인하고, 애초에 워커를 계속 붙잡고 있는 느린 쿼리나 플러그인을 찾아보세요.

4. 큰 헤더를 위해 버퍼 늘리기

nginx 서버 블록에서:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. WordPress의 경우

플러그인이나 테마를 업데이트한 직후의 502는 대개 PHP의 메모리가 부족하거나 모든 요청에서 치명적 오류가 발생한다는 뜻입니다. SFTP 또는 SSH로 플러그인 폴더의 이름을 바꿔 비활성화한 후(wp-content/plugins/plugin-name을 plugin-name.off로) 사이트를 다시 불러오세요. journalctl에 “Allowed memory size exhausted”가 표시되면 풀 또는 php.ini의 memory_limit를 올리세요. WP-CLI를 사용한다면: wp plugin deactivate plugin-name.

6. Cloudflare를 사용하는 경우

원본 서버가 직접 응답하는지 확인하세요: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. 이것이 작동하면 서버의 방화벽이 Cloudflare의 주소 범위를 차단하고 있거나, Cloudflare의 DNS 레코드가 이전 IP를 가리키고 있을 수 있습니다.

호스팅 업체의 문제인 경우

공유 호스팅에서는 PHP-FPM을 재시작할 수 없습니다. 호스팅 업체에 시각과 정확한 오류를 포함해 다음 내용을 보내세요.

안녕하세요. 제 웹사이트 example.com이 약 14:30 UTC부터 “502 Bad Gateway”를 반환합니다. 외부 확인에서도 같은 결과가 나오며, 제 쪽에서는 아무것도 변경하지 않았습니다. 제 호스팅 계정의 PHP 프로세스와 웹 서버를 확인해 주시고, 복구되면 알려 주시기 바랍니다.

다음번을 막으려면

502는 거의 항상 중지되었거나 과부하된 백엔드가 원인이며, 둘 다 방문자가 알아차리기 전에 확인할 수 있습니다. 중지된 PHP-FPM 서비스, 부족해지는 메모리, 차오르는 디스크가 그 예입니다. 에이전트를 이용한 서버 모니터링은 바로 이런 항목을 서버 내부에서 보고하고, 외부의 웹사이트 확인은 502가 나타나는 순간 이를 잡아냅니다. 직접 운영하는 서버에서는 Quick Fix가 설정 테스트를 통과한 후 중지된 서비스를 재시작할 수 있으며, 원인이 더 깊다면 Deep Fix가 24시간 맡아 처리합니다.