Files
pages/docs/design/storage-portability-and-operations.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

411 lines
31 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.
# 保存基盤の多様化と運用機能の統合
状態:詳細設計・段階導入。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)