Nginx 502 Bad Gateway 에러 원인과 해결방법 - 헤이든의 전산실 (Hayden's Server Room)

이번 포스트에서는 Nginx 502 Bad Gateway error(에러) 원인과 해결방법을 알아보겠습니다. 웹사이트를 운영하다 보면 누구나 한 번쯤은 마주치게 되는 502 Bad Gateway 에러. 특히 Nginx를 사용하는 서버에서는 더욱 자주 발생하는 문제입니다. 실제로 트위터에서 “bad gateway”를 검색해보면 매일 수천 개의 트윗이 호스팅 회사에 이 문제를 신고하고 있다고 합니다.

이 글에서는 Nginx 502 에러가 발생하는 이유부터 단계별 해결방법, 그리고 예방법까지 상세히 알아보고자 합니다.

목차(Contents)

1. Nginx – 502 Bad Gateway error(에러)란 무엇인가?

502 Bad Gateway 에러는 서버(Nginx)가 게이트웨이나 프록시 역할을 하면서 업스트림 서버로부터 유효하지 않은 응답을 받았을 때 발생합니다. 쉽게 말해, Nginx가 중간 다리 역할을 하는데 뒤쪽 서버에서 제대로 된 답변을 받지 못했다는 뜻입니다.

502 에러의 다양한 표현 방식

웹사이트마다 502 에러를 다르게 표시하기도 합니다:

“502 Bad Gateway”
“HTTP Error 502 – Bad Gateway”
“502 Service Temporarily Overloaded”
“502 Proxy Error”
“Bad Gateway NGINX”

모두 동일한 문제를 가리키지만, 사용하는 웹서버나 브라우저에 따라 표현이 조금씩 다를 뿐입니다.

2. 502 에러가 발생하는 주요 원인들

2-1. PHP-FPM 서비스 문제

Nginx가 PHP-FPM과 성공적으로 연결할 수 없거나 PHP-FPM이 적절하게 응답하지 못할 때 502 에러가 발생합니다. 이는 가장 흔한 원인 중 하나입니다.

주요 증상:

PHP-FPM 프로세스가 중지된 상태
소켓 파일이 존재하지 않음
권한 문제로 Nginx가 PHP-FPM에 접근 불가

2-2. 설정 불일치 문제

Nginx 설정에서 PHP-FPM과의 통신 방식(소켓 또는 TCP)이 일치하지 않을 때 502 에러가 발생합니다.

예시 상황:

Nginx: fastcgi_pass 127.0.0.1:9000; (TCP 방식)
PHP-FPM: listen = /var/run/php5-fpm.sock (소켓 방식)

2-3. 타임아웃 관련 문제

PHP-FPM의 타임아웃이 Nginx 타임아웃보다 짧을 경우, PHP-FPM이 먼저 연결을 끊어버려 502 에러가 발생할 수 있습니다.

기본 설정값:

PHP-FPM request_terminate_timeout: 20초
Nginx fastcgi_read_timeout: 60초

2-4. 서버 리소스 부족

업스트림 서버가 과부하로 인해 응답하지 못하거나 리소스 고갈로 새로운 요청을 처리할 수 없을 때 502 에러가 발생합니다.

3. 단계별 진단 방법 – 원인 파악해보기

3-1. 로그 파일 확인하기

먼저 Nginx 에러 로그를 확인해야 합니다:

# Nginx 에러 로그 확인
sudo tail -f /var/log/nginx/error.log

# PHP-FPM 로그 확인
sudo tail -f /var/log/php-fpm.log

로그에서 찾아야 할 주요 메시지:

connect() to unix:/var/run/php-fpm.sock failed (2: No such file or directory)
connect() to unix:/var/run/php-fpm.sock failed (11: Resource temporarily unavailable)
recv() failed (104: Connection reset by peer)

3-2. 서비스 상태 점검

# Nginx 상태 확인
sudo systemctl status nginx

# PHP-FPM 상태 확인 (버전에 따라 다름)
sudo systemctl status php8.1-fpm
sudo systemctl status php-fpm

3-3. 포트 및 소켓 확인

# 열린 포트 확인
sudo netstat -tlnp | grep :9000

# 소켓 파일 존재 여부 확인
ls -la /var/run/php/

4. 502 Bad Gateway 에러 해결 방법들

4-1. PHP-FPM 서비스 재시작

가장 간단하고 효과적인 해결방법입니다:

# PHP-FPM 재시작
sudo systemctl restart php8.1-fpm

# Nginx 재시작
sudo systemctl restart nginx

# 설정 리로드 (서비스 중단 없이)
sudo systemctl reload nginx
sudo systemctl reload php8.1-fpm

서비스가 실행되지 않거나 PID가 누락된 경우, 실패한 서비스를 재시작하는 것이 가장 빠른 해결책입니다.

4-2. 소켓/TCP 설정 통일

방법 1: TCP 방식으로 통일

PHP-FPM 설정 수정 (/etc/php/8.1/fpm/pool.d/www.conf):

; 기존 소켓 설정 주석 처리
; listen = /var/run/php/php8.1-fpm.sock

; TCP 방식으로 변경
listen = 127.0.0.1:9000

Nginx 설정 확인 (/etc/nginx/sites-available/your-site):

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

방법 2: 소켓 방식으로 통일

Nginx 설정 수정:

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

PHP-FPM 설정 확인:

listen = /var/run/php/php8.1-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

4-3. 타임아웃 설정 최적화

버퍼와 타임아웃 증가는 Nginx/PHP-FPM이 작업할 공간을 제공하며, 특히 무거운 PHP 스크립트가 있는 경우 도움이 됩니다.

Nginx 설정 최적화 (/etc/nginx/sites-available/your-site):

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    
    # 버퍼 크기 증가
    fastcgi_buffers 8 16k;
    fastcgi_buffer_size 32k;
    
    # 타임아웃 설정
    fastcgi_connect_timeout 60;
    fastcgi_send_timeout 300;
    fastcgi_read_timeout 300;
    
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

PHP-FPM 타임아웃 설정 (/etc/php/8.1/fpm/pool.d/www.conf):

; 요청 종료 타임아웃 (0은 무제한)
request_terminate_timeout = 300

; PHP 실행 시간 제한
php_admin_value[max_execution_time] = 300
php_admin_value[max_input_time] = 300

4-4. 프로세스 관리 최적화

PHP-FPM은 요청을 처리하기 위해 idle 상태로 대기하는 여러 개의 ‘워커’ 프로세스를 스풀링하여 작동합니다.

메모리 기반 프로세스 수 계산:

현재 PHP 프로세스 메모리 사용량 확인:

ps aux | grep php-fpm | awk '{sum+=$6} END {print "Average memory per process: " sum/NR/1024 " MB"}'

서버 총 메모리 확인:

free -h

최적 프로세스 수 계산:

최대 프로세스 수 = (사용 가능한 메모리 * 0.8) / 프로세스당 평균 메모리

PHP-FPM 프로세스 관리 설정:

; 프로세스 관리 방식
pm = dynamic

; 최대 자식 프로세스 수
pm.max_children = 50

; 시작 시 생성할 프로세스 수
pm.start_servers = 10

; 최소 idle 프로세스 수
pm.min_spare_servers = 5

; 최대 idle 프로세스 수
pm.max_spare_servers = 15

; 각 프로세스가 처리할 최대 요청 수 (메모리 누수 방지)
pm.max_requests = 500

5. 그래도 해결이 안된다면, 이 방법으로 : 추가적인 해결 방법!

5-1. 방화벽 설정 확인

방화벽이 요청을 차단하고 있다고 생각되면 방화벽 규칙을 확인하여 Nginx로의 인바운드 요청이 차단되지 않는지 확인해야 합니다.

# UFW 상태 확인
sudo ufw status

# 필요한 포트 허용
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# iptables 규칙 확인
sudo iptables -L -n

5-2. 권한 문제 해결

소켓 파일에 대한 권한 문제가 있을 수 있습니다:

# 소켓 파일 권한 확인
ls -la /var/run/php/

# 권한 수정 (필요한 경우)
sudo chown www-data:www-data /var/run/php/php8.1-fpm.sock
sudo chmod 660 /var/run/php/php8.1-fpm.sock

5-3. DNS 해결 문제

업스트림 서버에 도메인을 사용하는 경우:

# DNS 해결 테스트
nslookup your-backend-server.com
dig your-backend-server.com

# /etc/hosts에 직접 추가 (임시 해결책)
echo "127.0.0.1 your-backend-server.com" >> /etc/hosts

6. 502 Bad Gateway 에러를 실시간 모니터링 하거나, 예방하는 방법

6-1. 로그 모니터링 설정

실시간 로그 감시:

# 502 에러만 필터링하여 모니터링
sudo tail -f /var/log/nginx/access.log | grep " 502 "

# 에러 로그 실시간 감시
sudo tail -f /var/log/nginx/error.log

6-2. 성능 모니터링

시스템 리소스 확인:

# 메모리 사용량
free -h

# CPU 사용률
top | grep php-fpm

# 디스크 사용량
df -h

# 네트워크 연결 상태
ss -tlnp | grep :9000

6-3. 자동 복구 스크립트

간단한 모니터링 스크립트 예시:

#!/bin/bash
# check_502.sh

URL="http://your-website.com"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $URL)

if [ $RESPONSE -eq 502 ]; then
    echo "502 error detected. Restarting services..."
    systemctl restart php8.1-fpm
    systemctl reload nginx
    
    # 알림 발송 (선택사항)
    echo "502 error fixed at $(date)" | mail -s "Server Alert" admin@yoursite.com
fi

크론탭에 등록:

# 5분마다 체크
*/5 * * * * /path/to/check_502.sh

7. 문제 해결되고 복구 되었다면, 마지막으로 설정 테스트 및 검증을 해보자!

7-1. 설정 파일 문법 검사

# Nginx 설정 테스트
sudo nginx -t

# PHP-FPM 설정 테스트
sudo php-fpm8.1 -t

7-2. PHP 연동 테스트

테스트용 PHP 파일 생성:

<?php
// /var/www/html/test.php
phpinfo();
?>

브라우저에서 http://your-domain.com/test.php 접속하여 PHP 정보가 정상적으로 표시되는지 확인합니다.

7-3. 부하 테스트

ApacheBench와 같은 부하 테스트 도구를 사용하여 502 Bad Gateway 에러의 원인이 될 수 있는 성능 병목 현상을 식별할 수 있습니다.

# ApacheBench로 부하 테스트
ab -n 1000 -c 10 http://your-website.com/

# 동시 연결 수를 늘려가며 테스트
ab -n 100 -c 50 http://your-website.com/test.php

8. 트러블슈팅을 위한, 단계별 체크리스트 정리

502 에러 발생 시 다음 순서로 확인해보세요:

1단계: 기본 확인

[ ] Nginx 서비스 상태 확인
[ ] PHP-FPM 서비스 상태 확인
[ ] 에러 로그 확인

2단계: 설정 확인

[ ] Nginx와 PHP-FPM 통신 방식 일치 여부
[ ] 소켓 파일 존재 및 권한 확인
[ ] 타임아웃 설정 적절성

3단계: 리소스 확인

[ ] 메모리 사용량
[ ] 디스크 공간
[ ] PHP-FPM 프로세스 수

4단계: 네트워크 확인

[ ] 방화벽 설정
[ ] 포트 수신 상태
[ ] DNS 해결

Nginx 502 Bad Gateway 에러는 복잡해 보이지만, 체계적인 접근으로 충분히 해결할 수 있는 문제입니다. 대부분의 경우 PHP-FPM 설정이나 서비스 상태 문제로 발생하므로, 기본적인 진단 절차만 숙지해도 신속하게 해결할 수 있습니다. 무엇보다 중요한 것은 문제가 발생하기 전에 적절한 모니터링과 예방 조치를 취하는 것입니다. 정기적인 로그 확인, 성능 모니터링, 그리고 적절한 용량 계획을 통해 사용자에게 안정적인 서비스를 제공할 수 있습니다. 🙂

1. Nginx – 502 Bad Gateway error(에러)란 무엇인가?

502 에러의 다양한 표현 방식

2. 502 에러가 발생하는 주요 원인들

2-1. PHP-FPM 서비스 문제

2-2. 설정 불일치 문제

2-3. 타임아웃 관련 문제

2-4. 서버 리소스 부족

3. 단계별 진단 방법 – 원인 파악해보기

3-1. 로그 파일 확인하기

3-2. 서비스 상태 점검

3-3. 포트 및 소켓 확인

4. 502 Bad Gateway 에러 해결 방법들

4-1. PHP-FPM 서비스 재시작

4-2. 소켓/TCP 설정 통일

4-3. 타임아웃 설정 최적화

4-4. 프로세스 관리 최적화

5. 그래도 해결이 안된다면, 이 방법으로 : 추가적인 해결 방법!

5-1. 방화벽 설정 확인

5-2. 권한 문제 해결

5-3. DNS 해결 문제

6. 502 Bad Gateway 에러를 실시간 모니터링 하거나, 예방하는 방법

6-1. 로그 모니터링 설정

6-2. 성능 모니터링

6-3. 자동 복구 스크립트

7. 문제 해결되고 복구 되었다면, 마지막으로 설정 테스트 및 검증을 해보자!

7-1. 설정 파일 문법 검사

7-2. PHP 연동 테스트

7-3. 부하 테스트

8. 트러블슈팅을 위한, 단계별 체크리스트 정리

이 포스트와 관련 있는 글

댓글 남기기응답 취소

1. Nginx – 502 Bad Gateway error(에러)란 무엇인가?

502 에러의 다양한 표현 방식

2. 502 에러가 발생하는 주요 원인들

2-1. PHP-FPM 서비스 문제

2-2. 설정 불일치 문제

2-3. 타임아웃 관련 문제

2-4. 서버 리소스 부족

3. 단계별 진단 방법 – 원인 파악해보기

3-1. 로그 파일 확인하기

3-2. 서비스 상태 점검

3-3. 포트 및 소켓 확인

4. 502 Bad Gateway 에러 해결 방법들

4-1. PHP-FPM 서비스 재시작

4-2. 소켓/TCP 설정 통일

4-3. 타임아웃 설정 최적화

4-4. 프로세스 관리 최적화

5. 그래도 해결이 안된다면, 이 방법으로 : 추가적인 해결 방법!

5-1. 방화벽 설정 확인

5-2. 권한 문제 해결

5-3. DNS 해결 문제

6. 502 Bad Gateway 에러를 실시간 모니터링 하거나, 예방하는 방법

6-1. 로그 모니터링 설정

6-2. 성능 모니터링

6-3. 자동 복구 스크립트

7. 문제 해결되고 복구 되었다면, 마지막으로 설정 테스트 및 검증을 해보자!

7-1. 설정 파일 문법 검사

7-2. PHP 연동 테스트

7-3. 부하 테스트

8. 트러블슈팅을 위한, 단계별 체크리스트 정리

이 글 공유하기:

이 포스트와 관련 있는 글

댓글 남기기응답 취소