시스템 관리_24 Nginx FastCGI 및 Reverse Proxy 환경 504 Gateway Time-out 오류 원인 분석과 완벽 해결 가이드

# 1. 클라이언트 관점: curl 명령어로 504 응답 코드 및 소요 시간 확인
$ curl -Iv -w "\nHTTP Code: %{http_code}\nTime Total: %{time_total}s\n" https://example.com/api/heavy-task
* Connected to example.com (192.168.1.100) port 443
< HTTP/1.1 504 Gateway Time-out
< Server: nginx
< Content-Type: text/html
HTTP Code: 504
Time Total: 60.005s
# -> 약 60초(기본 타임아웃 값) 직후 정확히 504가 반환되는지 확인

# 2. Nginx 에러 로그에서 upstream timed out 세부 원인 확인
$ sudo tail -n 50 /var/log/nginx/error.log
# [출력 예시 - Reverse Proxy (Node.js/Tomcat/Gunicorn 등)]
# [error] 1420#1420: *120 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.10, server: example.com, request: "POST /api/export HTTP/1.1", upstream: "http://127.0.0.1:8080/api/export", host: "example.com"
# [출력 예시 - FastCGI (PHP-FPM)]
# [error] 1420#1420: *121 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.10, server: example.com, request: "GET /report.php HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.2-fpm.sock:", host: "example.com"

# 3. 백엔드 업스트림 포트 또는 Unix Domain Socket 수신 상태 및 큐(Send-Q/Recv-Q) 적체 점검
$ sudo ss -lntp '( sport = :8080 or sport = :9000 )'
# 또는 PHP-FPM 유닉스 소켓 버퍼 확인
$ sudo ss -lxp | grep -E 'php|fpm'

# 4. 백엔드 워커 프로세스가 가용한 상태인지 점검 (PHP-FPM 프로세스 고갈 여부 등)
$ ps aux | grep -E 'php-fpm|java|gunicorn' | grep -v grep | wc -l

#!/bin/bash
# diagnose_504_timeout.sh - Diagnose Nginx proxy/FastCGI timeouts and backend status

echo "=========================================="
echo " [Nginx 504 Gateway Time-out 원인 진단]"
echo "=========================================="

# 1. Nginx 에러 로그 내 최신 504 upstream timeout 발생 여부 점검
NGINX_LOG="/var/log/nginx/error.log"
echo -e "\n[1] Nginx 업스트림 타임아웃 로그 점검:"
if [ -f "$NGINX_LOG" ]; then
    TIMEOUT_ERRORS=$(grep -E "upstream timed out.*while reading response" "$NGINX_LOG" | tail -n 3)
    if [ -n "$TIMEOUT_ERRORS" ]; then
        echo "  [경고] 최근 타임아웃 로그가 감지되었습니다:"
        echo "$TIMEOUT_ERRORS" | sed 's/^/    /'
    else
        echo "  [정상] 최근 upstream timed out 에러 로그가 없습니다."
    fi
else
    echo "  [안내] 로그 파일을 찾을 수 없습니다: $NGINX_LOG"
fi

# 2. Nginx 타임아웃 관련 설정값 파싱
echo -e "\n[2] Nginx 설정 파일 내 타임아웃 지시어 점검:"
grep -rnE "(proxy_read_timeout|fastcgi_read_timeout|send_timeout)" /etc/nginx/ 2>/dev/null | grep -v "#" | head -n 10 | sed 's/^/  /'
if [ $? -ne 0 ]; then
    echo "  [기본값 사용 중] 별도 지시어가 없어 기본값(60s)으로 동작 중일 가능성이 높습니다."
fi

# 3. 백엔드 애플리케이션 데몬 상태 확인 (PHP-FPM / WAS)
echo -e "\n[3] 백엔드 데몬 구동 및 워커 부하 상태:"
FPM_PROCS=$(pgrep -fc "php-fpm: pool" 2>/dev/null)
JAVA_PROCS=$(pgrep -fc "java" 2>/dev/null)

echo "  - 감지된 PHP-FPM 워커 프로세스 수 : ${FPM_PROCS:-0}개"
echo "  - 감지된 Java(Tomcat 등) 프로세스 수: ${JAVA_PROCS:-0}개"

# PHP-FPM 설정 점검 (설치되어 있을 경우)
PHP_INI=$(php -i 2>/dev/null | grep "Loaded Configuration File" | awk '{print $NF}')
if [ -n "$PHP_INI" ] && [ -f "$PHP_INI" ]; then
    echo -e "\n[4] PHP-FPM 실행 제한 설정 점검 (${PHP_INI}):"
    MAX_EXEC=$(grep -E "^max_execution_time" "$PHP_INI" | head -n 1)
    echo "  - $MAX_EXEC"
fi

# 4. 상위 CPU 점유 백엔드 프로세스 Top 3 추출
echo -e "\n[5] 리소스 과점 백엔드 프로세스 확인:"
ps -eo pid,ppid,cmd,%mem,%cpu --sort=-%cpu | grep -E "php-fpm|java|node|gunicorn" | grep -v grep | head -n 3 | sed 's/^/  /'

echo -e "\n=========================================="
echo " [진단 완료]"
echo "=========================================="