TimeMachine

Paper 월드의 FULL·증분 snapshot을 만들고 실제 복원 가능한 chain을 검증합니다.

추적 범위
region · entities · poi
기본 모드
SAFE · SHA-256
복원 방식
offline verify · export

하는 일

월드의 region, entities, poi MCA 파일을 FULL 기준점과 후속 증분 snapshot으로 보관합니다. 첫 전역 /tm backup은 자동으로 FULL 기준점을 만듭니다.

SQLite는 history와 snapshot 위치 상태를 찾기 위한 보조 index이며, 복원 원본은 manifest와 snapshot 파일입니다.

빠른 시작

  1. 요구 사항 확인

    최소 Paper 1.21.11과 Java 21을 사용합니다. Paper 26.1 이상은 Java 25가 필요합니다.

  2. 첫 기준점 생성

    /tm backup으로 첫 FULL snapshot을 만듭니다.

  3. 상태 진단

    /tm status와 /tm doctor로 작업·저장소·chain 상태를 확인합니다.

  4. snapshot 검증

    /tm verify <snapshotId>로 manifest와 복원 chain을 검사합니다.

  5. 자동 실행 선택

    자동 백업은 기본 비활성입니다. schedule.enabled: true로 설정한 뒤 /tm reload를 실행합니다.

핵심 동작과 안전성

SAFE 변경 감지
모든 추적 파일을 SHA-256으로 비교해 size와 mtime이 같은 내용 변경도 찾습니다.
FAST 선택지
size와 mtime으로 후보를 선별하므로 같은 값 안에서 바뀐 내용을 놓칠 수 있습니다. 실제 복사 파일은 두 모드 모두 SHA-256으로 다시 확인합니다.
안정 상태 복사
복사 중 원본 변경을 감지하면 안정된 상태가 될 때까지 제한된 범위에서 다시 시도합니다.
chain 무결성
manifest, world mapping, 삭제 목록, entry identity, parent와 FULL base 관계를 함께 검증합니다.
진행 상태
status는 작업 단계, 파일·바이트 진행률, 경과 시간, 마지막 백업과 다음 실행을 표시합니다.
운영 진단
doctor는 쓰기·여유 공간, 변경 감지, 현재 chain, scope, SQLite, FULL 주기와 retention 위험을 확인합니다.
안전한 설정 교체
validate 성공 후에만 새 설정을 적용합니다. 저장소와 world 경로가 겹치면 거부하고 copy thread는 1~8개로 제한합니다.
자동 실행
daily time, interval, monthly 조합과 시작 시 누락 실행 보완을 지원합니다.
chain 단위 보존
retention은 기본 비활성입니다. FULL부터 마지막 child까지 완전한 chain 단위로 처리하고 현재·고정 snapshot chain과 최소 2개 chain을 보호합니다.
검증형 prune
manual prune은 preview token과 fingerprint가 일치해야 실행하며, 안전 검사 실패 시 파일을 삭제하지 않습니다.

주요 명령

조회 · viewer

/tm status현재 작업과 최근 백업 상태

/tm doctor저장소와 chain 진단

/tm history [count]최근 snapshot 이력

백업 · operator

/tm backup전역 백업, 첫 실행은 FULL

backup world · full · messageworld 범위, 새 FULL 기준점 또는 메시지 지정

/tm verify <snapshotId>snapshot과 chain 검증

관리 · admin

/tm prune미리보기와 fingerprint 검증 후 정리

/tm reconcilesnapshot과 보조 index 상태 조정

/tm reload검증 후 설정 교체

오프라인 복원

restore list복원 가능한 snapshot 조회

restore verify --snapshot <id>전체 chain 재검증

restore export --snapshot <id> --output <new-dir>새 디렉터리로만 내보내기

복원 명령은 서버를 완전히 종료한 복사 환경에서 동일한 JAR로 실행합니다. 운영 world를 자동으로 덮어쓰지 않습니다.

호환성과 한계

요구 사항

  • 최소 Paper 1.21.11, Java 21
  • Paper 26.1 이상 서버는 Java 25
  • backup snapshot과 별도의 검증된 off-site 백업
  • 정기적인 오프라인 복원 훈련

범위와 미지원

  • region, entities, poi MCA 전용이며 서버 전체 백업이 아닙니다.
  • playerdata, level.dat, datapack, plugin data와 config는 별도 백업이 필요합니다.
  • Folia, hot reload, 온라인·자동 in-place restore를 지원하지 않습니다.
  • 압축, 암호화, cloud upload와 webhook을 제공하지 않습니다.