# DR詳細設計:管理主系・データ主系・再参加 設計版:DR-D1、2026-09-27。**設計のみ。記載したAPI・状態機械・設定は未実装。** 今回の作業は文書のみを変更し、DB、schema、migration、実行コード、配置設定、本番データを変更しない。 既存の停止snapshot/手動昇格は [初版の実装・運用記録](disaster-recovery.md) に残す。 ## 1. 文書体系・決定の適用範囲 - 本書:責務、identity、再参加状態、書き込み条件、障害時判断、設定・UI。 - [通信・同期・主導権移譲契約](dr-protocol-and-sync.md):メッセージ、URI、検証、切替と保全。 - [実施計画・受入試験](dr-delivery-plan.md):作業単位、変更予定箇所、依存、導入・撤退手順。 DR-D1は初版文書の「次段階」の設計を具体化・更新する。初版の `role` や `epoch` の意味を 黙って変更せず、旧形式の移行は別の明示的操作とする。以下のMUST相当の条件は、 「できれば実装する」事項でなく、機能有効化の前提とする。 DB別件の完了を待たず、wire型・純粋な状態機械・認証probe・表示の実装準備はできる。 一方、writerを開く接続、online snapshot、manifest受理checkpointの永続化、 独立した主系切替は、保存層の契約確認と別途の実装承認まで無効とする。 ## 2. 決定一覧 | ID | 決定 | | --- | --- | | D01 | Campusの管理primaryとData replica groupの書き込みprimaryを分離する | | D02 | Instanceに全体共通のprimaryフラグを持たせず、役割はgroupごとに表現する | | D03 | 同じ物理writer境界を共有する役割は連動切替する。論理分離だけで独立writerにしない | | D04 | DR対象プロセスは再起動時に必ずrecoveringから入る。保存済みroleではwriterを開かない | | D05 | discovery/probeは情報収集。参加許可、昇格承認、正本の決定とは別 | | D06 | 発見したpeerの数や、最大の自己申告epochだけでは主系を選ばない | | D07 | 主系選定の既定はmanual、preempt既定はoff。自動モードは別の能力認定が必要 | | D08 | 自動裁定の最初の実装先は外部etcd v3 APIとする。PagesWiki独自Raftは作らない | | D09 | lease切れ・HTTP不通だけでは旧writer停止の証拠にならない。新grant前にfencingを要する | | D10 | 元primaryの未同期更新は隔離保存し、現primaryへ自動マージしない | | D11 | 共有DB環境での最初の同期単位はデータディレクトリ全体。Domain単位のSQL差分複製はしない | | D12 | バックアップ世代、データ書込世代、管理manifest世代を混同しない | | D13 | 状態収集/authority監視は通常のイベントキューに依存させない。大容量転送は低優先度 | | D14 | 主系復帰は同期→drain→最終checkpoint→権限移譲の協調的切替とする | etcd採用は自動モードの設計上のprovider選択であり、この変更でサービスを導入しない。 運用でetcdを用意しない場合もmanualの保全・復元を使える。実際のprovider配置、電源/保存先の fence手段、容量と目標RPO/RTOは導入時の入力であり、推測して本番設定に書かない。 ## 3. 三つの境界 ### 3.1 論理サービス | 対象 | 不変のidentity | 主系の責務 | 待機系に複製するもの | | --- | --- | --- | --- | | Controller group(CG) | group UUID、Campus UUID | Campus設定、Domain配置、管理側継承情報、設定manifest発行 | 管理正本、発行履歴、承認済み構成、復旧用鍵参照 | | Data replica group(DG) | group UUID、dataset UUID | Domainのページ/asset/カレンダー/タスク/ローカル権限等の更新 | metadata、CAS、可変正本、失効情報、outbox/checkpoint | | Instance | node UUID、ノード固有鍵 | 上記役割を実行する場所 | Instance自体を業務正本のownerとしない | 1 Campusにつき管理authorityは1 CG。1 DGは複数Domainを持てる。1 Domainは同一時点では 1 DGへ配置する。複数Campusのデータが1 DGに共存することも、既存DB構成の間は許容する。 CGのprimaryはDGのprimaryである必要はない。ただし次節の物理境界制約に従う。 Campus/DomainのUUID、FQDN、Path、ユーザー領域のURIは維持する。 Domain配置の将来形式は `replica_group_id` を正本にし、現在primaryのFQDNは解決結果とする。 物理ノード移動をDomainの改名として記録しない。旧 `placement_instance_fqdn` は移行中の 互換表示に限り、二つの値を別々のauthorityが更新する方式は採らない。 ### 3.2 保存領域のwriter境界 `WriterResource` はDB、可変正本ストア等の実際の排他単位を表す。ローカルpath文字列だけで なく保存層が提供する安定したresource identityで識別する。複製コピー同士も同じ論理正本の writer resourceに属する。NFS上のSQLiteを別resourceと見せるような登録を拒否する。 各役割は更新するresourceの集合を宣言し、共有resourceを持つ役割の推移的なまとまりを `coupling_bundle` とする。同じbundleのwriter許可は一括で一つのnodeにだけ与える。 例:CG1とDG1がpages.dbを共有、CG2も同じDBを更新するなら三役割すべてを連動させる。 テーブル名が異なっていても、DB全体を物理snapshotで複製する間は分離しない。 独立切替を許可する条件は、保存担当が次の能力を明示すること。 - 対象の正本、派生projection、署名発行状態に独立した所有者とwriter境界がある。 - 役割間の更新はversion付きのprotocolとして受理でき、別役割のDBへ直接書かない。 - 対象resourceへの旧writerのアクセスを実際に停止できる。 - role/resource対応の構成世代が全参加者で一致する。 能力が未申告なら `shared-instance` とし、独立切替要求は `WRITER_BOUNDARY_COUPLED` で拒否する。 不足能力を理由にDB分割・DDLを自動実行しない。 ### 3.3 障害・隔離の影響範囲 role単位で保存領域が分かれても、fenceがホスト電源断なら同居する全groupへ影響する。 切替planは「writer連動範囲」と「fenceの影響範囲」を別々に計算する。 他groupのprimaryまで停止するplanは、自動preemptしない。運用者の明示承認と、影響groupの サービス継続計画を必要とする。group単位のfence能力があると偽装して回避しない。 ## 4. identity、保存位置、世代 以下は論理レコードの契約であり、RDBのテーブル定義ではない。 | レコード/値 | 保存主体 | 更新ルール | | --- | --- | --- | | Membership | AuthorityStore | group種別、member/learner、鍵、resource対応。expected revisionでCAS | | NodeIdentity | ノードローカル保護領域 | node UUIDと専用鍵。業務snapshotから他ノードへ複製しない | | `boot_id` | 各プロセス | 起動ごとに乱数UUID。過去のgrant/probe応答を再利用しない | | `trust_generation` | AuthorityStore+運用保全 | authority自身の災害復旧時に明示更新するtrust世代 | | `control_epoch` | CG authority | CGの主導権交代ごとに単調増加 | | `data_epoch` | DG authority | DGの書込権交代ごとに単調増加 | | `resource_epoch` | writer resource authority | 共有保存境界の許可更新。bundle全体で矛盾なく確定 | | `manifest_sequence` | CGの管理正本 | control_epoch内の管理配信順序。data_epochとは比較しない | | Checkpoint | 保存層+受信側 | dataset、epoch、cut ID、親checkpoint、内容hash、検証ACK | | Operation | AuthorityStore | 永続したintent、phase、expected世代、証跡、結果。timeoutで削除しない | | Node runtime state | メモリ+ノードローカル記録 | 観測状態。書込権の正本にはしない | 初版 `dr-node.json` の `epoch` は監査値なので、control/data epochへコピーしてauthorityと みなさない。旧 `cluster_id` は移行mapで既存の復旧単位へ対応させる。 DR-D1では物理ノードを維持した世代更新でnode UUIDを変えず、`dataset_generation`を更新する。 新しい物理ノードは新規identityを登録する。初版のrestoreによる採番との差は移行計画に明記する。 単に最大のepochを採用しない。有効なのは、信頼済みauthorityが登録したtrust世代・group・ membershipに結び付いた証明だけ。timestampは監視用で、履歴の新旧や正本選定に使わない。 ## 5. 設定契約 設定案の中心は次のGroupPolicy。ノード一覧に秘密値を埋め込まず `secret_ref` を用いる。 | 設定 | 既定/検証 | 意味 | | --- | --- | --- | | `kind` | 必須:control/data | 二つの役割を混同しない | | `coordination_mode` | manual | manual / coordinated。Campusの既存authority_modeとは別項目。自動モードは必要能力の全検査を要求 | | `members` / `learners` | 明示登録、重複不可 | 発見しただけのpeerをmemberへ追加しない | | `preferred_node_id` | 未指定 | 期待する主系。実際のprimaryを上書きする値ではない | | `preempt` | off | off / manual / automatic。controlとdataで別設定 | | `stable_for_seconds` | 300、範囲60〜86400 | preferred nodeが継続して正常・同期済みである必要時間 | | `switch_cooldown_seconds` | 1800、stable以上 | 交代直後の再切替を抑制。障害対応は別の明示操作 | | `preempt_window` | 空=時間制限なし | 任意の許可時間帯。タイムゾーン必須、DSTは計画時にUTCへ解決 | | `probe_interval_seconds` | 5、範囲2〜60 | ±20% jitter。leaseの更新周期とは別 | | `probe_timeout_seconds` | 2、範囲1〜10 | 接続・応答の合計deadline | | `suspect_after_failures` | 3、範囲2〜10 | 表示をsuspectにするだけ。これで昇格しない | | `read_policy` | disabled | disabled / fresh-authorized。失効watermark未対応なら後者は選べない | | `max_read_staleness_seconds` | 300、範囲1〜3600 | read replica能力実装後に適用。初版3600秒設定とは別version | | `rpo_target_seconds` | 必須・導入時入力 | 目標。同期の成功や無損失を保証するフラグではない | | `rto_target_seconds` | 必須・導入時入力 | fence・起動・routingを含む実測比較の目標 | | `data_loss_policy` | require-approval | 自動failoverで不明/未複製の損失を黙認しない | | `fence_provider_ref` | coordinatedでは必須 | 対象identity・resource・影響範囲を検証できるprovider | 上記は試験開始用の既定値。実環境のRTTやI/Oに応じて変更できるが、同期完了、現主系の隔離、 相互排他、未知世代拒否といった安全条件は設定で無効化できない。 preempt=automaticはcoordinated、全target能力、writer境界、適合fence、失効同期を必須とする。 manualでは自動選挙も自動preemptも行わず、復帰しただけではwriterを再開しない。 ## 6. 再参加の状態機械 設定上の優先順位、現在の役割、実行状態を別フィールドにする。 状態遷移の入力は検証済みイベントのみ。単なるHTTP 200やpeerの文字列申告では遷移しない。 | 状態 | 入る条件 | 許可するもの | 次状態の条件 | | --- | --- | --- | --- | | `recovering` | 全DR対象プロセスの起動、許可失効、重大な構成変更 | ローカル検証、認証済みprobe | identity/構成が有効ならlearning | | `learning` | 書込gateを閉じてauthority/peerを照合中 | probe、checkpoint一覧、同期plan | authoritative state一致→syncing。矛盾→conflict | | `syncing` | 正しいsourceとbase世代が確定 | 不変世代の受信・検証 | 内容・schema・ACL等が一致→standby | | `standby` | 検証済み世代、最新membership | 同期追従、能力認定済みreadのみ | 書込grant取得→activating | | `activating` | 新grantとfence証跡が確定 | root切替、互換性検証、gate接続 | 二重確認+readiness成立→primary | | `primary` | group/resource/bootすべて一致した有効grant | 許可範囲のread/write | 計画移譲→draining。許可失効→recovering | | `draining` | operationが停止cutを要求 | 既存処理の完了待ち、checkpoint | writer停止証明後standby/停止。失敗ならoperation停止 | | `conflict` | 履歴分岐、同一世代で異hash、trust不一致 | 証拠保全、管理状態参照 | 運用者のreseed/解決planのみ | | `blocked` | 同期先不在、容量不足、fence不明、互換性不足 | 状態・監視 | 原因解消後、learningから再検査 | learning/syncing中は一般のreadも公開しない。復元されたprivate文書と古いACLをうっかり公開しない。 standbyでreadを許す場合も、内容の鮮度とは別に必要な失効watermarkを確認する。 複数groupを持つInstanceは各groupの状態を表示する。単一の緑ランプで全役割をprimaryと見せない。 ### 起動順序 1. ノードの専用identity、deployment期待値、承認済みmembershipを読む。 2. 通常HTTP handler、migrations、worker、CLI接続より先にすべてのwriter gateを閉じる。 3. read-only互換性検査と管理用control listenerだけを起動する。 4. 新boot_idで認証probeし、authorityの現在値と照合する。誰にも到達できなければblocked。 5. 必要なら旧ローカルデータを隔離保全し、正しいsourceから新generationへ同期する。 6. 同期済みでもまずstandby。新bootに対するgrant取得を別処理で行う。 正常終了時にprimaryだった場合もこの順序を省略しない。単一ノードの非DR運用は従来起動を 維持するが、DR設定の欠落を非DRへ自動フォールバックする経路はdeployment guardで拒否する。 ## 7. 書き込み許可の条件 次の論理式をすべて満たす場合だけwriterを開く。 ```text CanWrite(role, resource, boot) = approved_membership AND validated_trust_generation AND active_group_grant(holder=node, boot=boot, epoch=current) AND active_resource_grant(holder=node, bundle=current) AND verified_dataset AND schema_compatible AND revocations_applied AND local_gate_open AND NOT draining AND NOT expired ``` Web/APIだけでなくCalDAV、CLI、managed設定受理、migrations、GC、asset処理、calendar保存、 外部同期、outbox配信もwriter一覧に含める。HTTP GETでも修復/発行をする経路はwriteである。 RO standbyへのmanifest適用は、そのreplicaのauthoritative DBへ直接行わず、現DG primaryへ 適用するか同期対象のprojectionとして受け取る。ローカル状態報告の保存先と業務正本を混ぜない。 許可喪失時は新規処理を拒否し、実行中処理をキャンセル・停止する。しかしプロセス停止や ネットワーク遅延によりキャンセルが間に合わない可能性があるため、新primaryのgrant発行は 外部fence確認または認定済み保存側fencingの完了まで待つ。local mutex/lease確認だけでは代替不可。 ## 8. 裁定・信頼モデル 発見peer、複製peer、authority参加者は別。既存Campus参加トークンにbackup読出しや昇格権を 追加しない。ノード間通信は専用identityとgroup限定の許可を使う。 coordinatedの初段providerは外部etcdの通常整合性readと比較更新transactionを使う。 watchは再確認のきっかけで、watch結果だけから新grantを発行しない。epoch、membership、 operation intentは期限切れで消さず、leaseは生存・短期許可にのみ用いる。 etcdのKV transactionとwatchの保証は異なるためである。[etcd API guarantees](https://etcd.io/docs/v3.5/learning/api_guarantees/) authorityは業務snapshotと別の保全・失効境界に置く。旧authority backupを戻してepochを 巻き戻すことは禁止。authority全損時は全writerをfenceし、新trust_generationを out-of-bandで承認・再配布するbreak-glass手順を要求する。単にepochを大きくする操作ではない。 authority quorumが失われた場合は新grantを発行しない。既存writerも許可更新不能なら閉じる。 2台のPagesWikiを相互監視するだけではcoordinated modeを認定しない。 etcdは別途適切な障害領域に配置する。配置数やfence backendの接続情報は導入計画で確定する。 manual modeの運用者証跡は自動検証済みfenceと区別し、UIと監査に表示する。 ## 9. コントローラとデータ側の障害マトリクス | 事象 | 管理側 | データ側 | 判定 | | --- | --- | --- | --- | | CG停止、DG正常 | 配置変更・新manifestを停止 | 有効なdata grantと許可済み設定で継続 | CGへの疎通だけをDGの書込条件にしない | | DG停止、CG正常 | 管理操作は継続可 | 対象DGのfailover判定 | CGが配置文字列を書き換えるだけでは昇格不可 | | 旧CG復帰 | learning→管理checkpoint同期 | DGの切替は不要 | CG preempt設定のみ評価 | | 旧DG復帰 | 配置group identityを維持 | learning→現DG primaryから同期 | 古いデータを優先しない | | 同じDBでCG/DGが別nodeを要求 | 連動planが必要 | 連動planが必要 | 独立要求を拒否 | | primaryとreplicaが分断 | authoritative grantとfenceを照合 | 同左 | 応答者だけの多数決はしない | | authorityのみ停止 | 更新許可の有効期間内だけ処理 | 同左 | 新grantなし、期限到達でwriter停止 | | 最新受理manifestより復元内容が古い | 自動配信しない | 古い権限を再適用しない | 管理復旧の明示承認が必要 | | role fenceが同居別groupも停止する | impact planを提示 | 対象groupも判定 | 自動preemptを拒否 | ## 10. UI・権限・監視 設定の「運用 / DR」を親にし、「概要」「グループ」「同期・保全」「切替履歴」を子パネルにする。 概要は1group 1行、kind / Campus・Domain範囲 / 実primary / preferred / state / 同期点 / 遅延 / 書込許可 / 原因を表示。ノード追加・ポリシー編集はアイコンからダイアログに収める。 フォルダ名やpathではなくnode・groupを選択させ、秘密は参照名だけ表示する。 キャンパス設定にはCGの役割・状態とDR画面へのリンクを追加する。Domain設定では配置先を DG単位で選び、現在のnodeを補助表示する。旧配置方式は移行前であることを示す。 | 権限 | 許可 | | --- | --- | | instance operator(新しいホスト運用者権限) | node登録、trust/fence、backup秘密、bundle全体の切替・復元 | | campus_admin | 自Campusの管理状態参照、ポリシー変更/切替の申請 | | domain_admin | 自Domainの配置・同期状態参照。ホスト/鍵/他Domain情報は非表示 | | replica service identity | 明示groupのprobe、許可された世代の同期。operator API不可 | instance operatorはcampus_adminへの暗黙追加ではない。初段はホストCLIだけでこの権限を 実現し、既存認証DBに新roleを勝手に加えない。Webでのapplyは認可契約が完成するまで非表示。 切替UIはplan→影響範囲・損失・fence表示→承認→進行状態。操作中も平常画面をoverlayしない。 通知Inboxへ失敗/blocked/完了を集約し、probe失敗を毎回broadcastしない。 メトリクス:role state、grant残時間、最後のprobe成功、同期cut時刻、検証ACK時刻、 pending bytes、転送速度/制限、hash失敗数、fence結果、operation phase、未複製の更新有無。 UUID別の無制限時系列は避け、ノード/group別集計と履歴画面を分ける。秘密・文書本文をログに出さない。 緑=primary許可あり/検証済みstandby、黄=learning/syncing/suspect、赤=conflict/blocked。 色だけで判断させずラベルと原因コードを併記し、日本語・英語キーを用意する。 ## 11. 保存担当との接続条件 DB変更の担当へ渡す成果物は、テーブル要求ではなく以下の能力・整合性契約。 - `DescribeResources`:各正本とwriter排他境界、共有するrole、schema対応範囲。 - `InspectCheckpoint`:正本を変更せず、適用世代・内容digest・schema fingerprintを取得。 - `FreezeWriters/ReleaseBarrier`:全writerの停止、未完了処理、最終cutの確定。 - `CaptureCheckpoint/Pin/Unpin`:DBと可変正本を同じcutへ固定し、必要blobをGCから保護。 - `StageGeneration/Verify/ActivateGeneration`:非稼働rootへ復元し、検証後に切替。 - `ApplyControlManifest`:管理内容と受理checkpointを同じ永続化境界で確定。 - `CheckWritePermit`:対応できる場合のみ保存側fencingとして能力宣言。 詳細な入出力と失敗時条件は [protocol](dr-protocol-and-sync.md) に定義する。 契約を満たす実装がなければoffline capture/shared-instance/manualのままとし、DB別件を 妨げるDDL、直接SQL、独自の並行正本ファイルを追加しない。 ## 12. 参考と非目標 Learnerという考え方は、同期前のノードを選挙・サービス提供から外すための参考である。 PagesWikiの状態名をetcdの状態と同一視しない。[etcd learner design](https://etcd.io/docs/v3.5/learning/design-learner/) 非目標:active-active更新、複製DBのSQL行単位マージ、任意LAN参加、gossipによる独自投票、 DNSだけによるfencing、DB製品選択の変更、既存Campus/FQDNの改名、未同期更新の黙った破棄。 同期とバックアップは別であり、replicaの存在を履歴世代の保全の代替としない。