백업 및 복구
백업 및 복구
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
Loom 백업은 ClickHouse 백업이며, 카탈로그 행이 문서 버킷의 객체를 참조하는 동안에는 문서 버킷도 포함하고, Postgres가 메모리 상태의 기준 저장소인 구성에서는 Postgres 백업도 포함합니다.
ClickHouse는 원본의 카탈로그(loom.document_blobs, 기본 저장소에서는 원본의 바이트도 포함), 토큰 서명 키(loom.signing_keys), 관리자 런타임 오버라이드(loom.runtime_overrides)를 보관합니다. 다음 항목은 ClickHouse 밖에 있습니다.
LOOM_JWT_SECRET, 루트 시크릿입니다. 저장된 자격 증명과 서명 키를 봉인하므로, 이 값 없이 복원한 백업은 둘 중 어느 것도 열 수 없습니다. env 설정과 함께 보관하세요.var/code_repos아래에 있는 코드 인덱스의 git 미러입니다. ClickHouse에 기록된 원격 저장소의 캐시입니다. 미러가 없는 호스트는 다시 클론합니다.LOOM_DOCUMENT_S3_BUCKET,LOOM_DOCUMENT_OBJECT_STORE=s3인 동안 기록된 원본의 바이트를 보관합니다(다시 전환해도 그대로 남아 있습니다). ClickHouse는 각 객체의 위치를 보관합니다.
백업 방식 선택
| 방법 | 대상 | 일관된 스냅샷 | 용도 |
|---|---|---|---|
| ClickHouse Cloud 백업 | 서비스의 모든 테이블 | 예 (서비스 단위) | Cloud에서의 재해 복구 |
BACKUP DATABASE loom TO Disk(...) / S3(...), 또는 clickhouse-backup |
모든 loom.* 테이블 |
예 | 자체 관리형 OSS에서의 재해 복구 |
BACKUP DATABASE loom_telemetry TO ... |
SLI 롤업 (loom_telemetry.sli_minute) |
예 | 원장을 다시 접어(refold) 복구할 수 있는 31일을 넘어 SLO 이력을 보관 |
dev/backup_loom.py 이식 가능한 덤프 |
모든 Loom 테이블 (아래 참조) | 테이블 단위, 테이블 간에는 아님 | 배포, 조직 또는 네임스페이스 이전 (원본이 버킷에 있는 경우: 아래), 콜드 복사본 |
namespace.snapshot |
하나의 네임스페이스의 큐레이션된 메모리, 타입, 권한, 감사 로그 말미 | 한 번의 호출 | API를 통한 네임스페이스 복사 또는 동결 |
이식 가능한 덤프
dev/backup_loom.py는 테이블마다 JSONEachRow 파일 하나를 쓰고, 이어서 manifest.json을 씁니다. 매니페스트에는 원본 데이터베이스와, 테이블별로 파일, 행 수, 바이트 크기, SHA-256, CREATE 문(또는 덤프를 중단시킨 오류)이 담깁니다. 종료 코드 1은 테이블 하나가 실패했다는 뜻이고(complete: false), 종료 코드 2는 인자가 잘못되었거나 ClickHouse 대상이 없거나 출력 디렉터리에 이미 백업이 있다는 뜻입니다.
이 도구는 system.tables에서 읽은 데이터베이스의 모든 MergeTree 계열 테이블을 덤프합니다. 마이그레이션 러너의 _ 접두사 테이블, .inner 테이블, KeeperMap 리스(데이터가 아니라 실시간 조정 정보), 그리고 loom migrate가 만드는 뷰는 제외합니다. 매니페스트의 backup_version은 3입니다. --org는 org 컬럼이 있는 모든 테이블을 필터링하고, 컬럼이 없는 테이블(idempotency, signing_keys 등)은 건너뜁니다. 이런 테이블에는 모든 org의 행이 들어 있습니다.
dev/restore_loom.py는 모든 파일을 매니페스트와 대조해 검증하고(크기, 행 수, SHA-256), 계획을 출력합니다. 그다음 기록된 CREATE 문으로 대상 데이터베이스와 없는 테이블을 만들고, 각 파일을 해당 테이블의 스테이징 복사본에 로드한 뒤 스테이징된 파트를 테이블에 attach합니다. attach는 materialized view를 실행하지 않으므로, 복원된 행이 백업이 함께 복원하는 테이블에 다시 복사되지 않습니다(그렇지 않으면 memory_versions에 모든 버전이 두 번 들어갑니다). 뷰는 라이브 데이터베이스에 대한 쓰기에서는 계속 동작합니다. loom migrate가 준비한 데이터베이스(뷰가 있음)나 임시 데이터베이스(기록된 DDL로 테이블 생성)로 복원하십시오. 코드화된 벡터 테이블(기록된 CREATE에 Quantized(가 있음)이 들어 있는 백업은, 대상의 코덱 설정을 읽을 수 없거나 enable_quantized_codec을 켤 수 없는 경우 --dry-run을 포함해 아무것도 쓰기 전에 거부됩니다. 켤 수 있는 경우에도 allow_suspicious_codecs를 켤 수 없으면 해당 테이블은 Quantized 뒤의 일반 코덱을 잃습니다
(제한된 설정). insert는 optimize_on_insert = 0으로 실행되므로, ReplacingMergeTree 키가 중복된 행을 포함해 덤프된 모든 행이 그대로 들어가고, 테이블은 자체 머지에서 이를 합칩니다.
각 테이블은 attach 전에 … attaching <table>을, attach 후에 ✓를 출력합니다. 실행이 중간에 끊기면 마지막 줄이 그 시점에 처리 중이던 테이블을 알려 줍니다. --into-nonempty로 다시 실행하기 전에 해당 테이블의 행 수를 확인하십시오. 그대로 다시 실행하면 그 테이블에 행이 한 번 더 추가됩니다.
매니페스트에는 insert로 실행되는 각 materialized view의 소스 테이블과 대상 테이블이 기록됩니다. attach는 뷰를 실행하지 않으므로, 복원은 뷰의 한쪽 끝만 포함하는 선택을 거부합니다. memory_versions(및 memory_code_link_queue) 없이 memory만 복원하면 memory.history, memory.redact, namespace.rollback이 복원된 버전을 보지 못하게 되고, code_chunks 없이 code_term_freq만 복원하면 코드를 다시 수집할 때 그 테이블이 다시 채워집니다. documents와 document_blobs를 잇는 뷰는 없지만, 복원은 한쪽만 선택하는 것도 거부합니다. 원본이 없는 문서는 모든 다운로드에 410으로 응답하고, 문서가 없는 원본은 원본 정리 작업이 삭제하는 대상입니다. 두 도구 모두 documents를 다른 어떤 테이블보다 먼저 처리하므로, --into-live로 워커가 실행 중이어도 정리 작업이 그 원본을 가리키는 문서보다 먼저 복원된 원본 행을 보는 일은 없습니다(버킷의 객체는 아래를 참고하십시오). 양쪽 끝을 모두 선택하거나, 대상에 이미 그 행이 있다면 --allow-view-split을 전달하십시오. dev/backup_loom.py --exclude t1,t2는 패스가 다시 만드는 테이블과, 뷰가 그 테이블에서 채우는 모든 테이블을 함께 제외합니다(code_chunks를 제외하면 code_term_freq와 code_doc_stats도 제외됩니다). restore_loom.py --exclude는 백업의 일부 테이블을 복원에서 제외합니다.
문서 원본(document_blobs)은 바이너리입니다. 덤프는 이를 원시 바이트로 쓰고 output_format_json_validate_utf8 = 0을 직접 설정하므로, UTF-8을 검증하는 프로필이 있어도 원본이 대체되지 않습니다. 바이너리 원본은 덤프에서 원래 크기의 약 1.6배를 차지합니다.
LOOM_DOCUMENT_OBJECT_STORE=s3로 기록된 행에는 객체의 위치만 들어 있고, 바이트는 버킷에 있습니다. 버킷은 자체 버저닝이나 복제로 백업하십시오. 복원할 때는 같은 이름의 버킷으로(각 행에 버킷 이름이 있습니다), 그 객체를 가리키는 ClickHouse 백업 이후에 복원하거나, 둘 다 복원될 때까지 LOOM_DOCUMENT_BLOB_GC_ENABLED=false로 두십시오. 복원된 객체가 이전 수정 시각을 유지할 수 있고(복원 방식에 따라 다릅니다), 그러면 아직 document_blobs 행이 들어오지 않은 객체를 버킷 순회가 삭제하기 때문입니다.
버저닝된 버킷은 삭제된 모든 객체를 noncurrent 버전으로 보관하고, 복제는 기본적으로 삭제를 복제하지 않습니다. 따라서 지워지거나 정리된 원본은 수명 주기 규칙(NoncurrentVersionExpiration, 복제본의 만료 포함)이 제거할 때까지 버킷(또는 그 복제본)에 남습니다. 이 규칙의 기간이, 행에 대해 ClickHouse 백업의 보존 기간이 하는 역할처럼, 지워진 원본을 여전히 복원할 수 있는 기간입니다.
덤프에는 이런 행의 원본 바이트가 들어 있지 않으므로 옮길 수 없습니다. 다른 배포로 복원된 행은 여전히 원본 버킷을 가리키고, 지우기는 버킷과 접두사 밖이라며 이를 거부하며, 원본의 행이 사라지면 원본의 정리 작업이 그 객체를 삭제합니다. 또한 원본의 버킷과 접두사를 가리키도록 설정된 대상은 대상 카탈로그가 가리키지 않는 원본의 모든 객체를 정리해 버립니다. 문서를 대상에 다시 업로드해서 옮기거나, 원본을 중지한 상태에서 배포 전체를 옮기십시오.
스테이징 복사본은 해당 테이블의 엔진을 그대로 반복합니다. 단, Replicated가 아닌 데이터베이스에 있는 복제 엔진은 같은 매개변수의 로컬 형태가 됩니다(복사본이 테이블의 Keeper 경로를 다시 차지하는 일을 막기 위해서입니다). 이후 attach가 파트를 복제합니다.
복원이 만드는 복제 테이블은 백업 자체의 데이터베이스에서만, 그리고 그 경로로 복제하는 것이 더 이상 없을 때에만 기록된 Keeper 경로를 유지합니다(라이브 복제본이 남아 있으면 거부합니다). 다른 데이터베이스에서는 독립적인 경로를 받습니다. 서버의 default_replica_path 아래 새 UUID를 쓰거나, Replicated 데이터베이스에서는 그 데이터베이스 자체의 경로를 씁니다. 그 기본값에 필요한 매크로가 서버에 없으면 거부합니다.
각 실행은 스테이징 테이블 이름을 _restore_<run id>_<table>로 정하고 실행 ID를 가장 먼저 출력하며, 각 실행은 자신의 테이블만 삭제합니다. 한 데이터베이스로의 복원(예: org 두 개)은 한 번에 하나씩 실행됩니다. 실행은 default._loom_restore_lock_<db>를 점유하고(다른 실행의 점유를 최대 5분 기다립니다), 대상을 다시 확인한 뒤, 이전 실행이 남긴 상태에 아래의 거부 규칙을 적용합니다. 그래서 같은 범위를 두 번째로 복원하면 첫 번째 행에 합쳐질 행을 attach하는 대신 거부합니다. 점유는 default의 테이블이므로 자체 관리 클러스터에서는 같은 서버를 거치는 실행끼리만 순서가 정해집니다. 모든 복원을 한 서버로 향하게 하십시오. 비정상 종료한 실행은 스테이징 테이블과 점유를 남깁니다. 그 실행의 프로세스가 남아 있지 않다면 restore_loom.py --database <db> --drop-staging <run id>로 삭제하십시오.
insert 단계 전에는 아무것도 쓰지 않으며, --dry-run은 계획까지만 보여 주고 멈춥니다. 다음은 거부됩니다.
--into-live없이 라이브 데이터베이스(loom또는 서버 설정이 지정한 데이터베이스)로 복원하는 경우--into-nonempty없이, 백업 범위에서 이미 행이 있는 테이블로 복원하는 경우. insert는 행을 추가하므로 일반 MergeTree 테이블(audit_log,agent_events)에는 모든 행이 두 번 들어갑니다.
두 도구 모두 서버와 같은 방식으로 ClickHouse 대상을 결정하며(환경 변수나 .env의 LOOM_CH_*, 각각 --host, --port, --user, --database, --secure로 재정의 가능), 호스트가 지정되지 않으면 실행을 거부하고, 비밀번호는 LOOM_CH_PASSWORD에서만 읽습니다.
python dev/backup_loom.py --out-dir ./backups/$(date +%F) [--org acme] [--tables memory,namespaces]
python dev/restore_loom.py --in-dir ./backups/<date> --database loom_restore --dry-run
python dev/restore_loom.py --in-dir ./backups/<date> --database loom_restore --skip-idempotency
python dev/restore_loom.py --in-dir ./backups/<date> --into-live \
--tables memory,memory_versions,memory_code_link_queue # one end of a view needs the other
./scripts/ops/backup_drill.sh [--full-restore] # round-trip check into a scratch database
scripts/ops/backup_drill.sh는 라이브 데이터베이스를 임시 디렉터리에 덤프하고 매니페스트를 행 수 스냅샷과 대조합니다. --full-restore를 주면 임시 데이터베이스 <db>_drill로 복원하고, 모든 테이블의 행 수를 비교한 뒤, 종료할 때 임시 데이터베이스를 삭제합니다. 같은 키의 행을 합치는 테이블(ReplacingMergeTree, AggregatingMergeTree 등)은 attach 직후 임시 데이터베이스에서 머지될 수 있습니다. 머지가 실행된 뒤라면 행이 더 적어도 경고이고, 그렇지 않으면 실패입니다. 이 스크립트는 라이브 데이터베이스를 읽기만 합니다. 드릴은 일정에 따라 실행하십시오.
덤프는 테이블 단위이며 테이블 간 스냅샷이 아닙니다. 클러스터 간에 데이터를 옮기는 용도로 사용하고, 재해 복구에는 사용하지 마십시오.
복원 후 감사 로그 검증
python dev/verify_audit_chain.py [--org X] [--ts-since YYYY-MM-DD] [--json]은 모든 audit_log 행의 콘텐츠 해시를 다시 계산하며, 불일치가 있으면 1로, 검증을 수행하지 못했을 때(잘못된 인수, 대상 없음, 쿼리 실패)는 2로, 그 외에는 0으로 종료합니다(행이 없으면 통과로 처리합니다). 불일치 보고서는 해당 행을 파티션, 타임스탬프, 요청 ID로 식별하며, 행의 actor, subject, 네임스페이스는 절대 표시하지 않습니다. audit_verifier 워커는 동일한 행별 검사를 일정에 따라 실행합니다. 이 검사는 행 간 해시 체인이 아니라 행별 변조 탐지입니다. 매시간 생성되는 체크포인트는 별도로 체인으로 연결됩니다(감사).
네임스페이스 내부의 변경 되돌리기
이 operation들은 ClickHouse 복원 없이 잘못된 쓰기, 오작동하는 에이전트, 잘못된 import를 되돌립니다. 각 operation은 하나의 네임스페이스에 한정됩니다. namespace.snapshot, namespace.restore, namespace.rollback은 MCP all 목록에 없습니다. 이름으로 직접 호출하거나 HTTP로 호출하거나, 대시보드의 Health → Repairs 탭을 사용하세요. 네임스페이스 관리자는 이 탭에서 스냅샷을 다운로드하고, 복원하고, 롤백할 수 있습니다.
| 작업 | 역할 | 동작 |
|---|---|---|
memory.restore |
WRITER |
tombstone 처리된 키 하나를 되살립니다 |
namespace.snapshot |
ADMIN |
네임스페이스의 메모리, 타입, 권한 부여, 감사 로그 말미(include_audit_tail_n, 기본값 1000)를 JSON 페이로드로 고정합니다. include_embeddings=false(기본값)이면 대상이 자체 모델로 다시 임베딩할 수 있습니다 |
namespace.restore |
새 대상은 VIEWER, 기존 대상은 ADMIN |
스냅샷 페이로드를 target_namespace에 기록합니다(선택적으로 rebind_agent). snapshot_id 기준으로 멱등입니다. 행은 version, content_sha256, 증명 컬럼을 유지하므로 verified_by가 그대로 남습니다. 컬럼에 담을 수 없는 페이로드 값(UUID가 아닌 메모리 id)은 422로 거부됩니다. 컬렉션은 거부됩니다. 컬렉션의 스냅샷은 일반 네임스페이스로 복원합니다 |
namespace.rollback |
ADMIN |
모든 메모리 head(또는 memory_keys)를 as_of 시점의 버전으로 되돌립니다. 이전 버전을 새 head로 복구하고, 그 이후에 생성된 키는 tombstone 처리합니다. 기본은 dry run입니다(dry_run=false로 적용). 호출당 최대 max_keys개까지 처리하며(truncated는 다시 호출해야 할 때를 알려 줍니다) |
Postgres authority에서는 복원 시, 삭제(erasure)로 대상에서 제거된 메모리 중 삭제 증거가 남아 있는 것은 제외하고 counts.erased_skipped에 집계합니다. 이 증거는 삭제가 해당 메모리를 제거한 네임스페이스만 다룹니다. 따라서 삭제 이전의 스냅샷을 다른 곳에 복원하면 삭제된 메모리가 되살아납니다. 이런 복원 후에는 같은 삭제(그 scope)를 다시 실행하세요.
namespace.rollback과 memory.history는 loom.memory_versions를 읽습니다. 이것은 loom.memory에 대한 모든 insert를 기록하는 append-only 미러입니다(병합 시 대체된 버전은 loom.memory 자체에서 제거됩니다). 롤백은 다음과 같이 동작합니다.
- 네임스페이스의 이력보다 오래되었거나 미래인
as_of는 거부합니다. - 하드 삭제된 키는 건너뜁니다(
skipped_no_head). - 복구된 head의 재임베딩은 임베딩 워커에 맡깁니다.
AS_OF=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) # GNU date; the instant before the bad writes
curl -s -XPOST http://localhost:7777/v1/namespace.rollback -H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"org":"acme","namespace":"support","as_of":"'"$AS_OF"'"}' | jq '{dry_run, reinstate, remove, truncated}'
Postgres가 권위 저장소일 때
LOOM_STORAGE_AUTHORITY=postgres일 때 라이브 메모리, 그 리비전 저널, 지식 헤드, 수집 작업, 데이터셋 카탈로그는 Postgres에 있으며(권위 저장소), 배포 하나에 백업할 저장소는 Postgres와 ClickHouse 두 개입니다.
| 저장소 | 단독으로 보유하는 것 | RPO | 백업 방식 |
|---|---|---|---|
| Postgres | 모든 메모리 헤드와 리비전, 지식 헤드, 수집 작업, 데이터셋 카탈로그, 멱등성 응답 | 동기식 스탠바이로 장애 조치(failover)해도 확인된 쓰기는 0; 특정 시점 복구(point-in-time restore)는 그 시점 이후의 데이터를 잃음 | HA 관리자 또는 서비스의 베이스 백업과 WAL 아카이브 |
| ClickHouse | 검색 문서와 벡터, 지식 문서와 긴 메모리 값의 청크, Postgres가 유지하는 범위를 넘어선 기록, 분석, 트레이스, 감사 행 | ClickHouse만 보유한 데이터는 마지막 백업 이후 경과 시간; Postgres가 보유한 메모리 리비전과 지식 문서는 다시 게시되지만 그 청크와 데이터셋의 행은 그렇지 않음: loom reconcile은 다시 청크로 나눌 각 지식 소스를, 20개를 넘으면 그 네임스페이스(loom rechunk)를, 그리고 다시 수집할 각 소스를 알려주며, 긴 메모리 값은 다시 설정될 때까지 발췌문으로 검색됨 |
위의 방법들 |
복구에 걸리는 시간은 저장소 자체의 복구 시간에 loom reconcile을 더한 것이며, 이 명령은 복원된 저장소가 다른 저장소의 기록에서 잃은 것을 다시 실행합니다.
저장소 하나 복구하기
LOOM_PG_PAYLOAD_CLEAR_ENABLED가 켜진 상태에서 ClickHouse를 복구하기 전에, 페이로드 정리를 중지하고 Postgres 저널과 ClickHouse 복구에 설명된 대로 백업을 선택하십시오. 정리 패스가 한 번 실행된 뒤에는 010_revision_delivered_at.sql을 포함한 빌드로 3단계의 loom reconcile을 실행하고, 4단계에서도 그 빌드로 배포를 시작하십시오(롤링 업그레이드 규칙 43). 그다음 진행합니다.
- 배포의 모든 서버와 워커를 중지합니다.
- 백업에서 저장소를 복구하고, 백업 자체의 메타데이터에서 백업 시각을 기록해 둡니다(ClickHouse는
BACKUP의 시작 시각, Postgres는 복구 목표 시점). loom reconcile --restored clickhouse --point <time>(또는--restored postgres)을 실행하면 다시 실행할 내용이 출력됩니다. 그다음 같은 명령을--apply와 함께 실행합니다.- 배포를 시작합니다.
- ClickHouse 복구 후에는 reconcile이 출력한 각
loom rechunk를 실행하고, “to ingest again” 아래에 나열된 각 소스를 다시 업로드하고 수집합니다. 지식 문서의 청크와 데이터셋의 행은 ClickHouse에만 있기 때문입니다.
셀의 Postgres에는 셀이 테넌시 행을 가지지 않은 조직의 행을 거부하는 org 트리거와, 스스로 표시하지 않는 세션의 테넌시 행을 거부하는 loom.tenancy 가드가 있습니다. 셀로의 논리적 복구는 이런 세션에 해당합니다. 셀의 모든 프로세스를 중지한 상태에서 마커를 붙여 한 번의 명령으로 PGOPTIONS='-c loom.tenancy_checked=on' pg_restore ...를 실행한 다음, 다른 파드보다 먼저 LOOM_BOOT_MIGRATE를 켠 파드 하나를 시작하십시오. 기존 스키마에 대한 데이터 전용 pg_restore --disable-triggers는 마지막에 모든 트리거를 origin 트리거로 활성화하는데, 그러면 loom.cell_first의 트리거 두 개가 session_replication_role = replica에서 꺼진 상태가 됩니다. 그 파드의 부팅이 이를 ALWAYS로 되돌리며, 그때까지 loom doctor가 해당 트리거를 알려줍니다.
Helm 차트(Kubernetes)에서 릴리스 이름이 loom일 때:
-
중지합니다:
kubectl scale deploy/loom --replicas=0,workers.enabled이면deploy/loom-workers도 중지합니다. 분석 내보내기가 켜져 있으면 일시 중단합니다:kubectl patch cronjob loom-analytics-export -p '{"spec":{"suspend":true}}'. -
관리형 서비스는 새 서비스로 복구됩니다. 파드가 시작되지 않도록
helm upgrade ... --set replicaCount=0 --set workers.replicaCount=0 --set autoscaling.enabled=false로 릴리스가 새 서비스를 가리키게 합니다(새clickhouse.host또는postgres.host포함). 시점은 서비스가 해당 백업에 대해 나열하는 시작 시각이거나 Postgres 복구 목표 시점입니다. -
아래 Job은 릴리스의 이미지를 실행합니다. 정리 패스가 한 번 실행되었고 릴리스가
010_revision_delivered_at.sql이 없는 빌드라면, 먼저helm upgrade ... --set image.tag=<a build that carries it>(또는image.digest, 설정되어 있으면 이것이 우선)를 2단계의 새 호스트와 3개의--set오버라이드와 함께 실행해 파드가 시작되지 않게 하고, 4단계에서도 그 이미지를 유지하십시오. reconcile은 웹 파드 자체의 스펙으로 만든 Job에서 실행합니다. 이렇게 하면 릴리스의 환경, Secret, Postgres CA, 고유한 컴포넌트 레이블(NetworkPolicy는 이를 선택하지만 Service는 그렇지 않음)을 갖고 프로브는 없습니다.kubectl get deploy/loom -o json | jq '{apiVersion: "batch/v1", kind: "Job", metadata: {name: "loom-reconcile"}, spec: {backoffLimit: 0, template: { metadata: {labels: (.spec.selector.matchLabels | .["app.kubernetes.io/component"] = "reconcile")}, spec: (.spec.template.spec | .restartPolicy = "Never" | .containers |= [.[0] | del(.livenessProbe, .readinessProbe, .startupProbe) | .command = ["loom", "reconcile", "--restored", "clickhouse", "--point", "<time>"]])}}}' \ | kubectl apply -f - kubectl logs -f --pod-running-timeout=10m job/loom-reconcile kubectl wait --for=condition=complete --timeout=10s job/loom-reconcilePostgres 복구 후에는
"postgres"를 사용하십시오. Job이 아직 활성 상태인데wait가 실패하면(kubectl get job loom-reconcile -o jsonpath='{.status.active}'가1을 반환하고, 로그 스트림이 끊기면logs -f가 일찍 끝남) 아직 실행 중이라는 뜻이므로 로그를 다시 따라가십시오. Job이 실패했다면(.status.failed가1) 0이 아닌 값으로 종료된 것입니다. 출력을 읽고 Job을 삭제한 뒤 다시 실행하십시오. 드라이 런이 깨끗하게 끝나면"--apply"를 덧붙여 실행합니다. -
다시 시작합니다: 릴리스의 values 파일로
helm upgrade를 실행하되, 2단계의 새 호스트와 3단계에서 설정했다면image.tag또는image.digest를 포함하고, 2단계의 3개의--set오버라이드는 빼며, 분석 내보내기를 재개합니다. reconcile이 출력한 각loom rechunk를kubectl exec deploy/loom -- loom rechunk ...로 실행하고, “to ingest again” 아래에 나열된 각 소스를 다시 업로드하고 수집합니다.
loom reconcile --apply는 다음을 수행합니다.
- 다른 저장소가 시점 이후에 완료된 것으로 기록한 모든 삭제(erasure)를 다시 실행합니다(원장은 초 단위로 보관하므로 시점의 해당 초 전체부터). 이때 census는 수행하지 않으며(다른 저장소는 삭제 이후 사용자가 쓴 것을 보유함), 복원된 사본에서 시점 이전에 이미 실행된 것으로 보이는 단계는 제외합니다. 그 단계란 시점 이전에 기록된 마지막 ClickHouse 체크포인트의 단계(
BACKUP은 시작 시점부터 테이블을 차례로 복사하므로 그 삭제만 복사된 모든 테이블에 반영되어 있으며, 병합되어 사라진 행이 있으면 모든 단계를 실행함)에서 census가 다시 연 단계를 뺀 것, 또는 각 단계가 커밋된 트랜잭션에서 원장 행이 기록하는 Postgres 단계입니다(이전 빌드의 프로세스가 실행한 단계는 기록되지 않으므로 다시 실행됨). 이런 단계를 다시 실행하면 그 이후 사용자가 쓴 것을 삭제하게 됩니다. 복원된 원장 행은 모든 단계가 실행되면 completed가 됩니다. 그때까지 ClickHouse 복구 후에는 “replay after a restore pending”과 함께failed로 읽히며, 복구 워커도loom erasure-re-verify --resume도 이 행을 실행하지 않습니다. 복원된 행이 시점 이전에 completed였거나 이전 실행이 완료한 삭제는 다시 실행하지 않습니다. 재생 응답(replay answers) 단계는 모든 삭제가 그렇듯 두 저장소 모두에서 조직 전체의 재생 캐시를 삭제합니다. 종료 상태가 없는 삭제는 복구 워커에 맡기며, 그 체크포인트는 복구가 되돌린 단계를 다시 연 채로 다시 기록됩니다. ClickHouse 복구 후에 복원된 행이 completed 또는 abandoned로 나타나는 삭제는 대신 Postgres 원장 행에 그렇게 표시됩니다. 재개된 saga는 다른 것과 마찬가지로 census를 포함해 실행되며, 그 이후 범위 안에서 사용자가 쓴 것을 셉니다. 시점 이후에 완료되었지만 Postgres 원장 행이 완료를 놓친 삭제도 마찬가지인데, 이 경계 사례는 복구 패스가 요청 후 10분 뒤의 첫 패스에서(완료 후가 더 늦다면 완료 후에) 처리합니다. abandoned 상태인 것은 절대 실행하지 않습니다(loom erasure-re-verify가 담당합니다). - ClickHouse 복구 후: 먼저 시점 이후 커밋된 모든 Postgres 리비전과 지식 헤드(작성자의 리스와 insert의 한계, 즉 시점 이전에 할당된 쓰기가 그 이후에 커밋될 수 있는 여유분을 뺀 것), 그리고 ClickHouse가 더 오래된 버전으로 보유한 모든 Postgres 헤드를 아직 기한이 되지 않은 전달로 보류합니다. 그다음 삭제를 실행하되 Postgres 단계는 건너뜁니다(이미 유지되고 있으며 다시 실행하면 삭제 이후 사용자가 쓴 것을 삭제하게 됨). 보류한 전달을 게시하고, 마지막으로 시점 이후 Postgres가 기록한 모든 편집(redaction)을 다시 실행하여 ClickHouse가 복원한 것과 그것을 인용하는 캐시된 응답 및 선례를 지웁니다.
- Postgres 복구 후: 복원된 사본에서 삭제의 Postgres 단계와 재생 응답 단계를 실행하고, 시점 이후 ClickHouse가 기록한 모든 편집을 실행합니다. 편집된 버전이 다시 사본의 라이브 헤드가 된 경우(그것을 대체한 쓰기가 손실됨) 그 자리에서 지웁니다. 시점 이후에 쓴 것은 모든 특정 시점 복구와 마찬가지로 손실됩니다. ClickHouse에는 그 사본이 여전히 남아 있지만, Postgres에 일치하는 헤드가 없으면 검색은 이를 제공하지 않습니다.
데이터셋의 행은 ClickHouse에만 있으며 수집만이 이를 만듭니다. 따라서 ClickHouse 복구 후에는 시점 이후에 행이 쓰인 데이터셋(게시, 또는 열 타입을 바꾼 승인)이 행이 누락된 채로 읽힙니다. 그 카탈로그 행은 Postgres에 있어 해당 행들을 지목하기 때문입니다. loom reconcile은 드라이 런에서도 시점 이후에 카탈로그 행이 쓰인 각 소스를 다시 업로드하고 수집하도록 알려줍니다. 여기에는 남아 있던 행 위에 승인이나 메타데이터 편집이 덮어쓴 행도 포함됩니다.
지식 수집 작업에는 별도의 단계가 필요 없습니다. 작업을 읽을 때는 Postgres의 행과 ClickHouse의 행 중 더 새로운 것을 사용하며, Postgres가 보유한 작업은 큐가 제시할 때 다시 투영됩니다. ClickHouse 복구 시점 이후에 끝난 작업은 다시 제시되지 않으므로 ClickHouse를 읽는 knowledge.inspect는 그 행이 만료될 때까지 이를 나열하지 않습니다.
끝나지 않은 재생은 ClickHouse 행을 “replay after a restore pending”과 함께 failed로 남깁니다. 배포를 시작하기 전에, 그리고 reconcile보다 앞선 빌드로 롤백하기 전에 loom reconcile이 0으로 종료될 때까지 다시 실행하십시오. 그 빌드의 복구 워커는 해당 행을 census와 함께 재개하게 됩니다.
이 명령은 아무것도 쓰기 전에 다음 경우에 거부합니다. 시점이 현재보다 늦은 경우, 워커가 워커 리스(LOOM_SUPERVISOR_LEASE_TTL_S) 기간 두 번 이내(합쳐서 기본값 1분)에 패스를 보고한 경우, 시점이 LOOM_ERASURE_LEDGER_DAYS보다 오래된 경우(ClickHouse의 원장 읽기는 89일을 유지), 그리고 --restored both인 경우입니다. 두 복구 시점 이후에 이루어진 삭제와 편집은 어느 저장소에도 없으므로 감사 내보내기에서 다시 발행해야 합니다. 두 원장 모두 삭제를 요청된 시각으로 보관하므로, 해당 경계에서 삭제가 실행될 수 있는 최장 시간 이내의 시점은 경계 이전에 요청되고 시점 이후에 완료된 삭제를 놓칠 수 있습니다. 백업은 원장의 보관 일수보다 그만큼 더 짧게 유지하십시오. 쓰기 전에 코드 저장소 레지스트리를 읽으며, 읽기가 실패하면 거부합니다. 실행하는 모든 단계는 멱등이므로, 중단된 reconcile이나 1로 종료된 reconcile은 배포를 시작하기 전에 처음부터 다시 실행하십시오. 보류된 전달은 실행이 완료될 때까지 GET /v1/health?include=postgres에 parked로 나열됩니다.
복구할 수 있는 것과 없는 것
| 상황 | 복구 가능 여부 | 방법 |
|---|---|---|
memory.delete 또는 memory.clear로 삭제 표시(tombstone)된 메모리 |
가능 | memory.restore, 또는 삭제 이전 시점으로 namespace.rollback |
| 이후 버전으로 덮어쓰인 메모리 | 가능 | memory.history로 버전을 확인하고 namespace.rollback으로 한 버전을 복원 |
purge: true로 수행한 삭제, 또는 purge된 bench 네임스페이스 |
불가능 | purge는 완전 삭제이며 복원 기간이 없습니다. 그 이전에 만든 백업만 사용할 수 있습니다 |
삭제 표시(tombstone)로 처리된 삭제 (purge 없음) |
최종으로 간주 | saga의 census가 모든 읽기 경로에서 해당 범위가 사라졌음을 확인했습니다. 되살리면 삭제 요청을 취소하는 셈이므로, 삭제 자체가 실수였을 때만 백업에서 복원하십시오 |
| 이미지를 롤백한 후, 더 새로운 빌드의 스키마 | 필요 없음 | 마이그레이션은 추가형이므로 이전 빌드가 더 새로운 스키마를 읽을 수 있습니다 (업그레이드) |
| 이전 스키마 | 백업에서 복원 | down 마이그레이션이 없습니다. 업그레이드 이전에 만든 백업을 복원하십시오 |
| 단일 노드 ClickHouse OSS 서버의 디스크 | 백업에서 복원 | 복제와 특정 시점 복구(point-in-time recovery)가 없습니다. 노드는 자체 디스크까지만 내구성을 가집니다 |
| 코드 인덱스 테이블 | 재구축 가능 | loom code backfill이 git 미러에서 다시 생성합니다 (코드 인덱스 운영) |
| 선택적으로 설정한 보존 TTL로 제거된 행 | 불가능 | TTL 삭제는 최종적입니다. 그 이전에 만든 백업만 사용할 수 있습니다 |
단일 자체 관리 OSS 노드에서는 BACKUP DATABASE(또는 clickhouse-backup)를 호스트 외부 스토리지로 예약 실행하십시오. ClickHouse Cloud는 서비스 자체를 복제하고 백업하므로, 그곳의 이식 가능한 덤프는 내구성 확보용이 아니라 데이터 이전용입니다.
Postgres 저널과 ClickHouse 복원
권위 있는 메모리 상태를 Postgres가 소유하는 구성(Postgres authority)에서는 loom.memory_revisions가 모든 리비전을 보관합니다. ClickHouse를 복원하면 백업 이후에 커밋된 버전은 저널에는 있지만 복원된 memory_versions에는 없습니다. 이 버전들의 내용은 페이로드(row)가 저널에 남아 있는 동안에만 보존됩니다. LOOM_PG_PAYLOAD_CLEAR_ENABLED를 켜면 pg_payload_clear 워커가 사용 가능한 모든 백업에 들어 있는 버전의 페이로드를 비웁니다(페이로드 비우기). ClickHouse를 백업하지 않는 경우에는 이 설정을 꺼 두십시오. 그러면 저널이 모든 페이로드를 유지합니다.
기준 시간(horizon). LOOM_CH_BACKUP_INTERVAL_MINUTES를 ClickHouse 백업이 시작되는 주기로 설정합니다. 패스는 버전이 ClickHouse에 전달된 지 기준 시간보다 오래된 경우에만 해당 버전을 비웁니다. 기준 시간은 LOOM_PG_PAYLOAD_RESTORE_HORIZON_MINUTES입니다.
- 0(기본값)이면 주기의 두 배에 60을 더한 값입니다. 이 경우 가장 최근 백업이 실패했더라도 그 이전 백업이 일정대로 시작되었다면 복원 시 한 단계 이전 백업으로 돌아갈 수 있습니다.
- 주기에 60을 더한 값보다 작거나, 삽입 한계에 60을 더한 값보다 작을 수 없습니다. 더 낮게 설정한 값은 둘 중 큰 값으로 올라갑니다.
- 주기에 60을 더한 값 이상이고 주기의 두 배에 60을 더한 값 미만인 값은, 가장 최근 백업이 일정대로 시작된 경우에 한해 그 백업만 포함합니다.
두 설정 모두 LIVE입니다. 변경 사항은 프로세스가 오버라이드를 다시 읽은 뒤(LOOM_RUNTIME_OVERRIDES_REFRESH_SECONDS마다) 첫 번째 패스부터 적용됩니다. 이미 실행 중인 패스는 시작할 때의 기준 시간을 유지합니다.
여유 시간이 필요한 이유. 60분은 백업 시작 시각만으로는 드러나지 않는 다음 요소를 감안한 값입니다.
- 백업이 읽는 레플리카가 삽입을 받은 레플리카보다 뒤처지는 경우
- Postgres와 백업 호스트 사이의 시계 오차
비워진 모든 버전은 비우기가 중단되기 전 기준 시간보다 더 이전에 전달된 것입니다. 따라서 그 시점보다 기준 시간에서 60분을 뺀 시간 이내에 시작된 백업은, 지연과 시계 오차의 합이 60분 미만인 동안 비워진 모든 버전을 포함합니다. 늦게 시작된 백업은 자신의 시작 시각에 그 사실이 드러나며, 아래 4단계에서 이를 확인합니다. 가장 작은 기준 시간에서는 가장 최근 백업이 일정대로 시작되었을 때 통과하고, 늦게 시작된 백업은 통과하지 못할 수 있습니다. BACKUP ... ON CLUSTER는 모든 샤드를 한 번에 처리합니다. 노드별 도구를 사용한다면 백업의 시작 시각을 가장 먼저 시작한 노드의 시작 시각으로 계산하십시오.
복원 전에 비우기를 중단하십시오. 백업을 고르기 전에, ClickHouse에 백업에 없는 버전이 아직 남아 있는 동안 다음을 수행합니다.
- 배포 env에서
LOOM_PG_PAYLOAD_CLEAR_ENABLED=false로 설정합니다. 이 설정은 LIVE가 아니며,loom.runtime_overrides를 복원해도 다시 켜지지 않습니다. - 해당 env로 모든 Loom 프로세스를 재시작합니다. 다시 시작될 수 있는 중지된 인스턴스는 제거하거나 새 env로 다시 생성합니다.
- 오케스트레이터에서 실행 중이거나 시작될 수 있는 모든 Loom 프로세스에 이 스위치가 명시적으로
false로 설정되어 있는지 확인합니다. 설정하지 않은 채로 두면 스위치 값은 dotenv 파일(LOOM_ENV_FILE, 기본값은 작업 디렉터리의.env)이나, 환경 또는 해당 dotenv가 지정한 설정 파일(LOOM_SETTINGS_FILE)에서 가져오며, 둘 중 어느 쪽이든 이 스위치를 켤 수 있습니다. - 그런 다음에야 백업을 고르며, 위 3단계의 확인 시점(비우기가 중단된 시각)보다 기준 시간에서 60분을 뺀 시간 이내에 시작된 백업을 선택합니다. 기준 시간을 낮춘 적이 있다면, 최근 기준 시간 동안 적용된 값 중 가장 작은 기준 시간을 사용합니다. 기본 기준 시간에서는 일정대로 시작되었다면 가장 최근 백업 또는 그 이전 백업이 해당됩니다. 이보다 오래된 백업에는 페이로드가 이미 비워진 버전이 없을 수 있으며, 그 경우 해당 버전의 내용은 유실됩니다.
- 스위치는 하나의 저장소 복원의 4단계에서 배포가 다시 시작될 때 다시 켜고, 그 전에는 켜지 마십시오. 그 시점에는
loom reconcile --apply가 해당 시점 이후 커밋된 모든 리비전에 대해 전달 대기 상태를 다시 만들어 두었고, 리비전은 전달 대기 중인 동안 페이로드를 유지합니다. 먼저LOOM_CH_BACKUP_INTERVAL_MINUTES와LOOM_PG_PAYLOAD_RESTORE_HORIZON_MINUTES를 백업 일정과 대조하십시오. 복원으로 백업 시점의 오버라이드가 돌아왔으므로 그 이후 변경한 값은 다시 적용합니다. 복원 후에도 ClickHouse에 없는 버전은 페이로드를 유지하며, 그 버전에 도달하는 각 패스는 이를missing_in_clickhouse에 집계하므로 이 값이 0보다 큰 상태로 남을 수 있습니다. 하나의 저장소 복원의 4단계에서010_revision_delivered_at.sql이 포함된 빌드를, 그것이 없는 빌드를 서비스하던 배포에서 시작하는 경우, 해당 빌드가 단독으로 서비스한 뒤 비우기 기준 시간 하나가 지날 때까지 스위치를 꺼 둡니다(규칙 43).
무중단 이중화 구성에서는 다음과 같이 합니다.
.env를 수정합니다.origin/main보다 뒤처지지 않은 체크아웃에서./redeploy.sh --force를 실행합니다.- 재배포의 성공 여부와 관계없이,
docker inspect -f '{{.Config.Env}}'결과에LOOM_PG_PAYLOAD_CLEAR_ENABLED=false가 나타나지 않는 모든loom-*-workers컨테이너를 실행 중이든 종료되었든 중지하고docker rm으로 제거합니다. 웹 컨테이너는 워커를 실행하지 않으며, 이전 색상의 워커 컨테이너가 없으면--rollback은 현재 워커를 유지합니다. - 그 결과 워커 컨테이너가 하나도 남지 않으면 원인을 해결한 뒤 2단계를 다시 실행합니다.
이 단계를 건너뛰고 복원하면 백업과 복원 사이에 커밋된 버전의 내용이 유실될 수 있으며, 해당 버전의 메타데이터는 저널에 남습니다.
롤백 컬러
무중단 페어에서 redeploy.sh는 이전 컬러의 컨테이너(loom-<colour>, loom-<colour>-workers)를 제거하지 않고 중지하며, 이전 이미지에 loom:prev 태그를 붙입니다. ./redeploy.sh --rollback은 해당 컨테이너를 시작하고 상태 검사를 수행한 뒤 프록시를 다시 이전 컬러로 전환합니다. 이전 컬러의 컨테이너가 없으면 롤백은 “the previous build is gone”이라는 메시지와 함께 거부됩니다. 이 경우 정상 동작이 확인된 커밋을 대신 재배포하십시오.
경고. 페어를 실행하는 호스트에서는
docker container prune이나docker system prune을 절대 실행하지 마십시오. 중지된 롤백 컬러가 삭제됩니다. 디스크 공간은docker builder prune과docker image prune으로 확보하십시오. 임시 컨테이너에loom-blue또는loom-green이라는 이름을 붙이지 마십시오. 이름으로 컨테이너를 삭제하면 컬러 하나가 삭제됩니다.
롤백 후에도 롤포워드되었던 컬러의 웹 컨테이너는 사용자가 중지할 때까지 계속 실행됩니다(롤백이 출력하는 docker stop -t 75 loom-<colour>). 해당 컬러의 workers 컨테이너는 전환 전에 이미 중지되었으므로 workers 리스는 롤백된 컬러가 가지고 있습니다. 롤백된 컬러에 workers 컨테이너가 없는 경우에만 롤포워드되었던 컬러가 workers를 계속 실행합니다.
배포 이전
같은 ClickHouse(그리고 LOOM_STORAGE_AUTHORITY=postgres일 때는 Postgres)를 가리키거나, 이전했거나 복원한 ClickHouse를 가리키는 새 Loom 프로세스는 모든 기능을 되돌려 받습니다. Postgres가 권위 있는 저장소인 구성에서는 어느 저장소든 복사하기 전에 원본을 중지하세요. 한 저장소를 다른 시점에 만든 백업에서 복원하는 것은 단일 저장소 복원에 해당합니다. 다음 항목을 함께 옮기세요.
- ClickHouse: 같은 서비스, Keeper 상태가 포함된 복사본, 또는
loom migrate로 준비한 ClickHouse에 복원한dev/backup_loom.py덤프 - Postgres(
LOOM_STORAGE_AUTHORITY=postgres일 때): 같은 서비스 또는 복사본 - env 설정(
.env또는 컨테이너 환경) LOOM_JWT_SECRET. 이 값이 없으면 어떤 토큰도 검증되지 않으며, 저장된 자격 증명과 서명 키도 열리지 않습니다.- 카탈로그 행 중 하나라도 해당 버킷의 객체를 가리키는 동안은 같은 이름과 접두사의
LOOM_DOCUMENT_S3_BUCKET: 새 호스트에서 접근하는 같은 버킷, 또는 다른 엔드포인트에 있는 같은 이름의 버킷(LOOM_DOCUMENT_S3_ENDPOINT_URL은 행의 위치에 포함되지 않습니다). 모든 행에는 버킷 이름이 기록되어 있으며 Loom에는 이를 다시 쓰는 도구가 없습니다. 다른 이름으로 복사하면 모든 다운로드와 삭제가 이전 버킷을 계속 가리킵니다.
나머지는 모두 ClickHouse에서 복구됩니다. ClickHouse에 저장된 문서 원본, 서명 키, 런타임 오버라이드, supervisor 리스, 폐기 목록, 로그인 시도 횟수, 그래프 탐색 무효화 표시가 여기에 해당합니다. Git 미러는 다음 수집 과정에서, 또는 새 호스트에서 처음 이력을 읽을 때 기록된 원격 저장소로부터 다시 clone됩니다.
제한적인 예외:
- 이벤트 스트림(예산 위반)은
SIGTERM시 비워집니다.SIGKILL이나 OOM이 발생하면 해당 텔레메트리는 최대 한 번의 flush 주기 분량만 유실되며, 감사 행이나 메모리 행은 유실되지 않습니다. - 제공자 재구성은 종료된 프로세스가 있으면, 같은 호스트의 프로세스가 그 종료를 확인하거나 Kubernetes에서는 workers 리더가 해당 파드가 사라진 것을 확인할 때까지 대기합니다. 그 외의 경우, 호스트까지 사라진 프로세스(새 호스트로 이전하는 경우)는
loom participant retire --participant <id> --yes로 직접 폐기합니다(제공자 재구성). - 속도 제한 버킷의 충전 상태는 호스트별입니다. 몇 초 안에 다시 채워지므로 새 호스트는 가득 찬 버킷으로 시작합니다.