백업 가이드

# 백업 가이드 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:backup:remote # DB 상태 확인 npm run db:doctor # DB 문제 자동 수정 npm run db:fix ``` **로컬 vs 라이브 구분 (중요):** `db:backup`(및 별칭 `db:backup:local`)은 개발 환경의 로컬 사본(miniflare)만 백업합니다 , 실제 운영 중인 병원 데이터가 아닙니다. 실제 운영 데이터를 백업하려면 반드시 `db:backup:remote`를 사용하세요. 인증은 `CLOUDFLARE_API_TOKEN` 환경변수(또는 `.env`)만 사용됩니다 , wrangler의 `--env-file` 플래그는 D1 원격 인증에 관여하지 않습니다. --- ## 프로덕션 DB 관리 ### 프로덕션에서 로컬로 데이터 가져오기 ```bash npm run db:pull ``` 이 명령어는 배포된 프로덕션 D1 데이터를 로컬로 동기화합니다. (GitHub Codespace에서는 에이전트가 권장) ### 프로덕션 DB 백업 ```bash npm run db:backup:remote ``` 위 명령이 실제로 하는 일: `npx wrangler d1 export {db-name} --remote --output backup_prod.sql`을 그대로 실행하면 검색용 특수 표(`posts_fts` 계열, FTS5 가상 테이블)가 있는 스키마에서 **실패합니다** , `db:backup:remote`는 이 표들을 자동으로 제외하고 테이블별로 나눠 내보낸 뒤 하나의 `.sql` 파일로 합쳐줍니다. 직접 `wrangler d1 export`를 실행해야 한다면 `--table` 플래그로 대상 표를 개별 지정하세요. 한 표씩 내려받아 임시 폴더에 모은 뒤, 전부 성공적으로 모이면 그때 하나의 `.sql` 파일로 합치고 임시 폴더를 정리합니다 , 중간에 중단돼도 이전 백업 파일이 깨진 내용으로 덮어써지지 않습니다. 이 방식 때문에 백업이 진행되는 동안 잠시 필요한 여유 공간은 **최종 백업 파일 크기의 약 2배**입니다(표별 임시 파일 + 합쳐지는 파일을 동시에 들고 있는 구간이 있기 때문). 데이터베이스가 큰 병원이라면 백업 전 디스크 여유 공간을 미리 확인해주세요. --- ## 문제 해결 | 상황 | 해결 | |------|------| | **"로컬 DB가 없다"는 오류** | `npm run db:init` → 테이블 생성 | | **복원 후 데이터가 이상** | `npm run db:doctor` → `npm run db:fix` | | **백업 파일이 너무 크다** | GitHub 제외 설정 (`.gitignore`), 또는 에이전트에게 정리 요청 | | **백업 중 디스크 공간 부족 오류** | 백업 파일 크기의 약 2배 여유 공간이 필요합니다(위 설명 참고) , 불필요한 파일 정리 후 재시도, 또는 에이전트에게 `npm run cleanup`으로 오래된 백업/스냅샷 정리를 요청하세요 | --- ## 관련 문서 - **[GitHub 설정 가이드](/guides/github-setup-guide)** , 원격 백업을 위한 GitHub 연결 - **[배포 가이드](/guides/deployment-workflow)** , 배포 전 백업 절차

백업 가이드

이 페이지에서 확인할 내용