배포 직전 Laravel 서비스 점검, 화면보다 먼저 확인할 7가지

Laravel 배포는 새 화면이 열리는지 확인하는 것으로 끝나지 않습니다. 운영 환경에서 읽는 설정이 맞는지, 데이터 변경이 되돌릴 수 있는지, 작업 실패를 누가 발견하고 복구할지까지 확인해야 실제 배포가 완료됩니다. 배포 직전에는 기능 시연보다 서비스가 어떤 조건에서 동작하는지 확인하는 편이 안전합니다.

1. 배포 대상과 환경을 고정합니다

먼저 어떤 커밋과 어떤 설정 묶음을 배포하는지 기록합니다. 운영 서버에서 작업 트리와 커밋이 일치하는지, 의존성 설치가 lock 파일을 기준으로 이뤄지는지, PHP와 확장 모듈 버전이 애플리케이션 요구사항을 만족하는지 확인합니다. 이 정보가 없으면 장애가 났을 때 코드 문제와 서버 차이를 구분하기 어렵습니다.

• 배포 커밋, 배포 시각, 담당자를 기록합니다.

• 운영용 PHP, 확장 모듈, Node 빌드 환경을 확인합니다.

• Composer와 프런트엔드 lock 파일이 배포 묶음에 포함됐는지 확인합니다.

2. 환경 변수와 캐시를 함께 점검합니다

운영 설정은 코드에 들어 있는 값이 아니라 서버가 실제로 읽는 설정이 기준입니다. 데이터베이스, 큐, 메일, 파일 저장소, 외부 API의 연결 값과 애플리케이션 키가 운영 환경에 맞는지 확인합니다. 설정 캐시를 사용하는 경우에는 배포 후 캐시가 새 환경 변수를 반영했는지도 확인해야 합니다. 캐시된 설정에서 env 값을 직접 읽는 코드는 예상과 다르게 동작할 수 있으므로 env 호출은 설정 파일 안에 두는 편이 안전합니다.

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

3. 데이터 변경은 순서와 복구를 확인합니다

마이그레이션은 코드 배포와 별개의 운영 작업입니다. 새 컬럼을 먼저 추가하고 애플리케이션이 새 컬럼을 읽게 하는 식으로 호환 가능한 순서를 정하면 이전 버전과 새 버전이 잠시 공존하는 구간도 견딜 수 있습니다. 반대로 기존 컬럼을 즉시 삭제하거나 대량 데이터를 한 번에 변환하면 롤백이 코드만 되돌리는 것으로 끝나지 않을 수 있습니다.

• 마이그레이션 전 백업과 복구 확인 방법을 정합니다.

• 마이그레이션이 여러 번 실행돼도 안전한지 확인합니다.

• 대량 변환의 예상 시간과 사용자 영향 범위를 기록합니다.

• 실패 시 중단할 지점과 수동 복구 담당자를 정합니다.

4. 큐와 스케줄러를 실제 흐름으로 확인합니다

웹 요청이 성공해도 백그라운드 작업이 멈춰 있으면 사용자는 결과를 받지 못합니다. 큐 워커가 새 코드로 재시작됐는지, 실패 작업이 어디에 쌓이는지, 스케줄러가 중복 실행되지 않는지 확인합니다. 테스트 주문이나 문의 한 건을 만들어 요청 생성부터 알림·후속 처리까지 이어지는 전체 흐름을 관찰하면 화면 확인만으로는 발견하지 못하는 지연을 찾을 수 있습니다.

5. 헬스 체크와 로그를 배포 기준에 넣습니다

배포 직후에는 홈 화면 하나보다 인증, 데이터 조회, 파일 업로드, 외부 연동처럼 장애 영향이 큰 흐름을 작은 점검표로 실행합니다. 응답 코드뿐 아니라 로그에 요청 식별자와 예외 원인이 남는지 확인합니다. 운영 디버그 모드는 꺼져 있어야 하며, 사용자에게 상세 스택 트레이스나 환경 설정이 노출되지 않아야 합니다.

6. 롤백은 명령어가 아니라 판단 기준입니다

문제가 생기면 무조건 이전 커밋으로 돌아가는 것이 정답은 아닙니다. 데이터 구조가 이미 바뀌었다면 코드만 되돌렸을 때 더 큰 오류가 생길 수 있습니다. 어떤 지표가 어느 정도 악화되면 배포를 중단할지, 트래픽을 줄이거나 기능을 끌 수 있는지, 데이터 복구가 필요한지 미리 정해야 담당자가 압박 속에서도 같은 판단을 할 수 있습니다.

7. 완료 조건을 짧게 남깁니다

배포가 끝났다는 말 대신 확인한 증거를 남깁니다. 운영 URL과 핵심 API의 응답, 큐 처리 결과, 오류 로그 변화, 마이그레이션 결과, 롤백 담당자를 하나의 배포 기록에 묶습니다. 다음 배포자는 이 기록만 보고 같은 검증을 반복할 수 있어야 합니다. Laravel 공식 배포 가이드가 설정·라우트·뷰 캐시와 운영 디버그 설정을 별도 점검 항목으로 두는 이유도 배포 성공을 코드 복사보다 넓게 정의하기 위해서입니다.

1. 배포 커밋과 운영 환경을 확인합니다.

2. 환경 변수와 캐시를 갱신합니다.

3. 데이터 변경과 백업·복구 경로를 확인합니다.

4. 큐·스케줄러·핵심 사용자 흐름을 실행합니다.

5. 로그와 모니터링에서 이상 징후를 확인합니다.

6. 중단·롤백 조건과 배포 증거를 기록합니다.