본문으로 건너뛰기
Ankole

재해 복구

AI Agent용: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/disaster-recovery/index.md에 있습니다. 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

재해 복구는 배포 인스턴스가 사라졌을 때 — 호스트가 죽었거나, 클러스터를 잃었거나, 볼륨이 파괴되었을 때 — 다른 곳에서 되살려야 하는 경우에 하는 일입니다. 인시던트가 아닙니다(시스템이 잘못 동작하는 것이 아니라 부재합니다). 업그레이드도 아닙니다(앞으로 밀어 올릴 것이 없습니다). 이 페이지는 다른 가이드가 다루는 백업 규율과 마이그레이션 메커니즘 위에 세워진, 종단 간 복구의 형태입니다.

결정적인 속성을 먼저 말하면, 복구는 이전 인스턴스를 수리하는 것이 아니라 새 배포 위에 복원하는 것입니다. Ankole을 처음부터 배포하고, 백업에서 PostgreSQL과 Agent Home을 복원하며, 부트스트랩 시크릿을 다시 입력합니다. 복구되는 것은 백업한 것 그대로입니다. 더도 덜도 없습니다. 그리고 리허설하지 않은 복구는 능력이 아니라 계획입니다.

무엇을 복구할 수 있고 무엇을 복구할 수 없는가

상태 복구 가능? 출처
Principals, agents, sessions, jobs, audit, AuthZ grants 예 PostgreSQL pg_dump 아카이브
Agent별 workspaces, durable 문서, 설치된 Skills, 대화 및 Job 파일 예 Agent Home 볼륨 스냅샷
프로바이더 자격 증명, 채팅 채널 자격 증명, 암호화된 환경 변수 예 PostgreSQL과 Agent Home이 보관하므로 백업이 복원함
부트스트랩 시크릿(ANKOLE_SECRET_BASE, worker 인증 키) 수동 재입력 백업에 없음. 새로 생성하거나 기록해 둔 것을 재사용
실행 중인 turn, 실행 중인 background job, 라이브 Worker 상태 아니요 일시적(ephemeral). 프로세스와 함께 유실됨
외부 수집기로 전송되지 않은 로그 아니요 유실된 호스트에 있었음

사람들을 놀라게 하는 행은 부트스트랩 시크릿입니다. 다른 키를 파생하는 시크릿은 배포 시점의 입력이지 PostgreSQL 상태가 아니므로 pg_dump에 없습니다. 시크릿 관리자에 보관하거나(인스턴스 백업 안이 아니라 그 옆에), 아니면 새로 생성하고 파생 키가 바뀌는 것을 받아들이십시오.

복구 절차

1단계: Ankole을 처음부터 새로 배포

새 호스트나 클러스터에 새 배포 인스턴스를 세우되 빠른 시작의 배포 절차를 따릅니다. 새 인스턴스를 이전 호스트의 볼륨이나 데이터베이스에 붙이려 하지 마십시오. 이전 것들은 복구의 원천이며, 절반만 연결된 인스턴스는 깨끗한 인스턴스보다 나쁩니다. 새 데이터베이스, 새 Agent Home 볼륨, 새 부트스트랩 시크릿(또는 기록해 둔 이전 값 — 4단계 참고)을 사용하십시오.

2단계: PostgreSQL 복원

컨트롤 플레인을 실제로 시작하기 전에 아카이브에서 데이터베이스를 복원합니다.

# on the fresh deployment, with the control plane stopped or in setup mode
docker compose exec -T postgresql \
  pg_restore -U ankole -d ankole --clean --if-exists \
  < "ankole-YYYYMMDD.dump"

그런 다음 마이그레이션을 실행하여(bun run control-plane:setup, 로컬에서, 또는 Helm init 컨테이너에 맡김) 복원된 스키마를 이미지 수준으로 끌어올립니다. 복원된 데이터베이스에는 백업을 만든 시점의 Principals, agents, sessions, jobs, AuthZ grants가 있습니다.

3단계: Agent Home 복원

ankole_agents_data 볼륨(Helm에서는 RWX claim)을 스냅샷에서 같은 /agents 마운트 경로로 복원합니다. agent 키별 디렉터리 구조는 /agents/<agent-key>/...를 정확히 재현합니다. PostgreSQL 복원과 짝을 이루어야 합니다. 데이터베이스 행은 Agent Home 아래의 파일을 참조하므로, 짝이 맞지 않으면 살아 있는 것처럼 보이지만 없는 파일을 가리키는 배포가 됩니다.

4단계: 부트스트랩 시크릿 처리

부트스트랩 시크릿(ANKOLE_SECRET_BASE, ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY, POSTGRES_PASSWORD)은 백업에 없습니다. 두 가지 경로가 있습니다.

  • 기록해 둔 값 재사용 — 인스턴스 백업 옆(안이 아니라)의 시크릿 관리자에 보관했다면 다시 입력하십시오. 파생 키가 같으므로 복원된 PostgreSQL의 기존 암호화 행은 올바르게 복호화됩니다.
  • 새로 생성 — .env(Compose) 또는 Secret(Helm)에서 새 값을 생성하십시오. 복원된 PostgreSQL은 온전하지만, 이전 ANKOLE_SECRET_BASE로 암호화된 프로바이더 자격 증명, 채팅 채널 자격 증명, 환경 변수는 복호화되지 않습니다. 복구 후 Console에서 이 값들을 다시 입력하십시오.

재사용은 더 간단하고 시크릿을 보존합니다. 재해에서 이전 시크릿이 유출되었을 가능성이 있다면 새로 생성이 더 안전합니다. 복구하는 이유에 맞는 경로를 선택하십시오.

5단계: 백업에 없는 모든 것을 다시 입력

복원 후 구성 표면을 하나씩 돌아보며 각각 온전한지 확인합니다.

  • Providers 및 모델 프로파일 — PostgreSQL에 있으며 복원되었습니다.
  • Signal 라우팅 규칙 — PostgreSQL에 저장되어 복원되었습니다. 4단계에서 ANKOLE_SECRET_BASE를 새로 생성했다면 Channel Provider 자격 증명을 다시 입력해야 할 수 있습니다.
  • Identity providers — 동일합니다. 행은 복원되고, 자격 증명은 다시 입력이 필요할 수 있습니다.
  • Control Plane Plugins 활성화 목록 — 복원되었지만 다음 프로세스 시작 시에 적용됩니다.

바인딩을 통해 실제 turn 하나를 보내 새 배포에서 종단 간 경로가 작동하는지 확인하십시오.

호스트 간 마이그레이션(계획된 버전)

새 호스트로의 계획된 이동도 같은 절차이며, 의도적으로 수행합니다.

  1. 이전 배포를 중지합니다(Worker를 조용히 멈추고 쓰기를 중지).
  2. 최종 PostgreSQL 백업과 Agent Home 스냅샷을 만듭니다. 이것들이 마이그레이션의 진실의 원천입니다.
  3. 새 호스트에 새로 배포하고, 짝을 복원하며, 부트스트랩 시크릿을 처리합니다.
  4. 새 호스트에서 실제 turn 하나로 검증합니다.
  5. DNS(또는 로드 밸런서)를 새 호스트로 전환합니다. 확신이 생기면 이전 호스트는 해체할 수 있습니다.

재해 복구와의 차이는 “이전 배포 중지” 단계입니다. 재해에서는 이전 배포가 스스로 멈추며, 보유한 백업은 그 이전 시점의 것입니다. 격차를 최소화하려면 최종 백업을 전환 시점에 최대한 가깝게 만드십시오.

리허설

리허설하지 않은 복구는 능력이 아니라 계획입니다. 리허설은 이 가이드에서 가장 영향력이 큰 단일 요소입니다.

  • 매월, 임시 호스트에서 어젯밤의 PostgreSQL과 Agent Home을 복원하고 이미지를 배포한 뒤 실제 turn 하나를 실행하십시오. 복원이 작동하면 복구는 실제입니다. 작동하지 않으면 재해 중이 아니라 임시 호스트에서 알게 된 것입니다.
  • 부트스트랩 시크릿 단계를 포함하십시오. 그것을 건너뛴 리허설은 사람들을 놀라게 하는 부분을 시험하지 않은 것입니다. 기록해 둔 시크릿을 재사용하거나 자격 증명을 새로 생성해 다시 입력하십시오. 실제 상황에서 할 그쪽을 선택하십시오.
  • 호스트를 다양하게 바꾸십시오. 매번 같은 호스트에 복원하는 것은 복구가 아니라 백업을 시험하는 것입니다. 주기적으로 다른 호스트(다른 OS, 다른 클라우드)에 복원하십시오. 재해가 주는 것이 바로 그것이기 때문입니다.

다른 가이드와의 관계

  • 백업 및 복원은 복구를 가능하게 하는 규율입니다. 백업이 원천입니다.
  • 시스템이 여전히 존재하지만 잘못 동작한다면 먼저 장애를 진단하십시오. 이 페이지는 인스턴스를 사용할 수 없거나 데이터가 유실되었을 때 적용됩니다.
  • 계획된 업그레이드는 기존 인스턴스를 앞으로 이동시킵니다. 재해 복구는 새 환경에서 백업으로 인스턴스를 다시 구축합니다.
  • 보안 강화는 복원에 사용할 백업이 시험되었음을 전제합니다. 이 페이지가 바로 그 시험입니다.

이 가이드가 아닌 것

데이터가 유실되지 않는다는 보장이 아닙니다. 백업에 없는 것은 사라지며, 진행 중인 작업은 항상 일시적입니다. 리허설의 대체물도 아닙니다. 리허설이 바로 핵심입니다. 그리고 단일 명령도 아닙니다. 복구는 새 배포에 복원 짝과 시크릿을 더한 것이며, 각 단계에는 각자의 검증이 있습니다. 시간을 아끼려고 단계를 건너뛰는 것이 복구를 통해 깨진 배포가 만들어지는 방식입니다.

다음 단계

  • 복구가 의존하는 백업 규율은 백업 및 복원을 참고하세요.
  • 새 배포 단계는 빠른 시작을 참고하세요.
  • 시스템이 여전히 실행 중이지만 잘못 동작한다면 로그 읽기로 첫 번째 장애를 찾으십시오.