손상된 Keeper 스냅샷에서 복구하는 방법

손상되었거나 비정상적인 ClickHouse Keeper 스냅샷은 메타데이터 불일치, 테이블의 읽기 전용 상태, 리소스 고갈, 백업 실패와 같은 심각한 시스템 불안정을 초래할 수 있습니다. 이 문서에서는 다음 내용을 다룹니다.

스냅샷이 무엇이고 어디에서 찾을 수 있는지
문제가 어떻게 나타나는지
가능한 복구 전략과 각 전략의 의미

Keeper 스냅샷 개요

스냅샷이란 무엇입니까?

스냅샷은 특정 시점의 Keeper 내부 데이터(예: 클러스터 관련 메타데이터, 테이블 조정 경로, 구성)를 직렬화한 상태입니다. 스냅샷은 클러스터 내 Keeper 노드의 재동기화, 장애 발생 시 메타데이터 복구, 그리고 정상 상태로 확인된 Keeper 상태에 의존하는 시작 또는 재시작 과정에 매우 중요합니다.

스냅샷은 어디에서 찾을 수 있습니까?

스냅샷은 Keeper 노드의 로컬 파일 시스템에 파일 형태로 저장됩니다. 기본적으로 /var/lib/clickhouse/coordination/snapshots/에 저장되며, keeper_server.xml 파일의 snapshot_storage_path에 지정한 사용자 지정 경로에 저장될 수도 있습니다. 스냅샷 이름은 증가하는 순서로 지정되며(예: snapshot.23), 최신 스냅샷일수록 숫자가 더 큽니다. 멀티 노드 클러스터에서는 각 Keeper 노드가 자체 스냅샷 디렉터리를 가집니다.

복구를 위해서는 노드 간 스냅샷의 일관성이 매우 중요합니다.

손상된 Keeper 스냅샷의 주요 증상과 징후

아래 표는 손상된 Keeper 스냅샷에서 흔히 나타나는 몇 가지 주요 증상과 징후를 보여줍니다:

범주	문제 유형	확인할 사항
운영 문제	읽기 전용 모드	테이블이 예기치 않게 읽기 전용 모드로 전환됨
	쿼리 실패	`Coordination::Exception` 오류와 함께 쿼리 실패가 지속적으로 발생함
메타데이터 손상	오래된 메타데이터	삭제된 테이블이 반영되지 않음. 오래된 메타데이터 때문에 작업이 실패함
리소스 과부하	시스템 리소스 고갈	Keeper 노드가 CPU, 메모리 또는 디스크 공간을 과도하게 사용함. 다운타임이 발생할 수 있음
	디스크 공간 부족	스냅샷 생성 중 디스크 공간이 부족해짐
Backup 및 복원	Backup 실패	누락되었거나 일관되지 않은 Keeper 메타데이터로 인해 Backup이 실패함
스냅샷 생성/전송	Keeper 크래시	스냅샷 생성 도중 Keeper 크래시 발생(“SEGFAULT” 오류 확인)
	스냅샷 전송 손상	레플리카 간 스냅샷 전송 중 손상 발생
	경쟁 상태	로그 컴팩션 중 경쟁 상태 발생 - 백그라운드 commit 스레드가 삭제된 로그에 접근함
	네트워크 동기화	리더에서 팔로워로 스냅샷이 동기화되지 않게 하는 네트워크 문제

로그 징후: 스냅샷 손상을 진단하기 전에 Keeper 로그에서 특정 오류 패턴을 확인하십시오:

로그 유형	확인할 사항
스냅샷 손상 오류	• `Aborting because of failure to load from latest snapshot with index` • `Failure to load from latest snapshot with index {}: {}. Manual intervention is necessary for recovery` • `Failed to preprocess stored log at index {}, aborting to avoid inconsistent state` • 시작 시 스냅샷 serialization/loading 실패
기타 Keeper 문제	• `Coordination::Exception` • `Zookeeper::Session Timeout` • 동기화 또는 리더 선출 문제 • 로그 컴팩션 경쟁 상태

손상된 Keeper 스냅샷에서 복구하기

파일을 건드리기 전에 항상 다음 사항을 수행하십시오:

추가 손상을 방지하기 위해 모든 Keeper 노드를 중지합니다
전체 coordination 디렉터리를 안전한 위치에 복사해 모두 백업합니다
클러스터 정족수(quorum)를 확인하여 최소 1개의 노드에 정상 데이터가 있는지 검증합니다

1. 기존 Backup에서 복원

다음에 해당하면 이 절차를 따르십시오:

Keeper 메타데이터(metadata) 또는 스냅샷 손상으로 인해 현재 데이터를 복구할 수 없습니다.
정상 상태로 확인된 Keeper 상태가 포함된 Backup이 있습니다.

기존 Backup을 복원하려면 아래 단계를 따르십시오:

메타데이터 일관성을 기준으로 가장 최신 Backup을 찾아 검증합니다.
ClickHouse 및 Keeper 서비스를 종료합니다.
Backup 디렉터리의 스냅샷 및 로그로 손상된 항목을 대체합니다.
Keeper 클러스터를 다시 시작하고 메타데이터 동기화가 정상인지 검증합니다.

정기적으로 Backup하십시오Backup이 오래된 경우 최근 메타데이터 변경 사항이 손실될 수 있습니다. 따라서 정기적으로 Backup할 것을 권장합니다.

2. 이전 스냅샷으로 롤백

다음과 같은 경우 이 절차를 따르십시오.

최근 스냅샷이 손상되었지만, 이전 스냅샷은 여전히 사용할 수 있습니다.
일관된 복구에 필요한 증분 로그가 온전하게 유지되어 있습니다.

이전 스냅샷으로 롤백하려면 아래 단계를 따르십시오.

Keeper 디렉터리에서 유효한 이전 스냅샷(예: snapshot.19)을 찾아 선택합니다.
더 최신 스냅샷과 로그를 제거합니다.
Keeper를 다시 시작하여 로그를 재생하고 메타데이터 상태를 복구합니다.

메타데이터 비동기화 위험스냅샷과 로그가 없거나 불완전하면 메타데이터가 비동기화될 위험이 있습니다.

3. `SYSTEM RESTORE REPLICA`를 사용해 메타데이터 복원

다음과 같은 경우 이 절차를 따르십시오.

Keeper 메타데이터가 유실되었거나 손상되었지만 테이블 데이터는 여전히 디스크에 남아 있는 경우
ZooKeeper/Keeper 메타데이터가 없어 테이블이 읽기 전용 모드로 전환된 경우
로컬에서 사용 가능한 데이터 파트를 기반으로 Keeper 메타데이터를 다시 만들어야 하는 경우

메타데이터를 복원하려면 아래 단계를 따르십시오.

구성의 <path>로 설정된 clickHouse-server 데이터 경로에 테이블 데이터가 로컬에 존재하는지 확인하십시오. (기본값: /var/lib/clickhouse/data/)
영향을 받는 각 테이블에 대해 다음을 실행하십시오.

SYSTEM RESTART REPLICA [db.]table_name;
SYSTEM RESTORE REPLICA [db.]table_name;

데이터베이스 수준 복구를 수행하는 경우(Replicated 데이터베이스 엔진 사용 시):

SYSTEM RESTORE DATABASE REPLICA db_name;

동기화가 완료될 때까지 기다리십시오:

SYSTEM SYNC REPLICA [db.]table_name;

system.replicas에서 is_readonly = 0인지 확인하고 system.detached_parts를 모니터링하여 복구를 검증합니다

작동 방식SYSTEM RESTORE REPLICA는 기존의 모든 파트를 분리한 뒤 Keeper에 메타데이터를 다시 생성한 다음(새 빈 테이블인 것처럼), 모든 파트를 다시 연결합니다. 이렇게 하면 네트워크를 통해 데이터를 다시 다운로드하지 않아도 됩니다.

필수 조건이 방법은 로컬 데이터 파트가 온전한 경우에만 작동합니다. 데이터도 손상된 경우에는 대신 전략 #5(클러스터 재구축)를 사용하십시오.

4. Keeper에서 레플리카 메타데이터 삭제 및 재생성

다음과 같은 경우 이 절차를 따르십시오:

오류가 클러스터의 단일 레플리카에서 발생했고, Keeper의 메타데이터가 손상되었거나 일관되지 않은 경우
“Part XXXXX intersects previous part YYYYY”와 같은 오류가 발생하는 경우
로컬 데이터는 유지하면서 레플리카의 Keeper 메타데이터를 완전히 재설정해야 하는 경우

메타데이터를 삭제하고 다시 생성하려면 아래 단계를 따르십시오:

영향을 받은 레플리카에서 테이블을 detach합니다:

DETACH TABLE [db.]table_name;

Keeper에서 레플리카의 메타데이터를 제거합니다(임의의 레플리카에서 실행):

SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/{shard}/table_name';

올바른 ZooKeeper 경로를 찾으려면 다음과 같이 하십시오:

SELECT zookeeper_path, replica_name FROM system.replicas WHERE table = 'table_name';

테이블을 다시 ATTACH합니다(읽기 전용 모드로 전환됩니다):

ATTACH TABLE [db.]table_name;

레플리카 메타데이터를 복원합니다:

SYSTEM RESTORE REPLICA [db.]table_name;

다른 레플리카와 동기화:

SYSTEM SYNC REPLICA [db.]table_name;

복구 후 모든 레플리카에서 system.detached_parts를 확인합니다

영향을 받은 모든 레플리카에서 실행하십시오손상이 여러 레플리카에 영향을 미친 경우, 각 레플리카에서 이 단계를 순차적으로 반복하십시오.

전체 데이터베이스에 적용하는 경우복제된 데이터베이스를 사용하는 경우에는 대신 SYSTEM DROP REPLICA ... FROM DATABASE db_name을 사용할 수 있습니다.

대안: force_restore_data 플래그 사용 서버 시작 시 모든 복제된 테이블을 자동으로 복구하려면 다음을 수행하십시오.

ClickHouse 서버를 중지합니다
복구 플래그를 생성합니다:

sudo -u clickhouse touch /var/lib/clickhouse/flags/force_restore_data

ClickHouse 서버를 시작합니다
서버가 자동으로 플래그를 삭제하고 모든 복제된 테이블을 복원합니다
로그를 확인하여 복구 진행 상황을 모니터링합니다

이 방법은 여러 테이블을 동시에 복원해야 할 때 유용합니다.

5. Keeper 클러스터 재구축

다음과 같은 경우 이 절차를 따르십시오.

복구에 사용할 수 있는 유효한 스냅샷, 로그 또는 백업이 없습니다.
전체 Keeper 클러스터와 해당 메타데이터를 다시 생성해야 합니다.

아래 단계에 따라 Keeper 클러스터를 재구축하십시오.

ClickHouse 클러스터와 Keeper 클러스터를 완전히 중지합니다.
스냅샷 및 로그 디렉터리를 정리하여 각 Keeper 노드를 초기화합니다.
Keeper 노드 하나를 리더로 초기화한 다음, 다른 노드를 순차적으로 추가합니다.
외부 기록이 있는 경우 메타데이터를 다시 가져옵니다.

시간이 많이 소요되는 절차이 절차는 시간이 많이 소요되며 장시간 서비스 중단이 발생할 위험이 있습니다. 전체 데이터를 다시 구성해야 합니다.

​Keeper 스냅샷 개요

​스냅샷이란 무엇입니까?

​스냅샷은 어디에서 찾을 수 있습니까?

​손상된 Keeper 스냅샷의 주요 증상과 징후

​손상된 Keeper 스냅샷에서 복구하기

​1. 기존 Backup에서 복원

​2. 이전 스냅샷으로 롤백

​3. SYSTEM RESTORE REPLICA를 사용해 메타데이터 복원

​4. Keeper에서 레플리카 메타데이터 삭제 및 재생성

​5. Keeper 클러스터 재구축

Keeper 스냅샷 개요

스냅샷이란 무엇입니까?

스냅샷은 어디에서 찾을 수 있습니까?

손상된 Keeper 스냅샷의 주요 증상과 징후

손상된 Keeper 스냅샷에서 복구하기

1. 기존 Backup에서 복원

2. 이전 스냅샷으로 롤백

3. `SYSTEM RESTORE REPLICA`를 사용해 메타데이터 복원

4. Keeper에서 레플리카 메타데이터 삭제 및 재생성

5. Keeper 클러스터 재구축