Meta DB Backup Guide(KR)

Meta DB 백업 및 복구 가이드

Language: English | 한국어

1. 개요

• CB-Spider는 모든 관리 메타데이터(CSP 연결 설정, 자원 IID 등)를 단일 SQLite3 데이터베이스 파일(meta_db/cb-spider.db)에 저장한다.
• 이 파일이 훼손되거나 실수로 삭제되면, Spider가 여러 CSP 및 Region에서 관리 중인 자원의 식별 및 관리가 매우 어려워진다.
• 이러한 위험을 완화하기 위해 CB-Spider는 SQLite3의 VACUUM INTO를 활용한 자동 백그라운드 백업 기능을 제공한다.

┌───────────────────────────────────────────────────────────────┐
│                   CB-Spider Meta DB Backup                    │
│                                                               │
│  meta_db/                                                     │
│  ├── cb-spider.db                     ← 운영 Meta DB           │
│  └── backups/                         ← 백업 디렉토리            │
│      ├── cb-spider_backup_20260305_060000.db                  │
│      ├── cb-spider_backup_20260305_120000.db                  │
│      ├── cb-spider_backup_20260305_180000.db                  │
│      └── ...  (MaxCount까지 유지, 오래된 것부터 로테이션)             │
└───────────────────────────────────────────────────────────────┘

2. 백업 정책

2.1 온라인 백업 (VACUUM INTO)

• SQLite3의 VACUUM INTO 명령을 사용하여 백업을 수행한다.
• 완전한 온라인 작업으로, 백업 중에도 Meta DB에 대한 읽기/쓰기가 정상적으로 계속된다.
• 백업 파일은 실행 시점의 데이터베이스에 대한 최적화된 일관성 있는 스냅샷이다.

2.2 백업 주기

항목	기본값	설명
시작 시 백업	항상	Spider 서버 시작 시 즉시 백업 수행
주기적 백업	매 6시간	설정된 간격으로 백그라운드 스케줄러 실행
최소 간격	1분	1분 미만 값은 자동으로 1분으로 조정

2.3 보관 정책 (로테이션)

• 최대 보관 개수(MaxCount)만 적용된다.
• 백업 파일 수가 MaxCount를 초과하면 가장 오래된 파일부터 삭제된다.
• 시간 기반 만료는 없으며, 순수하게 개수 기반으로 보관한다.

항목	기본값	설명
최대 보관 개수	10	유지할 백업 파일 수

2.4 백업 파일 네이밍

cb-spider_backup_YYYYMMDD_HHMMSS.db

• 예시: cb-spider_backup_20260305_180000.db
• 파일명(타임스탬프)순으로 정렬되어 로테이션된다.

3. 설정

모든 백업 설정은 setup.env의 환경변수로 설정한다.
모든 설정은 선택사항이다. 설정하지 않으면 오류 없이 기본값이 적용된다.

환경변수	기본값	설명
SPIDER_BACKUP_ENABLED	true	백업 활성화/비활성화 (true, false, on, off, 1, 0)
SPIDER_BACKUP_INTERVAL	6h	백업 주기, Go duration 형식 (1h, 30m, 24h 등)
SPIDER_BACKUP_DIR	$CBSPIDER_ROOT/meta_db/backups	백업 파일 저장 디렉토리
SPIDER_BACKUP_MAX_COUNT	10	최대 보관 백업 파일 수

3.1 설정 예시

기본 설정 (별도 설정 불필요)

# 모든 기본값 적용: 활성화, 6시간 간격, 10개 보관
# 환경변수 설정 없이 사용 가능

고빈도 백업

export SPIDER_BACKUP_INTERVAL=1h
export SPIDER_BACKUP_MAX_COUNT=24

일 1회 백업

export SPIDER_BACKUP_INTERVAL=24h
export SPIDER_BACKUP_MAX_COUNT=7

백업 비활성화

export SPIDER_BACKUP_ENABLED=false

4. 복구 절차

Meta DB(cb-spider.db)가 훼손되거나 삭제된 경우, 가장 최신 백업으로 복원한다:

4.1 복구 단계

Step 1.  CB-Spider 서버를 중지한다.
Step 2.  (선택) 훼손된 DB 파일을 이동 또는 이름 변경한다:
           $ mv meta_db/cb-spider.db meta_db/cb-spider.db.corrupted
Step 3.  최신 백업 파일을 운영 DB로 복사한다:
           $ cp meta_db/backups/cb-spider_backup_20260305_180000.db meta_db/cb-spider.db
Step 4.  CB-Spider 서버를 재시작한다.

중요: SQLite가 파일 수준 잠금을 사용하므로, DB 파일 교체 전에 반드시 서버를 중지해야 한다.

4.2 최신 백업 확인

# 시간순으로 백업 목록 확인 (최신이 마지막)
$ ls -lt meta_db/backups/

파일명에 포함된 타임스탬프가 가장 최근인 파일이 최신 백업이다.

5. 로깅

모든 백업 작업은 cb-log를 통해 [MSB] (Meta Store Backup) 접두어로 로그를 기록한다:

로그 레벨	메시지	설명
INFO	[MSB] Meta DB Backup Scheduler started.	스케줄러 초기화
INFO	[MSB] Starting meta DB backup...	백업 주기 시작
INFO	[MSB] Meta DB backup completed: <경로> (took <소요시간>)	백업 성공
INFO	[MSB] Deleted old backup: <파일명>	로테이션 정리
WARN	[MSB] Meta DB file not found: <경로>. Skipping backup.	원본 DB 없음
ERROR	[MSB] Meta DB backup failed: <에러>	백업 실패
ERROR	[MSB] Backup rotation failed: <에러>	로테이션 실패

6. 아키텍처

apiserver.go (main)
    │
    ├── LoadBackupConfig()         ← 환경변수 읽기 (backup_config.go)
    │
    └── StartBackupScheduler()     ← 백그라운드 goroutine 시작 (backup_scheduler.go)
            │
            ├── 서버 시작 시 즉시 백업
            │
            └── 주기적 반복 (time.Ticker)
                    │
                    ├── BackupMetaDB()      ← VACUUM INTO (backup.go)
                    │
                    └── RotateBackups()     ← MaxCount 초과 시 오래된 것 삭제 (backup.go)

소스 파일	설명
info-store/backup_config.go	안전한 기본값을 가진 설정 파싱
info-store/backup.go	핵심 백업 로직 (VACUUM INTO) 및 로테이션
info-store/backup_scheduler.go	Graceful shutdown을 지원하는 백그라운드 스케줄러