Windows에서 PHP-FPM 설정을 만지는 순간 제일 무서운 건 “적용은 됐는데, 웹이 갑자기 502/timeout으로 죽는” 상황입니다. 그래서 이 글은 설정 파일 중심으로 예시를 보여주고, 검증→재시작→문제 시 롤백/복구 경로까지 한 번에 잡아두는 걸 목표로 합니다.
작게 바꾸고, 바로 확인하고, 언제든 되돌릴 수 있게요.
먼저 한 가지 전제부터요: Windows에서 “PHP-FPM”은 Linux처럼 표준 서비스로 굴리기보다, 빌드/배포 방식에 따라 실행 형태가 다릅니다. 아래 절차는 공통으로 쓸 수 있게 설정 파일 관리 + 안전장치에 집중합니다.
1) 변경 전에 준비: 현재 상태와 롤백 지점 만들기
설정 변경을 시작하기 전에, 되돌아갈 지점을 먼저 만들어두면 마음이 편합니다. 핵심은 파일 백업과 현재 동작 정보 기록입니다.
특히 php-fpm.conf 하나만 보지 말고, pool 설정(보통 www.conf 등)까지 같이 잡아두는 게 안전합니다.
- 백업 폴더 만들기: 예) C:\backup\php-fpm\YYYYMMDD-HHMM\
- 대상 파일 백업: php-fpm.conf, php.ini, pool 설정 파일들(예: php-fpm.d\*.conf 또는 개별 www.conf)
- 경로 기록: 실제 사용 중인 php.exe 위치, php-fpm 실행 파일/스크립트 위치, 현재 설정 파일 경로
- 증상 재현 메모: 변경 목적(예: pm 설정 변경, timeout 조정, 로그 경로 변경)과 현재 문제(있다면)를 간단히 적기
이 단계는 “나중에 롤백할 때 어떤 파일을 어디로 되돌려야 하는지”를 확실히 해줍니다.
2) 설정 파일 중심으로 보기: php-fpm.conf / pool 설정(예시)
PHP-FPM은 크게 전역 설정(php-fpm.conf)과 pool 설정(www.conf 같은 파일)로 나뉩니다. 실제로 장애를 만드는 건 pool 쪽(pm, listen, 접근권한, timeout)인 경우가 많습니다.
아래는 “어떤 줄이 리스크가 큰지”를 짚기 위한 예시입니다. (환경마다 키가 조금 다를 수 있어요.)
- listen: FastCGI를 받을 주소/포트/소켓. 예) 127.0.0.1:9000 또는 TCP 포트
- pm: static/dynamic/ondemand. 성능/메모리/응답에 영향
- pm.max_children: 과도하게 키우면 메모리 압박, 너무 낮으면 요청 대기 증가
- request_terminate_timeout: 무한 대기 방지. 너무 짧으면 정상 요청도 끊길 수 있음
- slowlog / request_slowlog_timeout: 느린 요청 추적. 경로/권한 문제로 로그가 안 찍히면 원인 파악이 어려움
- error_log / access.log: 파일 경로와 쓰기 권한이 맞는지(Windows 경로, 백슬래시/슬래시 혼용 포함)
가장 흔한 실수는 listen을 바꾸고(Nginx/Apache 설정은 그대로), 재시작 후 502가 나는 케이스입니다. 바꾸려면 웹서버 쪽 fastcgi_pass(또는 ProxyPassMatch 등)도 같이 맞춰야 합니다.
3) 적용 전 검증 체크: “설정 오류”와 “경로/권한” 먼저 잡기
Windows에선 특히 로그 경로와 프로세스 실행 계정 권한이 엮이면서, 설정 자체는 맞는데도 기동이 실패하는 일이 있습니다. 그래서 아래 순서로 확인하는 걸 추천합니다.
- 문법/키 오타: 키 이름 실수, 세미콜론/주석 처리 실수
- 경로 존재 여부: error_log, slowlog, pid 파일 경로의 폴더가 실제 존재하는지
- 쓰기 권한: PHP-FPM을 실행하는 계정이 로그/임시폴더에 쓸 수 있는지
- 포트 충돌: listen이 TCP 포트면 이미 사용 중인지(다른 서비스가 점유 중인지)
- 연결 대상 일치: 웹서버(Nginx/Apache)에서 바라보는 주소/포트와 PHP-FPM listen이 동일한지
가능하면 “한 번에 여러 변경”을 하지 말고, 변경 단위를 작게 나눠서 원인 추적을 쉽게 만드세요.
4) 재시작 절차(안전): 끊김 최소화 + 원인 로그 확보
재시작은 단순히 프로세스만 다시 올리는 작업이 아니라, 실패했을 때 증거를 남기는 작업이기도 합니다.
- 1) 현재 프로세스 상태 확인: PHP-FPM이 살아있는지, 몇 개 워커가 있는지(가능한 범위에서)
- 2) 로그 tail 준비: error_log 위치를 열어두고(또는 즉시 확인할 방법 준비)
- 3) 재시작 실행: 서비스/작업 스케줄러/수동 실행 등 운영 방식에 맞게 “정상 종료 → 기동” 순으로
- 4) 즉시 확인: 포트 리스닝 확인 + 웹에서 간단한 PHP 응답 확인(health endpoint나 단순 phpinfo 페이지 등)
- 5) 1~3분 관찰: 요청이 몰릴 때만 터지는 설정도 있어, 짧게라도 에러 로그/응답시간을 봅니다
만약 재기동이 실패하면, “왜 안 올라왔는지”는 대개 error_log 또는 표준 출력에 나옵니다. 이걸 확보한 뒤 롤백하세요. 로그 없이 바로 이것저것 만지면 더 꼬입니다.
5) 장애가 나면 바로 롤백: 복구 경로를 미리 정해두기
롤백은 빠를수록 좋고, 판단 기준이 명확해야 합니다. 예를 들어 “재시작 후 2분 내 200 OK 회복이 안 되면 롤백”처럼요.
- 롤백 트리거: 502/504 지속, PHP-FPM 기동 실패, CPU/RAM 급등, 요청 지연 급증
- 롤백 방법(파일 기준): 백업해둔 php-fpm.conf/pool conf/php.ini를 원위치로 복원
- 재시작: 복원 후 동일한 절차로 다시 재기동
- 검증: 포트 리스닝 + 간단한 PHP 응답 + 에러 로그가 정상으로 돌아왔는지 확인
롤백 후에도 문제가 남아있다면, 변경 전부터 있었던 문제이거나(우연히 겹침), 설정 외부(웹서버 upstream, 방화벽, 포트 충돌, 권한)일 가능성이 큽니다. 이 경우엔 “변경 내용”과 “에러 로그”를 묶어서 원인을 분리해 보세요.
6) 재발 방지: 다음 변경을 더 안전하게 만드는 작은 습관
한 번 장애를 겪으면, 다음부터는 같은 패턴을 줄이는 게 좋습니다. Windows 환경에서는 특히 운영 자동화가 약한 경우가 많아서, 사람이 실수하지 않게 “절차”를 남겨두는 효과가 큽니다.
- 변경 로그 남기기: 언제, 어떤 파일의 어떤 값을 왜 바꿨는지
- 백업 자동화: 적용 전 백업을 스크립트/배치 파일로 고정
- 헬스체크 고정: 재시작 직후 확인할 URL/커맨드/로그 위치를 문서화
- 로그 경로 표준화: error_log/slowlog 디렉터리를 고정하고 권한 문제를 미리 제거
- 변경 단위 쪼개기: pm 값 조정과 listen 변경을 같은 배포에 묶지 않기
이 정도만 해도 “설정 변경이 곧 장애”인 상황에서 꽤 멀어집니다.
마무리
Windows에서 PHP-FPM 설정을 바꿀 땐, 설정 자체보다도 검증/재시작/로그 확보/롤백 같은 운영 절차가 더 중요할 때가 많습니다.
백업을 먼저 만들고, 작은 변경을 빠르게 확인하고, 안 되면 즉시 되돌리는 흐름만 고정해도 장애 시간을 크게 줄일 수 있어요.