Laravel Log Viewer 운영 기준¶

운영 서버에서 Laravel 로그를 웹 화면으로 확인해야 하는 경우의 설치 기준, 접근 통제, 금지 패턴을 정의함.

Log Viewer는 장애 분석 보조 도구일 뿐이며, 운영 로그의 원본 보관, 감사, 장기 검색 체계를 대체하지 않음.

1. 적용 기준¶

Laravel Log Viewer는 다음 조건을 만족할 때만 검토함.

운영 로그 파일이 이미 서버에 정상 기록되고 있음
접근 주체가 운영자 또는 관리자 계정으로 제한됨
관리자 경로가 외부에 직접 공개되지 않음
Nginx, 인증 미들웨어, IP 제한 등 접근 통제가 준비됨
로그에 개인정보, 인증 토큰, 비밀번호 등 민감정보가 남지 않도록 관리됨

운영 기준:

Log Viewer는 운영 편의 도구로만 사용함
장애 분석의 기준은 원본 로그 파일과 중앙 로그 시스템임
외부 사용자에게 Log Viewer 경로를 공개하지 않음

2. 설치¶

프로젝트 경로에서 패키지를 설치함.

composer require rap2hpoutre/laravel-log-viewer

운영 기준:

운영 서버의 current 경로에서 직접 composer require를 실행하지 않음
의존성 변경은 개발/빌드 경로에서 수행하고 배포 절차로 반영함
패키지 버전과 Laravel 버전 호환성을 staging에서 먼저 확인함

3. Laravel 등록 기준¶

Laravel에서는 Service Provider 자동 등록 여부를 확인함.

명시 등록이 필요한 경우 config/app.php의 providers에 추가함.

Rap2hpoutre\LaravelLogViewer\LaravelLogViewerServiceProvider::class,

운영 기준:

자동 등록 여부는 설치된 Laravel 버전과 패키지 버전에 따라 확인함
운영 반영 전 php artisan package:discover 결과를 확인함

4. Lumen 등록 기준¶

Lumen에서는 bootstrap/app.php에 Service Provider를 등록함.

$app->register(\Rap2hpoutre\LaravelLogViewer\LaravelLogViewerServiceProvider::class);

Lumen은 Laravel과 달리 일부 vendor:publish 흐름이 제한될 수 있음. 이 경우 패키지의 view/config 파일을 직접 수정하기보다, 프로젝트 내부에서 override 가능한 구조인지 먼저 확인함.

운영 기준:

vendor 디렉터리 직접 수정은 원칙적으로 금지함
vendor 파일 직접 수정이 필요해 보이면 패키지 버전, override 방식, fork 여부를 먼저 검토함
배포 시 재설치로 수정 내용이 사라질 수 있는 구조를 만들지 않음

5. 라우트 등록¶

Log Viewer 라우트는 관리자 경로 하위에 둠.

예시:

Route::middleware(['auth', 'can:view-system-logs'])
    ->prefix('admin/system')
    ->group(function () {
        Route::get('logs', [\Rap2hpoutre\LaravelLogViewer\LogViewerController::class, 'index']);
    });

Lumen 라우터를 사용하는 경우:

$router->group([
    'prefix' => 'admin/system',
    'middleware' => ['auth'],
    'namespace' => '\Rap2hpoutre\LaravelLogViewer',
], function () use ($router) {
    $router->get('logs', 'LogViewerController@index');
});

운영 기준:

/logs 같은 단순 공개 경로 사용 금지
인증 없는 라우트 등록 금지
관리자 권한 또는 별도 운영 권한으로 제한함

6. 설정 및 View Publish¶

Laravel에서 view를 커스터마이징해야 하는 경우:

php artisan vendor:publish \
  --provider="Rap2hpoutre\LaravelLogViewer\LaravelLogViewerServiceProvider" \
  --tag=views

설정 파일을 커스터마이징해야 하는 경우:

php artisan vendor:publish \
  --provider="Rap2hpoutre\LaravelLogViewer\LaravelLogViewerServiceProvider"

운영 기준:

publish 결과물은 Git으로 관리함
운영 서버에서 publish 후 직접 수정하지 않음
설정 변경 후 staging에서 로그 파일 경로와 접근 권한을 검증함

7. Nginx 접근 제한¶

관리자 경로는 네트워크 레벨에서도 제한하는 것을 권장함.

예시:

location ^~ /admin/system/logs {
    allow [ADMIN_IP];
    deny all;

    try_files $uri $uri/ /index.php$is_args$args;
}

운영 기준:

애플리케이션 인증과 Nginx IP 제한을 함께 검토함
VPN, Bastion, 사내망 등 운영 접근 경로를 명확히 함
공개 인터넷에서 관리자 로그 화면에 직접 접근할 수 없게 함

8. 운영 금지 패턴¶

인증 없이 /logs 공개
운영 로그에 개인정보, 비밀번호, 토큰을 남긴 상태로 웹 뷰어 노출
vendor 디렉터리 직접 수정
운영 서버에서 composer install/require 후 즉시 반영
Log Viewer를 중앙 로그 시스템 대체 수단으로 사용
장애 중 원본 로그를 삭제하거나 truncate

9. 정리¶

Laravel Log Viewer는 운영 편의 도구이며 로그 운영 체계의 중심이 아님
운영 반영 전 접근 통제, 로그 민감정보, 패키지 호환성을 먼저 검증해야 함
공개 경로, 무인증 경로, vendor 직접 수정은 운영 기준에서 제외함