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을 지원하는 백그라운드 스케줄러

Meta DB Backup Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Meta DB 백업 및 복구 가이드

1. 개요

2. 백업 정책

2.1 온라인 백업 (VACUUM INTO)

2.2 백업 주기

2.3 보관 정책 (로테이션)

2.4 백업 파일 네이밍

3. 설정

3.1 설정 예시

4. 복구 절차

4.1 복구 단계

4.2 최신 백업 확인

5. 로깅

6. 아키텍처

⚠️ GitHub.com Fallback ⚠️

Meta DB Backup Guide(KR) - cloud-barista/cb-spider GitHub Wiki

Meta DB 백업 및 복구 가이드

1. 개요

2. 백업 정책

2.1 온라인 백업 (VACUUM INTO)

2.2 백업 주기

2.3 보관 정책 (로테이션)

2.4 백업 파일 네이밍

3. 설정

3.1 설정 예시

4. 복구 절차

4.1 복구 단계

4.2 최신 백업 확인

5. 로깅

6. 아키텍처

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️