# 백업 가이드
Clinic-OS는 3중 안전망으로 데이터를 보호합니다. 대부분의 경우 **에이전트가 자동으로 관리**하므로, 에이전트에게 요청하는 것이 가장 간단합니다.
---
## 에이전트에게 백업 요청하기 (기본)
위험한 작업 전, 에이전트에게 다음과 같이 요청하세요:
### 일상적인 백업
```
DB 백업해줘
```
또는 작업별 요청:
```
"환자 데이터 삭제하기 전에 백업해줘"
"온보딩 진행하기 전에 백업해줘"
"배포하기 전에 백업해줘"
```
### 복원 필요 시
```
"어제 백업으로 복원해줘"
"백업 목록 보여줘"
"문제 생겼는데 이전 상태로 돌려줘"
```
### 프로덕션 데이터
```
"프로덕션 DB 백업해줘"
"프로덕션 데이터를 로컬로 가져와줘"
```
---
## 3중 백업 구조 (참고)
에이전트가 자동으로 관리하는 백업:
```
Layer 1: 로컬 자동 백업 (최근 5개 유지)
├── 홈 디렉토리의 .clinic-os-backups/
├── 매일 자동 생성
└── 로컬에서만 복원 가능
Layer 2: GitHub 원격 백업
├── 코드와 함께 커밋
├── 다른 컴퓨터로 이동 시 활용
└── GitHub 연결 필요
Layer 3: 프로덕션 D1 (Cloudflare)
├── 클라우드 서비스가 관리
├── 배포 시 자동 반영
└── 별도 백업 불필요 (자동)
```
---
## 자동 백업 시점
에이전트가 다음 상황에서 자동으로 백업을 실행합니다:
| 시점 | 설명 |
|------|------|
| **DB 변경 전** | 테이블 추가, 컬럼 변경, 스키마 수정 |
| **대량 데이터 삭제 전** | 환자, 예약, 게시글 삭제 시 |
| **배포 전** | `npm run deploy` 실행 시 |
| **온보딩 진행 중** | 새 기능 추가 시 정기적으로 |
---
## 수동 백업 명령어 (필요시)
에이전트가 없을 때만 직접 사용하세요:
```bash
# 로컬 DB 백업 (스마트)
npm run db:backup
# 강제 백업
npm run db:backup -- --force
# 백업 목록 조회
npm run db:backup -- --list
# 복원 (대화형)
npm run db:backup -- --restore
# DB 상태 확인
npm run db:doctor
# DB 문제 자동 수정
npm run db:fix
```
---
## 프로덕션 DB 관리
### 프로덕션에서 로컬로 데이터 가져오기
```bash
npm run db:pull
```
이 명령어는 배포된 프로덕션 D1 데이터를 로컬로 동기화합니다.
(GitHub Codespace에서는 에이전트가 권장)
### 프로덕션 DB 백업
```bash
npx wrangler d1 export {db-name} --remote --output backup_prod.sql
```
---
## 문제 해결
| 상황 | 해결 |
|------|------|
| **"로컬 DB가 없다"는 오류** | `npm run db:init` → 테이블 생성 |
| **복원 후 데이터가 이상** | `npm run db:doctor` → `npm run db:fix` |
| **백업 파일이 너무 크다** | GitHub 제외 설정 (`.gitignore`), 또는 에이전트에게 정리 요청 |
---
## 관련 문서
- **[GitHub 설정 가이드](/guide#github-setup-guide)** — 원격 백업을 위한 GitHub 연결
- **[배포 가이드](/guide#deployment-workflow)** — 배포 전 백업 절차