콘텐츠로 이동

Laravel 런타임 운영 기준 (Production)

운영 서버에서 Laravel 런타임을 안정적으로 유지하기 위한 환경 변수, 캐시, PHP-FPM, Queue/Scheduler 실행 기준을 정의함.

코드 작성법이 아니라, "운영 런타임을 어떤 상태로 유지해야 하는가" 에 집중함.

1. Laravel 런타임의 책임 범위

운영 환경에서 Laravel 런타임의 책임:

  • 요청 처리 및 비즈니스 로직 실행
  • DB/Cache/세션 접근
  • Queue Job 처리

Laravel 런타임이 직접 책임지지 않는 영역:

  • TLS 종료
  • 외부 트래픽 필터링
  • Connection/Rate 제한
  • 정적 자산 전달 최적화

위 영역은 Nginx/OS 계층 책임임.

2. 필수 환경 변수 기준

운영 서버에서 핵심 환경 변수는 명시적으로 고정함.

APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
LOG_CHANNEL=daily
LOG_LEVEL=info
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

운영 기준:

  • .env 민감정보는 파일 권한으로 통제 (chmod 640 권장)
  • APP_DEBUG=true로 운영하지 않음
  • DB, Redis, API key는 문서화된 주입 경로로만 반영

3. 캐시 운영 원칙

설정 변경 후 캐시 재생성은 필수 절차임.

cd /var/www/[ProjectName]/current
php artisan config:clear
php artisan route:clear
php artisan view:clear

php artisan config:cache
php artisan route:cache
php artisan view:cache

주의:

  • clear 후 cache 생성을 누락하면 성능/동작 불일치가 발생함
  • 배포 직후 캐시 재생성 여부를 체크리스트로 관리함

4. PHP-FPM 런타임 기준

권장 확인 명령:

sudo systemctl status php-fpm
sudo php-fpm -t

운영 기준:

  • PHP-FPM은 systemd로만 관리함 (php-fpm -F 직접 실행 금지)
  • user/group은 Nginx 및 파일 권한 정책과 일치해야 함
  • 가능하면 Unix socket(/run/php-fpm/php-fpm.sock) 사용
  • TCP 포트 사용 시에는 SELinux 정책 점검을 선행함

5. Queue 런타임 기준

Queue worker는 항상 백그라운드에서 살아 있어야 하며, 재배포 후 재기동 절차가 명확해야 함.

기본 명령:

cd /var/www/[ProjectName]/current
php artisan queue:restart
php artisan queue:failed

운영 기준:

  • worker는 Supervisor/systemd로 관리
  • 임시 세션(screen, tmux) 실행 금지
  • worker 설정 변경 후 queue:restart 필수

6. Scheduler 런타임 기준

Scheduler는 cron이 분당 schedule:run을 호출하는 구조로 고정함.

* * * * * cd /var/www/[ProjectName]/current && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

검증:

crontab -l
php artisan schedule:list

운영 기준:

  • 운영 계정 기준으로 cron 등록
  • 배포 후 scheduler 누락 여부 반드시 확인

7. 로그 기준

로그는 계층별로 분리하여 추적 가능해야 함.

  • Nginx: /var/log/nginx/access.log, /var/log/nginx/error.log
  • PHP-FPM: /var/log/php-fpm/*
  • Laravel: /var/www/[ProjectName]/current/storage/logs/
  • Queue Worker: /var/log/supervisor/ 또는 journalctl

콘솔 출력만으로 운영 로그를 대체하지 않음.

8. 이 문서에서 의도적으로 다루지 않는 것

다음 항목은 별도 문서에서 다룸.

  • Nginx SSL/보안 헤더 정책
  • DB 백업/복구 런북
  • CI/CD 배포 파이프라인
  • 고가용성(HA) 구성

9. 정리

  • Laravel 런타임 안정성은 환경 변수 + 캐시 + php-fpm + queue/scheduler 조합으로 결정됨
  • 문제를 줄이는 핵심은 빠른 임시조치가 아니라 명시적 운영 기준 유지임