---
title: "재해 복구"
description: "Ankole 배포 인스턴스를 손실에서 복구하는 전체적인 형태 — 무엇을 복구할 수 있고 무엇을 복구할 수 없는지, 호스트 간 마이그레이션, 그리고 복구를 실제로 만드는 리허설을 다룹니다."
url: "https://ankole.agentbull.com/ko-KR/docs/disaster-recovery/"
lang: "ko-KR"
---

> AI Agent용 문서 색인: 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을 처음부터 새로 배포

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

### 2단계: PostgreSQL 복원

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

```bash
# 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, 다른 클라우드)에 복원하십시오. 재해가 주는 것이 바로 그것이기 때문입니다.

## 다른 가이드와의 관계

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

## 이 가이드가 아닌 것

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

## 다음 단계

- 복구가 의존하는 백업 규율은 [백업 및 복원](https://ankole.agentbull.com/ko-KR/docs/backup-and-restore/index.md)을 참고하세요.
- 새 배포 단계는 [빠른 시작](https://ankole.agentbull.com/ko-KR/docs/quickstart/index.md#deployment)을 참고하세요.
- 시스템이 여전히 실행 중이지만 잘못 동작한다면 [로그 읽기](https://ankole.agentbull.com/ko-KR/docs/log-reading/index.md)로 첫 번째 장애를 찾으십시오.