FPM과 Octane/RoadRunner 런타임
MSK Laravel 프로젝트는 PHP-FPM을 기본 런타임이자 즉시 복귀 가능한 안전 경로로 사용합니다. Laravel Octane과 RoadRunner는 처리량 개선이 필요한 프로젝트가 명시적으로 선택하는 개발 중(wip) 기능입니다.
첫 장시간 관찰 시작점은 immutable image 계약 결함이 발견되어 무효 처리되고 FPM으로 fail-close했습니다. 교정된 immutable image로 새 장시간 관찰을 시작했지만, 그 관찰과 rollback gate를 모두 통과하기 전에는 운영 전환 완료로 간주하지 마세요.
런타임 선택
| 모드 | 용도 | 운영 원칙 |
|---|---|---|
| FPM | 기본 운영 및 장애 복구 | 별도 Octane 설정 없이 사용합니다. |
| Canary | 제한된 요청으로 호환성 확인 | 신뢰된 운영 경로에서만 사용하고 공개 요청의 헤더를 신뢰하지 않습니다. |
| Octane | 검증을 마친 서비스의 선택형 런타임 | 사전 감사, 단계적 전환, 모니터링과 FPM 롤백 경로가 필요합니다. |
Octane은 장기 실행 워커를 사용하므로 단순한 PHP-FPM 교체가 아닙니다. 요청별 상태를 정적 프로퍼티나 싱글턴에 보관하는 코드, 요청 간 사용자·테넌트 컨텍스트가 남는 코드, 종료 시점에만 정리되는 리소 스는 전환 전에 수정해야 합니다.
전환 전 필수 조건
- 사용할 컨테이너 이미지와 RoadRunner 바이너리의 출처, 라이선스, 취약점을 검토합니다.
- 승인한 image repository와
sha256digest를 분리 입력하고 Compose가repository@sha256:digest만 구성하게 합니다. 이동 가능한 태그나 임의 image 문자열은 거부합니다. - 개발·테스트·스테이징 환경에서 인증, 권한, 테넌트 격리, 감사 로그, 로케일, 캐시와 큐 동작을 검증합니다.
- FPM 서비스와 설정을 제거하지 않고 즉시 복귀할 수 있게 유지합니다.
- 전환 전후의 오류율, 응답 시간, 메모리, 워커 재시작, 데이터베이스·Redis 연결 수를 비교할 수 있는 모니터링을 준비합니다.
설정
프로젝트 .env에서 다음 항목을 설정합니다. 실제 비밀값이나 내부 주소는 저장소에 커밋하지 마세요.
| 변수 | 설명 |
|---|---|
OCTANE_IMAGE_REPOSITORY | 보안·라이선스 감사를 마친 image repository. 태그나 digest를 포함하지 않음 |
OCTANE_IMAGE_SHA256 | 승인한 image의 64자리 SHA-256 digest. Compose가 repository@sha256:digest로 결합 |
MSK_HTTP_RUNTIME | fpm, canary, octane 중 선택하는 라우팅 모드 |
OCTANE_WORKERS | Octane 워커 수. 처음에는 보수적으로 시작한 뒤 측정값으로 조정 |
OCTANE_MAX_REQUESTS | 워커를 재시작하기 전 처리할 최대 요청 수 |
OCTANE_REQUEST_TIMEOUT | 요청 처리 제한 시간 |
OCTANE_GRACEFUL_TIMEOUT | 종료 시 진행 중 요청을 기다리는 시간 |
OCTANE_HTTPS | 프록시 뒤 HTTPS 요청을 Octane이 올바르게 인식하도록 하는 설정 |
OCTANE_LOG_LEVEL | RoadRunner 로그 수준 |
PLG_OCTANE_RUNTIME_ENABLED | Octane 런타임 플러그인 활성화 여부. Octane Compose 오버레이는 이를 활성화합니다. |
워커 수를 CPU 수에 맞춰 바로 늘리지 마세요. 데이터베이스 연결, Redis 연결, 메모리 사용량까지 함께 측정한 뒤 단계적으로 올립니다.
시작 방법
FPM은 프로젝트의 기본 Compose 구성으로 실행합니다. Octane을 평가할 때만 기본 구성에 _docker/docker-compose.octane.yml 오버레이와 octane 프로필을 추가합니다.
일반 _template 오버레이는 source bind mount를 사용하는 개발·호환성 검증 구조입니다. 아래 명령이 통과했다는 사실만으로 운영 immutable image 계약을 충족한 것은 아닙니다. 운영 배포는 애플리케이션·vendor·감사된 RoadRunner를 포함한 별도 image와 digest 형식 검증, non-root·read-only·resource limit을 함께 적용해야 합니다.
# FPM 기본 구성
docker compose -f _docker/docker-compose.amd64.yml up -d
# Octane/RoadRunner 선택형 구성
docker compose \
-f _docker/docker-compose.amd64.yml \
-f _docker/docker-compose.octane.yml \
--profile octane up -d
ARM64 환경에서는 기본 Compose 파일만 해당 아키텍처 파일로 바꿉니다. Octane 서비스는 애플리케이션의 내부 Docker 네트워크에서만 접근하고, 외부 트래픽은 기존 Nginx 보안·캐시·속도 제한 계층을 통과해야 합니다.
전환 검증
전환 전후에 같은 시나리오를 확인합니다.
- 상태 확인 엔드포인트와 공개 페이지가 정상 응답하는지
- 로그인, 로그아웃, 세션과 보안 쿠키가 정상인지
- SaaS·Tenant·Organization 컨텍스트와 권한이 요청 사이에 섞이지 않는지
- 감사 로그와 요청별 로케일·시간대가 정확한지
- 인증 응답, 개인화 응답과 오류 응답이 잘못 캐시되지 않는지
- 검색봇·스크레이퍼·일반 사용자의 Nginx 정책이 동일하게 유지되는지
- 워커 메모리가 계속 증가하지 않고 계획한 최대 요청 수에서 정상 재시작하는지
- 오류율, 지연 시간과 데이터베이스·Redis 연결 수가 허용 범위인지
단시간 기능 테스트만으로 운영 승인을 내리지 마세요. 자연 트래픽의 피크와 유휴 구간을 포함한 관찰 기간을 거쳐야 합니다.
롤백
다음 신호가 나타나면 Octane 확장을 중단하고 FPM 경로로 복귀합니다.
- 5xx, 시간 초과 또는 워커 재시작이 기준선을 지속적으로 초과함
- 사용자·테넌트·권한·로케일 상태가 요청 사이에 섞임
- 메모리나 데이터베이스·Redis 연결 수가 지속적으로 증가함
- 인증, 캐시 또는 감사 로그의 정합성이 FPM과 다름
롤백은 FPM hot standby를 유지한 상태에서, 프로젝트의 검증된 runtime 전환 도구로 Nginx upstream selector를 FPM으로 원자적 복귀하는 방식으로 수행합니다. 통과한 health check를 확인하고 Nginx 설정 검증과 reload를 수행하며, 데이터 볼륨 삭제나 데이터베이스 초기화는 필요하지 않습니다. 복귀 후 동일한 검증 항목으로 FPM 정상화를 확인하고, 원인을 해결하기 전까지 자동 또는 수동 Octane 재전환을 금지합니다.
플러그인과 확장 코드
OctaneRuntime 0.1.0은 Core >=1.26.0을 요구합니다. 런타임 플러그인은 런타임별 생명주기 연결점과 호환성 경계를 제공합니다. 프로젝트별로 워커 초기화·정리 로직을 복제하지 말고, 플러그인의 계약과 Laravel의 scoped binding을 사용하세요. 패키지나 런타임이 설치되지 않은 FPM 환경에서는 기능이 안전하게 비활성화되어야 합 니다. 활성 lifecycle 안에서 중첩 sync queue job은 컨텍스트 오염을 막기 위해 fail-close하므로 비동기 queue로 dispatch하세요.
관련 기능은 Core 및 플러그인 카탈로그와 공개 플러그인 카탈로그에서 확인할 수 있습니다.
코드를 쓸 때의 규약
이 문서는 런타임을 선택하고 전환·롤백하는 운영 절차를 다룹니다. 어떤 코드가 두 런타임에서 안전하고 어떤 코드가 상태를 누출하는지는 런타임 중립 개발 규약에 정리되어 있습니다.
전환을 검토하기 전에 개발 규약을 먼저 적용하세요. 규약을 지킨 코드는 FPM에서 동작도 성능도 동일하므로, Octane 도입 여부와 무관하게 지금 적용해 두는 편이 안전합니다.