kevin/baron-sso

Fork 0

forked from baron/baron-sso

Files

Lectom 5c8a338085 feat: update worksmobile sync and restore planning

2026-06-01 17:01:53 +09:00

12 KiB

Raw Blame History

Baron SSO 전체 시스템 백업 및 복구 설계

목적

Baron SSO의 전체 시스템 백업/복구는 CSV export/import의 확장판이 아니라, 서비스 저장소 전체를 일관된 시점으로 보존하고 복원하는 재해 복구 기능이다.

핵심 목표는 다음과 같다.

사용자, 조직, 권한, RP, WORKS 연동 참조에 쓰이는 UUID를 그대로 보존한다.
Kratos identity subject와 Baron local user ID가 어긋나지 않게 복구한다.
Hydra/Keto/Oathkeeper 기반 인증/인가 상태를 서비스 가능한 수준으로 복원한다.
복구 후 WORKS externalKey 기반 비교/동기화가 기존 연동과 이어지도록 한다.
백업 산출물의 무결성, 보안, 복구 가능성을 검증 가능한 절차로 만든다.

배경과 결론

사용자 CSV는 user_id를 포함해 내보낼 수 있지만, 실제 사용자 계정의 주체 ID는 Kratos identity ID다. Kratos Admin API의 identity 생성 요청은 id 필드를 받지 않으므로, CSV import만으로 기존 사용자 UUID를 보장할 수 없다.

따라서 사용자 UUID 보존이 필요한 복구는 반드시 Kratos DB까지 포함한 full backup/restore로 처리해야 한다. CSV import는 운영 편의 기능으로 유지하되, 재해 복구나 WORKS 연동 보존 목적의 원장 복구 수단으로 간주하지 않는다.

백업 대상

필수 저장소

대상	저장소	포함 이유	복구 필수 여부
Baron 애플리케이션 DB	`baron_postgres`	users, tenants, user_login_ids, user_groups, api_keys, outbox, WORKS mapping, RP metadata 등	필수
Kratos DB	`ory_postgres`의 `ory_kratos`	identity UUID, credentials, verifiable/recovery addresses, sessions	필수
Hydra DB	`ory_postgres`의 `ory_hydra`	OAuth2 clients, consent, token/session 관련 상태	필수
Keto DB	`ory_postgres`의 `ory_keto`	ReBAC relation tuple 원장	필수
Baron ClickHouse	`baron_clickhouse`	감사 로그, 운영 추적 데이터	운영 정책상 필수
Ory ClickHouse	`ory_clickhouse`	Ory/Oathkeeper/Vector 계열 로그	운영 정책상 필수
설정/비밀값	`.env`, generated Ory config, WORKS private key, gateway/Oathkeeper config	동일 환경 재기동과 외부 연동에 필요	필수

선택 저장소

대상	처리 원칙
Redis	로그인 pending state, cache, short code 등 휘발성 데이터다. full restore에서는 원칙적으로 제외하고 재시작 시 비운다. 무중단 이전 시나리오에서만 snapshot을 검토한다.
프론트 빌드 산출물	소스/이미지 태그로 재생성한다. 별도 보관은 배포 재현성을 위한 선택 항목이다.
로컬 개발 산출물	reports, coverage, test-results 등은 백업 대상에서 제외한다.

백업 산출물 형식

백업 단위는 압축된 디렉터리 또는 object storage prefix로 관리한다.

baron-sso-backup-YYYYMMDD-HHMMSSZ/
  manifest.json
  checksums.sha256
  postgres/
    baron.dump
    ory_kratos.dump
    ory_hydra.dump
    ory_keto.dump
    globals.sql
  clickhouse/
    baron_clickhouse/
    ory_clickhouse/
  config/
    env.redacted
    env.encrypted
    ory/
    gateway/
  reports/
    row-counts.json
    restore-readiness.json

manifest.json에는 최소한 다음 정보를 기록한다.

backup format version
생성 시각, git commit, 이미지 태그
서비스별 DB schema/migration version
각 dump 파일의 checksum, 크기, 생성 명령 버전
백업 모드: offline, maintenance, online-best-effort
암호화 방식과 key id
복구 대상 환경 제한: same-env-only, staging-rehearsal, cross-env

백업 모드

1. Offline backup

가장 안전한 모드다. 모든 writer를 중지한 뒤 dump한다.

순서:

gateway 또는 Oathkeeper에서 maintenance mode 활성화
backend, relay worker, vector 등 write producer 중지
Kratos/Hydra/Keto public/admin 요청 차단 또는 컨테이너 중지
Baron Postgres dump
Ory Postgres의 Kratos/Hydra/Keto DB dump
ClickHouse backup
설정/비밀값 백업
checksum과 row count 생성
서비스 재개

이 모드는 사용자 UUID, WORKS mapping, Keto relation, OAuth consent 상태의 일관성이 가장 좋다.

2. Maintenance backup

짧은 점검 모드에서 writer만 막고 read는 제한적으로 허용한다. 운영 기본 모드로 권장한다.

필수 조건:

사용자 생성/삭제/수정 차단
테넌트/조직 변경 차단
WORKS outbox relay 중지
Keto outbox relay 중지
OAuth client 변경 차단

3. Online best-effort backup

무중단 스냅샷이다. 저장소가 여러 개라 cross-store 일관성을 보장할 수 없다. 감사 로그나 분석용 백업에는 가능하지만, 재해 복구용 원본으로는 사용하지 않는다.

Postgres 백업 전략

Postgres는 논리 dump를 기본으로 한다.

pg_dump -Fc 형식 사용
DB별 dump 파일 분리
pg_dumpall --globals-only로 role/extension/권한 정보 별도 보관
백업 전후 row count와 핵심 UUID sample 기록

대상 DB:

Baron DB: DB_NAME
Kratos DB: ory_kratos
Hydra DB: ory_hydra
Keto DB: ory_keto

복구는 빈 DB에 pg_restore --clean --if-exists로 수행한다. 기존 운영 DB에 덮어쓰는 in-place restore는 금지한다.

ClickHouse 백업 전략

ClickHouse는 감사 로그 성격이 강하므로 정책을 분리한다.

재해 복구: ClickHouse native backup 또는 volume snapshot 사용
장기 보관: 파티션 단위 export 또는 object storage backup
복구 검증: 날짜 파티션별 row count와 min/max timestamp 비교

ClickHouse 백업 실패가 인증 기능 복구를 막지는 않지만, 감사 로그 보존 정책상 별도 실패로 취급한다.

Redis 처리 원칙

Redis는 기본적으로 백업하지 않는다.

복구 후 영향:

로그인 pending flow 만료
short code/link login flow 재시작 필요
headless JWKS cache 재생성
세션 cache miss 발생 가능

Kratos/Hydra 자체 session/token 원장은 Postgres 쪽에 있으므로 Redis가 비어 있어도 서비스는 재수렴해야 한다.

설정과 비밀값

DB dump만으로는 복구가 불완전하다. 다음 항목은 암호화해서 함께 보관한다.

.env 또는 배포 환경 변수
Ory generated config
Hydra system secret, cookie secret
Kratos courier/config secret
Keto config
Oathkeeper rules/config
WORKS Admin OAuth client private key
API gateway 설정
object storage backup key id

env.redacted는 검토용이고, 실제 복구에는 env.encrypted만 사용한다.

복구 절차

Full restore 기본 절차

대상 환경을 새로 준비한다.
모든 애플리케이션 서비스를 중지한다.
기존 DB가 있으면 별도 보관 후 빈 DB를 만든다.
Postgres globals를 복구한다.
Baron DB를 복구한다.
Kratos/Hydra/Keto DB를 복구한다.
ClickHouse를 복구한다.
설정/비밀값을 복호화해 배치한다.
migration은 자동 실행하지 않고 현재 dump의 schema version을 확인한다.
Ory Stack을 기동한다.
backend를 기동한다.
relay worker는 아직 켜지 않는다.
post-restore verification을 수행한다.
WORKS comparison dry-run을 수행한다.
문제가 없을 때 relay worker와 외부 동기화를 재개한다.

Post-restore verification

필수 검증:

Kratos identity 수와 Baron users 수 비교
Baron users.id가 Kratos identities.id에 존재하는지 확인
tenant parent tree 참조 무결성 확인
user_login_ids.user_id, user_login_ids.tenant_id 참조 무결성 확인
Keto relation subject/object가 복구된 사용자/테넌트를 참조하는지 확인
Hydra client와 Baron RP metadata 참조 확인
WORKS mapping의 BaronResourceID가 복구된 사용자/테넌트를 참조하는지 확인
super admin 로그인 확인
일반 사용자 로그인 확인
대표 RP OIDC login/consent 확인
WORKS comparison dry-run에서 externalKey 기준 대량 삭제/생성 후보가 없는지 확인

WORKS 연동 복구 정책

WORKS 자체 데이터는 Baron 백업으로 복구하지 않는다. Baron이 보존해야 하는 것은 WORKS와 연결되는 참조 키다.

필수 보존:

사용자 UUID
테넌트 UUID
WORKS resource mapping
WORKS outbox 처리 상태
WORKS domain mapping/config

복구 직후 정책:

relay worker 자동 실행 금지
comparison dry-run 먼저 실행
externalKey 기준으로 Baron/WORKS가 매칭되는지 확인
대량 delete/upsert가 감지되면 동기화 중단
확인 후 필요한 사용자/조직만 재동기화

outbox는 복구 모드에 따라 처리한다.

복구 모드	outbox 정책
같은 운영 환경 재해 복구	outbox 상태 보존, 단 relay 재개 전 dry-run 필수
staging rehearsal	outbox relay 비활성화, 외부 WORKS 호출 금지
cross-env migration	outbox는 보존하되 실행하지 않고 별도 remap 정책 필요

CSV export/import의 위치

CSV는 다음 목적으로만 사용한다.

운영자가 사용자/조직을 일괄 등록하거나 보정
일부 필드를 검토하기 위한 추출
dry-run 입력 보조 자료

CSV는 다음 목적에 사용하지 않는다.

Kratos identity UUID 보존 복구
비밀번호/credential 복구
OAuth consent/token/session 복구
Keto relation 원장 복구
WORKS mapping 원장 복구

구현 계획

Phase 1: 백업/복구 스크립트와 문서화

Estimate Time: 3~5d

scripts/backup/full-backup.sh
scripts/backup/full-restore.sh
scripts/backup/verify-backup.sh
scripts/backup/verify-restore.sh
manifest.json 생성기
checksum 생성
row count report 생성

Phase 2: staging restore rehearsal