백업/복구로직 변경, 깜빡임 버그 해결

2026-06-05 12:26:51 +09:00
parent 4bae1dd00d
commit 29038254dd
43 changed files with 3695 additions and 75 deletions
--- a/README.md
+++ b/README.md
@@ -527,6 +527,155 @@ docker compose --env-file .env --env-file config/.generated/auth-config.env -f d
 - **Hydra Public**: http://localhost:4444
 - **Kratos UI (UserFront)**: http://localhost:5000

+### 전체 백업/복구
+
+전체 백업/복구는 CSV export/import가 아니라 Baron SSO와 Ory Stack 저장소를 같은 시점의 재해 복구 단위로 보존하는 절차입니다. 사용자 UUID, Kratos identity ID, Hydra/Keto 원장, WORKS 연동 mapping이 어긋나면 안 되므로 운영 복구는 DB dump와 설정 snapshot을 함께 다룹니다.
+
+#### 백업 실행
+```bash
+# 전체 백업
+make dump
+
+# 출력 위치를 직접 지정
+make dump BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# 일부 서비스만 백업
+make dump DUMP_SERVICES=postgres,ory-postgres,clickhouse,ory-clickhouse,config
+make dump DUMP_SERVICES=ory-postgres,ory-clickhouse
+
+# 생성된 백업 검증
+make dump-verify BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# WORKS Drive로 외부 분산 저장
+make upload-cloud BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# 지정 경로로 dump 후 바로 WORKS Drive 업로드
+make dump-upload-cloud BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# 로컬 백업 목록
+make dump-list
+```
+
+기본값은 `DUMP_SERVICES=all`, `DUMP_MODE=maintenance`입니다. `DUMP_SERVICES`는 다음 값을 콤마로 조합할 수 있습니다.
+
+| 값 | 대상 |
+| --- | --- |
+| `postgres` | Baron Postgres (`baron_postgres`, `${DB_NAME:-baron_sso}`) |
+| `ory-postgres` | Ory Postgres의 `${KRATOS_DB:-ory_kratos}`, `${HYDRA_DB:-ory_hydra}`, `${KETO_DB:-ory_keto}` |
+| `clickhouse` | Baron ClickHouse (`baron_clickhouse`) |
+| `ory-clickhouse` | Ory ClickHouse (`ory_clickhouse`) |
+| `config` | `.env` redacted copy, generated Ory config, gateway, 주요 compose 파일 |
+
+백업 산출물은 기본적으로 `backups/baron-sso-backup-YYYYMMDD-HHMMSSZ/` 아래에 생성됩니다.
+
+```text
+manifest.json
+checksums.sha256
+postgres/
+clickhouse/
+config/
+reports/
+```
+
+#### WORKS Drive 외부 업로드
+
+`make dump`, `make restore`, `make upload-cloud`는 기본적으로 `docker/backup-tools/Dockerfile`에서 빌드한 `baron-sso-backup-tools:local` 컨테이너 안에서 실행됩니다. 호스트에는 Docker와 Docker socket 접근 권한만 필요하고, `zstd`, `jq`, `curl`, `openssl`, `postgresql-client` 같은 백업/복구 도구는 backup-tools image에 포함됩니다.
+
+`make upload-cloud`는 기존 백업 디렉터리를 `baron-sso-backup-*.tar.zst`로 묶은 뒤 WORKS Drive에 업로드합니다. 압축 포맷은 `.tar.zst`로 고정되어 있고, 압축/해제는 backup-tools 컨테이너 내부의 `zstd`로 수행합니다.
+
+백업이 완료되면 `reports/backup-report.md`도 생성됩니다. 이 report에는 사용자 수, 테넌트 수, RP 수, Hydra client 수, WORKS 관련 row count, 서비스별 수행 시간이 Markdown 표로 기록됩니다. `make upload-cloud`는 `reports/*.md`만 WORKS Drive 대상 폴더 아래의 `reports` 하위 폴더로 업로드하며, 업로드 파일명은 `backup-report-YYYYMMDD-HHMMSSZ.md`처럼 업로드 시각을 붙입니다. `reports/cloud-upload.json`은 로컬 업로드 실행 기록으로만 남기고 Drive에는 업로드하지 않습니다.
+
+```bash
+# 권장: 백업 경로를 명시해서 dump와 upload를 분리
+make dump BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+make upload-cloud BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# 또는 같은 BACKUP 경로로 연속 실행
+make dump-upload-cloud BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+
+# 실제 업로드 전 endpoint와 target만 확인
+make upload-cloud BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ WORKS_DRIVE_DRY_RUN=true
+
+# 예외적으로 호스트 도구로 직접 실행
+make restore BACKUP_USE_DOCKER=false BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ CONFIRM_RESTORE=baron-sso
+```
+
+주요 변수:
+
+| 변수 | 설명 |
+| --- | --- |
+| `WORKS_DRIVE_TARGET` | `sharedrive`, `mydrive`, `group`, `sharedfolder` 중 하나. 기본값은 `sharedrive`입니다. |
+| `WORKS_DRIVE_SHARED_DRIVE_ID` | `WORKS_DRIVE_TARGET=sharedrive`일 때 공용 드라이브 ID입니다. |
+| `WORKS_DRIVE_PARENT_FILE_ID` | 업로드할 대상 폴더의 WORKS Drive `fileId`입니다. 폴더 이름이나 경로가 아니며, 비우면 대상 drive/folder root에 업로드합니다. |
+| `WORKS_DRIVE_USER_ID` | `mydrive` 또는 `sharedfolder` 대상 사용자 ID입니다. 기본값은 `me`입니다. |
+| `WORKS_DRIVE_GROUP_ID` | `WORKS_DRIVE_TARGET=group`일 때 조직/그룹 ID입니다. |
+| `WORKS_DRIVE_SHARED_FOLDER_ID` | `WORKS_DRIVE_TARGET=sharedfolder`일 때 공유받은 폴더 ID입니다. |
+| `WORKS_DRIVE_ACCESS_TOKEN` | Drive API 호출용 Bearer token입니다. Drive API는 `file` scope가 필요합니다. |
+| `WORKS_DRIVE_ACCESS_TOKEN_FILE` | access token을 파일에서 읽을 때 사용합니다. |
+| `WORKS_DRIVE_ACCESS_TOKEN_CMD` | access token을 명령 출력으로 주입할 때 사용합니다. |
+| `WORKS_DRIVE_OAUTH_SCOPE` | Drive 업로드 앱 OAuth token에 사용할 scope입니다. 기본값은 `file`입니다. |
+| `WORKS_DRIVE_OAUTH_CLIENT_ID` | Drive 업로드 앱의 OAuth client ID입니다. 계정 동기화용 `WORKS_ADMIN_OAUTH_CLIENT_ID`와 분리합니다. |
+| `WORKS_DRIVE_OAUTH_CLIENT_SECRET` | Drive 업로드 앱의 OAuth client secret입니다. |
+| `WORKS_DRIVE_OAUTH_REFRESH_TOKEN` | Drive 업로드 앱의 refresh token입니다. 명시 access token이 없으면 이 값으로 access token을 갱신합니다. |
+| `WORKS_DRIVE_OAUTH_CLIENT_SERVICE_ACCOUNT` | Drive 업로드 앱의 service account입니다. JWT `sub`에 들어갑니다. |
+| `WORKS_DRIVE_OAUTH_CLIENT_PRIVATE_KEY_FILE` | Drive 업로드 앱 private key 파일입니다. 예: `./config/worksmobile-driveapp-private-key.pem` |
+| `WORKS_DRIVE_SPLIT_SIZE` | 분할 업로드 시 part 크기입니다. 기본값은 `9000M`입니다. |
+| `WORKS_DRIVE_MAX_SINGLE_FILE_BYTES` | 이 값보다 archive가 크면 split part로 나눕니다. 기본값 `0`은 자동 분할 비활성입니다. |
+| `WORKS_DRIVE_FORCE_SPLIT` | `true`이면 크기와 무관하게 split part로 업로드합니다. |
+| `WORKS_DRIVE_OVERWRITE` | WORKS Drive upload URL 생성 요청의 overwrite 플래그입니다. 기본값은 `false`입니다. |
+| `WORKS_DRIVE_UPLOAD_REPORTS` | `true`이면 `reports/*.md`를 Drive의 report 폴더로 함께 업로드합니다. 기본값은 `true`입니다. |
+| `WORKS_DRIVE_REPORT_FOLDER_NAME` | Markdown report를 업로드할 하위 폴더 이름입니다. 기본값은 `reports`입니다. |
+
+Drive API는 업로드 URL 생성 후 해당 URL에 multipart `Filedata`로 실제 파일을 전송하는 2단계 방식입니다. 계정 동기화용 `WORKS_ADMIN_OAUTH_*`와 Drive 업로드용 `WORKS_DRIVE_OAUTH_*`는 서로 다른 앱/키로 관리합니다. token 우선순위는 `WORKS_DRIVE_ACCESS_TOKEN`, `WORKS_DRIVE_ACCESS_TOKEN_FILE`, `WORKS_DRIVE_ACCESS_TOKEN_CMD`, `WORKS_DRIVE_OAUTH_REFRESH_TOKEN`, 서비스 계정 JWT fallback 순서입니다. 운영에서는 Drive API 권한과 `file` scope 위임 정책을 먼저 확인해야 합니다.
+
+#### 복구 계획과 복구 실행
+```bash
+# 복구 전 계획 확인
+make restore-plan BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ \
+  RESTORE_SERVICES=postgres,ory-postgres,clickhouse,ory-clickhouse,config \
+  CONFIRM_RESTORE=baron-sso
+
+# 복구 실행
+make restore BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ \
+  RESTORE_SERVICES=postgres,ory-postgres,clickhouse,ory-clickhouse,config \
+  CONFIRM_RESTORE=baron-sso
+
+# .tar.zst archive를 직접 복구 입력으로 사용
+make restore DUMP_FILE=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ.tar.zst \
+  RESTORE_SERVICES=all \
+  CONFIRM_RESTORE=baron-sso
+
+# report 경로를 명시
+make restore BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ \
+  CONFIRM_RESTORE=baron-sso \
+  RESTORE_REPORT=reports/restore/baron-sso-restore-report.json
+
+# 복구 후 기본 검증
+make restore-verify BACKUP=backups/baron-sso-backup-YYYYMMDD-HHMMSSZ
+```
+
+복구는 반드시 빈 volume 또는 restore 전용 stack에서 수행하는 것을 기본 정책으로 합니다. `make restore`는 `BACKUP` 또는 `DUMP_FILE` 중 하나와 `CONFIRM_RESTORE=baron-sso`가 없으면 실패하고, 기본적으로 non-empty Postgres 대상에는 복구하지 않습니다. 승인된 restore rehearsal에서만 `ALLOW_NON_EMPTY_RESTORE=true`를 사용하세요. `DUMP_FILE=.tar.zst` 해제도 backup-tools 컨테이너에서 수행하므로 호스트 `zstd` 설치에 의존하지 않습니다.
+
+`make restore`는 복구 report를 JSON과 Markdown으로 남깁니다. `BACKUP` 디렉터리 입력의 기본 JSON report는 `<BACKUP>/reports/restore-report.json`이고, `DUMP_FILE` archive 입력의 기본 JSON report는 `reports/restore/<archive-name>-restore-report.json`입니다. 같은 경로에 `.md` 확장자의 Markdown 요약도 함께 생성됩니다. `RESTORE_REPORT`로 직접 지정할 수 있습니다. report에는 입력 archive, 복구 서비스, checksum 검증 상태, 복구 후 대상 row count 비교 결과가 기록됩니다.
+
+`config` 복구는 운영 파일을 직접 덮어쓰지 않고 `config-restored/`에 풀어 수동 검토하도록 합니다. migration은 자동 실행하지 않으며, Ory Stack과 backend 기동 후 super admin login, 대표 OIDC login, WORKS comparison dry-run을 통과하기 전까지 WORKS relay를 자동 재개하지 않습니다.
+
+#### 백업/복구 범위
+
+필수 백업 대상:
+- Baron Postgres: users, tenants, user_login_ids, user_groups, RP metadata, WORKS mapping/outbox 등
+- Ory Postgres: Kratos identity/credentials/session, Hydra client/consent/token state, Keto relation tuple
+- Baron ClickHouse: 감사 로그와 RP usage event
+- Ory ClickHouse: Oathkeeper/Ory 계열 접근 로그
+- 설정 snapshot: `.env` redacted copy, generated Ory config, gateway, compose 파일
+
+기본 제외 대상:
+- Redis: pending login, short code, cache 등 휘발성 데이터이므로 복구 후 재수렴 대상으로 봅니다.
+- 프론트 빌드 산출물: 소스와 이미지 태그로 재생성합니다.
+- coverage, reports, test-results 같은 로컬 개발 산출물
+
+상세 설계와 운영 정책은 `docs/backup-restore-design.md`를 기준으로 유지합니다.
+
 ### MCP 서버 (Hydra/Kratos/Keto)
 MCP 서버는 기존 Hydra/Kratos에 연결하며 별도 Ory 스택이나 포트를 추가로 띄우지 않습니다.  
 프로덕션에서는 실행하지 않도록 `mcp` 프로파일을 로컬에서만 켜세요.