---
title: "백업, 시점 복구, 복구 훈련"
description: "Quire를 백업하고 시점으로 복구하며 복구 훈련으로 증명하기."
image: "https://docs.quirelms.com/og.png"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ko/llms.txt
> Use this file to discover all available pages before exploring further.
# 백업, 시점 복구, 복구 훈련
설계는 `docs/architecture/23-ops.md` 8절입니다. 이것은 Docker Compose
제품의 런북입니다. 이 문서를 쓰지 않은 사람이 따라할 수 있도록 쓰여
있습니다. 단계가 명확하지 않다면 그것은 이 문서의 결함입니다.
## 무엇을, 어떻게 보호하는가
| 자산 | 방법 | 위치 |
| --- | --- | --- |
| 데이터베이스 | 첫 부팅부터 WAL을 연속 보관. 최대 60초 간격 | `pgwal` 볼륨 |
| 데이터베이스 | `pg_basebackup`으로 기준 백업. 기본은 매일(`backup-scheduler`) | `pgbackup` 볼륨 |
| 데이터베이스 | 기준 백업과 WAL의 암호화 사본. 5분마다(`backup-offsite`) | 직접 지정하는 별도 저장소 |
| 파일 | `files` 볼륨. 호스트의 백업 도구로 복사하거나 버전 관리 객체 저장소 사용 | `files` 볼륨 |
| 시크릿 | `docker/.env`, 그중에서도 `QUIRE_MASTER_KEY`(사용 중인 모든 `QUIRE_MASTER_KEY_RETIRED` 포함), `QUIRE_BACKUP_ENCRYPTION_KEY`, `docker/secrets/audit-signing-key.pem` | 이 호스트 밖에 사본 보관 |
| 검색 색인, 캐시, 렌더링 | 백업하지 않음; 다시 구축 | |
목표: 실패 시점에서 60초 이내의 복구 지점, 500GB 데이터베이스는 60분 이내의
복구.
흔한 실수는 두 가지입니다. **파일 없이** 복구된 데이터베이스는 깨진
페이지를 렌더링합니다. **`QUIRE_MASTER_KEY` 없이** 복구된 데이터베이스는
보관 중인 SSO, 웹훅, 연동 자격 증명을 복호화할 수 없습니다. 마스터 키
로테이션이 미해결 없이 끝날 때까지([key-rotation.md](/ko/ops/key-rotation/)),
은퇴한 키도 여기에 포함됩니다. 둘 다 백업의 일부입니다.
## 백업 만들기
클러스터 전체의 기준 백업:
```sh
docker compose -f docker/compose.yaml --profile backup run --rm backup
```
가장 최신한 `QUIRE_BACKUP_KEEP`개의 기준 백업(기본 5)을 남기고, 가장 오래된
것이 더 이상 필요로 하지 않는 WAL은 정리하므로 보관함이 무한히 커지지
않습니다. 호스트의 cron이나 systemd 타이머로 매일 예약하세요.
```cron
15 2 * * * cd /srv/quire && docker compose -f docker/compose.yaml --profile backup run --rm backup >> /var/log/quire-backup.log 2>&1
```
또는 스택이 예약하게 하세요. `backup` 프로필은 `backup-scheduler`(매
`QUIRE_BACKUP_INTERVAL_HOURS`마다 기준 백업, 기본 24)와 다음에 설명할
`backup-offsite`를 실행합니다.
```sh
docker compose -f docker/compose.yaml --profile backup up -d
```
## 호스트 밖의 암호화 사본
두 볼륨 모두 데이터베이스와 같은 호스트에 있고, 실패한 기계의 백업은
백업이 아닙니다. `backup-offsite`는 모든 기준 백업과 보관된 WAL 세그먼트를
스토리지 포트를 통해 암호화된 별도 저장소로 복사하고, 보존 규칙에 따라
거기에 보관합니다.
- **암호화.** `QUIRE_BACKUP_ENCRYPTION_KEY`(또는
`QUIRE_BACKUP_ENCRYPTION_KEY_FILE`이 지정하는 파일)로 하는 AES-256-GCM.
32바이트이며 `openssl rand -hex 32`로 만듭니다. 각 파일은 고유한 nonce와
인증 태그를 가지므로 키 없이는 읽을 수 없고 어떤 변경도 감지됩니다. 키는
`QUIRE_MASTER_KEY`와 함께, 이 호스트와 백업 저장소 모두에서 멀리 두세요.
키가 없으면 복구는 없습니다.
- **어디에.** `QUIRE_BACKUP_STORAGE_DRIVER`는 `s3`, `azure`, `local`
(`QUIRE_BACKUP_STORAGE_ROOT`의 마운트된 원격 디스크) 중 하나입니다. 설정은
파일 저장소 설정에 `QUIRE_BACKUP_` 접두어를 붙인 것입니다.
`QUIRE_BACKUP_S3_ENDPOINT`, `QUIRE_BACKUP_S3_BUCKET`,
`QUIRE_BACKUP_S3_ACCESS_KEY_ID` 등이 있습니다. 파일과 다른 버킷을, 가능하면
다른 계정을 쓰고, 제공자가 허하면 쓸 수는 있으나 삭제할 수 없는 자격
증명을 쓰세요.
- **보존.** 가장 최신한 `QUIRE_BACKUP_OFFSITE_KEEP`개의 기준 백업(기본은
`QUIRE_BACKUP_KEEP`, 없으면 7)과 그중 가장 오래된 것이 필요로 하는 WAL.
더 오래된 세트와 세그먼트는 저장소에서 삭제됩니다.
- **언제.** `QUIRE_BACKUP_SHIP_INTERVAL_SECONDS`마다(기본 300). 전송은
멱등합니다. 이미 저장된 것은 건너뛰며, 기준 백업은 마지막에 매니페스트가
쓰여야 저장으로 칩니다.
같은 명령을 직접 실행할 수도 있습니다.
```sh
docker compose -f docker/compose.yaml run --rm backup-offsite bun apps/worker/src/backups/main.ts ship
docker compose -f docker/compose.yaml run --rm backup-offsite bun apps/worker/src/backups/main.ts verify
```
새 호스트에서 복구하려면 먼저 세트를 가져온 뒤, 아래 단계를 따라가되
내려받은 디렉터리로 `pgbackup` 볼륨을, 내려받은 `wal-archive`로 `pgwal`을
대체하세요.
```sh
bun apps/worker/src/backups/main.ts fetch base-20260924T021500Z /srv/restore
```
## 시점 복구
데이터 손실 뒤에 사용하세요. 잘못된 가져오기, 삭제된 코스, 되돌려야 하는
축소 마이그레이션이 그렇습니다. 라이브 데이터베이스를 대체하므로, 먼저
아래 훈련으로 연습하세요.
1. **목표 시각을 고르세요.** UTC로, 손상 직전 시점입니다.
`2026-09-24 09:30:00+00`. 감사 로그(`/admin/audit`)가 그 순간을 대개
보여줍니다.
2. **쓰는 것을 모두 멈추세요**:
`docker compose -f docker/compose.yaml stop web content worker scheduler collab`
3. **손상된 클러스터를 보관하세요.** 복구가 검증될 때까지:
```sh
docker compose -f docker/compose.yaml stop postgres
docker run --rm -v quire_postgres18-data:/from -v quire_postgres-damaged:/to alpine cp -a /from/. /to/
```
4. **목표보다 오래된 가장 최신한 기준 백업을 데이터 볼륨에 풀고**,
대상 지정 복구를 요청하세요:
```sh
docker run --rm -v quire_pgbackup:/backups:ro -v quire_postgres18-data:/var/lib/postgresql postgres:18-alpine sh -euc '
base="$(ls -1d /backups/base-* | sort | tail -n 1)" # or the one before the target
rm -rf /var/lib/postgresql/18/docker && mkdir -p /var/lib/postgresql/18/docker
tar -xzf "$base/base.tar.gz" -C /var/lib/postgresql/18/docker
touch /var/lib/postgresql/18/docker/recovery.signal
chown -R postgres:postgres /var/lib/postgresql/18/docker && chmod 700 /var/lib/postgresql/18/docker'
```
5. **복구하세요**: 복구 설정과 함께 Postgres를 한 번 시작합니다. 일반 파일을
건드리지 않도록 Compose 오버라이드로 합니다.
```yaml
# docker/compose.recover.yaml
services:
postgres:
command: [postgres, -c, "restore_command=cp /var/lib/postgresql/wal-archive/%f %p",
-c, "recovery_target_time=2026-09-24 09:30:00+00",
-c, recovery_target_action=promote, -c, archive_mode=off,
-c, max_connections=200, -c, hba_file=/etc/postgresql/pg_hba.conf]
```
오버라이드는 명령 전체를 대체하므로 복구가 의존하는 두 설정을 반복합니다.
`max_connections`는 주 서버보다 낮지 않아야 하며(그렇지 않으면
"insufficient parameter settings"로 복구가 중단됩니다), 마운트된
`pg_hba.conf`도 포함됩니다.
```sh
docker compose -f docker/compose.yaml -f docker/compose.recover.yaml up -d postgres
docker compose -f docker/compose.yaml logs -f postgres # wait for "database system is ready"
```
6. **아무도 들어가기 전에 확인하세요.** 감사 체인
(`docker compose -f docker/compose.yaml run --rm worker bun tooling/audit-verify/run.ts`)과
잃어버린 데이터가 돌아왔는지 확인합니다.
7. **정상으로 돌아오세요**: `docker compose -f docker/compose.yaml up -d`.
아카이빙을 켠 채 Postgres를 재시작하며 새 WAL 타임라인이 시작됩니다.
곧바로 새로운 기준 백업을 만드세요.
프로젝트 이름 `quire`가 각 볼륨의 접두어가 됩니다. 정확한 이름은
`docker volume ls`로 확인하세요.
## 예약된 검증 훈련
`backup-offsite`는 `QUIRE_BACKUP_DRILL_INTERVAL_HOURS`마다(기본 168, 주
1회) 훈련도 실행하며, 하나가 실패하면 다음 주기에 다시 실행합니다. 최신한
호스트 밖 기준 백업과 그 뒤의 모든 WAL 세그먼트를 가져와 각각을 복호화하고
(키가 여전히 열리고 아무것도 변조되지 않았음을 증명), 각 파일을 매니페스트와
비교하며, 보관함이 Postgres 데이터 디렉터리인지 확인하고, 백업 이후의 WAL에
공백이 없는지 확인합니다. 보고서는 `reports/drill-