Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
286 lines
22 KiB
Markdown
286 lines
22 KiB
Markdown
# 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の存在を履歴世代の保全の代替としない。
|