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.
411 lines
31 KiB
Markdown
411 lines
31 KiB
Markdown
# 保存基盤の多様化と運用機能の統合
|
||
|
||
状態:詳細設計・段階導入。2026-09-27。
|
||
本書は [基本設計](arch.md) と [拡張契約](platform-extension-architecture.md) を補完する。
|
||
各 TODO は実装済みを意味しない。本番 DB・保存先の移行は別途承認する。
|
||
|
||
## 1. 優先順位と対象
|
||
|
||
先に SQLite / PostgreSQL / MySQL、Redis 等の KV、ローカル / S3 / SSH / NFS / SMB の
|
||
役割・契約を整える。その上にバックアップ、リリース、CLI、export/import、Web バックアップ、
|
||
初回「ようこそ」画面を載せる。Web と CLI で別の保存実装を作らない。
|
||
|
||
実装順は **保存契約 → 正本の分離 → DB 移植 → 外部 Document → 運用ジョブ → UI**。
|
||
Redis を RDB の代わりに選ぶ UI や、S3 URL をローカルディレクトリ欄へ指定する方式は採用しない。
|
||
初期設定が SQLite + ローカルだけでも、単一ノード運用が追加サービスなしで成立すること。
|
||
|
||
## 2. 現行実装の監査
|
||
|
||
| 箇所 | 現状 | 移植前に必要な変更 |
|
||
| --- | --- | --- |
|
||
| `internal/db/db.go` | SQLite 固定、WAL、busy_timeout、NORMAL | 接続プロファイル、durability 設定、driver ごとの検証 |
|
||
| `internal/db/migrate.go` / `Ensure*Schema` | DDL とデータ移行が分散。core bootstrap の ALTER エラー無視は是正、他の Ensure は継続監査 | 新 migration runner への段階集約と driver 別 DDL |
|
||
| `internal/store` | `*sql.DB` への直接 SQL。SQLite 固有式が多い | repository ごとの SQL 分離・契約テスト |
|
||
| `internal/store/document_store.go` | SHA-256 正本と DB body の移行互換 | payload backend の分離、復旧時以外の暗黙再作成の縮小 |
|
||
| `internal/calendar/repository.go` | 月別 ICS + calendar.json、flock、rename、DB はキャッシュ | mutable canonical repository と条件付き世代更新 |
|
||
| `DocumentRoot` の利用箇所 | calendar、auth.key の親、preview、import、payload を兼用 | payload / canonical state / secrets / scratch の分離 |
|
||
| `DocumentPath` の利用箇所 | 外部コマンドへ直接ローカルパス | 期限付き Materialize、容量制限・後処理 |
|
||
| `data/pageswiki-cli` | Python sqlite3 とローカル Document を直接操作 | online API モードを主経路に、offline repair を明示分離 |
|
||
|
||
調査時点で SQLite 固有語(PRAGMA、sqlite_master、rowid、INSERT OR、strftime 等)が
|
||
テストを除く約 50 ファイルに存在する。接続ドライバだけ追加しても動作しない。
|
||
「接続できた」と「PagesWiki の全機能を利用できる」をサポート状態として区別する。
|
||
|
||
## 3. 正本・派生物・機密情報を分離する
|
||
|
||
| 層 | 主なデータ | 保存先 | 消失時の扱い |
|
||
| --- | --- | --- | --- |
|
||
| MetadataRepository | UUID、Path、Revision、ACL、ユーザー/グループ、タスク、設定、outbox、確定ジョブ | SQLite / PostgreSQL / MySQL | バックアップから復元が必要 |
|
||
| DocumentStore | SHA-256 で識別する不変バイト列 | local / S3 / 検証済み mounted filesystem / SFTP | バックアップから復元が必要 |
|
||
| CanonicalStateRepository | カレンダーのメタ情報、月ごとの ICS 世代、ユーザー設定 | 世代付きファイル正本(local から段階拡張) | バックアップから復元が必要 |
|
||
| CacheStore | 検索・表示・サジェスト・リソース集計の再生成可能データ | memory / SQL cache / Redis | 正本から再生成 |
|
||
| SecretStore | auth.key、署名鍵、暗号化鍵、接続資格情報 | secret file / 環境 / 外部 Secret manager | 別権限・暗号化して保全 |
|
||
| Scratch/Materialization | import 展開、外部ビューア用一時ファイル、生成中 preview | ノードローカルの専用領域 | 破棄して再実行 |
|
||
|
||
セッション失効、承認、ジョブ完了、タスクの変更を Redis のみの情報にしない。
|
||
「Redis の AOF を有効にしたから正本のバックアップを省略できる」とはしない。
|
||
|
||
## 4. 共通インターフェース
|
||
|
||
### 4.1 不変 Document
|
||
|
||
Go 契約は `internal/geduldh.Store`。2026-11-01に既存ローカル実装を
|
||
[Geduldh](ja/geduldh.md) へ分離し、`internal/documentstore.Store` は同じ型の互換aliasとした。
|
||
|
||
```text
|
||
Stat(ctx, sha256) -> { hash, size }
|
||
Open(ctx, sha256) -> Reader + ReaderAt + Seeker + Closer
|
||
PutIfAbsent(ctx, sha256, size, stream)
|
||
Verify(ctx, sha256)
|
||
```
|
||
|
||
- 保存キーは既存互換の `sha256/<先頭2文字>/<64桁hash>`。Path やファイル名ではない。
|
||
- サイズとハッシュの検証前に、完全な Document として読める状態にしない。
|
||
- 不変 payload を先に永続化し、その後に参照する DB transaction を commit する。
|
||
- DB rollback で未参照 blob が残るのは許容するが、存在しない blob の参照確定はしない。
|
||
- 読み取りの Open/Seek/ReadAt は大容量全体の先読みをしない。remote range は上限・期限付き。
|
||
- ETag は HTTP の条件付き取得に使い、SHA-256 とは別フィールドとする。
|
||
- timeout、not found、破損、認証失敗、容量不足を区別する。エラー時に local へ勝手に書かない。
|
||
- 通常の Put/Read インターフェースに Delete を含めない。GC は参照 snapshot、保持、backup pin、
|
||
進行中 upload の保護を持つ専用経路から実施する。
|
||
- local path を返すことを全 backend の必須機能にしない。
|
||
|
||
接続済みの範囲はローカルの保存・通常読み取り・サイズ取得・部分読み取りと、
|
||
外部ツール用 Materialize。HTTP の主要な本文配信・部分取得には Request.Context を接続した。
|
||
remote backend、従来の Revision 本文取得/保存 API 全体への context 伝搬は未接続。
|
||
既存の DB body fallback は互換のため維持する。起動時 backfill は保存先ごとの進捗を記録し、
|
||
完了済みの保存先では revisions の走査を省略する(後述)。
|
||
|
||
### 4.2 可変正本
|
||
|
||
カレンダーはファイル正本を維持し、月ごとの不変 ICS 世代を作成してから
|
||
calendar manifest を `CompareAndSwap(expectedVersion, nextManifest)` で更新する。
|
||
DB のカレンダー cache は manifest version に従って再生成する。
|
||
S3 で POSIX rename/flock を模倣せず、条件付き manifest 更新を使う。
|
||
カレンダーの競合は明示的に返し、古いキャッシュで正本を上書きしない。
|
||
世代の削除はバックアップ pin と参照中 version を考慮する。
|
||
|
||
### 4.3 外部ツールへの受け渡し
|
||
|
||
`Materialize(ctx, hash, quota) -> localPath, cleanup` を別サービスにする。
|
||
archive/PDF/動画/PE/DEB 等のローカルパス必須ツールはこれを利用する。
|
||
SHA-256 検証、容量上限、同一 blob の取得集約、参照中の退避禁止、期限、キャンセルを持つ。
|
||
remote Object URL や presigned URL を無条件にツールへ渡さない。
|
||
ZIP の範囲参照で足りる処理は Materialize せず ReaderAt を使う。
|
||
|
||
実装は `internal/geduldh.Materializer`(旧 `internal/documentstore.Materializer` は互換alias)と
|
||
`Store.MaterializeDocument(ctx, hash, maxBytes)`。同じ Store 内で同じ hash の取得をまとめ、
|
||
利用者ごとの lease で参照中のコピーを保持する。待機者の一人がキャンセルしても他の待機者の
|
||
取得は中断しない。全員がキャンセルしたら共有取得を中断し、最後の lease の Close で削除する。
|
||
取得・検証に成功するまで外部コマンドへパスを渡さない。コピーは 0700 の専用一時ディレクトリに
|
||
0400 で作り、正本への hardlink は渡さない(外部ツールが誤って正本を変更するのを防ぐ)。
|
||
|
||
現時点の固定上限(将来 deployment profile に移す):
|
||
|
||
- Store ごとに同時取得 2 件、取得待ち/利用中を含め 64 件、予約容量合計 2 GiB。
|
||
- 共有取得の期限は 2 分。呼び出し元の request/preview/metadata の期限でも待機を中断する。
|
||
- metadata / PDF は 512 MiB、動画 / 非 ZIP 展開は 1 GiB、Excalidraw は 16 MiB。
|
||
- 保存先は `TMPDIR`(未設定時は OS の一時領域)。DocumentRoot やネットワークマウントを使わず、
|
||
ノードローカルの十分な空き容量を持つ領域を指定する。tmpfs の場合はメモリ消費になる。
|
||
- 削除失敗時には予約容量を解放済みと見なさない。プロセス強制終了で残った一時ファイルの
|
||
安全な回収とリソース監視へのメトリクス接続は残件。
|
||
|
||
画像・ZIP サムネイル、ZIP 内の個別ファイル配信は Reader/ReaderAt を直接利用する。
|
||
ZIP の個別配信は互換 DB body の全体 hydration をしない。非 ZIP / PDF / 動画などは、
|
||
ローカル正本でも検証付き一時コピーを作るため追加 I/O が発生する。永続キャッシュや
|
||
reflink 最適化は容量/失効/破損検出の契約を保った上で別途導入する。
|
||
|
||
## 5. RDB の対応設計
|
||
|
||
### 接続と migration
|
||
|
||
- 接続プロファイルはインスタンス管理で指定。Domain 管理者に DSN を公開しない。
|
||
- driver ごとに host/port/database/TLS/secret reference/pool/timeout を持つ。
|
||
- 未対応 driver は起動前に明示エラー。SQLite にフォールバックしない。
|
||
- SQLite を既存互換で維持し、まず PostgreSQL、次いで MySQL 8.4 LTS / InnoDB を対象にする。
|
||
PostgreSQL の最低対応版は CI matrix の確定時に明示する。MariaDB を MySQL と同一扱いしない。
|
||
- 起動時 Ping、schema version、driver と schema の一致を検証する。
|
||
- migration は driver/version/checksum/applied_at の履歴と排他的ロックを持つ。
|
||
起動ごとの分散 Ensure* を段階的に集約し、未知の DDL エラーを無視しない。
|
||
- MySQL の DDL は暗黙 commit を前提に、再開可能な移行段階を記録する。
|
||
migration rollback を DB transaction だけで保証しない。
|
||
|
||
#### 初段の migration runner(実装済み範囲)
|
||
|
||
`internal/db.ApplySQLiteMigrations` は component ごとに連続した version、name、SQL の
|
||
SHA-256 checksum、適用時刻を `schema_migration_steps` に記録する。
|
||
専用 DB connection の `BEGIN IMMEDIATE` で他プロセスとの適用を直列化し、
|
||
DDL と履歴を一つの transaction で commit する。失敗時は rollback し、transaction の
|
||
状態が確定できなかった connection を pool へ戻さない。
|
||
適用済み SQL の変更、version の欠落、バイナリより新しい移行履歴は起動時にエラーにする。
|
||
適用済みの手順は編集せず、新しい version を追加する。
|
||
|
||
移行済みの利用先は Document backfill の進捗テーブルと、下表の 6 領域。
|
||
既存の `schema_migrations` / `revision_metadata_v1` は変更せず維持する。
|
||
core bootstrap の列追加は PRAGMA で存在確認し、未知の ALTER エラーを無視しない。
|
||
古い revision の hash 計算は 128 件ずつ UUID を選択し、本文は一度に一件だけ読み込む。
|
||
既存のすべての Ensure*Schema が新 runner へ移行したわけではなく、
|
||
PostgreSQL/MySQL 対応や schema drift の完全な検査を意味しない。
|
||
|
||
| component | 対象 | 旧版から不足時に追加する列 |
|
||
| --- | --- | --- |
|
||
| `projection-metadata` | `projection_metadata` | なし |
|
||
| `resource-history` | `resource_samples` | なし |
|
||
| `broadcasts` | `broadcasts` | なし |
|
||
| `browser-navigation` | `browser_navigation_links` | `is_directory` |
|
||
| `adapter-sessions` | `adapter_sessions` | `root_path`, `principal_uuid` |
|
||
| `imports` | import session/item/journal/City 対応の 5 テーブル | `import_journal.completed` |
|
||
| `event-jobs` | jobs/definitions/logs/log policies/log buckets/queue settings | `event_uuid`, `priority`, `max_attempts`, `started_at_ms`, `finished_at_ms`, `cancel_requested` |
|
||
| `document-store` | 本文移行の進捗 `document_backfills` | なし(v2 で契約を検証) |
|
||
|
||
定義は `internal/store/schema_modules.go` / `schema_jobs.go` と
|
||
`document_backfill.go` に置き、診断時には同じ定義を参照する。既存 `Ensure*Schema` メソッドは
|
||
互換ラッパーとして残し、テーブルの再作成・行の削除はしない。
|
||
条件付き列追加は存在確認と ALTER を同じ migration transaction 内で実施する。
|
||
追加列の宣言と schema assertion も checksum 対象とする。旧式定義の checksum は、
|
||
新しい空フィールドを JSON へ出さないことで維持する。
|
||
|
||
component の最新 version に、現在のスキーマ全体に必要な assertions を記載する。
|
||
適用済みでも毎回検査する。必要な列、一意性の対象列、インデックスの所属と列順、
|
||
追加列の型/NOT NULL/default、adapter session の部分 UNIQUE 条件を確認する。
|
||
すべての列の型・CHECK・照合順序・外部キーまでを網羅する汎用 diff ではない。
|
||
後続 version が意図的に列を削除する場合に備え、過去 version の assertions は最新の契約で
|
||
置き換える(過去の定義と checksum は改変しない)。
|
||
|
||
初回採用時は既存の行を保持したまま不足する既知の列・索引を作成する。
|
||
採用後に schema が欠落/変更した場合は自動再作成せず、起動を止めて調査対象とする。
|
||
event_jobs 用の検索索引は projection の初期化から Event Jobs の初期化へ移し、
|
||
派生キャッシュからジョブ正本のスキーマへ向かう不要な依存を取り除いた。
|
||
イベントキューは、既知の不足列を追加する v1 と、列を使う索引・周辺テーブルを採用する v2 に分ける。
|
||
実行中ジョブの再キューイングは通常起動の状態復旧処理として分離し、migration runner や診断から呼ばない。
|
||
|
||
`pageswiki schema status|check` は `mode=ro` / `query_only` 接続で、管理対象の履歴/checksum と
|
||
最新 schema assertions を検査する。読み取り transaction の snapshot から判断し、
|
||
未作成 DB の初期化・鍵生成・本文移行・ジョブ復旧を実行しない。
|
||
`check` の終了コードは current=0 / pending=2 / blocked・unknown・実行エラー=1。
|
||
未適用 DDL は実行せず計画だけ表示するため、pending の成功を保証する dry-run ではない。
|
||
未移行の従来 schema 処理は診断範囲外として出力し、起動リハーサルを別途要求する。
|
||
反映前の確認項目は [保存基盤のスキーマ変更・反映手順](../operations/storage-schema-rollout.md) を参照。
|
||
|
||
#### 再開可能な Document backfill(実装済み範囲)
|
||
|
||
- `Store.BackfillDocuments(ctx, batchSize)` が一回最大 128 件の UUID/hash を取得する。
|
||
本文は不足 blob の一件分だけ読む。単一の巨大な legacy 本文のメモリ上限は別の課題である。
|
||
- 保存先の `.document-store-id` と DB の `document_backfills` を対応させ、
|
||
UUID cursor・処理数・完了状態・更新時刻を記録する。UUID cursor は VACUUM で変わらない。
|
||
- payload の検証・永続化後にバッチの checkpoint を更新する。失敗時は未完了バッチを再実行する。
|
||
保存先単位のファイルロックで二重実行を防ぎ、ロック待ちも context のキャンセルを受け付ける。
|
||
- 正本が既にある場合はその SHA-256 を検証し、古い/空の DB body は使わない。
|
||
破損した正本は互換キャッシュで上書きせず、明示エラーにする。
|
||
- 保存先を空のディレクトリへ差し替えると identity が変わり、以前の完了状態を流用しない。
|
||
既存正本が一部欠落した場合の検出は verify/repair の役割であり、通常起動で全件監査しない。
|
||
- DB-only の旧 writer/importer を止めた保守状態で実施する。通常の Page 保存は
|
||
Document 永続化が先行するため、移行 cursor より前の UUID が増えても不足しない。
|
||
- 初回移行は引き続き起動前に完了させる。完了済みの通常起動では revisions を問い合わせない。
|
||
非同期化する際は未移行 payload の配信・readiness・保守モードの契約を先に整備する。
|
||
- backup/restore は `.document-store-id` も含めて保存先を保全する。これは資格情報ではない。
|
||
identity が欠落した旧バックアップは新しい保存先と扱い、再検証・移行する。
|
||
|
||
### SQL 差異と対策
|
||
|
||
| 差異 | 対策 |
|
||
| --- | --- |
|
||
| `?` / `$1` | repository の dialect/query builder で生成。文字列の単純置換はしない |
|
||
| PRAGMA / sqlite_master | schema inspector を backend ごとに分離 |
|
||
| `rowid` による順序 | 明示 sequence または `(created_at_ms, uuid)` 等の仕様化した順序へ移行 |
|
||
| INSERT OR IGNORE/REPLACE / UPSERT | conflict target と更新列を明示。REPLACE の delete+insert を模倣しない |
|
||
| 時刻関数 | 保存時刻はアプリ生成 UTC epoch ms / BIGINT、必要な DB 時刻用途は別途定義 |
|
||
| LIKE / 照合順序 | Path/UUID/ハッシュの大小文字・正規化規則を共有。DB の既定照合に依存しない |
|
||
| TEXT を含む複合 UNIQUE | MySQL の索引長を検討。長い Path は正規化 UTF-8 の digest を索引候補にし、原文比較で衝突検出 |
|
||
| FTS / 日本語 / ranking | SearchIndex 契約へ分離。DB ごとの全文検索結果が完全一致すると仮定しない |
|
||
| エラーコード | unique / FK / deadlock / serialization / busy を共通分類 |
|
||
| job claim / pagination | SQLite single writer、PostgreSQL/MySQL row lock + claim token、安定した keyset cursor |
|
||
|
||
SQL を全機能一度に書き換えず、スキーマ → Object/Path/Revision/Asset → 認証/ACL →
|
||
タスク/CalDAV → event/outbox/通知 → City/検索/管理の順に契約テストを追加する。
|
||
全 repository の通過前は PostgreSQL/MySQL を本番選択可能と表示しない。
|
||
外部 RDB を導入しただけでは HA ではない。job lease/fencing、可変正本、鍵共有が別の条件。
|
||
|
||
### DB 移行
|
||
|
||
既存データを上書きするのではなく、新規 target DB へ schema 作成 → snapshot import →
|
||
UUID/件数/参照整合性/ACL検証 → 停止時間内の差分反映 → 接続先切替を行う。
|
||
最初は書き込み停止で一貫性を確保し、オンライン dual-write は採用しない。
|
||
移行元は保持。新 DB に書き込み開始後の単純な DSN 戻しはデータ喪失となるため禁止する。
|
||
|
||
## 6. Redis / KV
|
||
|
||
初期用途は TTL 付き共有キャッシュ、短時間の同一処理集約、通知配信の補助。
|
||
永続ジョブ・通知 Inbox・失効情報・監査 outbox は RDB 側を正本とする。
|
||
|
||
- key は instance / domain / provider / schema / policy epoch を含める。
|
||
- 認可を含む表示 cache は principal と権限 version を分離し、古い ACL で許可しない。
|
||
- 接続 pool、TLS、ACL、タイムアウト、value 上限、TTL jitter、hit/miss/eviction を持つ。
|
||
- cache 障害は安全な DB 参照へ限定的に縮退し、全リクエストの stampede を防止する。
|
||
- Redis Pub/Sub は配送保証に使わない。通知の取りこぼしは DB Inbox から再取得する。
|
||
- 分散ロックだけで正本の排他を保証しない。多ノード更新は DB の fencing token を検証する。
|
||
- 永続化方式 RDB/AOF の運用と、再生成可能 cache のバックアップ不要性を区別する。
|
||
|
||
## 7. ファイルストア別の対応
|
||
|
||
| backend | 導入方法 | 必須条件・制限 |
|
||
| --- | --- | --- |
|
||
| local | 現在の data/documents と互換 | fsync、原子的な no-replace publish、ルート内アクセス |
|
||
| S3 compatible | SDK adapter、bucket/prefix/region/endpoint | 条件付き作成、range、checksum、multipart 中断回収、TLS |
|
||
| over SSH | 原則 SFTP adapter。SSHFS mount は別の検証対象 | known_hosts 固定、専用 user/root、host-key 変更を拒否、shell コマンド文字列禁止 |
|
||
| NFS | OS/Compose で管理者が mount、アプリはパスを利用 | protocol/mount/lock/durability を環境別認証、切断時に失敗させる |
|
||
| SMB | 同上、CIFS mount または後続 adapter | case-sensitive key 契約、rename/link/flush の実環境試験 |
|
||
|
||
### S3
|
||
|
||
SDK の標準 credential chain と secret reference を使い、本文や manifest に資格情報を埋め込まない。
|
||
bucket は private を既定とし、公開 URL と物理キーを分離する。
|
||
`If-None-Match: *` による作成、既存時の checksum 検証、`412` と通信障害の区別が必要。
|
||
S3 ETag は Document SHA-256 と見なさない。互換製品ごとに conditional/multipart/checksum を検証する。
|
||
upload は bounded spool または検証付き streaming とし、未検証データを final key へ公開しない。
|
||
LIST をバックアップの整合性境界にせず、DB snapshot の参照 manifest で必要な hash を列挙する。
|
||
障害中は書き込みを失敗させ、プロセスごとのローカル正本へ分岐させない。
|
||
|
||
### ネットワーク filesystem / SSH
|
||
|
||
SQLite の DB/WAL/SHM を NFS・SMB・SSHFS に置くことは禁止する。
|
||
共有可能にするのは、契約テストで検証した Document/正本 backend に限る。
|
||
アプリに mount 権限や任意 SSH コマンド実行権限を与えない。
|
||
mount が消えた際に空のローカル mountpoint へ書くことを防ぐ sentinel / device / mount-id 検証が必要。
|
||
context のキャンセルだけで、停止した NFS syscall を必ず中断できるとは扱わない。
|
||
独立 worker、I/O 上限、circuit breaker、管理者向け degraded 状態を設計する。
|
||
hard-link/no-replace や directory fsync のない共有領域を local backend として認定しない。
|
||
|
||
## 8. バックアップと export の区別
|
||
|
||
| 操作 | 目的 | 含めるもの |
|
||
| --- | --- | --- |
|
||
| backup/restore | 同一インスタンスの災害復旧 | DB snapshot、Document、カレンダー正本、設定、必要な鍵の暗号化保全 |
|
||
| export/import | Domain/Path/プロジェクトの移動・交換 | 許可範囲の内容・revision・asset依存・選択したメタ情報。秘密は既定で除外 |
|
||
| release/deploy | 実行コードの更新 | SemVer、Git commit、イメージ digest、schema互換条件。ユーザーデータとは別 |
|
||
|
||
バックアップ manifest は format_version、instance ID、アプリ SemVer、schema version、
|
||
各 DB snapshot、正本 generation、Document の hash/size、暗号化情報、完了状態を持つ。
|
||
全生成物を検証してから complete marker を発行する。部分生成を復旧可能と表示しない。
|
||
|
||
最初は全書き込み元(Web/API/CalDAV/CLI/同期 worker)を止める maintenance barrier を使い、
|
||
GC を pin して DB と可変正本を snapshot する。不変 blob のコピーはその参照集合で行う。
|
||
「DB はコピーしたが calendar.json は後から別の時点でコピーした」を許さない。
|
||
オンライン化は revision/outbox watermarks と snapshot pin 実装後の段階とする。
|
||
|
||
- SQLite:online backup API / 検証済み snapshot。稼働中の pages.db 単独 rsync はしない。
|
||
- PostgreSQL:論理 dump と必要に応じた physical backup/PITR を別モードにする。
|
||
- MySQL:InnoDB の consistent snapshot と migration/DDL 排他を確認する。
|
||
- Redis:再生成可能 cache は除外。独自永続用途を追加したら manifest へ明示する。
|
||
- 鍵・接続資格情報:別保護領域へ暗号化。復元に必要な鍵を同じ暗号化アーカイブ内だけに入れない。
|
||
- restore:新規領域へ展開・検証・dry-run、互換性確認、切替。通常 Web から稼働 DB を上書きしない。
|
||
|
||
保持期間、容量、転送帯域、暗号化、定期実行、リモート複製、リストア訓練を独立設定にする。
|
||
バックアップ削除は全世代を単純削除せず、増分依存と稼働リリースの復旧条件を確認する。
|
||
|
||
## 9. 手動スクリプト・CLI・Web の共通化
|
||
|
||
将来の `pageswiki-admin` / `pageswiki` 運用サブコマンドに処理を集約し、
|
||
編集可能な shell script は環境変数・設定ファイル・コマンドの薄い組み合わせにする。
|
||
スクリプトから直接各 DB のテーブルへ別々に書く方式は増やさない。
|
||
|
||
候補コマンド(**まだ未実装**):
|
||
|
||
```text
|
||
storage status / verify / migrate --plan / migrate --apply
|
||
backup create / list / verify / restore --plan / restore --apply
|
||
export --domain … --path … --format pageswiki-bundle
|
||
import --file … --plan / import --file … --apply
|
||
release verify / deploy --version vX.Y.Z --plan / deploy --apply
|
||
```
|
||
|
||
online CLI は共通 API と権限・監査・event queue を通す。offline は保守モード専用で、
|
||
直接 DB を開く現行 Python CLI は当面の互換/repair 経路として残す。
|
||
import はサイズ・件数・展開率上限、zip-slip、symlink/hardlink を検証し、試行計画を先に表示する。
|
||
UUID保持/新規採番、Path衝突、ACL継承、Cityサジェスト、部分失敗の再試行を明示選択にする。
|
||
|
||
Web バックアップは instance/campus 管理者向け。Domain export 権限と混同しない。
|
||
設定パネルには履歴・状態・検証結果をコンパクトに表示し、作成条件はダイアログに収める。
|
||
作成は既存 scheduler の `backup.create` / `backup.verify` event としてキューへ入れる。
|
||
API は `/_/api/v1/backup/`、ジョブ状態は既存 `/_/api/v1/event/` / `queue` を利用する案とする。
|
||
ダウンロードにも現在の認可、有効期限、監査、no-store を適用する。秘密付き archive を公開しない。
|
||
Web から任意の保存先パス・任意コマンド・任意外部 URL を指定できるようにしない。
|
||
|
||
release script は v0.1.0 で整備した digest 昇格を再利用する。
|
||
deploy は backup 検証 → image pull → maintenance/migration → health check → 切替。
|
||
DB migration 後の旧イメージへの自動 rollback は互換性が明示された場合だけ許可する。
|
||
|
||
## 10. 初回ようこそ画面
|
||
|
||
状態は `uninitialized → claimed → configuring → validating → ready`。
|
||
既存データのあるインスタンスには表示せず、DB 到達不能を未初期化と判定しない。
|
||
初期 DB 未作成でも使える bootstrap 設定は local protected file / secret mount に置く。
|
||
|
||
1. ホスト側で生成した短寿命・一回限りの setup token で管理者が claim(競合時は一人だけ成功)。
|
||
2. 単独 / controller / 外部 Campus 管理モードを選択。外部管理の名前等は従来どおり継承する。
|
||
3. Metadata DB、Document backend、canonical state、任意 Redis を設定。
|
||
4. TLS・資格情報・必要な保存操作を管理者指定 backend 内の専用 probe 領域で検証。
|
||
5. 最初の管理者、言語・タイムゾーン、FQDN、バックアップ先/保持方針を確認。
|
||
6. 設定を原子的に保存し migration/初期化を実行。成功後 setup token を失効し ready にする。
|
||
|
||
公開ネットワークで最初にアクセスした人を無条件に管理者にしない。
|
||
setup 完了後は token 再利用不可。機密欄の再表示・ログ出力をしない。
|
||
外部 Campus 自動参加など既存の非対話起動を維持する。
|
||
|
||
## 11. 段階別 TODO と受入条件
|
||
|
||
### S0:契約とローカル保存の是正
|
||
|
||
- [x] 不変 Document Store interface と既存キー規則を実装。
|
||
- [x] local の streaming 検証、no-replace publish、directory fsync、root 内アクセスを実装。
|
||
- [x] 現行 Store の保存・読み取り・サイズ・部分読み取りを接続。
|
||
- [x] 並行書き込み、既存破損、サイズ/hash不一致、キャンセル、パス逸脱をテスト。
|
||
- [ ] backup inventory / canonical state / secret / scratch の設定と寿命をコード上で分離。
|
||
|
||
### S1:移植準備
|
||
|
||
- [x] Open/Size/Window の context 付き API と主要 HTTP 配信への伝搬。
|
||
- [x] archive/preview/一覧サイズの直ファイルアクセスを置換し Materialize を導入。
|
||
- [x] ZIP 個別配信・画像/ZIP サムネイルを Reader/ReaderAt ベースへ変更。
|
||
- [x] 共有取得、キャンセル、容量/件数制限、破損、最終利用後の削除をテスト。
|
||
- [ ] 従来の Revision hydration/保存、一覧 DB クエリを含む全 payload API へ context を伝搬。
|
||
- [ ] Document の byte size を DB のメタデータとして確定し、外部 backend で一覧ごとの
|
||
Stat/HEAD が N+1 呼び出しにならないようにする(現状は既存のサイズ補完動作を維持)。
|
||
- [ ] Materialize の固定上限を設定化し、クラッシュ残骸の安全な回収・メトリクスを接続。
|
||
- [x] Document backfill の保存先 identity、UUID cursor、バッチ checkpoint、完了後の起動時走査省略。
|
||
- [x] SQLite migration runner の version/checksum/排他/rollback と旧 hash 移行のメモリ使用改善。
|
||
- [x] projection/resource/broadcast/browser-navigation/adapter-session/import の schema 定義集約、
|
||
既存データを保持した採用、条件付き列追加、schema assertion の契約テスト。
|
||
- [x] event queue/log schema の管理、起動時ジョブ復旧と schema 処理の分離。
|
||
- [x] 読み取り専用 `schema status|check` CLI(JSON/終了コード/履歴・契約検査/対象外範囲の明示)。
|
||
- [ ] backfill を保守 CLI / event queue / 進捗 UI へ接続し、非同期実行時の配信契約を整備。
|
||
- [ ] 既存 Ensure*Schema を migration runner へ段階移行し repository 別 SQL 契約テストを整備。
|
||
- [ ] deployment profile で SQL / Document / canonical / cache / secret の設定を分離。
|
||
|
||
### S2:外部 backend
|
||
|
||
- [ ] PostgreSQL の全 repository 移植と SQLite との共通機能テスト。
|
||
- [ ] MySQL の DDL/索引/照合順序/同時書き込み試験。
|
||
- [ ] S3 adapter と互換サービスで range/条件付き作成/破損/切断/容量制限を検証。
|
||
- [ ] SFTP adapter と host-key 検証、NFS/SMB/SSHFS の契約検査と mount 喪失検知。
|
||
- [ ] Redis cache adapter と停止時の制限付き縮退、policy epoch による失効。
|
||
- [ ] mutable canonical CAS と metadata 参照の回復プロトコル、HA の fencing。
|
||
|
||
### S3:運用と移行
|
||
|
||
- [ ] 編集可能な設定例と薄い backup / release / deploy script。
|
||
- [ ] DB/Document/calendar/keys を束ねる backup manifest、pin、verify、restore rehearsal。
|
||
- [ ] 共通 online CLI、portable bundle export/import、plan/apply/retry。
|
||
- [ ] Web バックアップ管理、初回ようこそ画面、ジョブ状態とリソース監視の接続。
|
||
|
||
完了条件は接続成功だけではなく、機能契約・故障注入・再起動・データ移行・
|
||
バックアップからの復旧試験まで通ること。未実装 backend を「対応済み」と表示しない。
|
||
|
||
## 12. 根拠資料
|
||
|
||
- [SQLite WAL:network filesystem の制約](https://sqlite.org/wal.html)
|
||
- [S3 の conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)
|
||
- [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)
|
||
- [PostgreSQL backup / restore](https://www.postgresql.org/docs/current/backup.html)
|
||
- [MySQL 8.4 backup / recovery](https://dev.mysql.com/doc/refman/8.4/en/backup-and-recovery.html)
|