콘텐츠로 이동

웹 콘솔 가이드

mcctl-console 웹 관리 인터페이스의 전체 사용 가이드입니다. 브라우저에서 Docker Minecraft 서버를 관리할 수 있는 현대적이고 기능이 풍부한 대시보드입니다.

개요

mcctl-console은 Minecraft 서버 인프라의 모든 측면을 그래픽 인터페이스로 관리할 수 있는 Next.js 웹 애플리케이션입니다. CLI 명령어를 실행하는 대신, 서버, 월드, 플레이어, 백업, 감사 로그, 라우팅을 직관적인 다크 테마 UI에서 관리할 수 있으며, Server-Sent Events(SSE)를 통한 실시간 업데이트를 지원합니다.

기본 URL: http://localhost:5000

아키텍처

mcctl-console은 안전한 API 통신을 위해 Backend-for-Frontend(BFF) 프록시 패턴을 사용합니다:

+------------------+      +-------------------+      +---------------+
|   웹 브라우저     | ---> |   mcctl-console   | ---> |   mcctl-api   |
|   (React Query)  |      |   (Next.js BFF)   |      |   (Fastify)   |
+------------------+      +-------------------+      +---------------+
       ^                          |
       |                   세션 인증 +
       |                   X-API-Key 전달
       |
   React Query
   (자동 새로고침)

BFF 프록시를 사용하는 이유

  1. 보안: API 키가 서버 측에 유지되어 브라우저에 노출되지 않습니다
  2. 세션 관리: Better Auth가 JWT 토큰 기반 사용자 인증을 처리합니다
  3. 타입 안전성: 프론트엔드와 백엔드 간 TypeScript 인터페이스를 공유합니다
  4. 캐싱: React Query가 낙관적 업데이트와 지능적인 캐싱을 제공합니다

콘솔 접속

첫 로그인

  1. Management Console 서비스를 시작합니다: 

    mcctl console service start

  2. 브라우저를 열고 http://localhost:5000으로 이동합니다

  3. 자격 증명을 입력합니다:

  4. 사용자명: mcctl console init 과정에서 생성한 관리자 사용자명

  5. 비밀번호: 관리자 비밀번호

  6. 로그인 버튼을 클릭합니다

세션 유지

세션은 기본적으로 24시간 동안 유지됩니다. 리프레시 토큰이 활성 세션을 자동으로 연장합니다. 우측 상단의 사용자 아바타 메뉴에서 로그아웃을 클릭하면 수동으로 세션을 종료할 수 있습니다.

대시보드

대시보드는 여러분의 지휘 센터입니다. Minecraft 서버 인프라 전체를 한눈에 파악할 수 있습니다.

대시보드

통계 카드

대시보드 상단에 4개의 통계 카드가 주요 지표를 보여줍니다:

카드 설명
Total Servers 플랫폼에 구성된 전체 Minecraft 서버 수
Online Servers 현재 running 상태인 서버 수 (SSE를 통해 실시간 업데이트)
Total Players 실행 중인 모든 서버의 총 접속 플레이어 수
Total Worlds 월드 저장소에 있는 사용 가능한 월드 수

서버 패널

대시보드 왼쪽에는 Servers 패널이 각 서버를 목록으로 표시합니다:

  • 서버 이름과 호스트명 (예: botagent.local)
  • 접속 중인 플레이어 수를 나타내는 플레이어 수 배지
  • running, starting, exited, unhealthy, stopped 등의 색상별 상태 배지

서버 이름을 클릭하면 해당 서버의 상세 페이지로 바로 이동합니다.

External Access 카드

오른쪽에 있는 External Access 카드는 playit.gg 터널 상태를 보여줍니다:

  • 외부 도메인이 구성된 서버 수 (예: "1 / 3 servers")
  • 현재 에이전트 상태 (Running 또는 Stopped)
  • 상세 설정을 위한 Routing 페이지로의 Manage 링크

최근 활동 피드

Recent Activity 피드는 서버에서 수행된 최근 관리 작업을 표시합니다:

  • 서버 시작/중지 이벤트
  • 백업 스케줄 변경
  • 구성 수정
  • 플레이어 관리 작업

각 항목에는 액션 유형(색상별 배지), 대상 서버 또는 리소스, 수행자, 경과 시간이 표시됩니다. View All을 클릭하면 전체 감사 로그 페이지로 이동합니다.

최근 업데이트 피드

Recent Updates 섹션은 mcctl 플랫폼 자체의 최신 버전 변경 로그를 보여줍니다. 최근 릴리스에 추가된 기능이나 수정된 버그를 빠르게 확인할 수 있습니다.

서버

서버 페이지에서 모든 Minecraft 서버를 관리합니다.

서버

서버 목록

페이지에 구성된 모든 서버가 그리드 레이아웃의 카드로 표시됩니다. 각 서버 카드에는 다음이 표시됩니다:

  • 서버 이름 (예: botagent, factory, wild-deity)
  • 상태 배지 -- Running(녹색) 또는 Stopped(빨간색)
  • 구성된 호스트명 수와 함께 호스트명 (예: botagent.local +2)
  • 컨테이너 이름 (예: mc-botagent)
  • 빠른 작업 버튼 -- 우측 하단의 시작(Play) 또는 중지(Stop) 버튼

필터링 및 검색

페이지 상단에서 상태별로 서버를 필터링할 수 있습니다:

  • ALL -- 모든 서버 표시
  • RUNNING -- 실행 중인 서버만 표시
  • STOPPED -- 중지된 서버만 표시

오른쪽의 Search 박스로 서버 이름을 실시간으로 검색할 수 있습니다.

새 서버 만들기

페이지 헤더의 + Create Server 버튼을 클릭하면 서버 생성 다이얼로그가 열립니다. 다이얼로그에서 다음을 설정합니다:

  1. 서버 이름 -- 서버의 고유 식별자
  2. 서버 유형 -- PAPER, VANILLA, FORGE, NEOFORGE, FABRIC 등
  3. Minecraft 버전 -- 원하는 게임 버전 선택
  4. 메모리 할당 -- 할당할 RAM 용량
  5. 추가 옵션 -- 월드 이름, 시드, 기타 구성

생성 과정에서 Server-Sent Events를 사용하여 서버 컨테이너 설정의 실시간 진행 상황을 보여줍니다.

서버 상세 페이지

서버 카드를 클릭하면 상세 서버 관리 화면이 열립니다. 상세 페이지의 구성:

헤더 섹션

  • 서버 이름, 유형, 버전, 호스트명 정보
  • 서버 생명주기 제어를 위한 Stop 및 Restart 버튼
  • 현재 서버 상태를 나타내는 상태 배지

리소스 모니터링

3개의 통계 카드가 실시간 리소스 사용량을 표시합니다:

  • CPU Usage -- 현재 CPU 사용률 (원형 프로그레스 인디케이터)
  • Memory Usage -- 할당된 메모리 대비 현재 RAM 소비량 백분율
  • World Size -- 현재 월드가 사용하는 디스크 공간

탐색 탭

서버 상세 페이지는 7개의 탭으로 구성됩니다:

탭 설명
Overview 실시간 로그 출력과 RCON 명령 입력이 가능한 서버 콘솔
Activity 이 서버에서 수행된 모든 작업의 서버별 감사 기록
Mods 모드 관리 -- Modrinth에서 모드 검색, 설치, 제거
Files 서버 파일 탐색, 편집, 업로드, 다운로드를 위한 파일 관리자
Backups 서버별 백업 정보
Access 사용자 권한 관리 -- 사용자별 접근 권한 부여, 수정, 철회
Options 호스트명 관리와 게임 설정이 포함된 서버 구성 편집기

Overview 탭

Overview 탭은 서버 상세 페이지를 열었을 때 기본으로 표시되는 화면입니다. 서버를 실시간으로 모니터링하고 상호작용할 수 있는 지휘 센터 역할을 합니다.

서버 Overview

콘솔

Overview 탭의 핵심은 Console 패널로, 서버의 실시간 로그 출력과 명령어 인터페이스에 직접 접근할 수 있습니다:

  • 실시간 로그 스트림 -- 콘솔은 서버 로그 메시지를 실시간으로 표시합니다. 월드 로딩, 플레이어 접속, RCON 초기화, 게임 상태 변경 등의 서버 이벤트에 대한 타임스탬프가 포함된 항목을 보여줍니다. 각 로그 줄에는 타임스탬프와 로그 레벨(예: INFO)이 포함되어 문제 해결에 유용합니다.
  • 명령어 입력 -- 콘솔 하단의 "Send a command" 입력 필드에서 RCON을 통해 Minecraft 서버 명령어를 직접 실행할 수 있습니다. 명령어(예: say Hello!, gamemode creative Player1, time set day)를 입력하고 Enter를 누르면 서버로 전송됩니다. 명령어 결과는 위의 로그 스트림에 표시됩니다.
  • 자동 스크롤 -- 콘솔은 최신 로그 항목이 도착하면 자동으로 스크롤되어 항상 가장 최근의 서버 활동을 확인할 수 있습니다.

콘솔 명령어

콘솔은 모든 표준 Minecraft 서버 명령어를 지원합니다. 명령어 앞에 /를 붙일 필요 없이, 명령어 이름과 인수를 직접 입력하면 됩니다 (예: whitelist add Player1).

서버 정보

하단 왼쪽의 Server Information 패널은 서버 구성과 런타임 상태에 대한 핵심 정보를 표시합니다:

필드 설명
Name 서버의 표시 이름 (예: botagent)
Container Docker 컨테이너 이름 (예: mc-botagent)
Hostname 클라이언트 연결을 위한 주 호스트명 (예: botagent.local)
Type 서버 플랫폼 유형 (VANILLA, PAPER, FORGE, NEOFORGE, FABRIC 등)
Version Minecraft 게임 버전 (예: 1.21.11)
Memory 할당된 JVM 메모리 (예: 2G)
Uptime 마지막 시작 이후 서버 실행 시간

플레이어

하단 오른쪽의 Players 패널은 현재 서버에 접속 중인 플레이어 목록을 보여줍니다. 접속 중인 플레이어가 없을 때는 "Player information unavailable" 또는 빈 상태가 표시됩니다. 플레이어가 접속하면 Minecraft 사용자명과 아바타가 표시되어 빠르게 확인할 수 있습니다.

Mods 탭

Mods 탭은 모드 서버 플랫폼(FORGE, NEOFORGE, FABRIC)을 실행하는 서버를 위한 완전한 모드 관리 인터페이스를 제공합니다. 수동 파일 관리 없이 Modrinth 저장소에서 직접 모드를 검색, 설치, 제거할 수 있습니다.

서버 Mods

모드 서버 전용

Mods 탭은 모드 서버 유형(FORGE, NEOFORGE, FABRIC)에서 가장 유용합니다. 모든 서버에서 탭이 표시되지만, 모드 설치에는 호환되는 서버 플랫폼이 필요합니다.

설치된 모드

Installed Mods 섹션은 서버에 현재 설치된 모든 모드를 목록으로 표시합니다:

  • 소스 배지 -- 모드 출처를 나타냅니다 (예: Modrinth)
  • 모드 아이콘 -- Modrinth에서 가져온 모드의 썸네일 이미지
  • 모드 이름 -- 모드의 표시 이름 (예: Create)
  • 설명 -- 모드의 기능을 간략하게 요약한 텍스트 (예: "Aesthetic Technology that empowers the Player")
  • 다운로드 수 -- Modrinth에서의 총 다운로드 수 (예: 12.6M)로, 모드의 인기도를 나타냅니다
  • 제작자 -- 모드 제작자의 사용자명 (예: simibubi)
  • 편집 버튼 (외부 링크 아이콘) -- Modrinth에서 모드의 상세 정보, 변경 로그, 문서를 새 탭에서 엽니다
  • 삭제 버튼 (빨간색 쓰레기통 아이콘) -- 확인 프롬프트 후 서버에서 모드를 제거합니다

새 모드 추가

Installed Mods 섹션 우측 상단의 + Add Mods 버튼을 클릭하면 모드 검색 다이얼로그가 열립니다. 검색 인터페이스에서 다음을 수행할 수 있습니다:

  1. Modrinth에서 이름이나 키워드로 모드를 검색합니다
  2. 서버의 Minecraft 버전과 모드 로더와의 호환성으로 결과를 필터링합니다
  3. 설명, 버전 이력, 의존성 등 모드 상세 정보를 미리 확인합니다
  4. 설치 버튼 한 번으로 선택한 모드를 설치합니다 -- 시스템이 서버에 맞는 올바른 버전을 자동으로 다운로드합니다

서버 재시작 필요

모드를 설치하거나 제거한 후에는 변경사항을 적용하기 위해 서버를 재시작해야 합니다. 모드 변경이 감지되면 UI에서 재시작을 안내합니다.

서버 파일

Files 탭은 서버 파일 시스템을 위한 완전한 기능의 파일 관리자를 제공합니다.

서버 파일

파일 브라우저

파일 브라우저는 서버의 데이터 디렉토리 내용을 익숙한 목록 레이아웃으로 표시합니다:

  • 상단의 경로 탐색(Breadcrumb)이 현재 경로(예: root /)를 보여주며, 클릭으로 상위 디렉토리로 이동할 수 있습니다
  • 현재 디렉토리에서 파일 이름으로 필터링하는 검색 박스
  • 각 파일 항목에 파일 이름, 크기, 마지막 수정일이 표시됩니다
  • 폴더가 먼저 나열되고, 그 다음에 파일이 표시됩니다

파일 작업

툴바에서 여러 작업을 수행할 수 있습니다:

작업 설명
Upload 드래그 앤 드롭 다이얼로그를 통해 현재 디렉토리에 파일 업로드
New Folder 현재 경로에 새 디렉토리 생성
Refresh 파일 목록 새로고침

파일의 컨텍스트 메뉴(우클릭)에서 다음을 수행할 수 있습니다:

  • Rename -- 파일 또는 폴더 이름 변경
  • Delete -- 확인 다이얼로그와 함께 파일 삭제
  • Download -- 로컬 머신으로 파일 다운로드

스마트 파일 에디터

파일 관리자에는 파일 유형에 맞게 적응하는 지능적인 에디터가 포함되어 있습니다:

  • server.properties -- 카테고리별 설정이 있는 특화된 폼 기반 에디터로 열립니다 (서버 옵션 섹션 참조)
  • 플레이어 데이터 파일 (whitelist.json, ops.json, banned-players.json) -- Mojang API 통합으로 사용자명 조회가 가능한 전용 플레이어 에디터로 열립니다
  • 텍스트 파일 (.txt, .json, .yml, .yaml, .properties, .cfg, .conf, .log, .toml) -- 구문 인식이 가능한 코드 에디터로 열립니다
  • 기타 파일 -- 다운로드만 가능합니다

server.properties 편집

파일 브라우저에서 server.properties를 클릭하면 시스템이 자동으로 FORM 모드(구조화된 필드)와 RAW 모드(일반 텍스트 편집)를 모두 제공하는 특화된 속성 에디터를 엽니다. Options 탭에서 사용할 수 있는 것과 동일한 에디터입니다.

서버 옵션

Options 탭은 서버의 포괄적인 구성 편집기를 제공합니다.

서버 옵션

호스트명 / 도메인

Options 탭 상단의 Hostnames / Domains 섹션은 이 서버로의 연결 라우팅에 구성된 모든 호스트명을 보여줍니다:

  • System Hostnames -- 자동 생성된 호스트명 (예: botagent.local, botagent.192.168.xx.xx.nip.io)
  • Custom Domains -- 사용자 정의 커스텀 도메인 이름
  • 추가 커스텀 호스트명을 구성하는 + Add Domain 버튼
  • mc-router와 호스트명 구성을 동기화하는 Sync Hostnames 버튼

게임플레이 설정

Gameplay 섹션에서 핵심 게임 규칙과 플레이어 경험을 구성합니다:

설정 설명
Difficulty Normal, Easy, Hard, 또는 Peaceful
Game Mode Survival, Creative, Adventure, 또는 Spectator
Max Players 최대 동시 접속 플레이어 수
Enable PvP 플레이어 간 전투(PvP) 허용 여부

Show Advanced Settings 토글을 열면 스폰 보호 반경, 엔티티 브로드캐스팅 범위 등 추가 옵션을 확인할 수 있습니다.

월드 설정

World 섹션은 월드 생성과 서버 아이덴티티를 제어합니다:

설정 설명
MOTD (오늘의 메시지) Minecraft 서버 브라우저에 표시되는 환영 메시지
World Seed 월드 생성에 사용되는 시드
World Name 월드 디렉토리의 이름
Level Type 월드 생성 유형 (Default, Flat 등)

추가 설정 카테고리

고급 설정을 펼치면 더 많은 구성 섹션이 나타납니다:

  • JVM / 성능 -- 메모리 할당, Aikar's flags, JVM 옵션
  • 네트워크 -- Online 모드, RCON 설정, 포트 구성
  • 고급 -- Auto-pause, Auto-stop, 타임존, UID/GID 설정

저장 및 재시작

설정을 수정하면:

  1. 페이지 하단에 고정 액션 바가 나타나 변경된 필드 수를 보여줍니다
  2. Save를 클릭하여 변경사항을 적용합니다
  3. 변경된 설정 중 서버 재시작이 필요한 항목(예: 메모리, 온라인 모드, 월드 설정)이 있으면 재시작 확인 다이얼로그가 나타나 지금 재시작할지 나중에 할지 묻습니다
  4. Reset을 클릭하면 저장하지 않은 변경사항을 취소합니다

재시작 필요

메모리 할당, 온라인 모드, 월드 시드 같은 일부 설정은 적용하려면 서버 재시작이 필요합니다. UI에서 변경 후 어떤 설정이 재시작을 필요로 하는지 명확하게 표시합니다.

플레이어 관리

Players 페이지에서 모든 서버의 플레이어를 종합적으로 관리합니다.

플레이어 관리

서버 선택

페이지 상단의 Server 드롭다운으로 관리할 서버를 선택합니다. 선택한 서버에 따라 아래 모든 탭에 표시되는 플레이어 데이터가 결정됩니다.

탭

플레이어 관리 페이지는 4개의 탭으로 구성됩니다:

Online Players

선택한 서버에 현재 접속 중인 플레이어를 보여줍니다. 서버가 실행 중일 때 실시간 플레이어 정보가 표시됩니다.

Whitelist

서버에 참여할 수 있는 플레이어를 관리합니다:

  • Whitelist 토글 -- 화이트리스트 활성화/비활성화 (ON/OFF 스위치)
  • 플레이어 입력 필드 -- 화이트리스트에 추가할 Minecraft 사용자명 입력
  • Add 버튼 -- 단일 플레이어 추가
  • Bulk 버튼 -- 여러 플레이어를 한 번에 추가
  • 플레이어 목록 -- 화이트리스트에 등록된 모든 플레이어가 Minecraft 아바타와 함께 표시되며, 제거 버튼 포함

오프라인 서버 데이터

서버가 오프라인일 때 Players 페이지는 서버의 JSON 파일(whitelist.json, ops.json, banned-players.json)에서 직접 데이터를 읽습니다. "Server is offline. Showing data from whitelist.json. Changes will apply on next server start."라는 안내 배너가 표시됩니다.

Operators

운영자(관리자) 권한을 가진 플레이어를 관리합니다:

  • 구성 가능한 권한 레벨(1-4)로 플레이어를 운영자로 추가
  • 레벨 1: 스폰 보호를 우회할 수 있음
  • 레벨 2: /clear, /gamemode 등을 사용할 수 있음
  • 레벨 3: /ban, /kick, /op 등을 사용할 수 있음
  • 레벨 4: /stop 사용 가능, 전체 접근 권한

오른쪽 정보 패널에서 각 OP 레벨에 대한 상세 설명을 확인할 수 있습니다.

Ban List

차단된 플레이어를 관리합니다:

  • 선택적 사유와 함께 사용자명으로 플레이어 차단
  • 현재 차단된 모든 플레이어 조회
  • 한 번의 클릭으로 플레이어 차단 해제(사면)
  • 차단 작동 방식을 설명하는 정보 패널

월드

Worlds 페이지에서 플랫폼에 저장된 모든 Minecraft 월드를 관리합니다.

월드

월드 목록

월드가 그리드 레이아웃의 카드로 표시됩니다. 각 월드 카드에는 다음이 표시됩니다:

  • 월드 이름 (예: Wild-Deity, botagent, factory)
  • 상태 배지 -- 잠금 해제된 월드는 Available(녹색), 현재 서버에 할당된 월드는 Locked
  • 크기 -- 월드가 사용하는 디스크 공간 (예: 610.2MB, 20.5MB)
  • 날짜 -- 월드가 생성되거나 마지막으로 수정된 시점
  • 작업 버튼:
    • 링크 아이콘 -- 월드를 서버에 할당
    • 삭제 아이콘 (빨간색 쓰레기통) -- 월드 삭제

필터링 및 검색

페이지 상단에서:

  • ALL -- 모든 월드 표시
  • AVAILABLE -- 사용 가능한(잠금 해제된) 월드만 표시
  • LOCKED -- 현재 서버에 할당된 월드만 표시

Search 박스로 월드 이름을 검색할 수 있습니다.

새 월드 만들기

페이지 헤더의 + Create World를 클릭하면 생성 다이얼로그가 열립니다:

  1. 월드 이름 입력
  2. 선택적으로 월드 생성을 위한 시드 지정
  3. Create 클릭

월드를 서버에 할당

월드 카드의 링크 아이콘을 클릭하면 할당 다이얼로그가 열립니다. 사용 가능한(실행 중이 아닌) 서버 목록에서 서버를 선택하고 할당을 확인합니다. 월드가 해당 서버에 연결되고 Locked로 표시됩니다.

월드 삭제

월드 카드의 빨간색 쓰레기통 아이콘을 클릭합니다. 실수로 삭제하는 것을 방지하기 위해 정확한 월드 이름을 입력해야 하는 확인 다이얼로그가 나타납니다. 이 작업은 되돌릴 수 없습니다.

데이터 손실

월드를 삭제하면 지형, 플레이어 건축물, 엔티티를 포함한 모든 월드 데이터가 영구적으로 제거됩니다. 월드를 삭제하기 전에 반드시 백업을 생성하세요.

백업

Backups 페이지에서 월드 백업과 자동 백업 스케줄을 관리합니다.

백업

백업 상태

상단 섹션에 현재 백업 구성이 표시됩니다:

  • Repository -- 백업 저장소로 구성된 Git 리포지토리 (예: smallmiro/minecraft-worlds-backup)
  • Status -- 백업 시스템이 Configured(녹색 체크마크)인지 여부
  • 백업 수 -- 기존 백업 수

수동 백업

페이지 헤더의 Push Backup 버튼을 클릭하면 모든 월드를 구성된 Git 리포지토리로 즉시 수동 백업합니다.

백업 스케줄

Backup Schedules 섹션에서 자동 cron 기반 백업 스케줄을 관리합니다:

  • 각 스케줄에 월드 이름, 빈도 (예: "Every hour"), cron 표현식이 표시됩니다
  • Retention 배지 -- 백업 보존 정책의 구성 여부를 나타냅니다
  • 토글 스위치 -- 개별 스케줄 활성화/비활성화
  • 편집 버튼 (연필 아이콘) -- 스케줄 수정
  • 삭제 버튼 (쓰레기통 아이콘) -- 스케줄 제거
  • + Add Schedule 버튼으로 새 자동 백업 스케줄 생성

백업 이력

Backup History 섹션(백업 시스템이 구성된 경우 표시)은 타임스탬프, 상태, 오류 정보를 포함한 과거 백업 작업 로그를 보여줍니다.

감사 로그

Audit Log 페이지는 서버 전체에서 수행된 모든 관리 작업에 대한 포괄적인 활동 로그를 제공합니다.

감사 로그

실시간 모니터링

감사 로그에는 페이지 헤더에 실시간 SSE 연결 상태를 보여주는 Live 인디케이터가 있습니다:

  • 녹색 점 + "Live" -- 연결됨, 실시간 이벤트 수신 중
  • 회색 점 + "Offline" -- SSE 연결 끊김 (자동 재연결)

페이지를 보는 동안 새 감사 이벤트가 도착하면 알림 배너가 나타납니다: "X new logs available - Click to refresh."

통계 개요

상단의 4개 통계 카드가 요약 지표를 제공합니다:

카드 설명
Total Logs 전체 감사 로그 항목 수
Success Rate 성공한 작업의 비율
Failures 실패한 작업 수
Active Users 작업을 수행한 고유 사용자 수

필터

감사 로그는 강력한 필터링 기능을 제공합니다:

  • 날짜 범위 선택기 -- 시작 및 종료 날짜로 필터링
  • 액션 필터 -- 특정 액션 유형으로 필터링 (예: server.start, server.stop, backup.schedule.create)
  • 대상 유형 필터 -- 대상 카테고리로 필터링: ALL, SERVER, PLAYER
  • 상태 필터 -- ALL, SUCCESS, FAILURE
  • 액터 필터 -- 작업을 수행한 사용자 이름으로 검색
  • Export 버튼 -- 필터링된 감사 데이터 내보내기

로그 테이블

메인 테이블에 다음 컬럼의 감사 항목이 표시됩니다:

컬럼 설명
Timestamp 작업이 수행된 시점 (상대 시간, 예: "21m ago")
Action 색상별 배지가 있는 액션 유형
Actor 작업을 수행한 사용자명
Target 영향을 받은 서버, 월드, 또는 리소스
Status 성공(녹색) 또는 실패(빨간색) 표시

아무 행이나 클릭하면 요청 메타데이터, IP 주소, 전체 액션 페이로드를 포함한 상세 정보가 있는 상세 드로어가 열립니다.

내보내기

Export 버튼을 클릭하면 현재 필터 선택에 기반하여 다양한 형식으로 감사 데이터를 다운로드할 수 있는 내보내기 다이얼로그가 열립니다.

라우팅

Routing 페이지에서 네트워크 라우팅 구성을 완전히 확인하고 제어할 수 있습니다.

라우팅

플랫폼 정보

왼쪽 패널에 mc-router 설정에 대한 Platform Information이 표시됩니다:

필드 설명
Router Name mc-router 컨테이너 이름
Port 수신 포트 (기본값: 25565)
Mode 라우팅 모드 (예: Auto Discovery)
Uptime 라우터 실행 시간

네트워크 설정

Network Settings 카드에 다음이 표시됩니다:

  • Listening Port -- mc-router가 수신하는 포트
  • Routing Mode -- 호스트명 해석 방법 (예: Auto Discovery)
  • Active Routes -- 활성 라우팅 항목 수

MC Router 상태

오른쪽 패널에 라이브 라우팅 테이블과 함께 MC Router Status가 표시됩니다:

  • Healthy / Unhealthy 상태 인디케이터
  • 각 서버별로 라우팅 테이블에 다음이 표시됩니다:
    • Minecraft 버전과 함께 서버 이름
    • 구성된 라우트 수
    • 모든 호스트명 매핑 (예: botagent.local, botagent.192.168.xx.xx.nip.io)

mDNS (Avahi) 상태

mDNS (Avahi) 카드는 Avahi mDNS 데몬의 활성 상태를 보여줍니다. 이를 통해 로컬 네트워크의 Minecraft 클라이언트가 .local 호스트명을 사용하여 서버에 연결할 수 있습니다.

외부 접근 (playit.gg)

External Access 섹션에서 포트 포워딩 없이 인터넷에서 서버에 접근할 수 있도록 하는 playit.gg 터널 구성을 관리합니다:

  • playit 에이전트 관리를 위한 Start Agent / Auto Dashboard 버튼
  • Agent Status -- Running 또는 Stopped
  • 외부 도메인이 구성된 서버를 보여주는 Server Domains 테이블 (예: possible-tracks.gl.joinmc.link)
  • 외부 도메인이 없는 서버의 상태 정보

내비게이션

상단 내비게이션 바는 모든 페이지에서 일관되게 표시되며 다음을 포함합니다:

항목 설명
MINECRAFT CONSOLE 로고 클릭하면 대시보드로 돌아감
Dashboard 인프라 개요
Servers 서버 관리
Worlds 월드 관리
Players 플레이어 관리
Audit 활동 감사 로그
Backups 백업 관리
Routing 네트워크 라우팅 구성
사용자 아바타 (우측 상단) 계정 설정, 테마 전환, 로그아웃

현재 활성화된 페이지가 내비게이션 바에서 강조 표시됩니다.

모범 사례

보안

  1. 강력한 비밀번호 사용 -- mcctl console init 과정에서 비밀번호 요구사항을 따르세요
  2. 접근 제한 -- Access 탭을 사용하여 각 사용자에게 최소한의 권한만 부여하세요
  3. HTTPS 사용 -- 프로덕션 배포에서는 SSL이 포함된 리버스 프록시를 구성하세요
  4. 감사 로그 검토 -- 예상치 못한 활동이 있는지 정기적으로 감사 로그를 확인하세요

서버 관리

  1. 대시보드 모니터링 -- 서버 상태, 플레이어 수, 최근 활동을 정기적으로 확인하세요
  2. 정상적인 종료 -- 컨테이너를 강제 종료하지 말고 항상 Stop 버튼을 사용하세요
  3. 변경 전 백업 -- 서버 구성이나 월드 데이터를 수정하기 전에 백업을 푸시하세요
  4. 자동 백업 활용 -- 안심을 위해 자동 백업 스케줄을 구성하세요

성능

  1. 동시 작업 지양 -- 여러 서버를 동시에 시작/중지하지 마세요
  2. 리소스 사용량 모니터링 -- 서버 상세 페이지의 리소스 통계 카드로 CPU와 메모리를 추적하세요
  3. 미사용 월드 정리 -- 더 이상 필요하지 않은 월드를 삭제하여 디스크 공간을 확보하세요

문제 해결

콘솔에 접근할 수 없음

  1. 서비스 상태 확인: 

    mcctl console service status

  2. 포트 확인: 

    netstat -tlnp | grep 5000

  3. 로그 확인: 

    pm2 logs mcctl-console --lines 100

로그인 실패

  1. 자격 증명 확인: 

    mcctl console user list

  2. 비밀번호 재설정: 

    mcctl console user reset-password admin

서버 상태가 업데이트되지 않음

  1. API 상태 확인: 

    curl http://localhost:5001/health

  2. Docker 소켓 확인: Docker가 실행 중이고 mcctl-api 프로세스가 Docker 소켓에 접근할 수 있는지 확인하세요.

  3. 네트워크 확인: mcctl-console이 5001 포트로 mcctl-api에 연결할 수 있는지 확인하세요.

명령이 작동하지 않음

  1. 서버가 실행 중이어야 함 -- RCON 명령은 서버가 running 상태일 때만 작동합니다
  2. RCON이 활성화되어야 함 -- 서버 구성에서 RCON이 활성화되어 있는지 확인하세요
  3. API 로그 확인: 
    pm2 logs mcctl-api --lines 100

모바일 접근

웹 콘솔은 다양한 화면 크기에 적응하는 반응형 Material UI 레이아웃을 사용합니다:

  • 폰 -- 접을 수 있는 내비게이션이 있는 간소화된 카드 레이아웃
  • 태블릿 -- 터치에 최적화된 컨트롤이 있는 전체 대시보드
  • 데스크톱 -- 나란히 배치된 패널의 전체 기능 세트

모바일 팁

  • 콘솔에서 더 나은 명령 입력을 위해 가로 모드를 사용하세요
  • 작은 화면에서는 내비게이션이 햄버거 메뉴로 접힙니다
  • 모든 다이얼로그는 모바일에서 더 쉬운 상호작용을 위해 전체 화면으로 표시됩니다