백업
백업은 SQLite Backup API를 통해 만든 온라인 SQLite 스냅샷으로, WAL에서 안전하게 실행할 수 있고 외부 도구 없이 복원할 수 있습니다.
백업 모델
백업은 서버가 실행되는 동안 만들어지는 SQLite 데이터베이스의 일관된 스냅샷입니다.
POST /api/v2/backups가 SQLite Backup API를 통해 스냅샷을 만듭니다. WAL에서 안전하며 읽기를 막지 않습니다.GET /api/v2/backups는 기존 백업을 나열합니다. 캐시 내용과 로그는 포함되지 않습니다.
각 백업 레코드는 날짜, 크기, 스키마 버전, 소스, 상태를 보여줍니다. UI도 같은 정보를 보여주며, 백업 생성이 로컬 데이터 읽기를 막지 않습니다.
백업이 다루는 범위
백업은 구조화된 데이터베이스 전체를 다룹니다. 캐릭터, 페르소나, 채팅과 메시지, 로어북, 프리셋, 프로바이더 구성, 플러그인 상태, 설정입니다. 포함되지 않는 것은 다음과 같습니다.
cache/thumbnails/— 재생성 가능하며 설계상 제외됩니다;- 로그 — 설계상 제외됩니다;
- 가져오기 스테이징 디렉터리 — 설계상 일시적입니다.
files/의 원본은 콘텐츠 주소로 지정되고 캐시 유지 관리가 절대
건드리지 않으므로 스냅샷 자체의 일부가 아닙니다.
복원
POST /api/v2/backups/:id/restore는 안전한 순서를 따릅니다.
- 현재 상태의 안전 백업을 만들고 순환시킵니다.
- 선택한 스냅샷을
PRAGMA quick_check로 검증합니다. - SQLite Online Backup API로 라이브 데이터베이스에 복사합니다.
연결과 리포지토리는 열린 채로 유지됩니다. 응답은
restartRequired: false를 담고, 이후 읽기와 쓰기는 재시작 없이 계속
동작합니다. 복원에는 외부 SQLite 도구가 필요하지 않습니다. 스냅샷이나
복사가 실패하면 RESTORE_FAILED를 반환하고 안전 백업은 유지되므로,
실패한 복원에서도 현재 상태가 절대 손실되지 않습니다.
UI에서 복원은 명시적 확인을 요구하고, 무결성 검사가 통과하기 전에는 성공으로 보고되지 않으며, 문제가 생기면 안전 복사본으로 자동 복귀를 제안합니다. 백업 삭제 시 마지막으로 동작하는 복사본이라면 경고합니다.
안전망으로서의 백업
같은 스냅샷 메커니즘이 위험한 작업을 지킵니다.
- 마이그레이션 실행기는 테이블을 재구축하거나 재형성하는 마이그레이션 전에 데이터가 채워진 데이터베이스에 대해 마이그레이션 전 백업을 만듭니다.
- 가져오기 실행은 선택된 데이터를 쓰기 전에 안전 백업을 만들므로 실패하거나 중단된 가져오기는 항상 롤백할 수 있습니다.
- 복원은 위에서 설명한 대로 항상 먼저 현재 상태를 스냅샷합니다.
함께 보기
- 데이터베이스 자체는 SQLite 저장소.
- 데이터베이스 밖에 있는 것은 파일 및 이미지.
- 사용자 흐름은 사용자 가이드에 문서화되어 있습니다.