업그레이드와 복구¶

변경 중에도 신원, 금전 의무, 감사 증거를 보존하세요. 새 권한이나 지출이 존재하면 오래된 DB 스냅샷으로 되돌리는 것만으로는 안전한 롤백이 되지 않습니다.

업그레이드 계획¶

현재·후보 커밋과 이미지를 고정하고 변경된 ADR·설정 스키마를 읽습니다.
프로파일, 권한 네임스페이스, 정책 세대, 참여 바이너리, CRD 버전, 신원 선언을 기록합니다.
격리된 스테이징에서 합성 신원·일회용 상태·가짜 공급자로 검증한 후 통제된 실제 모델 시험을 수행합니다.
관련 저장소를 일관되게 백업하고 격리 환경에서 복원을 확인합니다. SQLite는 적절한 백업 기능이나 중지된 서비스를 사용해 부속 파일을 포함하고, 비공개 노드 저널·감사 구간·모든 Postgres 신원/정책/권한 테이블을 보존합니다.
비호환 변경 시 이전 쓰기 주체와 게이트웨이를 중지·차단하는 방법을 정합니다. 발급된 권한을 추적하세요. 노드를 중지했다고 잔액이 미사용이라는 뜻은 아닙니다.
호환 바이너리·CRD를 배포하고 준비 상태, 키 교체, 거부 사례, 관측 사용량, 불확실성 유지, 감사 검증을 확인합니다.

지원되는 공급자·모델·가격 토폴로지는 SIGHUP으로 다시 읽을 수 있습니다. 백엔드, 신원 선언, 권한 모드, 노드 ID, 저널 경로, 리스너 변경은 재시작이 필요합니다. 스키마·프로파일 마이그레이션은 핫 리로드가 아닙니다.

장애 대응¶

장애	안전한 대응
CP 접근 불가	정책·권한 전달 복구. 설치된 준비 상태·정책 만료·권한 기한 준수
공유 Postgres 접근 불가	검증된 DB 경로 복구. 신규 공유 승인은 거부됨
노드 저널 접근 불가	영향받는 승인 중지. 저널과 부속 파일 보존
불완전 스트림·사용량 불명	미확정 의무를 예약 상태로 유지. 관측값과 공급자 증거 비교
감사 저장 대상·WAL 장애	WAL 바이트 보존. 필수 저장 대상 누적·WAL 실패는 새 추론 승인을 닫으므로 복구·대조 후 재시작
노드 유실	중앙 권한을 확정된 예약으로 유지. 만료는 환급 근거가 아님

ADR-045는 모든 조건 안에서 유효한 기존 로컬 권한만 사용할 수 있습니다. ADR-046의 신규 공유 승인은 항상 DB가 필요합니다. CP HTTP 장애와 DB 장애는 별도로 시험하세요.

권한 상태를 안전하게 복원¶

오래된 정책·신원·권한 행을 복원하면 백업 이후 사용한 예산이 되살아날 수 있습니다. 쓰기 주체를 차단하고 복원 상태를 공개하기 전에 백업 이후 모든 의무를 확인하세요. 완료된 지출, 열린 권한, 대기 중인 공유 허가, 지연 보고를 조정에 포함합니다.

미해결 권한을 확정할 수 없으면 영향받는 윈도를 동결 상태로 유지하세요. 접근할 수 없는 게이트웨이나 만료된 권한은 미사용 잔액의 증거가 아닙니다. 카운터 절단, 허가·권한 행 삭제, 실행 중 저널 복제, 새 계정 참조로 재발급하여 서비스를 복구하지 마세요.

자동 환급·조정 API나 일반적인 무중단 롤백 절차는 제공하지 않습니다. 영속 권한, 공유 저장소, 신원 마이그레이션의 구체적인 계약을 따르세요.

감사 승인 복구¶

buffer_then_block은 보관 WAL 기록 1024개 또는 WAL 추가·정리 실패 시 새 추론 승인을 닫습니다. 이 상태는 해당 프로세스에서 고정됩니다. 같은 가득 찬 WAL로 재시작해도 준비되지 않으며, 손상·절단된 WAL은 시작을 거부합니다. 게이트웨이는 WAL을 감사 저장 대상으로 자동 재생하지 않습니다.

영향받는 쓰기 주체를 중지하고 파일을 변경하기 전에 WAL, 인스턴스별 저장 구간, 관련 전달·체크포인트 증거를 정확한 사본으로 보존합니다.
저장 권한·용량과 필수 저장 대상 가용성을 복구합니다. 보관한 완전한 구간은 mayu audit verify로 검증하고 손상된 끝부분은 조사를 위해 별도 보존합니다. 조용히 버리지 마세요.
각 저장 대상이 이미 받은 기록을 대조합니다. 누락 기록은 정확한 줄 바이트, 인스턴스별 순서와 전달 체크포인트 또는 멱등성을 유지하는 격리된 대상별 절차로 복구합니다. 무조건 재생하면 일부 전달 중 이미 저장된 기록이 중복될 수 있습니다.
보관 증거를 아카이브하고 누락 전달을 처리한 뒤 새 구간을 위한 활성 WAL을 준비하고 재시작합니다. 보존·외부 검증 요구가 충족될 때까지 아카이브를 유지합니다. 트래픽 복원 전에 /readyz, 버퍼 메트릭과 새 기록의 전달을 확인합니다.

범용 감사 WAL 재생 CLI는 없습니다. 이 절차는 영속 저장에 도달하지 않은 기록을 복구하거나 호스트의 이력 재작성에 대한 저항을 증명하지 않습니다.

분석 근거 복구¶

분석 이벤트·rollup은 재구축 가능한 읽기 모델이며 감사 JSONL이 원본입니다. 이 복구는 키/거버넌스/신원·권한·grant·permit·정산 테이블을 바꾸지 않습니다. 투영 초기화·산정액 0·비용 누락을 환급이나 승인 잔액 복구로 취급하지 마세요(ADR-053).

프로파일·업그레이드 writer 버전·원본 구간 목록·보관 공백을 기록합니다. 정확한 원본 JSONL 바이트와 파생 DB, Mode B의 checkpoint/lease 메타데이터를 진단용으로 보존합니다. 일관된 백업을 사용하고 완전성을 주장하려고 원본·checkpoint를 삭제하지 마세요.
재생 전에 모든 analytics writer를 업그레이드합니다. 이전/새 writer 혼합 구간의 투영 완전성은 검증되지 않았습니다. 구버전은 Cost=nil을 건너뛰거나 보수적 기본 투영을 쓸 수 있습니다. 스키마 잠금 시간을 계획하고 격리 환경에서 롤백·복원을 시험하세요. 구버전 바이너리로 돌아가는 것만으로 검증된 롤백이 되지 않습니다.
아래 원본 복구 경로를 적용한 후 명시적 UTC 기간의 health/lag·보관 원본 건수·결과와 비용 불변식을 비교합니다. 과거 행이 0이어도 누락 원본 기간은 기록합니다.

SQLite Mode A¶

업그레이드한 index를 열면 누락 열을 멱등적으로 추가합니다. 기존 행은 has_cost=true, outcome_state=unknown, cost_state=legacy_unknown, projection_version=0을 유지합니다. 과거 HTTP 200만으로 성공·완전한 비용을 증명하지 않습니다. SQLite의 additive ALTER는 개별 적용되며 Mode-B 단일 backfill 트랜잭션과 다릅니다. 열기 중단 후 누락 열 마이그레이션을 재개할 수 있습니다.

재생할 보관 원본을 명시적으로 선택합니다. 게이트웨이 시작 시 Mode A는 설정된 audit.sinks의 각 file 경로에 Index.Replay를 호출합니다. 트래픽을 중지한 상태에서 업그레이드 바이너리와 의도한 Mode-A index/원본 file sink 설정을 사용하고 시작 재생 경고·summary/logs를 확인합니다. 시작 동작은 회전된 모든 archive를 발견하거나 stdout을 자동 복구하지 않습니다. 설정된 읽기 가능한 파일만 재생합니다. 원본을 보존하고 추가 archive 평가에는 격리된 원본 재생을 사용하세요. Mode-A HTTP rebuild나 감사 재생 CLI 명령은 없으며 rebuild 경로는 405입니다.

Replay는 동일 version-0 ID를 원본 근거로 version 1로 갱신하며 version-1 ID는 first-write-wins를 유지합니다. 반복 재생은 중복 집계하지 않습니다. 이전에 빠진 Cost=nil 완료 기록도 들어올 수 있습니다. 구버전 Cost=nil 원본은 unavailable, Cost가 있으나 사용량 근거가 없는 원본은 version 1에서도 legacy_unknown입니다. 불완전 JSONL 마지막 줄은 건너뜁니다. 원본이 없으면 보수적 version-0 행의 근거를 얻거나 누락된 비용 없는 이력을 복원할 수 없습니다.

PostgreSQL Mode B¶

최초 업그레이드의 시작 마이그레이션은 단일 연결·advisory lock·한 트랜잭션으로 이벤트/rollup 열을 추가하고 보관 파생 이벤트에서 rollup을 재생성합니다. 영속 마이그레이션 마커도 같은 트랜잭션에서 커밋하므로 현재 스키마를 다시 열 때는 rollup을 재작성하지 않습니다. 실패하면 열·backfill·마커를 함께 롤백해 재시도할 수 있으며 statement timeout을 복원합니다. 최초 업그레이드에는 스키마 잠금과 보관 이벤트 스캔이 필요할 수 있습니다. 이미 전진한 checkpoint 전에 구버전 수집기가 건너뛴 Cost=nil 원본은 복구하지 않습니다. 원본 구간과 checkpoint 백업을 보존하세요.

모든 writer 업그레이드 후 권한 있는 full admin이 기존 POST /admin/analytics/rebuild를 호출할 수 있습니다. 204는 초기화 성공이지 재생 완료가 아닙니다. 초기화는 파생 events/rollups/checkpoints를 비우고 lease epoch을 전진해 이전 worker를 차단합니다. 이후 수집기가 리더십을 다시 얻고 보관 원본을 처음부터 재생합니다. 오래된 epoch은 events·rollups·checkpoints를 바꾸지 못합니다. 재생이 따라잡을 때까지 /admin/analytics/health와 조회 결과를 확인합니다. PostgreSQL corrected-record upsert는 이전·새 팀/모델/날짜 그룹을 모두 재계산하며 반복 재생도 멱등적입니다.

원본이 만료되었으면 마이그레이션/rebuild가 없어진 이력을 만들 수 없습니다. legacy_projection_records 0도 전체 수집 증거가 아니므로 원본 보관·수집 drop·lag를 비교합니다. 검증과 보관 요구가 충족될 때까지 rebuild 전 백업·원본을 유지하세요.

이 절차는 구현된 복구 동작을 설명합니다. 로컬 합성 테스트와 일회용 PostgreSQL 검증은 ADR-053에 기록하며 live DB rebuild·운영 배포·유료 모델 검증 완료를 주장하지 않습니다.

운영 전에 필요한 증거¶

실제 복원·장애 조치 시험에서 복구 시간과 허용 데이터 손실을 기록하세요. CP 프로세스 장애와 DB 장애, 충돌 후 유지되는 불확실성, 과거 잔액을 보존하는 신원 교체를 포함합니다. 이는 직접 측정해야 할 인수 기준이며 이 문서가 제공하는 보장이 아닙니다.