Vigilance 패키지로 Laravel 서버 상태를 1분마다 자동 모니터링하는 방법

Vigilance 패키지 개요 — 아키텍처 관점에서 살펴보기

cms-orbit/vigilance 패키지는 Laravel 스케줄러에 올라타는 경량 에이전트 방식을 선택했습니다. 별도 데몬을 띄우지 않고 기존 크론 인프라(* * * * * php artisan schedule:run)를 그대로 활용하기 때문에, 이미 Laravel 스케줄러를 운영 중인 팀이라면 추가 서버 설정 없이 .env에 SENTINEL_HUB_URL 한 줄만 추가하면 1분 주기 모니터링이 활성화됩니다. 진입 장벽이 매우 낮다는 점에서 실용적인 선택입니다.

아키텍처 측면에서 눈여겨볼 부분은 AbstractStatusGetter 계층 구조입니다. OS를 자동 감지한 뒤 Ubuntu 버전별·Windows 버전별 구현체를 선택하는 구조이므로, 팀 내에 Linux 혼용 환경(Ubuntu 20 / 22 / 24, CentOS, Rocky, Debian)이 있어도 단일 패키지로 커버됩니다. 다만 이 추상화가 실제로 얼마나 촘촘히 구현되어 있는지는 소스를 직접 확인해야 하며, 엣지 케이스(컨테이너 내부 OS 식별, WSL 등)에서 예상치 못한 폴백이 발생할 수 있으므로 스테이징 환경에서 php artisan vigilance:report 수동 전송으로 페이로드를 먼저 검증하는 것을 권장합니다.

실무 도입 시 추가로 검토할 포인트를 정리하면 다음과 같습니다.

• 외부 의존성: Sentinel-Hub(sentinel-hub.amuz.co.kr)가 단일 수신 엔드포인트입니다. 이 서비스의 SLA·데이터 보관 정책을 사전에 확인해야 합니다.
• 재시도 설정: 기본값은 최대 3회, 지수 백오프 최대 60초인데, 스케줄러 주기(1분)보다 총 대기 시간이 길어질 수 있어 max_delay를 30초 이하로 줄이는 것이 안전합니다.
• LogMonitor 중복 제거: SHA256 해시 기반이므로 같은 메시지라도 타임스탬프가 포함된 포맷이면 중복으로 처리되지 않을 수 있습니다. 로그 포맷 커스터마이징 여부를 확인하세요.
• 호환성: 현재 소스 기준 Laravel 9–13 / PHP 8.0–8.5를 공식 지원하며, Laravel 8 이하는 지원하지 않습니다.

패키지 설치 전에 Sentinel-Hub가 자체 호스팅 가능한지, 아니면 외부 SaaS에만 종속되는지 여부가 도입 결정의 핵심 변수가 될 것입니다. 이 부분에 대한 정보가 README에 명시되어 있지 않아, 보안 정책이 엄격한 환경이라면 GitHub Issues를 통해 먼저 질의하는 것을 권합니다.

보안·호환성 관점에서 짚어야 할 핵심 사항

서니어님이 언급하신 Sentinel-Hub 외부 전송 이슈는 보안 관점에서도 가장 중요한 검토 항목입니다. 페이로드에는 서버 UUID, OS 버전, PHP/Laravel 버전, DB 연결 상태, 큐 상태, 그리고 **Laravel 오류 로그 내용(최대 200자)**이 포함됩니다. 오류 로그에는 스택 트레이스, 파일 경로, 경우에 따라 민감한 환경 변수 값이 노출될 수 있으므로, sentinel-hub.amuz.co.kr로 전송되는 데이터가 TLS로 암호화되는지, 수신 측의 데이터 보관·파기 정책이 무엇인지를 도입 전에 반드시 서면으로 확인해야 합니다. 규제 산업(금융, 의료, 공공)이라면 외부 SaaS 전송 자체가 내부 보안 정책 위반이 될 수 있습니다.

현재 소스 기준으로 알려진 CVE는 보고되지 않았습니다. 다만 패키지 점수가 0점이고 초기 릴리스 이력이 짧기 때문에, 보안 감사를 받은 코드베이스라고 보기 어렵습니다. 아래 두 가지를 코드 레벨에서 직접 확인하시길 권장합니다.

• VIGILANCE_SERVER_ID 자동 생성 로직: UUID가 어디에 저장되는지(.env 직접 수정 여부), 예측 가능한 값인지 확인 필요
• HTTP 요청 인증: Sentinel-Hub에 전송 시 Bearer 토큰 등 인증 헤더가 없다면, UUID만 탈취해도 타 서버 데이터를 덮어쓰는 스푸핑이 이론상 가능

PHP/Laravel 호환성 측면에서는 공식 지원 범위(PHP 8.0–8.5, Laravel 9–13)가 명확하게 문서화되어 있어 양호합니다. 단, PHP 8.0과 8.1은 이미 공식 지원이 종료된 버전입니다. 해당 버전을 사용 중인 팀은 이 패키지 도입과 별개로 PHP 업그레이드를 우선 진행하는 것이 보안상 올바른 순서입니다. 현재 운영 환경 기준으로 권장 조합은 PHP 8.3 + Laravel 11 이상입니다.

운영·성능 관점: 스케줄러 기반 에이전트의 런타임 비용과 프로덕션 체크리스트

스케줄러 점유 시간과 큐 영향을 먼저 짚겠습니다. Vigilance는 별도 프로세스 없이 schedule:run 내에서 동기 실행됩니다. 즉, vigilance:report 커맨드가 실행되는 동안 동일 스케줄러 워커가 블로킹됩니다. 기본 HTTP 타임아웃이 10초이고 재시도가 최대 3회이므로, 네트워크 지연이 심한 상황에서는 이론상 단일 실행 주기에서 상당한 시간이 소요될 수 있습니다. 서니어님이 언급하신 max_delay 단축 권고에 동의하며, 운영 환경에서는 timeout도 5초 이하로 낮추는 것을 권장합니다.

Docker/Sail/컨테이너 환경에서 주의할 점이 있습니다.

• AbstractStatusGetter가 OS를 자동 감지하는데, 컨테이너 내부에서 /proc/version 또는 uname 결과가 호스트와 다를 수 있습니다. 세큐님이 언급한 WSL 엣지 케이스 외에도, distroless 이미지나 Alpine 기반 컨테이너는 지원 구현체 목록(Ubuntu/CentOS/Rocky/Debian)에 포함되어 있지 않아 폴백 동작을 반드시 확인해야 합니다.
• 크론 작업은 컨테이너 외부 호스트 crontab 또는 별도 schedule 컨테이너에서 실행해야 합니다. Sail 기본 구성에서는 스케줄러 컨테이너가 분리되어 있지 않으므로, docker-compose.yml에 전용 서비스(command: php artisan schedule:work)를 추가하는 방식을 권합니다.

프로덕션 도입 전 체크리스트를 정리하면 다음과 같습니다.

LogMonitor의 I/O 비용도 빠뜨릴 수 없습니다. 1분마다 로그 파일을 읽어 SHA256 해시를 계산하는 구조인데, 트래픽이 많은 서비스에서 laravel.log가 수 MB 이상으로 불어나면 디스크 I/O 압박이 생길 수 있습니다. config/vigilance.php의 log_monitor_prefixes를 필요한 파일만 한정하고, 로그 로테이션 주기를 daily로 고정하는 것이 운영 안정성에 유리합니다.

정리하면서 생기는 질문들 🙋

앞의 세 분 말씀을 들으면서 기초적인 부분이 궁금해졌어요. 아직 모니터링 패키지를 써본 적 없는 분들을 위해 제가 먼저 물어볼게요!

첫 번째 질문 — 처음 설치할 때 뭘 먼저 확인해야 하나요?

README에는 .env에 SENTINEL_HUB_URL 한 줄 추가하고 composer require만 하면 된다고 되어 있는데, 서니어님·퍼프님이 스테이징에서 php artisan vigilance:report를 먼저 실행해보라고 하셨잖아요. 이 명령어를 실행했을 때 어떤 출력이 나오면 "정상"이고, 어떤 게 나오면 "문제 있다"고 봐야 하는 건가요? 실제로 Sentinel-Hub 대시보드가 있어야만 확인이 가능한 건지, 아니면 터미널 출력만으로도 전송 성공 여부를 알 수 있는지가 궁금해요.

두 번째 질문 — VIGILANCE_SERVER_ID가 "자동 생성"된다는 게 정확히 어떤 뜻인가요?

세큐님이 UUID가 어디에 저장되는지 확인이 필요하다고 하셨는데, README에는 "최초 실행 시 자동으로 생성된다"고만 나와 있고 저장 위치가 명시되어 있지 않아요. 혹시 .env 파일을 패키지가 직접 수정하는 건지, 아니면 DB나 다른 곳에 쓰는 건지 — 운영 서버에서 .env가 버전 관리 밖에 있을 때 재배포하면 UUID가 바뀌어버리는 상황이 생기는 건 아닌지 걱정이 돼요.

💡 지금까지 나온 내용을 정리하면: Vigilance는 설치는 쉽지만, ① Sentinel-Hub 외부 전송 데이터 범위(로그 포함), ② 컨테이너 환경에서의 OS 감지, ③ 스케줄러 블로킹 시간, ④ UUID 저장 위치 — 이 네 가지를 도입 전에 꼭 확인해야 한다는 게 핵심이에요.

누비님 질문에 답변 — 두 가지 실무 핵심 포인트

vigilance:report 정상 여부 판단 기준에 대해 말씀드리겠습니다. README 기준으로 이 명령어는 Sentinel-Hub로 JSON 페이로드를 HTTP POST하는 동작을 즉시 실행합니다. 터미널 출력만으로 성공 여부를 확인할 수 있는지는 소스 코드를 직접 확인해야 알 수 있고, README에는 명시되어 있지 않습니다. 따라서 가장 확실한 검증 방법은 두 가지를 병행하는 것입니다. 첫째, 수동 실행 후 Sentinel-Hub 대시보드에서 해당 서버의 최신 reported_at 타임스탬프가 갱신되었는지 확인합니다. 둘째, Laravel 로그(storage/logs/laravel.log)에서 전송 실패나 재시도 관련 예외가 기록되었는지 확인합니다. 재시도 로직이 지수 백오프로 구현되어 있으므로, 전송에 실패하면 로그에 흔적이 남을 가능성이 높습니다.

VIGILANCE_SERVER_ID 자동 생성 저장 위치는 누비님이 정확히 짚으셨습니다. README에는 "최초 실행 시 자동 생성된다"고만 되어 있고 저장 방식이 명시되어 있지 않습니다. 세큐님이 우려하신 것처럼, 만약 패키지가 .env 파일을 직접 수정하는 방식이라면 재배포 시 .env가 초기화되거나 덮어쓰여질 경우 UUID가 소실되어 Sentinel-Hub에서 동일 서버가 새 서버로 인식될 수 있습니다. 실무적으로는 아래 순서로 확인하고 대응하는 것을 권장합니다.

• php artisan vigilance:report를 최초 실행한 뒤 .env 파일과 config/vigilance.php를 즉시 확인하여 VIGILANCE_SERVER_ID 값이 어디에 기록되었는지 확인
• .env에 기록되었다면, 해당 값을 배포 파이프라인의 시크릿 관리 도구(예: GitHub Actions Secret, Vault, AWS Parameter Store)에 별도로 백업
• config/vigilance.php의 server_uuid가 .env 변수를 참조하는 구조이므로, 운영 서버에서 이 값이 비어 있으면 매 실행마다 UUID가 재생성될 위험이 있음

요약하면, 설치 직후 UUID 확정 → 외부 시크릿 저장소 백업 → 배포 스크립트에 복원 단계 추가가 UUID 안정성을 보장하는 가장 안전한 운영 패턴입니다. 이 부분은 패키지 문서의 공백이므로, GitHub Issues를 통해 저장 방식 명문화를 요청하는 것도 기여 차원에서 의미 있는 행동입니다.

UUID 저장 방식과 인증 부재 — 보안 관점 보충

서니어님이 정리하신 UUID 백업 권고에 보안 측면을 추가합니다. 만약 패키지가 .env를 직접 수정하는 방식이라면, 이는 Laravel 관례를 벗어난 동작입니다. 웹 서버 프로세스가 .env에 쓰기 권한을 갖는 상황 자체가 보안상 바람직하지 않으며, 파일 퍼미션 설정을 잘못하면 .env 전체가 외부에 노출될 공격 표면이 됩니다. 첫 실행 전에 .env 파일의 퍼미션이 640 이하인지 반드시 확인하세요.

누비님이 질문하신 배경에서 파생되는 더 큰 우려는 인증 없는 페이로드 전송입니다. README 어디에도 Sentinel-Hub 전송 시 API 키나 Bearer 토큰이 사용된다는 언급이 없습니다. UUID만으로 서버를 식별한다면 아래 시나리오가 이론상 가능합니다.

• 공격자가 UUID를 획득(예: 로그 유출, 네트워크 스니핑) → 동일 UUID로 위조 페이로드를 Sentinel-Hub에 전송 → 모니터링 데이터 오염
• 반대로, 다른 서버의 UUID를 추측하거나 열거하여 해당 서버의 상태 정보를 확인

이 부분은 소스 코드에서 HTTP 요청 헤더를 직접 확인해야 해결됩니다. cms-orbit/vigilance GitHub 저장소에서 Guzzle 클라이언트 초기화 부분을 찾아 Authorization 헤더 유무를 점검하세요. 인증 헤더가 없다면 도입 전에 메인테이너에게 이슈를 제기하거나, 내부망 전용 Sentinel-Hub 구성 여부를 확인하는 것이 선행되어야 합니다.

현시점 종합 보안 판단을 정리하면 다음과 같습니다.

규제 산업 환경이 아니더라도, 인증 메커니즘 확인 전까지는 프로덕션 적용을 보류하는 것이 원칙적으로 올바른 판단입니다.