Files
pages/docs/design/ja/dr-authority-and-rejoin.md
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

22 KiB
Raw Permalink Blame History

DR詳細設計:管理主系・データ主系・再参加

設計版:DR-D1、2026-09-27。設計のみ。記載したAPI・状態機械・設定は未実装。 今回の作業は文書のみを変更し、DB、schema、migration、実行コード、配置設定、本番データを変更しない。 既存の停止snapshot/手動昇格は 初版の実装・運用記録 に残す。

1. 文書体系・決定の適用範囲

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を開く。

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の存在を履歴世代の保全の代替としない。