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.
232 lines
20 KiB
Markdown
232 lines
20 KiB
Markdown
# DR詳細設計:実施計画・受入試験・導入判定
|
||
|
||
設計版:DR-D1、2026-09-27。**詳細設計完了、実装作業は未着手。**
|
||
ここでいう実装作業はDR-D1の再参加・役割分離protocol。既存のoffline DR CLIは別の初版。
|
||
今回の成果物は文書のみであり、DB・migration・本番配置を変更する作業指示ではない。
|
||
|
||
## 1. 設計成果物と完了条件
|
||
|
||
| 成果物 | 本版で定義した範囲 |
|
||
| --- | --- |
|
||
| [役割・再参加](dr-authority-and-rejoin.md) | CG/DG/Instance、writer連動境界、identity、状態機械、設定・UI・権限 |
|
||
| [protocol・同期](dr-protocol-and-sync.md) | 認証probe、API、authority契約、checkpoint、manifest v3案、切替・失敗時動作 |
|
||
| 本書 | 実施順、予定変更箇所、DB別件への接続条件、試験、導入/撤退手順 |
|
||
| [初版記録](disaster-recovery.md) | 既存機能と制約を保持し、DR-D1と区別 |
|
||
|
||
- [x] primaryを管理/データに分け、物理保存境界による連動条件を記述。
|
||
- [x] 起動・probe・Learning・同期・昇格・preempt・失敗からの再参加を定義。
|
||
- [x] 身元、世代、許可、同期内容、承認、未知損失の扱いを定義。
|
||
- [x] API入出力、サイズ上限、再試行、冪等性、切替phase、認可主体を定義。
|
||
- [x] DBを変更せずに準備できる範囲と、保存担当との合意待ち範囲を分離。
|
||
- [x] 実装タスク、依存、合格条件、障害注入試験、導入/撤退条件を定義。
|
||
- [ ] 実装・実機でのfencing認定・復旧訓練・本番反映。
|
||
|
||
「詳細設計完了」は実装方針と判断規則を定義した状態であり、未知の本番設備の能力を保証した
|
||
意味ではない。RPO/RTO値、ノード数/FQDN、fence機器、容量、鍵保管先は導入時の必須入力として残す。
|
||
これらを未設定のまま自動運転へ移行することはできない。
|
||
|
||
## 2. DB別件との作業境界
|
||
|
||
本タスクでは以下を行わない。
|
||
|
||
- アプリDBへのSELECTを含むアクセス、DBのコピー・バックアップ・復元、schema inspectの実行。
|
||
- SQL/DDL/migration/repositoryの編集、コード生成、サーバ起動、CLIによるデータ操作。
|
||
- compose、認証鍵、federation token、node設定、稼働コンテナ、外部カレンダーへのアクセス。
|
||
- 文書を本番Wikiへアップロードする操作(アップロードもDBへの書き込みになるため)。
|
||
|
||
読み取る対象は設計書と必要最小限のソースコードだけ。ドキュメントの静的整合性確認を実施する。
|
||
別件の変更を前提にDBの物理分割方法やテーブル名を確定させない。
|
||
|
||
保存担当へ渡すinterface要求は次の通り。応答はSQLの実装ではなく、能力の宣言とテスト結果で受け取る。
|
||
|
||
| 契約 | 保存担当に確認する事項 | 未提供時の挙動 |
|
||
| --- | --- | --- |
|
||
| Resource map | metadata/可変正本/署名発行状態が共有するwriter境界 | shared-instance連動のみ |
|
||
| Schema inspection | 非破壊・read-onlyでの互換性/世代取得 | 復旧世代をservableにしない |
|
||
| Consistent cut | DBとcalendar等を同じ論理時点で固定できる範囲 | 全writer停止snapshotのみ |
|
||
| Durable pin | snapshot/GC/転送/再起動を跨ぐ参照保持 | online同期不可 |
|
||
| Restore activation | 新generationの検証、root切替、途中停止からの復旧 | 自動復元不可、既存手動手順のみ |
|
||
| Manifest apply | 管理内容と受理位置のatomic commit | manifest v3配信不可 |
|
||
| Write fencing | 旧許可を実際の書込み先で拒否できるか | 外部fence必須 |
|
||
| Durability receipt | client成功応答済み更新がreplica上で永続化された境界 | 自動無損失failover不可 |
|
||
| Identity/secret inventory | logical service keyとphysical node keyの区別 | nodeを自動参加させない |
|
||
|
||
合意前に作業できるのは仕様型、pure state machine、mock provider、観測専用probe、
|
||
静的UI/認可契約の設計まで。runtimeへのwrite gate接続も、別件の保存経路を網羅できることを
|
||
確認してから行う。この順序は「DBが共有のままでもroleのflagだけ先に動かす」ことを禁止する。
|
||
|
||
## 3. 実装タスクと依存順
|
||
|
||
以下は将来の予定。行が存在しても対象ソースを今回変更しない。
|
||
|
||
| ID | 実施内容 | 主な変更予定箇所 | 依存 | 完了判定 |
|
||
| --- | --- | --- | --- | --- |
|
||
| DR01 | version付き型、ID/epoch/構成検証、resource coupling planner | `internal/dr`の新model/config/planner | 設計D1 | 不正構成・独立不可・未知版を拒否。DB依存なし |
|
||
| DR02 | pure state machineとoperation phase reducer、fake clock | `internal/dr`のstate/operation | DR01 | 不変条件N1〜N10の遷移試験。失敗時はwriterを開かない |
|
||
| DR03 | 専用node identity、mTLS/署名/nonce、観測専用probe | `internal/dr`のtransport、server管理route | DR01 | 未認証/別group/replayを拒否。probeでroleが変わらない |
|
||
| DR04 | runtime startup gateの接続、非DR互換、旧CLI禁止 | `cmd/pageswiki/main.go`、server middleware、store/CLI全writer入口 | DR02/03+保存経路合意 | 再起動で必ずrecovering。起動修復/workerも許可前にwriteしない |
|
||
| DR05 | AuthorityStore interface、manual provider、etcd providerと限定service | `internal/dr`のauthority、専用運用cmd | DR01/02 | CAS競合/timeout/再起動でgrantが二重にならない |
|
||
| DR06 | checkpoint adapter、世代/pin台帳、schema/read-only検証 | 既存`internal/dr/snapshot.go`と保存担当adapter | DR01+保存契約合意 | offline fixtureから再開可能。online未対応を明示拒否 |
|
||
| DR07 | 認証済みmanifest/Range転送、recipient ACK、負荷制御 | DR transport、documentstore adapter、scheduler表示 | DR03/06 | 中断再開/破損/別groupアクセス/容量不足を検出 |
|
||
| DR08 | v1/v2 anchor移行、管理manifest v3発行/受理/ACK | federation manifest、enroll/reconcile、受理repository | DR03/05/06+受理永続化合意 | 同内容再送・旧epoch・欠落履歴・rollbackを正しく処理 |
|
||
| DR09 | fence provider契約、impact planner、証跡照合 | DR fence/operation、運用connector | DR05 | 隔離未確認/誤node/別boot/別group影響で昇格拒否 |
|
||
| DR10 | 手動switchover/failover/reseedをoperationへ統合 | DR CLI/API、root activation、routing adapter | DR04〜09 | 完全fixtureでroleごとの切替と共有DB連動が成立 |
|
||
| DR11 | preempt planner、自動coordinated gate、cooldown | DR policy executor | DR10+設備認定 | flapping抑制、0損失の計画復帰、不可条件時の提案のみ |
|
||
| DR12 | DR管理UI、i18n、health、Inbox、監査集約 | config panels、status APIs、metrics | DR03/10+operator認可 | group別表示、権限境界、秘密非表示、plan/applyが一致 |
|
||
| DR13 | v0移行/本番runbook、復旧訓練、負荷/障害試験 | docs/operations、隔離検証環境 | DR10/12 | 受入matrix全通過、RPO/RTO実測、明示承認後のみ有効化 |
|
||
|
||
DR04以降のコード接続は、DB別件の差分が落ち着き接続点が合意された後。
|
||
DR08のschema実装は保存担当の変更計画に載せ、DRタスクが独自migrationを追加しない。
|
||
DR09の機器connectorは任意shell入力ではなく、許可された設備・resource IDへのtyped操作とする。
|
||
|
||
### 段階リリース
|
||
|
||
| 段階 | 提供するもの | 明示的に提供しないもの |
|
||
| --- | --- | --- |
|
||
| L0:現行初版 | offline snapshot、検証、手動復元・昇格 | 再参加判定、オンライン同期、自動fencing |
|
||
| L1:観測 | DR01〜03、状態の参照UI | 自動昇格、既存writerのruntime変更 |
|
||
| L2:再参加gate | DR04/05、operator承認下の起動、shared bundle判定 | 未接続の保存経路があるprofileの有効化 |
|
||
| L3:同期・手動切替 | DR06〜10、認証転送、group別の計画操作 | 未認定providerの自動切替 |
|
||
| L4:自動主系復帰 | 認定済みDR11/12、coordinated preempt | snapshotのみを根拠にした無人・無損失failover |
|
||
| L5:自動障害復旧 | replica durability receipt等が揃うprofileのみ | 未複製更新や未知損失の黙認 |
|
||
|
||
各段階で有効化フラグは既定off。capabilityの揃わない段階へUI操作で飛び越せない。
|
||
L1の観測機能が動作しても「Learningから自動で昇格できる」と表示しない。
|
||
|
||
## 4. CLI・API・UIの実施内容
|
||
|
||
将来CLI案(すべて未実装、DB直接更新用コマンドではない):
|
||
|
||
```text
|
||
pageswiki dr config validate --file <operator-config>
|
||
pageswiki dr groups status --group <id>
|
||
pageswiki dr rejoin plan --group <id> --node <id>
|
||
pageswiki dr switchover plan --group <id> --to <id>
|
||
pageswiki dr failover plan --group <id> --to <id>
|
||
pageswiki dr operations apply --plan <id> --plan-sha256 <hash>
|
||
pageswiki dr operations show --id <id>
|
||
pageswiki dr operations cancel --id <id>
|
||
pageswiki dr reseed plan --group <id> --node <id> --checkpoint <id>
|
||
```
|
||
|
||
現行の `dr promote` はL0専用とする。D1管理されたdatasetでは旧epochの手動書換えに
|
||
ならないよう拒否し、operationへ案内する。旧binary/旧CLIもwriterとして動けない配置制約を
|
||
設ける。新設定ファイルの存在を古いbinaryが無視する可能性は、file markerだけでは解決しない。
|
||
|
||
online CLI、Web、policy executorは同じplan/operation serviceを使う。
|
||
dry-run/planはfence・permission・同期実体を変更しない。operatorがCLIから秘密付きbackupを
|
||
扱えることと、campus_adminがWebから全DBをダウンロードできることを同一にしない。
|
||
|
||
UIは最初に観測だけを実装し、operationが完成した段階で切替ボタンを追加する。
|
||
コンパクトなgroup一覧、control/dataの別ラベル、preempt状態、同期点、ブロック理由を優先する。
|
||
確認dialogには「どのCampus/Domain/同居groupが止まるか」「失う可能性のある期間」
|
||
「隔離手段」「未達条件」を列挙する。UNIX時刻入力や、色だけの安全判定は使わない。
|
||
|
||
## 5. 受入試験マトリクス
|
||
|
||
テストはfake clock/fake authority/fake fence/一時保存領域から開始し、
|
||
実カレンダー・個人文書・本番ノードには接続しない。各テストは最終状態だけでなく、
|
||
途中のwriter許可集合を記録し、同一resourceで2 holderになっていないことを検査する。
|
||
|
||
| ID | 入力・障害注入 | 期待結果 |
|
||
| --- | --- | --- |
|
||
| T01 | primary記録を持つnodeが再起動、peer応答なし | recovering→blocked、migration/worker含めwrite 0 |
|
||
| T02 | 非DR instance起動 | 従来の起動を維持。DR期待環境で設定欠落なら起動拒否 |
|
||
| T03 | 別group、未知鍵、同FQDNで別fingerprint、失効nodeからprobe | 認証/認可拒否、WARNING。membership変化なし |
|
||
| T04 | 古いboot/nonce、応答遅延、重複JSON key、未知protocol、大きすぎるbody | 状態遷移なし。入力種別に応じたerror |
|
||
| T05 | peerが大きいepoch/primaryを自己申告、authorityは異なる | 再確認・conflict、安全側停止。自己申告で昇格なし |
|
||
| T06 | 発見peerの半数以上が同じ内容、登録authorityに到達不能 | 観測の多数決でgrantを出さない |
|
||
| T07 | 同一DBのCG/DGが別holderを要求、alias resourceも混在 | WRITER_BOUNDARY_COUPLED、連動planを提示 |
|
||
| T08 | 独立storeのCG停止、DGは有効grantと設定を保持 | CGだけ停止。DGは権限鮮度条件の範囲で継続 |
|
||
| T09 | CGのpreempt on、DGのpreempt off | 独立profileならCGのみ戻る。sharedなら連動影響を承認前に提示 |
|
||
| T10 | primaryの停止・再開、時計逆行、VM pause、permit応答喪失 | stale permitでwrite再開なし。新grantにはfenceを要求 |
|
||
| T11 | 2 executor/2 candidateが同時に同group操作、response消失、manual agent二重起動 | 一つのoperation/grantだけ確定。同じIDで結果照合、manual agent排他 |
|
||
| T12 | fence要求送信済みだが確認不明、別node/古いbootの証跡 | FENCE_UNCONFIRMED、grantなし |
|
||
| T13 | ホストfenceが別DG primaryにも影響 | 自動preempt禁止、impactに全groupを列挙 |
|
||
| T14 | capture中にDB更新・calendar世代更新・GC・schema変更 | barrier/capabilityに従い排他。保証不能ならcapture中止 |
|
||
| T15 | 転送中断/Range再開、chunk改変、symlink/path traversal、未登録file ID | 検証失敗、他データを読ませずactive root不変 |
|
||
| T16 | blobの一部欠落、calendar参照世代欠落、schema不適合、secret欠落 | verified/applicable ACKなし、standby公開なし |
|
||
| T17 | pin後にsource再起動、transfer期限切れ、GC/保持処理 | 必要世代を消さない。残存pinを照合して回収 |
|
||
| T18 | 同期中に新しいwrite、表示上lag=0だが最終cut未確定 | switchover不可。final checkpointの一致を必須とする |
|
||
| T19 | metadataのみ最新、ACL/session失効は古い | read/write readinessとも不成立 |
|
||
| T20 | 旧primaryに現系列にない更新 | 隔離保全、conflict。自動マージ/削除なし |
|
||
| T21 | manifest旧epoch、同sequence異hash、欠落親、receiptなし | 適用拒否。v3導入後のv1/v2 downgradeも拒否 |
|
||
| T22 | 内容適用と受理checkpointの間で失敗、publication receipt応答喪失 | 一体rollback/同内容照合。別payloadで再発行しない |
|
||
| T23 | controller復元点が管理ノード受理位置より古い | blocked、epochを増やして古い権限を再配信しない |
|
||
| T24 | 各operation phaseの前後でprocess kill | 文書化したphaseから再開。REVOKING以降は旧epoch復活なし |
|
||
| T25 | GRANTED後root切替失敗、RO filesystem、disk full、fsync失敗 | 新primaryを公開せず、次の復旧operationへ |
|
||
| T26 | routing更新失敗、DNS cacheに旧宛先、既存keep-alive | 新primaryは一つ。旧宛先はwrite拒否、routing修復 |
|
||
| T27 | 同期済みpreferred nodeが繰り返しflap、時間帯/DST境界 | 安定時間リセット、cooldown遵守、不要な再切替なし |
|
||
| T28 | snapshotの鮮度はRPO内だがclient成功応答の反映が不明 | 自動障害昇格不可。損失確認をoperatorへ要求 |
|
||
| T29 | grant lease失効/authority quorum喪失/watch欠落 | 新grantなし。local gate期限で停止、外部fence前は他holder不可 |
|
||
| T30 | AuthorityStoreを古いbackupへ復元、manual台帳の破損/消失 | 全writerを隔離、新trust世代の手動復旧。epochの黙認・自動初期化なし |
|
||
| T31 | high IO/CPU/foreground要求増、巨大snapshot | stream/帯域/hash上限を維持。制御通信が転送に埋もれない |
|
||
| T32 | campus_admin/domain_adminが他scope切替/backup秘密を要求 | 拒否。read UIも他Campus・secretを漏らさない |
|
||
| T33 | restart後workerが過去jobを拾う、外部通知結果が曖昧 | 許可と再送条件を確認。曖昧な副作用は自動で成功/再送しない |
|
||
| T34 | operatorがcancel/disable/旧binaryへのrollbackを要求 | 安全点だけ取消。active grantを消して旧系を復活させない |
|
||
|
||
T24はPLANNED〜COMPLETEDの全境界で行う。ネットワークを切るタイミングも
|
||
「要求送信前」「相手がcommit後、応答前」「応答後、ローカル永続化前」に分ける。
|
||
fixtureの全writer経路を一度ずつ実行し、HTTP guardだけで満たしたと判定しない。
|
||
|
||
## 6. 性能・運用の合格条件
|
||
|
||
固定のRTO保証値を現時点で作らず、次の測定結果を導入記録に残す。
|
||
|
||
- 通常foreground p50/p95/p99と、同時同期時の差。目安の許容悪化率は10%以内、超過なら転送予算を縮小。
|
||
- DB/可変正本のbarrier時間、checkpoint作成時間、初回/増分転送時間、検証時間、必要空き容量。
|
||
- suspect検知、fence確認、grant、起動、routing完了の各所要時間と合計RTO。
|
||
- 障害時点と最後のDR側検証cutの差、client成功応答境界の確認可否、未複製損失の有無。
|
||
- スナップショット10万/100万file相当のmanifest paging、RSS/heap、descriptor数の上限。
|
||
初版v1の10万file上限を、v2の性能試験なしに解除しない。
|
||
- 一日継続のprobe/転送/再起動試験で、timer・goroutine・scratch・pin・operationが無制限に増えない。
|
||
|
||
10%は候補性能予算であり、実機測定前に達成と表明しない。別件の保存層の性能評価と同じ
|
||
fixture条件を使用する。外部サービス/実データにアクセスする実機試験は別途承認を得る。
|
||
|
||
## 7. 導入時に入力・承認する事項
|
||
|
||
設計として未決のアルゴリズムではなく、設備・運用に依存する導入パラメータを列挙する。
|
||
|
||
| 入力 | 決定する主体 | 未入力時 |
|
||
| --- | --- | --- |
|
||
| node FQDN/管理origin、node identity、対象Campus/DG、resource対応 | 運用者+保存担当 | 登録・同期を開始しない |
|
||
| RPO/RTO、retention、容量/帯域予算 | 運用者 | 本番enable不可 |
|
||
| authority配置、CA、専用service key保管/更新、quorum障害領域 | 運用者 | manualのみ |
|
||
| fence機器/credential参照、再起動抑止、影響group | 運用者 | coordinated enable不可 |
|
||
| backup/secret暗号化と復号担当、別障害領域の保全先 | 運用者 | 秘密付き転送不可 |
|
||
| CG/DGごとのpreferred、preemptと許可時間帯 | 運用者+管理者 | preempt off |
|
||
| 保存profile能力と対応app/image/schema | 保存担当 | offline/shared-instanceのみ |
|
||
|
||
## 8. 本番導入手順
|
||
|
||
1. 運用者が対象と入力を確定し、保存担当がresource map・能力契約を承認する。
|
||
2. 本番とは通信しない隔離fixtureで対応段階のT01〜T34と負荷試験を実施する。
|
||
3. 既存環境の保全・image digest・schema互換性・復旧手順をレビューする。実データ保全は別途承認。
|
||
4. L1観測のみを配置し、比較表示を確認する。旧roleに基づくサービス挙動はこの段階では変えない。
|
||
5. 全writerと旧CLIを停止する保守枠を取り、L2への移行planを確認する。
|
||
6. 旧cluster/node/roleを新group/resourceに対応させ、fresh authorityをbootstrapする。
|
||
旧primaryの確認記録を付け、元のepochを新authorityの根拠にしない。
|
||
7. 新startup gate下で起動し、他nodeはlearnerとして参加。sourceと同期内容を検証する。
|
||
8. L3の手動switchoverと復帰を1往復実施し、RPO/RTO・監査・権限失効・queueを検証する。
|
||
9. 保存分離済みprofileならCG/DGの独立切替、共有profileなら連動拒否/連動切替を確認する。
|
||
10. 能力が揃ったgroupに限り、明示承認を得てL4を有効化する。L5は別の認定を要求する。
|
||
|
||
ローリング移行中、旧ノードをwriter候補に残さない。mixed protocolで書込み可能nodeを
|
||
増やす移行はしない。旧nodeからのprobeは対応版を表示し、新grant候補から除外する。
|
||
管理manifest v3は全対象が移行anchorをACKした後に切替える。
|
||
|
||
## 9. 撤退・失敗時
|
||
|
||
DRの「無効化」は設定ファイル削除ではない。新operation受付を止め、active operationを照合し、
|
||
一つのwriterを運用者が確定・隔離確認してから非DR運用への移行planを実行する。
|
||
authorityを停止しただけで旧nodeに書き込みを許可しない。
|
||
|
||
L1だけなら観測プロセスを停止して戻せる。L2以降はrole/許可/DB互換性の記録を保持する。
|
||
新epochでwriteが発生した後は、旧snapshotを起動することでrollbackしない。
|
||
旧binaryに戻す場合は、最新データとschema互換性を検証し、DRのtrust/gateを無視するbinaryが
|
||
同時に動かないことを外部で保証する。保証できなければ停止を継続する。
|
||
|
||
実施結果には、適用していない段階、満たしていない能力、最後に検証した世代、
|
||
次に必要な承認を必ず残す。設計完了・実装完了・復旧訓練完了・本番稼働を同じチェックにしない。
|