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

20 KiB
Raw Permalink Blame History

DR詳細設計:実施計画・受入試験・導入判定

設計版:DR-D1、2026-09-27。詳細設計完了、実装作業は未着手。 ここでいう実装作業はDR-D1の再参加・役割分離protocol。既存のoffline DR CLIは別の初版。 今回の成果物は文書のみであり、DB・migration・本番配置を変更する作業指示ではない。

1. 設計成果物と完了条件

成果物 本版で定義した範囲
役割・再参加 CG/DG/Instance、writer連動境界、identity、状態機械、設定・UI・権限
protocol・同期 認証probe、API、authority契約、checkpoint、manifest v3案、切替・失敗時動作
本書 実施順、予定変更箇所、DB別件への接続条件、試験、導入/撤退手順
初版記録 既存機能と制約を保持し、DR-D1と区別
  • primaryを管理/データに分け、物理保存境界による連動条件を記述。
  • 起動・probe・Learning・同期・昇格・preempt・失敗からの再参加を定義。
  • 身元、世代、許可、同期内容、承認、未知損失の扱いを定義。
  • API入出力、サイズ上限、再試行、冪等性、切替phase、認可主体を定義。
  • DBを変更せずに準備できる範囲と、保存担当との合意待ち範囲を分離。
  • 実装タスク、依存、合格条件、障害注入試験、導入/撤退条件を定義。
  • 実装・実機での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直接更新用コマンドではない):

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が 同時に動かないことを外部で保証する。保証できなければ停止を継続する。

実施結果には、適用していない段階、満たしていない能力、最後に検証した世代、 次に必要な承認を必ず残す。設計完了・実装完了・復旧訓練完了・本番稼働を同じチェックにしない。