# DR詳細設計:実施計画・受入試験・導入判定 設計版:DR-D1、2026-09-27。**詳細設計完了、実装作業は未着手。** ここでいう実装作業はDR-D1の再参加・役割分離protocol。既存のoffline DR CLIは別の初版。 今回の成果物は文書のみであり、DB・migration・本番配置を変更する作業指示ではない。 ## 1. 設計成果物と完了条件 | 成果物 | 本版で定義した範囲 | | --- | --- | | [役割・再参加](dr-authority-and-rejoin.md) | CG/DG/Instance、writer連動境界、identity、状態機械、設定・UI・権限 | | [protocol・同期](dr-protocol-and-sync.md) | 認証probe、API、authority契約、checkpoint、manifest v3案、切替・失敗時動作 | | 本書 | 実施順、予定変更箇所、DB別件への接続条件、試験、導入/撤退手順 | | [初版記録](disaster-recovery.md) | 既存機能と制約を保持し、DR-D1と区別 | - [x] primaryを管理/データに分け、物理保存境界による連動条件を記述。 - [x] 起動・probe・Learning・同期・昇格・preempt・失敗からの再参加を定義。 - [x] 身元、世代、許可、同期内容、承認、未知損失の扱いを定義。 - [x] API入出力、サイズ上限、再試行、冪等性、切替phase、認可主体を定義。 - [x] DBを変更せずに準備できる範囲と、保存担当との合意待ち範囲を分離。 - [x] 実装タスク、依存、合格条件、障害注入試験、導入/撤退条件を定義。 - [ ] 実装・実機でのfencing認定・復旧訓練・本番反映。 「詳細設計完了」は実装方針と判断規則を定義した状態であり、未知の本番設備の能力を保証した 意味ではない。RPO/RTO値、ノード数/FQDN、fence機器、容量、鍵保管先は導入時の必須入力として残す。 これらを未設定のまま自動運転へ移行することはできない。 ## 2. DB別件との作業境界 本タスクでは以下を行わない。 - アプリDBへのSELECTを含むアクセス、DBのコピー・バックアップ・復元、schema inspectの実行。 - SQL/DDL/migration/repositoryの編集、コード生成、サーバ起動、CLIによるデータ操作。 - compose、認証鍵、federation token、node設定、稼働コンテナ、外部カレンダーへのアクセス。 - 文書を本番Wikiへアップロードする操作(アップロードもDBへの書き込みになるため)。 読み取る対象は設計書と必要最小限のソースコードだけ。ドキュメントの静的整合性確認を実施する。 別件の変更を前提にDBの物理分割方法やテーブル名を確定させない。 保存担当へ渡すinterface要求は次の通り。応答はSQLの実装ではなく、能力の宣言とテスト結果で受け取る。 | 契約 | 保存担当に確認する事項 | 未提供時の挙動 | | --- | --- | --- | | Resource map | metadata/可変正本/署名発行状態が共有するwriter境界 | shared-instance連動のみ | | Schema inspection | 非破壊・read-onlyでの互換性/世代取得 | 復旧世代をservableにしない | | Consistent cut | DBとcalendar等を同じ論理時点で固定できる範囲 | 全writer停止snapshotのみ | | Durable pin | snapshot/GC/転送/再起動を跨ぐ参照保持 | online同期不可 | | Restore activation | 新generationの検証、root切替、途中停止からの復旧 | 自動復元不可、既存手動手順のみ | | Manifest apply | 管理内容と受理位置のatomic commit | manifest v3配信不可 | | Write fencing | 旧許可を実際の書込み先で拒否できるか | 外部fence必須 | | Durability receipt | client成功応答済み更新がreplica上で永続化された境界 | 自動無損失failover不可 | | Identity/secret inventory | logical service keyとphysical node keyの区別 | nodeを自動参加させない | 合意前に作業できるのは仕様型、pure state machine、mock provider、観測専用probe、 静的UI/認可契約の設計まで。runtimeへのwrite gate接続も、別件の保存経路を網羅できることを 確認してから行う。この順序は「DBが共有のままでもroleのflagだけ先に動かす」ことを禁止する。 ## 3. 実装タスクと依存順 以下は将来の予定。行が存在しても対象ソースを今回変更しない。 | ID | 実施内容 | 主な変更予定箇所 | 依存 | 完了判定 | | --- | --- | --- | --- | --- | | DR01 | version付き型、ID/epoch/構成検証、resource coupling planner | `internal/dr`の新model/config/planner | 設計D1 | 不正構成・独立不可・未知版を拒否。DB依存なし | | DR02 | pure state machineとoperation phase reducer、fake clock | `internal/dr`のstate/operation | DR01 | 不変条件N1〜N10の遷移試験。失敗時はwriterを開かない | | DR03 | 専用node identity、mTLS/署名/nonce、観測専用probe | `internal/dr`のtransport、server管理route | DR01 | 未認証/別group/replayを拒否。probeでroleが変わらない | | DR04 | runtime startup gateの接続、非DR互換、旧CLI禁止 | `cmd/pageswiki/main.go`、server middleware、store/CLI全writer入口 | DR02/03+保存経路合意 | 再起動で必ずrecovering。起動修復/workerも許可前にwriteしない | | DR05 | AuthorityStore interface、manual provider、etcd providerと限定service | `internal/dr`のauthority、専用運用cmd | DR01/02 | CAS競合/timeout/再起動でgrantが二重にならない | | DR06 | checkpoint adapter、世代/pin台帳、schema/read-only検証 | 既存`internal/dr/snapshot.go`と保存担当adapter | DR01+保存契約合意 | offline fixtureから再開可能。online未対応を明示拒否 | | DR07 | 認証済みmanifest/Range転送、recipient ACK、負荷制御 | DR transport、documentstore adapter、scheduler表示 | DR03/06 | 中断再開/破損/別groupアクセス/容量不足を検出 | | DR08 | v1/v2 anchor移行、管理manifest v3発行/受理/ACK | federation manifest、enroll/reconcile、受理repository | DR03/05/06+受理永続化合意 | 同内容再送・旧epoch・欠落履歴・rollbackを正しく処理 | | DR09 | fence provider契約、impact planner、証跡照合 | DR fence/operation、運用connector | DR05 | 隔離未確認/誤node/別boot/別group影響で昇格拒否 | | DR10 | 手動switchover/failover/reseedをoperationへ統合 | DR CLI/API、root activation、routing adapter | DR04〜09 | 完全fixtureでroleごとの切替と共有DB連動が成立 | | DR11 | preempt planner、自動coordinated gate、cooldown | DR policy executor | DR10+設備認定 | flapping抑制、0損失の計画復帰、不可条件時の提案のみ | | DR12 | DR管理UI、i18n、health、Inbox、監査集約 | config panels、status APIs、metrics | DR03/10+operator認可 | group別表示、権限境界、秘密非表示、plan/applyが一致 | | DR13 | v0移行/本番runbook、復旧訓練、負荷/障害試験 | docs/operations、隔離検証環境 | DR10/12 | 受入matrix全通過、RPO/RTO実測、明示承認後のみ有効化 | DR04以降のコード接続は、DB別件の差分が落ち着き接続点が合意された後。 DR08のschema実装は保存担当の変更計画に載せ、DRタスクが独自migrationを追加しない。 DR09の機器connectorは任意shell入力ではなく、許可された設備・resource IDへのtyped操作とする。 ### 段階リリース | 段階 | 提供するもの | 明示的に提供しないもの | | --- | --- | --- | | L0:現行初版 | offline snapshot、検証、手動復元・昇格 | 再参加判定、オンライン同期、自動fencing | | L1:観測 | DR01〜03、状態の参照UI | 自動昇格、既存writerのruntime変更 | | L2:再参加gate | DR04/05、operator承認下の起動、shared bundle判定 | 未接続の保存経路があるprofileの有効化 | | L3:同期・手動切替 | DR06〜10、認証転送、group別の計画操作 | 未認定providerの自動切替 | | L4:自動主系復帰 | 認定済みDR11/12、coordinated preempt | snapshotのみを根拠にした無人・無損失failover | | L5:自動障害復旧 | replica durability receipt等が揃うprofileのみ | 未複製更新や未知損失の黙認 | 各段階で有効化フラグは既定off。capabilityの揃わない段階へUI操作で飛び越せない。 L1の観測機能が動作しても「Learningから自動で昇格できる」と表示しない。 ## 4. CLI・API・UIの実施内容 将来CLI案(すべて未実装、DB直接更新用コマンドではない): ```text pageswiki dr config validate --file pageswiki dr groups status --group pageswiki dr rejoin plan --group --node pageswiki dr switchover plan --group --to pageswiki dr failover plan --group --to pageswiki dr operations apply --plan --plan-sha256 pageswiki dr operations show --id pageswiki dr operations cancel --id pageswiki dr reseed plan --group --node --checkpoint ``` 現行の `dr promote` はL0専用とする。D1管理されたdatasetでは旧epochの手動書換えに ならないよう拒否し、operationへ案内する。旧binary/旧CLIもwriterとして動けない配置制約を 設ける。新設定ファイルの存在を古いbinaryが無視する可能性は、file markerだけでは解決しない。 online CLI、Web、policy executorは同じplan/operation serviceを使う。 dry-run/planはfence・permission・同期実体を変更しない。operatorがCLIから秘密付きbackupを 扱えることと、campus_adminがWebから全DBをダウンロードできることを同一にしない。 UIは最初に観測だけを実装し、operationが完成した段階で切替ボタンを追加する。 コンパクトなgroup一覧、control/dataの別ラベル、preempt状態、同期点、ブロック理由を優先する。 確認dialogには「どのCampus/Domain/同居groupが止まるか」「失う可能性のある期間」 「隔離手段」「未達条件」を列挙する。UNIX時刻入力や、色だけの安全判定は使わない。 ## 5. 受入試験マトリクス テストはfake clock/fake authority/fake fence/一時保存領域から開始し、 実カレンダー・個人文書・本番ノードには接続しない。各テストは最終状態だけでなく、 途中のwriter許可集合を記録し、同一resourceで2 holderになっていないことを検査する。 | ID | 入力・障害注入 | 期待結果 | | --- | --- | --- | | T01 | primary記録を持つnodeが再起動、peer応答なし | recovering→blocked、migration/worker含めwrite 0 | | T02 | 非DR instance起動 | 従来の起動を維持。DR期待環境で設定欠落なら起動拒否 | | T03 | 別group、未知鍵、同FQDNで別fingerprint、失効nodeからprobe | 認証/認可拒否、WARNING。membership変化なし | | T04 | 古いboot/nonce、応答遅延、重複JSON key、未知protocol、大きすぎるbody | 状態遷移なし。入力種別に応じたerror | | T05 | peerが大きいepoch/primaryを自己申告、authorityは異なる | 再確認・conflict、安全側停止。自己申告で昇格なし | | T06 | 発見peerの半数以上が同じ内容、登録authorityに到達不能 | 観測の多数決でgrantを出さない | | T07 | 同一DBのCG/DGが別holderを要求、alias resourceも混在 | WRITER_BOUNDARY_COUPLED、連動planを提示 | | T08 | 独立storeのCG停止、DGは有効grantと設定を保持 | CGだけ停止。DGは権限鮮度条件の範囲で継続 | | T09 | CGのpreempt on、DGのpreempt off | 独立profileならCGのみ戻る。sharedなら連動影響を承認前に提示 | | T10 | primaryの停止・再開、時計逆行、VM pause、permit応答喪失 | stale permitでwrite再開なし。新grantにはfenceを要求 | | T11 | 2 executor/2 candidateが同時に同group操作、response消失、manual agent二重起動 | 一つのoperation/grantだけ確定。同じIDで結果照合、manual agent排他 | | T12 | fence要求送信済みだが確認不明、別node/古いbootの証跡 | FENCE_UNCONFIRMED、grantなし | | T13 | ホストfenceが別DG primaryにも影響 | 自動preempt禁止、impactに全groupを列挙 | | T14 | capture中にDB更新・calendar世代更新・GC・schema変更 | barrier/capabilityに従い排他。保証不能ならcapture中止 | | T15 | 転送中断/Range再開、chunk改変、symlink/path traversal、未登録file ID | 検証失敗、他データを読ませずactive root不変 | | T16 | blobの一部欠落、calendar参照世代欠落、schema不適合、secret欠落 | verified/applicable ACKなし、standby公開なし | | T17 | pin後にsource再起動、transfer期限切れ、GC/保持処理 | 必要世代を消さない。残存pinを照合して回収 | | T18 | 同期中に新しいwrite、表示上lag=0だが最終cut未確定 | switchover不可。final checkpointの一致を必須とする | | T19 | metadataのみ最新、ACL/session失効は古い | read/write readinessとも不成立 | | T20 | 旧primaryに現系列にない更新 | 隔離保全、conflict。自動マージ/削除なし | | T21 | manifest旧epoch、同sequence異hash、欠落親、receiptなし | 適用拒否。v3導入後のv1/v2 downgradeも拒否 | | T22 | 内容適用と受理checkpointの間で失敗、publication receipt応答喪失 | 一体rollback/同内容照合。別payloadで再発行しない | | T23 | controller復元点が管理ノード受理位置より古い | blocked、epochを増やして古い権限を再配信しない | | T24 | 各operation phaseの前後でprocess kill | 文書化したphaseから再開。REVOKING以降は旧epoch復活なし | | T25 | GRANTED後root切替失敗、RO filesystem、disk full、fsync失敗 | 新primaryを公開せず、次の復旧operationへ | | T26 | routing更新失敗、DNS cacheに旧宛先、既存keep-alive | 新primaryは一つ。旧宛先はwrite拒否、routing修復 | | T27 | 同期済みpreferred nodeが繰り返しflap、時間帯/DST境界 | 安定時間リセット、cooldown遵守、不要な再切替なし | | T28 | snapshotの鮮度はRPO内だがclient成功応答の反映が不明 | 自動障害昇格不可。損失確認をoperatorへ要求 | | T29 | grant lease失効/authority quorum喪失/watch欠落 | 新grantなし。local gate期限で停止、外部fence前は他holder不可 | | T30 | AuthorityStoreを古いbackupへ復元、manual台帳の破損/消失 | 全writerを隔離、新trust世代の手動復旧。epochの黙認・自動初期化なし | | T31 | high IO/CPU/foreground要求増、巨大snapshot | stream/帯域/hash上限を維持。制御通信が転送に埋もれない | | T32 | campus_admin/domain_adminが他scope切替/backup秘密を要求 | 拒否。read UIも他Campus・secretを漏らさない | | T33 | restart後workerが過去jobを拾う、外部通知結果が曖昧 | 許可と再送条件を確認。曖昧な副作用は自動で成功/再送しない | | T34 | operatorがcancel/disable/旧binaryへのrollbackを要求 | 安全点だけ取消。active grantを消して旧系を復活させない | T24はPLANNED〜COMPLETEDの全境界で行う。ネットワークを切るタイミングも 「要求送信前」「相手がcommit後、応答前」「応答後、ローカル永続化前」に分ける。 fixtureの全writer経路を一度ずつ実行し、HTTP guardだけで満たしたと判定しない。 ## 6. 性能・運用の合格条件 固定のRTO保証値を現時点で作らず、次の測定結果を導入記録に残す。 - 通常foreground p50/p95/p99と、同時同期時の差。目安の許容悪化率は10%以内、超過なら転送予算を縮小。 - DB/可変正本のbarrier時間、checkpoint作成時間、初回/増分転送時間、検証時間、必要空き容量。 - suspect検知、fence確認、grant、起動、routing完了の各所要時間と合計RTO。 - 障害時点と最後のDR側検証cutの差、client成功応答境界の確認可否、未複製損失の有無。 - スナップショット10万/100万file相当のmanifest paging、RSS/heap、descriptor数の上限。 初版v1の10万file上限を、v2の性能試験なしに解除しない。 - 一日継続のprobe/転送/再起動試験で、timer・goroutine・scratch・pin・operationが無制限に増えない。 10%は候補性能予算であり、実機測定前に達成と表明しない。別件の保存層の性能評価と同じ fixture条件を使用する。外部サービス/実データにアクセスする実機試験は別途承認を得る。 ## 7. 導入時に入力・承認する事項 設計として未決のアルゴリズムではなく、設備・運用に依存する導入パラメータを列挙する。 | 入力 | 決定する主体 | 未入力時 | | --- | --- | --- | | node FQDN/管理origin、node identity、対象Campus/DG、resource対応 | 運用者+保存担当 | 登録・同期を開始しない | | RPO/RTO、retention、容量/帯域予算 | 運用者 | 本番enable不可 | | authority配置、CA、専用service key保管/更新、quorum障害領域 | 運用者 | manualのみ | | fence機器/credential参照、再起動抑止、影響group | 運用者 | coordinated enable不可 | | backup/secret暗号化と復号担当、別障害領域の保全先 | 運用者 | 秘密付き転送不可 | | CG/DGごとのpreferred、preemptと許可時間帯 | 運用者+管理者 | preempt off | | 保存profile能力と対応app/image/schema | 保存担当 | offline/shared-instanceのみ | ## 8. 本番導入手順 1. 運用者が対象と入力を確定し、保存担当がresource map・能力契約を承認する。 2. 本番とは通信しない隔離fixtureで対応段階のT01〜T34と負荷試験を実施する。 3. 既存環境の保全・image digest・schema互換性・復旧手順をレビューする。実データ保全は別途承認。 4. L1観測のみを配置し、比較表示を確認する。旧roleに基づくサービス挙動はこの段階では変えない。 5. 全writerと旧CLIを停止する保守枠を取り、L2への移行planを確認する。 6. 旧cluster/node/roleを新group/resourceに対応させ、fresh authorityをbootstrapする。 旧primaryの確認記録を付け、元のepochを新authorityの根拠にしない。 7. 新startup gate下で起動し、他nodeはlearnerとして参加。sourceと同期内容を検証する。 8. L3の手動switchoverと復帰を1往復実施し、RPO/RTO・監査・権限失効・queueを検証する。 9. 保存分離済みprofileならCG/DGの独立切替、共有profileなら連動拒否/連動切替を確認する。 10. 能力が揃ったgroupに限り、明示承認を得てL4を有効化する。L5は別の認定を要求する。 ローリング移行中、旧ノードをwriter候補に残さない。mixed protocolで書込み可能nodeを 増やす移行はしない。旧nodeからのprobeは対応版を表示し、新grant候補から除外する。 管理manifest v3は全対象が移行anchorをACKした後に切替える。 ## 9. 撤退・失敗時 DRの「無効化」は設定ファイル削除ではない。新operation受付を止め、active operationを照合し、 一つのwriterを運用者が確定・隔離確認してから非DR運用への移行planを実行する。 authorityを停止しただけで旧nodeに書き込みを許可しない。 L1だけなら観測プロセスを停止して戻せる。L2以降はrole/許可/DB互換性の記録を保持する。 新epochでwriteが発生した後は、旧snapshotを起動することでrollbackしない。 旧binaryに戻す場合は、最新データとschema互換性を検証し、DRのtrust/gateを無視するbinaryが 同時に動かないことを外部で保証する。保証できなければ停止を継続する。 実施結果には、適用していない段階、満たしていない能力、最後に検証した世代、 次に必要な承認を必ず残す。設計完了・実装完了・復旧訓練完了・本番稼働を同じチェックにしない。