Files
pages/docs/design/ja/dr-authority-and-rejoin.md
T
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

286 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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の存在を履歴世代の保全の代替としない。