백업 가이드

백업 가이드

Clinic-OS는 3중 안전망으로 데이터를 보호합니다. 대부분의 경우 에이전트가 자동으로 관리하므로, 에이전트에게 요청하는 것이 가장 간단합니다.

에이전트에게 백업 요청하기 (기본)

위험한 작업 전, 에이전트에게 다음과 같이 요청하세요:

일상적인 백업

DB 백업해줘

또는 작업별 요청:

"환자 데이터 삭제하기 전에 백업해줘"
"온보딩 진행하기 전에 백업해줘"
"배포하기 전에 백업해줘"

복원 필요 시

"어제 백업으로 복원해줘"
"백업 목록 보여줘"
"문제 생겼는데 이전 상태로 돌려줘"

프로덕션 데이터

"프로덕션 DB 백업해줘"
"프로덕션 데이터를 로컬로 가져와줘"

3중 백업 구조 (참고)

에이전트가 자동으로 관리하는 백업:

Layer 1: 로컬 자동 백업 (최근 5개 유지)
├── 홈 디렉토리의 .clinic-os-backups/
├── 매일 자동 생성
└── 로컬에서만 복원 가능

Layer 2: GitHub 원격 백업
├── 코드와 함께 커밋
├── 다른 컴퓨터로 이동 시 활용
└── GitHub 연결 필요

Layer 3: 프로덕션 D1 (Cloudflare)
├── 클라우드 서비스가 관리
├── 배포 시 자동 반영
└── 별도 백업 불필요 (자동)

자동 백업 시점

에이전트가 다음 상황에서 자동으로 백업을 실행합니다:

수동 백업 명령어 (필요시)

에이전트가 없을 때만 직접 사용하세요:

# 로컬 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 관리

프로덕션에서 로컬로 데이터 가져오기

npm run db:pull

이 명령어는 배포된 프로덕션 D1 데이터를 로컬로 동기화합니다. (GitHub Codespace에서는 에이전트가 권장)

프로덕션 DB 백업

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배입니다(표별 임시 파일 + 합쳐지는 파일을 동시에 들고 있는 구간이 있기 때문). 데이터베이스가 큰 병원이라면 백업 전 디스크 여유 공간을 미리 확인해주세요.

문제 해결

관련 문서

• GitHub 설정 가이드 , 원격 백업을 위한 GitHub 연결
• 배포 가이드 , 배포 전 백업 절차