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.
22 KiB
DR詳細設計:管理主系・データ主系・再参加
設計版:DR-D1、2026-09-27。設計のみ。記載したAPI・状態機械・設定は未実装。 今回の作業は文書のみを変更し、DB、schema、migration、実行コード、配置設定、本番データを変更しない。 既存の停止snapshot/手動昇格は 初版の実装・運用記録 に残す。
1. 文書体系・決定の適用範囲
- 本書:責務、identity、再参加状態、書き込み条件、障害時判断、設定・UI。
- 通信・同期・主導権移譲契約:メッセージ、URI、検証、切替と保全。
- 実施計画・受入試験:作業単位、変更予定箇所、依存、導入・撤退手順。
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と見せない。
起動順序
- ノードの専用identity、deployment期待値、承認済みmembershipを読む。
- 通常HTTP handler、migrations、worker、CLI接続より先にすべてのwriter gateを閉じる。
- read-only互換性検査と管理用control listenerだけを起動する。
- 新boot_idで認証probeし、authorityの現在値と照合する。誰にも到達できなければblocked。
- 必要なら旧ローカルデータを隔離保全し、正しいsourceから新generationへ同期する。
- 同期済みでもまずstandby。新bootに対するgrant取得を別処理で行う。
正常終了時にprimaryだった場合もこの順序を省略しない。単一ノードの非DR運用は従来起動を 維持するが、DR設定の欠落を非DRへ自動フォールバックする経路はdeployment guardで拒否する。
7. 書き込み許可の条件
次の論理式をすべて満たす場合だけwriterを開く。
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
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 に定義する。 契約を満たす実装がなければoffline capture/shared-instance/manualのままとし、DB別件を 妨げるDDL、直接SQL、独自の並行正本ファイルを追加しない。
12. 参考と非目標
Learnerという考え方は、同期前のノードを選挙・サービス提供から外すための参考である。 PagesWikiの状態名をetcdの状態と同一視しない。etcd learner design
非目標:active-active更新、複製DBのSQL行単位マージ、任意LAN参加、gossipによる独自投票、 DNSだけによるfencing、DB製品選択の変更、既存Campus/FQDNの改名、未同期更新の黙った破棄。 同期とバックアップは別であり、replicaの存在を履歴世代の保全の代替としない。