감사 로그 웹 콘솔 가이드¶
웹 콘솔은 mcctl-console 서비스를 통해 감사 로그를 보고 관리하기 위한 사용자 친화적인 인터페이스를 제공합니다.
감사 로그 접근¶
URL:
내비게이션: 메인 대시보드에서 사이드바 내비게이션의 Audit Logs를 클릭합니다.
기능 개요¶
1. 감사 로그 테이블¶
메인 감사 로그 테이블은 다음 열로 최근 활동을 표시합니다:
| 열 | 설명 |
|---|---|
| Timestamp | 작업이 발생한 시간 (로컬 시간대) |
| Action | 작업 타입 (색상 코딩된 칩) |
| Actor | 작업을 수행한 주체 |
| Target | 영향을 받은 대상 (server/player/audit) |
| Status | 성공 (녹색 체크) 또는 실패 (빨간색 X) |
| Details | 전체 컨텍스트를 볼 수 있는 확장 가능한 행 |
테이블 기능: - 정렬 가능한 열 (헤더 클릭하여 정렬) - 확장 가능한 행 (행 클릭하여 세부 정보 보기) - 페이지네이션 (기본 페이지당 50개 항목) - 자동 새로고침 (30초 간격) - SSE를 통한 실시간 업데이트
2. 필터링¶
필터 패널을 사용하여 결과 범위를 좁힙니다:
필터 옵션: - Action Type: 모든 작업 타입이 있는 드롭다운 - Actor: Actor 필터를 위한 텍스트 입력 - Target Name: 서버/플레이어 이름을 위한 텍스트 입력 - Status: Success/Failure 토글 - Date Range: From/To 날짜를 위한 캘린더 선택기
빠른 필터: - All Logs - Server Operations - Player Management - Failures Only - Last 24 Hours - Last 7 Days - Last 30 Days
예제 워크플로: 1. "Failures Only" 빠른 필터 선택 2. "Last 24 Hours" 날짜 범위 선택 3. "Apply Filters" 클릭 4. 실패한 작업 검토
3. 확장 가능한 세부 정보¶
모든 로그 항목을 클릭하여 전체 세부 정보 보기:
확장 뷰 포함 사항: - 밀리초 단위의 전체 타임스탬프 - 오류 메시지 (실패 시) - JSON 세부 정보 객체 (형식화 및 구문 강조 표시) - ID 복사 버튼 - 관련 엔티티 링크 (server/player)
예제 세부 정보 (서버 생성):
{
"type": "PAPER",
"version": "1.21.1",
"memory": "4G",
"worldOptions": {
"type": "new",
"seed": null
}
}
4. 통계 대시보드 위젯¶
메인 대시보드에는 Audit Log Stats 위젯이 포함됩니다:
표시 내용: - 전체 로그 수 - Success 대 Failure 비율 (파이 차트) - 상위 5개 작업 (막대 차트) - 상위 5개 Actor (막대 차트) - 최근 실패 (목록)
새로고침: - 60초마다 자동 업데이트 - 수동 새로고침 버튼
5. 서버 활동 탭¶
각 서버 세부 정보 페이지에는 서버별 감사 로그를 표시하는 Activity 탭이 포함됩니다:
표시 내용:
- 해당 서버와 관련된 모든 작업
- targetName: <server-name>으로 필터링됨
- 동일한 필터링 및 정렬 옵션
- 타임라인 뷰 (시간순)
사용 사례: - 서버 생명주기 추적 (create → start → stop → delete) - 서버 설정을 수정한 사람 검토 - 서버 시작 실패 디버그
6. 내보내기 기능¶
외부 분석 또는 규정 준수를 위해 감사 로그 내보내기:
내보내기 형식: - CSV: 스프레드시트 호환 - JSON: 세부 정보가 포함된 전체 데이터 - PDF: 인쇄 가능한 보고서 (적용된 필터 포함)
내보내기 방법: 1. 원하는 필터 적용 2. 툴바에서 Export 버튼 클릭 3. 형식 선택 (CSV/JSON/PDF) 4. 파일 자동 다운로드
CSV 예제:
Timestamp,Action,Actor,Target Type,Target Name,Status,Error Message
2026-02-05 14:32:15,server.create,cli:local,server,myserver,success,
2026-02-05 14:30:45,player.whitelist.add,web:admin,player,Steve,success,
7. 오래된 로그 삭제¶
UI를 통해 오래된 감사 로그 삭제:
접근: - 감사 로그 페이지에서 Settings 아이콘 클릭 - Purge Logs 선택
삭제 대화 상자: - 보관 기간 선택 (30/60/90/180일 또는 사용자 지정 날짜) - 삭제 수 미리보기 - 비밀번호로 확인 (관리자만)
안전 기능: - 삭제 전 Dry-run 미리보기 - 확인 대화 상자 - 7일 미만의 로그는 삭제 불가
실시간 업데이트¶
감사 로그 페이지는 실시간 업데이트를 위해 Server-Sent Events (SSE)를 사용합니다:
라이브 표시기: - 녹색 점: 연결됨 및 업데이트 수신 중 - 빨간색 점: 연결 끊김 (클릭하여 재연결)
새 로그 도착 시: - 행이 잠시 강조 표시됨 (노란색 페이드) - 카운터 업데이트 - 통계 새로고침
자동 스크롤: - 도착하는 최신 로그를 보기 위해 자동 스크롤 토글 - 중단 방지를 위해 기본적으로 비활성화됨
작업 색상 코딩¶
작업은 카테고리별로 색상 코딩됩니다:
| 색상 | 카테고리 | 작업 |
|---|---|---|
| 파란색 | 서버 생명주기 | create, start, stop, restart, delete |
| 녹색 | 플레이어 추가 | whitelist.add, op |
| 노란색 | 플레이어 수정 | kick, unban, deop |
| 빨간색 | 플레이어 제거 | whitelist.remove, ban |
| 보라색 | 유지보수 | audit.purge |
키보드 단축키¶
| 키 | 작업 |
|---|---|
F |
필터 검색에 포커스 |
R |
로그 새로고침 |
E |
내보내기 대화 상자 열기 |
Esc |
확장된 세부 정보 닫기 |
/ |
검색 바에 포커스 |
↑/↓ |
행 탐색 |
Enter |
선택한 행 확장 |
권한¶
감사 로그 접근에는 적절한 역할이 필요합니다:
| 역할 | 권한 |
|---|---|
| Admin | 전체 접근 (보기, 내보내기, 삭제) |
| Operator | 보기 및 내보내기만 가능 |
| Viewer | 보기만 가능 (내보내기 또는 삭제 불가) |
문제 해결¶
로그가 업데이트되지 않음¶
증상: - 라이브 표시기에 빨간색 점 표시 - 새 로그가 나타나지 않음
해결 방법: 1. 네트워크 연결 확인 2. 재연결 버튼 클릭 3. 페이지 새로고침 (F5) 4. mcctl-api 서비스가 실행 중인지 확인
성능 문제¶
증상: - 대규모 결과 세트로 인한 느린 페이지 로드
해결 방법: 1. 날짜 범위 필터 축소 2. 작업 필터 적용 3. 설정에서 페이지네이션 크기 증가 4. 서버 측 페이지네이션 활성화
로그 누락¶
증상: - 예상 로그가 나타나지 않음
가능한 원인: 1. 자동 정리로 오래된 로그 삭제됨 (보관 설정 확인) 2. 수동 삭제가 수행됨 3. 필터가 로그를 숨기고 있음 (필터 재설정) 4. 시간대 불일치 (브라우저 시간대 확인)