🚨 504/502 Gateway 오류 해결 포스팅: PHP-FPM 프로세스 고갈 문제

1. 문제 증상 및 초기 진단

갑자기 웹사이트에 접속했을 때 504 Gateway Time-out 또는 502 Bad Gateway 오류가 발생하며 사이트가 간헐적으로 먹통이 되는 현상이 발생했습니다. 특히 특정 사이트에서만 오류가 발생하고, HTML 같은 정적 파일은 잘 열렸습니다.

초기 진단 결과, MySQL 서버는 정상 작동 중이었으며, 문제는 Nginx와 백엔드 PHP-FPM 사이의 통신 문제로 좁혀졌습니다.

💡 로그에서 발견된 핵심 단서

PHP-FPM 오류 로그(sudo tail -n 50 /var/log/php/8.3/fpm/www-error.log 또는 sudo tail -n 50 /var/log/php*-fpm.log)를 확인한 결과, 다음과 같은 경고와 알림이 반복적으로 나타났습니다.

WARNING: [pool www] server reached pm.max_children setting (30), consider raising it
WARNING: [pool www] seems busy...
NOTICE: Terminating ... exiting, bye-bye!

진단 결과: PHP-FPM이 동시에 처리할 수 있는 최대 프로세스 수(pm.max_children)가 부족하여 모든 프로세스가 고갈되었거나, 프로세스가 메모리를 과도하게 사용하여 운영체제가 PHP 서비스를 강제 종료하고 있는 상황이었습니다.

---

2. 근본 원인: 외부 API 중단과 리소스 고갈

문제가 발생한 시점에 오픈 API 서비스가 중단되었다는 점이 확인되었습니다. 이것이 PHP 프로세스를 마비시킨 근본 원인이었습니다.

1. 무한 대기: PHP 스크립트는 API 응답을 기다리지만, API 서버가 중단되어 응답을 받지 못하고 무한 대기 상태에 빠집니다.
2. 프로세스 점유: 대기 상태에 빠진 프로세스는 리소스를 점유한 채 다른 요청을 처리하지 못합니다.
3. 리소스 고갈: 접속자가 늘어나면서 대기하는 프로세스가 pm.max_children 한도를 채우고, 결국 서버의 모든 PHP 리소스를 고갈시켜 다른 정상적인 사이트까지 느려지거나 504 오류를 발생시킵니다.

---

3. 해결책: PHP-FPM 설정 최적화 및 타임아웃 조정

이 문제는 서버의 RAM 용량에 맞춰 PHP-FPM 프로세스 한도를 늘리고 PHP가 외부 응답을 무한정 기다리지 않도록 타임아웃을 설정하여 해결할 수 있습니다.

A. PHP-FPM 프로세스 한도 증설 (pm.max_children)

서버의 RAM 용량을 확인한 후, /etc/php/8.3/fpm/pool.d/www.conf 파일에서 pm.max_children 값을 조정합니다.

서버 RAM (예시)	PHP 프로세스당 메모리 (가정)	안전한 pm.max_children 값 (권장 시작점)
2 GB	50 MB	약 30개
4 GB	50 MB	약 70개
8 GB	50 MB	약 150개

PHP-FPM 설정 파일 (www.conf) 수정 예시:

Ini, TOML

; pm.max_children을 RAM 용량에 맞춰 조정
pm.max_children = 70      
pm.start_servers = 15     
pm.min_spare_servers = 10 
pm.max_spare_servers = 30 

B. PHP-FPM 및 Nginx 타임아웃 설정

PHP 프로세스가 외부 API를 무한정 기다리는 것을 막기 위해 타임아웃을 설정합니다.

설정 항목	설정 위치	권장 값	역할
request_terminate_timeout	/etc/php/8.3/fpm/pool.d/www.conf	60s	PHP 스크립트 실행 시간을 강제로 제한 (Nginx 타임아웃보다 짧게 설정)
proxy_read_timeout	Nginx 사이트 설정 파일 (.conf)	300s	Nginx가 백엔드(PHP)의 응답을 기다리는 최대 시간 (504 오류 완화)

Sheets로 내보내기

🛠️ 최종 적용 명령어

설정 파일 수정 후에는 반드시 두 서비스를 모두 재시작해야 변경 사항이 적용됩니다.

Bash

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

# 2. Nginx 재시작
sudo systemctl restart nginx 

이 과정을 통해 PHP 프로세스 고갈 문제가 해결되어 서비스가 정상화될 수 있습니다. 장기적으로는 PHP 코드 내에서 외부 API 호출 시 타임아웃 옵션(예: cURL의 CURLOPT_TIMEOUT)을 짧게 설정하여 외부 장애가 서버 전체에 영향을 미치는 것을 방지해야 합니다.