백업

백업 (Backups)

데이터를 저장하는 시스템이라면, 지우고 잘못 건드려도 되돌릴 수 있는 안전망이 필요해요. Weaviate의 백업 기능은 클라우드 기술과 잘 어울리게 설계되어 있어서, AWS S3·GCS·Azure Storage 같은 객체 스토리지와 매끄럽게 통합되고 한 번의 명령으로 백업·복원이 가능합니다.

출처: 공식문서 - Backups

백업 기능의 특징은 다음과 같습니다.

AWS S3, GCS, Azure Storage 같은 널리 쓰이는 클라우드 블롭 스토리지와의 매끄러운 통합
서로 다른 스토리지 제공자 간 백업·복원
단일 명령 백업·복원
전체 인스턴스 또는 선택한 컬렉션만 백업 선택
변경된 데이터만 저장하는 증분 백업 — 백업 크기와 시간을 줄임
새 환경으로의 쉬운 마이그레이션

중요 백업 고려사항

버전 요건 — Weaviate v1.23.12 이하를 쓰면 복원 전에 v1.23.13 이상으로 업데이트해야 합니다. 데이터 손상을 막기 위해서예요.

멀티테넌시 제한 — 백업에는 active(HOT)와 inactive(COLD) 테넌트가 모두 포함됩니다. inactive 테넌트는 활성화 없이 디스크에서 직접 백업돼요. offloaded(FROZEN) 테넌트는 로컬 데이터가 없어 여전히 건너뜁니다. inactive 테넌트 지원은 v1.37.0에 추가됐고 v1.35.17, v1.36.10에 백포트됐습니다. 그 이전 릴리스에서는 active 테넌트만 포함되므로 백업 전에 필요한 테넌트를 활성화하세요.

백업 퀵스타트

로컬 파일시스템을 백업 제공자로 쓰는, 개발·테스트 환경에 적합한 퀵스타트입니다.

1. Weaviate 구성

Weaviate 구성(Docker 또는 Kubernetes 구성 파일)에 환경 변수를 추가합니다.

# 파일시스템 백업 모듈 활성화
ENABLE_MODULES=backup-filesystem

# 백업 위치 설정 (예: Docker 컨테이너 안 또는 Kubernetes 파드 안)
BACKUP_FILESYSTEM_PATH=/var/lib/weaviate/backups

2. 백업 시작

Weaviate를 재시작해 새 구성을 적용한 뒤 백업을 시작할 수 있습니다.

result = client.backup.create(
    backup_id="my-very-first-backup",
    backend="filesystem",
    include_collections=["Article", "Publication"],
    wait_for_completion=True,
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # (선택) Weaviate 1.27.2 / 1.28.0 이상과 Python 클라이언트 4.10.3 이상 필요
)

print(result)

백업은 지정한 로컬 파일시스템 위치에 저장됩니다. 이후에는 백업을 복원하거나, 완료를 기다리지 않았다면 상태를 확인하거나, 필요하면 취소할 수 있어요.

로컬 백업은 프로덕션에 적합하지 않습니다. 운영 환경에서는 S3, GCS, Azure Storage 같은 클라우드 제공자를 쓰세요.

스토리지 제공자 구성

Weaviate는 네 가지 백업 스토리지 옵션을 지원합니다.

제공자	모듈 이름	적합한 용도	멀티 노드 지원
AWS S3	`backup-s3`	프로덕션, AWS 환경	예
Google Cloud Storage	`backup-gcs`	프로덕션, GCP 환경	예
Azure Storage	`backup-azure`	프로덕션, Azure 환경	예
로컬 파일시스템	`backup-filesystem`	개발·테스트, 단일 노드	아니요

어떤 제공자를 쓰든: (1) ENABLE_MODULES 환경 변수에 모듈 이름을 추가해 모듈을 활성화하고, (2) 필요한 모듈을 구성합니다. 여러 제공자를 동시에 활성화할 수 있어요.

S3 (AWS 또는 S3 호환)

Amazon S3와 S3 호환 객체 스토어(예: MinIO)에서 동작하며 멀티 노드 배포를 지원하고 프로덕션에 권장됩니다. backup-s3을 구성하려면 모듈 활성화와 환경 변수 구성이 필요합니다.

ENABLE_MODULES에 backup-s3을 추가합니다.

ENABLE_MODULES=backup-s3,text2vec-cohere

주요 S3 환경 변수는 다음과 같습니다.

환경 변수	필수	설명
`BACKUP_S3_BUCKET`	예	모든 백업이 저장될 S3 버킷 이름
`BACKUP_S3_PATH`	아니요	버킷 안에서 백업이 복사·조회될 루트 경로. 기본 `""`는 버킷 루트
`BACKUP_S3_ENDPOINT`	아니요	S3 엔드포인트 호스트(포트 포함 가능). `http://`·`https://` 스킴을 넣으면 안 되고, 포함하면 `backup-s3` 모듈 초기화 실패로 Weaviate가 시작되지 않음. 기본 `"s3.amazonaws.com"`
`BACKUP_S3_USE_SSL`	아니요	연결을 SSL/TLS로 보호할지. 정확히 `false`(대소문자 무관)만 TLS를 끄고, 다른 값(`0`, `off`, `no`, 오타 포함)은 TLS를 유지. 기본 `"true"`
`BACKUP_SKIP_ACCESS_CHECK`	아니요	백업 전에 버킷에 대해 실행하는 쓰기·삭제 프로브를 건너뜀. 객체 쓰기는 되지만 삭제는 안 되는 최소 권한 자격증명에 유용. 기본 `false`

S3 인증은 AWS IAM/ARN 기반 또는 액세스 키 기반으로 할 수 있고, S3 호환 스토어는 액세스 키 인증을 씁니다. backup-s3 모듈은 자체 로직으로 자격증명을 해석합니다 — ~/.aws/credentials의 프로필과 AWS_PROFILE 변수는 읽지 않아요. 우선순위는 다음과 같습니다.

BACKUP_S3_AUTH_PROXY_ENDPOINT가 설정된 경우 외부 인증 브로커 (모든 것보다 우선)
두 액세스 키(키와 시크릿)가 모두 환경에 설정된 경우
액세스 키·시크릿이 모두 없을 때만 AWS IAM (IRSA 또는 EC2 인스턴스 롤)

주의 — AWS_ACCESS_KEY_ID와 AWS_SECRET_ACCESS_KEY가 모두 환경에 있으면 Weaviate는 IAM에 접촉하지 않고 액세스 키를 씁니다. 오래되거나 남은 키가 롤보다 조용히 우선하므로, IAM으로 인증하려면 두 변수를 모두 해제하세요.

S3 호환 엔드포인트를 쓰려면 BACKUP_S3_ENDPOINT에 제공자의 S3 엔드포인트 호스트를 설정하고 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY로 인증하며, 제공자가 요구하면 AWS_REGION을 설정합니다.

BACKUP_S3_BUCKET=weaviate-backups
BACKUP_S3_ENDPOINT=your-s3-endpoint.example.com   # host[:port], 스킴 없이
BACKUP_S3_USE_SSL=true
AWS_ACCESS_KEY_ID=<your-access-key-id>
AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
# 선택: 제공자가 리전을 요구하면 설정
# AWS_REGION=<your-region>

GCS (Google Cloud Storage)

Google Cloud Storage에서 동작하며 멀티 노드 배포를 지원하고 프로덕션에 권장됩니다. ENABLE_MODULES에 backup-gcs를 추가합니다.

ENABLE_MODULES=backup-gcs,text2vec-cohere

환경 변수	필수	설명
`BACKUP_GCS_BUCKET`	예	모든 백업을 위한 GCS 버킷 이름
`BACKUP_GCS_USE_AUTH`	아니요	인증에 자격증명을 쓸지. 기본 `true`. 로컬 GCS 에뮬레이터용으로 `false` 사용 가능
`BACKUP_GCS_PATH`	아니요	백업이 복사·조회될 버킷 안 루트 경로. 기본 `""`

backup-gcs 모듈은 Google Application Default Credentials 모범 사례를 따릅니다. 자격증명을 환경·로컬 gcloud CLI·연결된 서비스 계정을 통해 발견할 수 있어요. 환경 변수로는 GOOGLE_APPLICATION_CREDENTIALS(서비스 계정 또는 워크로드 아이덴티티 파일 경로)와 선택적으로 GCP_PROJECT를 씁니다.

Azure Storage

Microsoft Azure Storage에서 동작하며 멀티 노드 배포를 지원하고 프로덕션에 권장됩니다. ENABLE_MODULES에 backup-azure을 추가합니다.

ENABLE_MODULES=backup-azure,text2vec-cohere

환경 변수	필수	설명
`BACKUP_AZURE_CONTAINER`	예	모든 백업을 위한 Azure 컨테이너 이름
`BACKUP_AZURE_PATH`	아니요	백업이 복사·조회될 컨테이너 안 루트 경로. 기본 `""`

Azure 인증은 Azure Storage 연결 문자열 또는 계정 이름과 키 중 하나로 합니다. 둘 다 주어지면 AZURE_STORAGE_CONNECTION_STRING이 우선합니다. 최소한 둘 중 하나는 있어야 해요.

환경 변수	필수	설명
`AZURE_STORAGE_CONNECTION_STRING`	예 (*참고)	권한 부여 정보를 포함한 문자열. `AZURE_STORAGE_ACCOUNT`보다 먼저 확인·사용됨
`AZURE_STORAGE_ACCOUNT`	예 (*참고)	Azure Storage 계정 이름
`AZURE_STORAGE_KEY`	아니요	계정 액세스 키. 익명 액세스는 `""` 지정

Azure 블록 크기와 동시성은 AZURE_BLOCK_SIZE(기본 41943040 = 40MB), AZURE_CONCURRENCY(기본 1)로 제어합니다.

파일시스템

로컬 파일시스템과 클라우드 제공자에서 동작하지만 단일 노드 배포만 지원하며 프로덕션에는 권장되지 않습니다. ENABLE_MODULES에 backup-filesystem을 추가하고 BACKUP_FILESYSTEM_PATH로 백업 루트 경로를 설정합니다.

ENABLE_MODULES=backup-filesystem,text2vec-cohere

API

REST API 문서는 Backups 섹션에서 볼 수 있습니다.

백업 생성

모듈이 활성화되고 구성이 제공되면 실행 중인 인스턴스에서 단일 요청으로 백업을 시작할 수 있습니다. 백업에 특정 컬렉션을 포함하거나 제외할 수 있으며, 아무것도 지정하지 않으면 기본으로 모든 컬렉션이 포함됩니다.

include와 exclude 옵션은 상호 배타적입니다. 둘 다 두거나 정확히 하나만 설정할 수 있어요. v1.36.0부터는 와일드카드 패턴으로 여러 컬렉션을 한 번에 매칭할 수 있으며, 대소문자를 구분합니다. *는 임의 문자 시퀀스에 매칭돼서 Article*는 Article, ArticleV1, ArticleV2에 매칭되지만 article, Publication에는 매칭되지 않아요.

config 객체의 주요 속성은 다음과 같습니다.

name	type	required	default	description
`CPUPercentage`	number	아니요	`50%`	CPU 코어 사용률을 1%~80%로 설정하는 정수
`ChunkSize`	number	아니요	-	폐기됨. 효과 없음. 값이 무시되며, 청크 크기는 `BACKUP_CHUNK_TARGET_SIZE` 환경 변수가 제어
`CompressionLevel`	string	아니요	`DefaultCompression`	사용할 압축 수준
`Path`	string	아니요	`""`	백업 위치를 직접 설정. Weaviate `v1.27.2` 도입
`incremental_base_backup_id`	string	아니요	`None`	증분 백업의 기반으로 쓸 이전 백업 ID. Weaviate `v1.37` 도입

result = client.backup.create(
    backup_id="my-very-first-backup",
    backend="filesystem",
    include_collections=["Article", "Publication"],
    wait_for_completion=True,
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # (선택)
)

print(result)

백업이 완료되기를 기다리는 동안에도 Weaviate는 계속 사용 가능합니다.

압축 수준

zstd 압축은 Weaviate v1.35.0, v1.34.1, v1.33.6, v1.32.18 이상에서만 사용할 수 있어요. 지원되면 ZstdDefaultCompression, ZstdBestSpeed, ZstdBestCompression 중 하나를 고릅니다. 그 외에는 표준 gzip 옵션 DefaultCompression, BestSpeed, BestCompression을 쓰고, NoCompression으로 명시적으로 압축을 끌 수도 있습니다.

비동기 상태 확인

모든 클라이언트 구현에는 "완료 대기(wait for completion)" 옵션이 있어 백업 상태를 백그라운드에서 폴링하고 완료된 뒤에만 반환합니다. 이 옵션을 false로 두면 백업 생성 상태 API로 직접 확인할 수 있습니다.

GET /v1/backups/{backend}/{backup_id}

result = client.backup.get_create_status(
    backup_id="my-very-first-backup",
    backend="filesystem",
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # 생성 시 비기본 위치를 썼다면 필수
)

print(result)

증분 백업

증분 백업은 이전 백업 이후 변경된 데이터만 저장해서 백업 크기와 시간을 줄입니다. 모든 파일을 다시 복사하는 대신, 증분 백업은 기본(베이스) 백업의 변경되지 않은 파일을 참조합니다. 결과적으로 백업이 훨씬 작아지고 빨라집니다.

증분 백업은 Weaviate v1.37에 도입됐습니다.

동작 방식

백업을 만들 때 Weaviate는 샤드의 파일을 청크로 묶습니다. 증분 백업에서는 각 파일을 기본 백업과 비교해, 변경되지 않은 파일은 다시 복사하는 대신 기본 백업을 가리키는 포인터로 저장합니다. 복원 시 Weaviate는 기본 백업에서 참조된 파일을 자동으로 가져와요.

기본 백업이 될 수도 있는 증분 백업을 이어서 체인을 만들 수도 있습니다. Weaviate는 전체 체인을 돌며 변경되지 않은 파일을 찾으므로, 체인의 모든 백업은 계속 사용 가능해야 합니다. 기준이 되는 기본 백업(그리고 체인의 중간 증분 백업)은 의존하는 증분 백업을 복원해야 하는 동안 계속 남아 있어야 해요. 자체 청크를 가질 만큼 큰 파일만 개별 참조가 되므로, 파일을 청크로 묶는 방식이 증분 백업 재사용량을 정합니다.

증분 백업 만들기

먼저 기본이 될 일반 백업을 만듭니다.

result = client.backup.create(
    backup_id="base-backup",
    backend="filesystem",
    include_collections=["Article", "Publication"],
    wait_for_completion=True,
)

print(result)

기본 백업의 ID와 함께 incremental_base_backup_id 파라미터를 넘겨 증분 백업을 만듭니다.

result = client.backup.create(
    backup_id="incremental-backup-1",
    backend="filesystem",
    include_collections=["Article", "Publication"],
    wait_for_completion=True,
    incremental_base_backup_id="base-backup",
)

print(result)

이전 증분 백업을 기반으로 사용하면 증분 백업을 체인할 수 있습니다. Weaviate는 변경되지 않은 파일을 찾기 위해 원래 전체 백업까지 체인을 거슬러 갑니다.

result = client.backup.create(
    backup_id="incremental-backup-2",
    backend="filesystem",
    include_collections=["Article", "Publication"],
    wait_for_completion=True,
    incremental_base_backup_id="incremental-backup-1",
)

print(result)

증분 백업 복원

증분 백업의 복원은 다른 백업 복원과 같습니다. Weaviate가 자동으로 체인을 해석하고 필요할 때 이전 백업의 파일을 가져옵니다.

result = client.backup.restore(
    backup_id="incremental-backup-2",
    backend="filesystem",
    wait_for_completion=True,
)

print(result)

백업 목록

백업 백엔드에 저장된 백업을 나열합니다. 목록은 각 백업의 상태, 담은 컬렉션, 크기, 그리고 증분 백업이면 기반이 된 백업을 보고합니다. 증분 백업 체인을 점검하고 체인이 의존하는 모든 백업이 남아 있는지 확인하는 방법이에요.

GET /v1/backups/{backend}

backend URL 파라미터는 backup- 접두사가 없는 모듈 이름(예: s3, gcs, filesystem)입니다. order 쿼리 파라미터로 정렬할 수 있고 기본은 desc(최신순)입니다.

응답의 주요 필드는 id, classes(담은 컬렉션), status(예: SUCCESS·FAILED), startedAt, completedAt, size(압축 전 GiB), incremental_base_backup_id입니다.

이름 하나, 서로 다른 두 뜻 — incremental_base_backup_id는 백업 API의 양쪽에 나타나며 서로 바꿔 쓸 수 없습니다. 생성 쪽에서는 입력(새 백업이 기반으로 삼을 백업)이고, 목록 쪽에서는 읽기 전용 출력(만들어진 백업이 기반으로 삼은 백업)이에요. 목록 API로 기본 백업을 고를 수는 없습니다.

또한 목록 쪽의 incremental_base_backup_id를 민감 정보로 취급해 root 사용자에게만 채워줍니다. HTTP 인증이 있는 백업 권한을 가진 호출자라도 root가 아니면 빈 값을 받아요. 백업 체인을 감사할 때 모든 항목이 비어 있으면, 연결하는 신원을 확인해 보세요.

복원 백업

소스와 대상 간 노드의 이름과 수가 같기만 하면 백업은 어떤 머신에도 복원할 수 있습니다. 백업이 같은 인스턴스에서 만들어질 필요는 없어요.

백업 생성과 마찬가지로 include와 exclude는 상호 배타적이며, 이번에는 백업에 담긴 컬렉션 기준으로 동작합니다. 복원 시점에 이 인스턴스에 어떤 컬렉션이 이미 존재하면 복원은 실패합니다.

v1.23.12 이하 백업 복원 주의 — v1.23.13 미만 버전은 백업 데이터를 잘못 저장할 수 있는 버그가 있었어요. 복원 전에 1.23.13 이상으로 업데이트하세요.

복원 config 객체 속성:

name	type	required	default	description
`cpuPercentage`	number	아니요	`50%`	CPU 코어 사용률 1%~80% 설정
`Path`	string	커스텀 경로로 생성됐다면 필수	`""`	백업 위치를 직접 지정. Weaviate `v1.27.2` 도입
`rolesOptions`	string	아니요	`"noRestore"`	RBAC 역할·권한을 백업·복원할지. `"noRestore"` 또는 `"all"`. Weaviate `v1.32.0` 도입
`usersOptions`	string	아니요	`"noRestore"`	RBAC 사용자를 백업할지. `"noRestore"` 또는 `"all"`. Weaviate `v1.32.0` 도입

result = client.backup.restore(
    backup_id="my-very-first-backup",
    backend="filesystem",
    exclude_collections="Article",
    wait_for_completion=True,
    roles_restore="all",
    users_restore="all",
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # 생성 시 비기본 위치를 썼다면 필수
)

print(result)

비동기 상태 확인

복원도 "완료 대기" 옵션으로 상태를 백그라운드 폴링합니다. false로 두면 백업 복원 상태 API로 직접 확인하고, 응답의 "status" 필드가 SUCCESS면 복원 완료, FAILED면 추가 오류가 함께 제공됩니다.

result = client.backup.get_restore_status(
    backup_id="my-very-first-backup",
    backend="filesystem",
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # 생성 시 비기본 위치를 썼다면 필수
)

print(result)

백업 취소

불필요한 백업을 취소할 수 있습니다.

result = client.backup.cancel(
    backup_id="some-unwanted-backup",
    backend="filesystem",
    backup_location=BackupLocation.FileSystem(path="/tmp/weaviate-backups"),  # 생성 시 비기본 위치를 썼다면 필수
)

print(result)

기술적 고려사항

백업 중 읽기·쓰기 요청 — 백업이 실행되는 동안에도 Weaviate는 읽기·쓰기 요청을 계속 처리합니다.
백업 API의 비동기 특성 — 백업은 비동기로 실행됩니다.
청킹과 파일 분할 — 백업 파일은 청크 단위로 나뉘며, 이 동작은 BACKUP_CHUNK_TARGET_SIZE 환경 변수 등으로 제어합니다.
스토리지 접근 확인 건너뛰기 — 최소 권한 자격증명(쓰기는 되지만 삭제는 안 되는)을 쓰면 BACKUP_SKIP_ACCESS_CHECK로 백업 전 접근 프로브를 건너뜁니다.

다른 용도

다른 환경으로 마이그레이션

백업은 새 환경으로 데이터를 이전하는 쉬운 경로입니다. 백업을 생성하고 대상 인스턴스에서 복원하면 됩니다.

백업

백업 (Backups)

백업 퀵스타트

1. Weaviate 구성

2. 백업 시작

스토리지 제공자 구성

S3 (AWS 또는 S3 호환)

GCS (Google Cloud Storage)

Azure Storage

파일시스템

API

백업 생성

압축 수준

비동기 상태 확인

증분 백업

동작 방식

증분 백업 만들기

증분 백업 복원

백업 목록

복원 백업

비동기 상태 확인

백업 취소

기술적 고려사항

다른 용도

다른 환경으로 마이그레이션

더 알아보기 (Learn more)