CoreProtect — Minecraft Java Edition 1.16 - 1.21.11+

Minecraft 멀티플레이어 서버는 무단 맵 변경과 게임 내 귀중품 도난을 방지하기 위해 플레이어 행동에 대한 상세한 감사가 필요합니다. 서버의 바닐라 코어는 지형 편집 기록이나 컨테이너 내 아이템 이동을 기록하지 않으므로, 관리자는 백업에서 맵 파일을 완전히 복원하지 않고서는 위반자를 식별하거나 파괴를 되돌릴 방법이 없습니다. 서버 플러그인 CoreProtect는 세계를 변경하는 모든 이벤트를 기록하고, 사용자 행동의 상세한 색인을 생성하며, 복잡한 매개변수 쿼리를 기반으로 공간의 부분적 롤백(rollback)을 수행합니다. 이 도구는 비동기 모드로 작동하며, 서버의 메인 스레드를 지연으로부터 보호하기 위해 트랜잭션을 큐에 기록합니다.

1. 데이터베이스와 비동기 로깅 아키텍처

CoreProtect 플러그인은 Bukkit/Paper API의 이벤트 핸들러를 사용하여 서버 이벤트를 가로챕니다. 초당 수천 건의 기록을 처리하는 동안 서버 메인 스레드(Server Thread)가 차단되는 것을 방지하기 위해 플러그인은 비동기 로깅 모델을 사용합니다. 이벤트(블록 파괴, 상자 인벤토리 변경, 명령어 사용)는 먼저 내부 동적 버퍼인 DataQueue에 배치됩니다. 백그라운드 소비자 스레드(Consumer Thread)는 버퍼에서 트랜잭션을 읽어 일괄 트랜잭션(Batch processing)으로 데이터베이스에 기록하며, 이는 저장 장치의 부하를 줄여 줍니다.

플러그인은 두 가지 데이터베이스 관리 시스템(DBMS)과의 작업을 지원합니다:

1. SQLite(기본적으로 로컬): 모든 정보는 플러그인 디렉터리의 database.db 파일에 기록됩니다. SQLite는 타사 서비스의 설치가 필요하지 않으므로, 트랜잭션 수준이 낮은 소규모 로컬 서버에 편리합니다.

2. MySQL / MariaDB(외부 서버): 별도의 데이터베이스 서버에 대한 네트워크 연결을 사용합니다. 이 솔루션은 높은 동시 접속자 수(50명 이상)를 가진 대규모 서버 및 서버 네트워크를 위한 업계 표준입니다. MySQL은 색인 쿼리의 높은 실행 속도를 보장하고 로컬 저장소의 단편화를 방지합니다.

데이터베이스 테이블 스키마

CoreProtect는 데이터 저장을 최적화하기 위해 일련의 관계형 테이블을 생성합니다. 각 기록마다 전체 텍스트 문자열을 저장하는 대신, 플러그인은 플레이어, 세계, 블록 유형 및 엔티티의 고유한 이름을 위한 사전 테이블을 사용합니다.

모든 좌표 x, y, z는 지정된 반경 내 트랜잭션의 즉각적인 검색을 보장하기 위해 세계 식별자 wid와 함께 색인됩니다.

2. 명령어 구문과 필터링 매개변수

CoreProtect 데이터베이스와의 상호 작용은 텍스트 명령어를 통해 이루어집니다. 주요 작업은 검사, 검색, 롤백 및 롤백 취소입니다.

검사관 모드 /co inspect 또는 /co i)

이 명령어는 클라이언트를 로컬 감사 모드로 전환합니다. 활성화 후 플레이어는 로그를 얻기 위해 세계와 상호 작용할 수 있습니다:

·        기존 블록을 좌클릭하면 그것을 설치한 사람의 닉네임, 날짜, 시간 및 좌표가 채팅에 표시됩니다.

·        빈 표면(또는 블록)을 우클릭하면 이전에 그 공간을 차지했거나 철거된 블록의 기록이 표시됩니다.

·        컨테이너(상자, 화로, 통, 셜커)를 우클릭하면 아이템 이동 로그가 표시됩니다.

쿼리 필터링 매개변수 /co rollback, /co restore, /co lookup)

데이터 선택을 위해 플러그인은 매개변수:값 형식의 조합 매개변수를 사용합니다. 매개변수는 공백으로 구분됩니다:

1. 사용자 u:<이름>): 확인할 플레이어를 지정합니다. 쉼표로 구분하여 여러 이름을 지정할 수 있습니다(예: u:Stevie,Alex). 자연 이벤트를 롤백하려면 기술 식별자를 사용합니다:

·        u:#fire – 불의 확산.

·        u:#lava – 용암의 유출.

·        u:#water – 물의 유출.

·        u:#creeper – 크리퍼의 폭발.

·        u:#tnt – TNT 폭발.

·        u:#enderman – 엔더맨에 의한 블록 이동.

2. 시간 t:<값>): 분석을 위한 시간 간격. 측정 단위를 지원합니다: s(초), m(분), h(시간), d(일), w(주), y(년). 단위를 조합할 수 있습니다, 예: t:2w4d6h(2주 4일 6시간).

3. 반경 r:<숫자>): 명령어 실행자 주변의 블록 단위 검색 영역 반경. 특수 값도 지원합니다:

·        r:#global – 전체 데이터베이스 검색(로드된 모든 청크 내).

·        r:#world – 현재 게임 세계 내 검색.

·        r:#chunk – 플레이어의 현재 청크 내 검색.

·        r:#selection (또는 r:#we) – 검색을 WorldEdit의 현재 선택 영역 경계로 제한합니다.

4. 동작 a:<유형>): 작업 유형별로 기록을 필터링합니다:

·        a:block – 블록 설치 및 파괴.

·        a:+block – 블록 설치만.

·        a:-block – 블록 파괴만.

·        a:container – 인벤토리 트랜잭션.

·        a:+container – 컨테이너에 아이템 추가.

·        a:-container – 컨테이너에서 아이템 제거.

·        a:kill – 동물과 몬스터의 사망.

·        a:spawn – 엔티티의 스폰.

·        a:chat – 채팅 메시지.

·        a:command – 입력한 명령어.

·        a:session – 플레이어의 인증.

5. 블록 b:<재료>): 검색을 지정된 재료로 제한합니다(예: b:stone,oak_planks).

6. 제외 e:<재료>): 처리에서 재료를 제외합니다(예: e:tnt).

롤백 미리보기 및 작업 취소

대규모 롤백 중 오류를 최소화하기 위해 CoreProtect는 시각적 시뮬레이션 시스템을 지원합니다:

1. 롤백 명령어를 #preview 플래그와 함께 실행하면(예: /co rollback u:Griefer t:2h r:20 #preview) 맵 파일이 변경되지 않습니다. 대신 클라이언트는 현재 렌더링 세션에서 블록 변경 패킷을 수신합니다. 관리자는 세계를 "롤백 후" 상태로 보지만, 다른 플레이어에게는 블록이 변경되지 않은 채로 남아 있습니다.

#preview

/co apply

2. 결과를 적용하려면 /co apply 명령어를 사용합니다.

3. 미리보기를 취소하려면 /co cancel 명령어를 사용합니다.

4. 이미 수행된 물리적 롤백을 취소하려면 /co undo 명령어를 적용하며, 이는 좌표를 /co rollback 실행 이전 상태로 되돌립니다.

3. 구성 파일 config.yml의 전체 설명

구성 파일은 제한, 로깅 매개변수 및 데이터베이스 연결을 관리합니다.

일반 매개변수 블록(General Settings)

·        verbose: true – 롤백 실행 중 변경된 각 좌표에 대한 상세 보고서를 콘솔에 출력합니다. false로 설정하면 변경된 블록의 총 개수만 출력됩니다.

·        check-updates: true – 시작 시 개발자 서버에 플러그인의 새 버전이 있는지 확인합니다.

·        api-enabled: true – 타사 플러그인이 CoreProtect 데이터와 상호 작용하도록 허용합니다.

·        default-radius: 10 – 이 매개변수가 명령어에 지정되지 않은 경우의 기본 롤백 반경.

·        max-radius: 250 – 단일 명령어에 대한 최대 반경을 제한합니다. 0 값은 제한을 해제합니다.

로깅 매개변수 블록(Logging Settings)

이 매개변수는 정확히 어떤 이벤트가 데이터베이스에 기록되는지를 결정합니다. 불필요한 로그를 비활성화하면 데이터베이스 크기를 줄이는 데 도움이 됩니다:

·        block-place: true / block-break: true – 플레이어가 블록을 일반적으로 설치하고 파괴하는 것의 로깅.

·        natural-break: true – 이동이나 지지 블록의 파괴로 인한 블록 낙하의 로깅(예: 횃불이 붙어 있던 블록의 파괴).

·        block-movement: true – 모래, 자갈 또는 콘크리트의 중력 낙하 로깅.

·        pistons: true – 피스톤을 사용한 블록 이동의 로깅.

·        block-burn: true – 불에 의한 블록 파괴의 로깅.

·        block-ignite: true – 플레이어가 부싯돌이나 화염구를 사용하여 블록에 불을 붙이는 것의 로깅.

·        explosions: true – TNT, 크리퍼, 네더의 침대 또는 엔드 수정의 폭발 로깅.

·        entity-kills: true – 주민, 동물, 몬스터 및 갑옷 거치대의 사망 기록.

·        player-chat: true / player-command: true – 채팅 메시지 및 콘솔 명령어의 로깅.

·        player-session: true – 플레이어가 서버에 입장하고 퇴장한 시간의 로깅.

·        container-transactions: true – 상자, 화로, 깔때기 및 셜커에서의 아이템 이동 작업 로깅.

데이터베이스 블록(Database Settings)

·        use-mysql: false – 데이터베이스 유형 전환기. true로 설정하면 플러그인이 외부 MySQL DBMS에 연결됩니다.

·        table-prefix: co_ – SQL 테이블 이름의 접두사.

·        mysql-host: localhost – MySQL 데이터베이스 서버의 IP 주소 또는 도메인 이름.

·        mysql-port: 3306 – 연결을 위한 네트워크 포트.

·        mysql-database: minecraft – 대상 데이터베이스의 이름.

·        mysql-username: root – 데이터베이스 사용자 이름.

·        mysql-password: password – 사용자의 비밀번호.

·        mysql-ssl: false – 데이터베이스 서버에 대한 연결의 SSL 암호화를 활성화합니다.

4. 플러그인 개발자를 위한 API

CoreProtect는 CoreProtectAPI 클래스를 통해 개발자에게 자체 데이터베이스에 대한 접근을 제공합니다. 이를 통해 다른 플러그인(예: WorldEdit 또는 보호 시스템)이 자신의 변경 사항을 기록하거나 기록에서 자동 검색을 수행할 수 있습니다.

API 초기화

API에 연결하려면 초기화 메서드를 사용합니다:

API 인터페이스의 주요 메서드

·        boolean logPlacement(String user, Location location, Material type, BlockData blockData) – 지정된 사용자를 대신하여 블록 설치를 데이터베이스에 기록합니다.

·        boolean logRemoval(String user, Location location, Material type, BlockData blockData) – 블록 파괴를 기록합니다.

·        boolean logContainerTransaction(String user, Location location, Material type, ItemStack itemStack, boolean isAdded) – 컨테이너에서 아이템 추가(true) 또는 제거(false) 작업을 기록합니다.

·        List<String[]> performLookup(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 지정된 필터에 따라 검색을 수행하고 결과 배열을 반환합니다.

·        List<String[]> performRollback(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 세계 내 변경 사항의 비동기 롤백을 시작합니다.

·        List<String[]> performRestore(int time, List<String> restrictUsers, List<String> excludeUsers, List<Object> restrictBlocks, List<Object> excludeBlocks, List<Integer> restrictActions, int radius, Location location) – 변경 사항의 비동기 복원을 시작합니다.

·        boolean hasPlaced(String user, Block block, int time, int offset) – 지정된 플레이어가 특정 시간 내에 이 블록을 설치했는지 확인합니다.

·        boolean hasRemoved(String user, Block block, int time, int offset) – 지정된 플레이어가 이 블록을 파괴했는지 확인합니다.

5. 성능, 호환성 및 유지 관리

높은 동시 접속자 수를 가진 서버에서 CoreProtect를 사용할 때 관리자는 최신 서버 아키텍처와의 상호 작용 특성을 고려합니다:

·        Folia 지원: Folia 서버 코어는 지역화된 다중 스레드 스케줄링(Regionized multithreading)을 사용하며, 이는 세계와 작업할 때 플러그인에 엄격한 스레드 안전성을 요구합니다. CoreProtect는 Folia에서 작동하도록 조정되어 있습니다: /co rollback 및 /co restore 작업의 실행은 지역 스케줄러(Region Scheduler)를 통해 이루어지며, 이는 청크 접근 충돌과 ConcurrentModificationException 유형의 치명적 오류를 방지합니다.

·        MultiPaper 클러스터링: MultiPaper 유형의 서버에서는 CoreProtect가 단일 외부 MySQL 데이터베이스를 사용하도록 구성됩니다. 이는 클러스터의 여러 노드에서 플레이어 행동 기록을 동기화하는 데 도움이 됩니다.

·        데이터베이스 정리(Purge): 로컬 SQLite 데이터베이스는 시간이 지남에 따라 단편화되고 커지면서 명령어 실행을 느리게 만듭니다. /co purge t:30d 명령어는 30일이 지난 기록을 삭제합니다. SQLite 데이터베이스를 정리한 후에도 database.db 파일은 자동으로 크기가 줄어들지 않는데, 이는 SQLite DBMS가 향후 기록을 위해 빈 페이지를 보존하기 때문입니다. 디스크에서 파일을 물리적으로 줄이려면 데이터베이스 콘솔을 통해 VACUUM 명령어를 실행하거나 서버를 중지하고 타사 유틸리티를 사용하여 압축을 수행해야 합니다. MySQL 사용은 이 문제를 제거하는데, 이는 MySQL DBMS가 사용하지 않는 디스크 공간을 더 효율적으로 해제하기 때문입니다.

결론

CoreProtect는 Minecraft Java Edition 서버에서 로깅 및 복원 시스템의 표준입니다. LogBlock(MySQL과의 작업만 지원하고 블록 로깅으로 제한됨)이나 Prism(더 복잡한 설정 구조를 가짐)과 같은 대안과 달리, CoreProtect는 SQLite를 사용한 완전히 독립적인 실행, 컨테이너 내용의 상세한 추적, 그리고 고유한 롤백 미리보기 시스템 #preview를 제공합니다. 플러그인의 유일한 기술적 제한은 대규모 로컬 SQLite 데이터베이스를 정리하는 동안 저장 장치에 가해지는 상당한 부하이므로, 대규모 프로젝트에는 빠른 NVMe 디스크에 전용 MySQL DBMS를 사용하는 것이 권장됩니다. 이 플러그인은 친구들 사이의 소규모 프라이빗 서버부터 수백 명의 활성 플레이어가 있는 대규모 프로젝트까지 모두에 적합합니다.