Files
pages/docs/design/ja/dr-delivery-plan.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

232 lines
20 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。**詳細設計完了、実装作業は未着手。**
ここでいう実装作業は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が
同時に動かないことを外部で保証する。保証できなければ停止を継続する。
実施結果には、適用していない段階、満たしていない能力、最後に検証した世代、
次に必要な承認を必ず残す。設計完了・実装完了・復旧訓練完了・本番稼働を同じチェックにしない。