Laravel 프로세스 운영 기준¶
운영 서버에서 Laravel 서비스의 프로세스를 어떻게 실행·유지·복구할 것인지에 대한 운영 기준을 정의함.
Laravel은 단일 프로세스 매니저 하나로 끝나는 구조가 아니므로, 역할별 프로세스 관리 체계가 필수임.
⚠️ 가장 중요한 운영 원칙 (반드시 숙지)¶
도구 설치(root)와 애플리케이션 실행(user)을 분리한다. HTTP는 php-fpm(systemd), Queue는 supervisor/systemd, Scheduler는 cron으로 분리 관리한다.
이 원칙이 깨지면 다음 문제가 발생함.
- 재부팅 후 서비스 일부 미기동
- worker 유실/중복 실행
- 로그 경로 및 권한 꼬임
- 장애 원인 추적 실패
1. Laravel 프로세스 운영 원칙¶
운영 환경에서는 다음 원칙을 고정함.
- HTTP 요청 실행 주체는
php-fpm하나로 고정 - Queue worker는 백그라운드 관리 도구로 실행
- Scheduler는 cron으로 분당 트리거
- 임시 세션 실행(
screen,tmux) 금지
Laravel 프로세스는 "살아있으려고 노력"하지 않음. 살아있게 만드는 책임은 systemd/supervisor/cron이 담당함.
2. 프로세스 역할 분리¶
| 역할 | 권장 도구 | 비고 |
|---|---|---|
| HTTP 요청 처리 | php-fpm + systemd |
Nginx와 fastcgi 연동 |
| Queue worker | supervisor (또는 systemd) |
자동 재시작 필수 |
| Scheduler | cron + schedule:run |
분당 1회 고정 |
3. PHP-FPM 운영 기준¶
sudo systemctl enable --now php-fpm
sudo systemctl status php-fpm
sudo php-fpm -t
운영 기준:
php-fpm -F직접 실행 금지- 설정 변경 후 문법 검증(
php-fpm -t) 선행 - Nginx 반영 전후 상태 확인 필수
4. Queue Worker 운영 기준 (Supervisor)¶
Supervisor 설치 및 기동:
sudo dnf install -y supervisor
sudo systemctl enable --now supervisord
sudo systemctl status supervisord
설정 파일 예시:
/etc/supervisord.d/laravel-worker.ini
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/[ProjectName]/current/artisan queue:work --sleep=3 --tries=3 --timeout=120 --max-time=3600
directory=/var/www/[ProjectName]/current
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=2
user=[User]
redirect_stderr=true
stdout_logfile=/var/log/supervisor/laravel-worker.log
stopwaitsecs=3600
반영:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
5. 배포 반영 시 Queue 표준 절차¶
코드 반영 후 Queue worker는 아래 순서로 처리함.
cd /var/www/[ProjectName]/current
php artisan queue:restart
sudo supervisorctl status
운영 기준:
queue:restart없이 코드만 교체하지 않음- 실패 job 누적 여부를 함께 점검 (
php artisan queue:failed)
6. Scheduler 운영 기준¶
운영 사용자 기준 cron 등록:
* * * * * cd /var/www/[ProjectName]/current && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
검증:
crontab -l
php artisan schedule:list
7. 실행 경로 기준¶
Laravel 관련 실행 기준 경로는 항상 동일함.
/var/www/[ProjectName]/current
릴리즈 구조를 사용해도 실제 실행 기준은 current로 고정함.
8. 운영자 계정 원칙¶
- 서비스 설치/등록: root
- 앱 실행/관리: 운영 사용자(
[User]) - queue worker를 root로 실행하지 않음
- 파일 소유권과 실행 계정 정책을 일치시킴
9. 정리¶
- Laravel 프로세스 운영의 표준은
php-fpm + supervisor + cron조합 - 핵심은 기능이 아니라 자동복구 가능성과 역할 분리임