Files
pages/docs/design/ja/disaster-recovery.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:単一書き込みノードと検証済み復旧世代

状態:2026-09-27、設計と第1段階の実装。自動フェイルオーバー、オンライン同期、設定画面は未実装。本番への適用・実データでの復旧訓練は別の承認を得て行う。

次段階の詳細設計DR-D1が完了(文書のみ): 管理主系・データ主系と再参加、 通信・同期・切替protocol、 実施計画・受入試験。 本書は既存offline実装の記録として保持する。次段階の判断・実装順はDR-D1を優先する。 DBは別件の変更対象のため、本詳細設計作業ではDB・schema・実装コードを変更していない。

1. 基本方針

Campus / Domain の意味、UUID、FQDN、所属関係を変えず、そのデータを動かすインスタンスの復旧構成を追加する。通常時は primary だけが書き込み、standby は検証済みの過去世代を読み取り専用で扱う。ネットワーク疎通失敗だけでは昇格しない。

「相手が落ちた」と「こちらから相手へ接続できない」は区別できない。2台だけで相互監視して両方が書き込みを開始すると、SQLite のトランザクションが各ノードで正常でも、全体では異なる正本が生まれる。旧 primary の電源・ストレージ・通信経路を外部で確実に隔離する fencing を昇格の前提とする。初版のコマンドは運用者の確認記録を残すもので、fencing 自体を実行・保証しない。

復旧の単位

現状の pages.db は複数 Campus / Domain の情報を共有する。したがって第1段階は データディレクトリ全体=1インスタンスを複製・昇格する。Campus の設定欄だけで1 Campusを昇格させ、同じDB内の別Campusを読み取り専用に残す操作は提供しない。

コントローラと配下の管理インスタンスはそれぞれ別の復旧単位。コントローラのスナップショットにはリモート配置 Domain の設定は含まれるが、別インスタンスにある記事の実体までは含まれない。それぞれ保全する。

2. 論理モデル

項目 意味・保全先
Campus / Domain UUID・FQDN 既存の論理 identity。復旧でも変更しない
cluster_id 同じ復旧単位の primary / standby をまとめるUUID
node_id DRノード固有のUUID。復元時に新規採番する
primary_node_id スナップショットの作成元、または昇格後の自ノード
role primary / standby。プロセス起動時に読み、稼働中には変更しない
epoch 手動昇格の監査世代。分散ロック・署名manifestのfencing tokenではない
snapshot_id, captured_at 復元世代と保全開始時刻。再起動で鮮度をリセットしない
max_read_age_seconds 待機系の閲覧期限。初期値3,600秒、設定範囲1〜86,400秒
workers_enabled キュー、GC、管理Campus reconcilerの再開許可。復元・昇格直後はfalse
promotion_history 時刻、旧primary UUID、隔離の証跡、復元世代、epoch

設定は data/dr-node.json。これはノード固有なのでprimaryのファイルをstandbyへ丸ごとコピーしない。dr restore がstandby用に生成する。dr-node.json を削除して昇格してはいけない。設定のない既存インスタンスは後方互換のため従来の書き込み可能起動となる。

DRホストの起動環境には PAGESWIKI_DR_EXPECT_ROLE=standby を指定する。設定が欠けた空volumeや、異なるroleのvolumeを誤mountした場合はDBを作らず起動を拒否する。昇格後に再起動するときだけ、配置設定も primary へ変更する。これは役割を変更する設定ではなく、期待した役割と実際が一致することを確認する安全装置。

既存の instance-ed25519.key と認証鍵は復旧する論理サービスの鍵であり、DRの物理 node_id とは別。鍵の複製を持つ旧ノードは確実に隔離する。

3. 初版の状態遷移とAPI

  1. 既存 primary を停止し、dr init でノード設定を作成する。
  2. 全writer停止中に dr snapshot で世代を作成する。primaryは完了後に再開できる。
  3. 別ホストへ転送し、dr verify → dr restore。復元結果は常にstandby。
  4. standby を別のローカルデータディレクトリから起動する。データvolumeは read-only mount とする。primaryとSQLiteファイルを共有しない。
  5. 障害時は旧primaryを永続的に隔離し、standbyも停止して dr promote。
  6. 復元後の権限・鍵・設定・キューを確認し、必要な修正をした上で、書き込み可能mountで再起動する。LB/DNSの切替は外部運用。
  7. キューの重複実行・外部送信を検討して、停止中に dr resume-workers。再起動でジョブとreconcilerが動く。

dr promote と dr resume-workers はホスト運用者向けCLIに限定する。campus_admin や domain_admin が他Campusを巻き込んでインスタンス全体の役割を変えるHTTP APIは設けない。

待機系の動作

  • SQLiteを mode=ro + query_only で開く。マイグレーション、Ensure系の初期化、認証鍵生成を行わない。
  • 書き込みHTTPメソッドを503で拒否する。認証発行、エディタ起動、外部エディタ起動、外部図表レンダリング、設定・連携・インポートも拒否する。POSTを成功扱いで捨てない。
  • GC、イベントスケジューラ、preview生成、外部カレンダー同期、Campus reconcilerを起動しない。
  • 普通のWiki文書・RAWの読み取りは従来の認可を通す。既存sessionもスナップショット時点のものに限る。新規ログインは不可。
  • 初版のorganizer/CalDAVと拡張機能APIはstandbyでは503。既存の読み取り経路にDB索引の修復・資格情報の更新があるため。昇格後は通常の機能を使える。全機能のread replicaを実装済みとはしない。
  • レスポンスは X-PagesWiki-DR-Role: standby、Cache-Control: private, no-store。RAWの長期cache指定よりも優先する。
  • 古くなった復元世代からの閲覧は503で閉じる。/health は生存確認だけで、書き込み可能の判定に使用しない。
  • GET /health/read はDB接続と閲覧期限を検査する。GET /health/write はstandbyで常に503。primary側の200も他ノードが停止している証明ではない。

公開範囲縮小、アカウント失効、セッション失効は保全時点より後の変更が反映されない。閲覧期限はその時間を制限するだけで即時失効を保証しない。第1段階ではstandbyは運用者の隔離された検証環境とし、通常の読み取りLBには組み込まない。実際に外部公開へ切り替える前に、復旧時点以降の権限縮小・失効を再適用する。

4. バックアップの内容と整合性

対象 取扱い
pages.db SQLite Backup APIで複製。コミット済みWALを含め、rowidを保存する
documents/** 記事・asset・taskのCASと、カレンダーの月別ICS・metadataを含む
themes/** ローカルテーマ
auth.key, instance-ed25519.key 存在する場合に保全。極めて機密性が高い
federation/** 管理Campus参加token・endpointなどの復旧情報
dr-node.json 除外。復元先でstandby用に新規生成
preview・一時import・編集中adapter workspace 除外。未保存編集は復旧対象外
Docker image、Compose、環境変数、TLS鍵、外部volume このCLIの対象外。別の保全対象台帳で管理

PAGESWIKI_AUTH_KEY を環境変数で与えている場合、それも別の暗号化されたsecret保全が必要。復旧先に同じ値を供給しないと既存認証・暗号化情報を復旧できない。CLIは環境変数の秘密値をmanifestに書かない。復旧に使用するアプリのimage digestと設定・secretの世代を運用記録に残し、まず同じバージョンで復元する。

なぜ初版は停止バックアップか

SQLite Backup APIはDB内の整合性を確保するが、同時に更新中の calendar.json や別ファイルまで同じ論理時点へ固定しない。DBとファイル正本の境界にglobal snapshot barrierがない現状では、稼働中の cp / rsync data/ を整合バックアップとはみなさない。

全てのWebサーバ、CLI、旧バイナリ、SQLite直接編集、外部writerを止める。新しいサーバ・データCLIは .pageswiki-instance.lock の共有ロックを保持し、保全・昇格は排他ロックで稼働中を拒否する。ただしこれは協調ロックであり、旧版や外部ツールを強制停止する機能ではない。--writers-stopped は実際の停止を運用者が確認したことの明示。

世代の作成・転送・復元

  • 同じfilesystem内の一時ディレクトリへ作成し、ファイルfsync、manifest検証後にno-replaceのatomic renameで公開する。既存の保存先へ上書きしない。Linuxの renameat2(RENAME_NOREPLACE) を必要とする。
  • manifestはsnapshot/cluster/source-node/epoch、保全開始・完了時刻、相対path・size・SHA-256の一覧を持つ。初版は最大100,000ファイル、manifest最大64MiB。
  • 全payloadのSHA-256、CASファイル名、DBの quick_check、Revision/asset/task正本参照の存在、カレンダーmetadataから参照する月別世代のhashを確認する。カレンダーイベント本文の意味的再パースや外部同期はしない。
  • symlink、絶対path、..、重複path、未知の保全root、manifestにないpayloadを拒否する。
  • 転送はSSH等の認証された経路で行う。検証に渡す期待manifest SHA-256を同じ未認証転送から自己申告させない。現在のmanifestは署名付きではなく、期待hashの真正性は運用者が保証する。
  • バックアップは暗号化済み保管先、暗号化transport、復旧担当者だけのアクセス権で扱う。CLI自身の暗号化・KMS連携は未実装。ファイル0600、ディレクトリ0700で生成する。
  • 復元は新規ディレクトリへコピーし、コピー後もhash検証する。稼働中のデータへoverlayしない。失敗世代は公開せず、旧世代を勝手に削除しない。
  • 世代更新は新規復元→standby停止→mount切替→再起動。初版の復元では物理node UUIDが毎回変わるため、その都度配置台帳を更新する。

世代保持の初期案は「直近3世代+日次7世代+週次4世代」。容量・法的保持・鍵ローテーションの要件を確認して決定する。自動削除はまだ実装しない。破損・誤削除が複製されても戻せるよう、同期先とは独立した世代バックアップを最低1系統持つ。

5. CLIの運用例

以下はLinux上のバイナリ例。実環境の絶対pathへ置換する。全コマンドは対象ディレクトリを明示し、保全先はデータディレクトリ外にする。コンテナでは一時CLI用コンテナへ同じdataとbackup保存先をmountし、entrypointに /pageswiki を指定する(image内の実際の配置を確認する)。

# 先にprimaryのサーバ・全writerを停止する。
pageswiki dr init --data-dir /srv/pageswiki/data
pageswiki dr status --data-dir /srv/pageswiki/data
pageswiki dr snapshot --data-dir /srv/pageswiki/data \
  --output /srv/backup/pageswiki/generation-001 --writers-stopped

# 出力された manifest_sha256 を保管し、snapshotとともにDR側へ安全に転送する。
# この時点でprimaryは再開できる。

# DR側。期待hashは安全に受け取った値。<EXPECTED_SHA256> は置換する。
pageswiki dr verify --snapshot /srv/backup/pageswiki/generation-001 \
  --manifest-sha256 '<EXPECTED_SHA256>'
pageswiki dr restore --snapshot /srv/backup/pageswiki/generation-001 \
  --manifest-sha256 '<EXPECTED_SHA256>' --target /srv/pageswiki/standby-001
pageswiki dr status --data-dir /srv/pageswiki/standby-001
# standby-001を /data:ro として起動。元の論理FQDN/Hostと環境secretを維持する。
# PAGESWIKI_DR_EXPECT_ROLE=standby も起動環境に設定する。

昇格例:

# 旧primaryを停止・隔離し、再起動しても復帰しない外部fenceを確認する。
# standbyも停止し、失われる範囲(captured_at以降)を確認する。
pageswiki dr promote --data-dir /srv/pageswiki/standby-001 \
  --fenced-node '<FORMER_PRIMARY_NODE_UUID>' \
  --fence-reference 'incident-123: power fencing independently verified' \
  --accept-data-loss

# 隔離環境でrw mount、PAGESWIKI_DR_EXPECT_ROLE=primaryへ切替。
# 権限失効を再適用し、起動・読み書き確認後に経路切替。
# ジョブはまだ停止。内容を確認・調整し、再びプロセスを停止してから実行する。
pageswiki dr resume-workers --data-dir /srv/pageswiki/standby-001 \
  --reviewed-restored-jobs
# 再起動でスケジューラ/GC/Campus reconcilerが再開する。

旧primaryはそのまま再参加させない。旧データは隔離して差分調査・必要な手動救出用に保全し、新primaryの最新スナップショットから新しいstandbyを作る。古いDBで新primaryを上書きする「切り戻し」は禁止。自動の双方向マージは提供しない。

6. Campusコントローラに固有の注意

Campus manifestの署名、発行sequence、管理ノードの受理sequenceと参加tokenを一体で保全する。記事バックアップとmanifest配信は同義ではない。

初版では既存Campus FQDNをDR側へ向け直す方式を採り、管理ノードへ勝手に別Campusを登録しない。ホスト名・証明書・reverse proxyの扱いは復旧手順に含める。PAGESWIKI_INSTANCE_FQDN も復旧する論理サービスに合わせる。

重大な未解決事項: 保全後にprimaryが新しいmanifestを発行し、管理ノードが既に受理していた場合、復元したcontrollerのsequenceが後退して再送を拒否され得る。DRのローカル epoch を増やすだけでは既存署名プロトコルのsequence後退を解消しない。reconcilerを既定停止する理由の一つである。強引なDB sequence書換えで回避せず、次段階で「外部fenceで承認されたcontroller epoch+epoch内sequence」のプロトコルと管理側の受理規則を実装する。それまではcontroller配信の完全自動復旧を保証しない。

7. 次段階:オンライン同期と自動昇格の詳細設計

以下は初版時点の構想。詳細化後の実施順は DR01〜DR13 を正とし、 probe/再参加gateと役割・writer境界の分離を先行する。実装済み項目ではない。

  1. オンライン整合checkpoint:全正本writer(Web、CLI、calendar metadata、GC)で共有する短時間barrierを設ける。DB backup cutoffとcalendar metadata世代一覧を固定し、その世代が参照するCAS/monthly blobのGC pinを持つ。大きいblob転送はbarrier解除後に低優先度で行う。SQLite単独online backupをこの代替としない。
  2. 転送と受理:instance-boundの別用途資格情報、mTLSまたは短命署名、cluster/node/epoch/sequence固定。Campus参加tokenを丸用しない。CAS差分転送→hash確認→DBとmetadata世代の受理→active pointer切替の順。途中世代はservableにしない。retryは同じsnapshot IDで冪等、帯域・IO・CPU上限、foreground優先、同時転送数を設定可能にする。
  3. 監視とUI:設定画面の「運用 / DR」にノード、role、最終検証世代、保全時刻、受信時刻、遅延、容量、最終訓練結果を表示。Campus画面から復旧単位への関連リンクを出す。緑は「HTTP疎通」ではなく「検証済み世代・鮮度・役割整合」、黄は遅延、赤は破損/期限切れ。Domain設定へDRのhostnameを重複入力させない。
  4. operator権限分離:インスタンス運用者がreplica/転送鍵/役割を管理し、campus_adminは所属Campusの復旧状態を参照する。共有DBを跨ぐ昇格・secret操作はcampus_adminだけでは許可しない。初版のCLIに後からAPIを接続する際も同じ境界とする。
  5. キュー・認証の復旧:session/policy revocation watermarkを同期し、古いACLからのreadをfail closedにする。jobにepoch leaseとidempotency keyを導入し、外部副作用は送信先も含む重複制御または確認フローを設ける。lease期限だけで旧executorを安全とはみなさない。
  6. controller epoch:署名対象にleader identityとepochを含め、管理インスタンスは承認された単調増加epochとsequenceを永続化する。epoch移行はout-of-bandで信頼したfencing承認だけが行えるようにする。古い鍵/epochの再送と復元後のrollbackを試験する。
  7. 自動昇格:第三のwitnessまたはconsensus storeと外部fencing backendを選択。lease失効時は旧primaryがcommitを拒否し、すべてのDB/ファイルwriterとジョブがepochを照合する。fence失敗・quorumなしでは書き込み停止を選び、二重writerを選ばない。これができるまで自動昇格ボタンや「疎通断だけでwrite ok」は実装しない。
  8. LB参照構成:write readiness、read freshness、drain、長時間upload、WebSocket、Host検証、接続中断時の冪等再試行を統合する。read/write振り分けはHTTPメソッドだけで決めない。RO nodeをwrite routeへ入れない。

API案は /_/api/v1/instance/dr/... を予約候補とするが現時点で未登録。転送はユーザーのPath URIと分離し、POST snapshots、snapshot ID配下のmanifest/payload、POST acknowledge をinstance-to-instance限定で設ける。公開 /_/api/v1/federation/enroll にbackupの読み出し能力を追加しない。

8. RPO / RTOと受入基準

初版のRPOは「障害発生時刻 − 最後にDR側で検証完了したsnapshotのcaptured_at」。保全予定間隔や転送開始時刻ではない。RTOには障害判断、外部fence、復元/検証、権限失効の再適用、サービス検査、経路切替を含む。目標値は実データ量と許容停止時間から別途決定する。RPO=0・無停止とは表明しない。

自動試験は合成データを使い、次を確認する。

  • 未checkpointのコミット済みWALを取り込み、rowidを維持する。
  • DB参照先の欠落・payload改変・manifest改変・path traversal・symlinkを拒否する。
  • 同じsnapshotを繰り返しverifyしても書き換えない。復元先既存ディレクトリを上書きしない。
  • サーバ/CLIの共有ロック中は保全・昇格を拒否する。
  • 復元後はノードUUIDが別になり、role=standby、worker停止となる。
  • standbyの起動とWiki読取でDBを変更せず、書込API/Store、外部起動、期限切れ閲覧を拒否する。認可をバイパスしない。
  • 旧primary identity・隔離の証跡・データ損失受容のいずれかがない昇格を拒否する。
  • 昇格後もjobを勝手に再送せず、明示的再開が必要。

実機の電源断、ネットワーク分断、鍵失効、容量不足、転送中断、DNS切替、controller sequence後退、復旧元と受信先のバージョン差異は別の復旧訓練が必要。訓練未完了を成功と扱わない。

9. 根拠資料と関連設計