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.
31 KiB
保存基盤の多様化と運用機能の統合
状態:詳細設計・段階導入。2026-09-27。 本書は 基本設計 と 拡張契約 を補完する。 各 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 へ分離し、internal/documentstore.Store は同じ型の互換aliasとした。
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 処理は診断範囲外として出力し、起動リハーサルを別途要求する。
反映前の確認項目は 保存基盤のスキーマ変更・反映手順 を参照。
再開可能な 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 のテーブルへ別々に書く方式は増やさない。
候補コマンド(まだ未実装):
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 に置く。
- ホスト側で生成した短寿命・一回限りの setup token で管理者が claim(競合時は一人だけ成功)。
- 単独 / controller / 外部 Campus 管理モードを選択。外部管理の名前等は従来どおり継承する。
- Metadata DB、Document backend、canonical state、任意 Redis を設定。
- TLS・資格情報・必要な保存操作を管理者指定 backend 内の専用 probe 領域で検証。
- 最初の管理者、言語・タイムゾーン、FQDN、バックアップ先/保持方針を確認。
- 設定を原子的に保存し migration/初期化を実行。成功後 setup token を失効し ready にする。
公開ネットワークで最初にアクセスした人を無条件に管理者にしない。 setup 完了後は token 再利用不可。機密欄の再表示・ログ出力をしない。 外部 Campus 自動参加など既存の非対話起動を維持する。
11. 段階別 TODO と受入条件
S0:契約とローカル保存の是正
- 不変 Document Store interface と既存キー規則を実装。
- local の streaming 検証、no-replace publish、directory fsync、root 内アクセスを実装。
- 現行 Store の保存・読み取り・サイズ・部分読み取りを接続。
- 並行書き込み、既存破損、サイズ/hash不一致、キャンセル、パス逸脱をテスト。
- backup inventory / canonical state / secret / scratch の設定と寿命をコード上で分離。
S1:移植準備
- Open/Size/Window の context 付き API と主要 HTTP 配信への伝搬。
- archive/preview/一覧サイズの直ファイルアクセスを置換し Materialize を導入。
- ZIP 個別配信・画像/ZIP サムネイルを Reader/ReaderAt ベースへ変更。
- 共有取得、キャンセル、容量/件数制限、破損、最終利用後の削除をテスト。
- 従来の Revision hydration/保存、一覧 DB クエリを含む全 payload API へ context を伝搬。
- Document の byte size を DB のメタデータとして確定し、外部 backend で一覧ごとの Stat/HEAD が N+1 呼び出しにならないようにする(現状は既存のサイズ補完動作を維持)。
- Materialize の固定上限を設定化し、クラッシュ残骸の安全な回収・メトリクスを接続。
- Document backfill の保存先 identity、UUID cursor、バッチ checkpoint、完了後の起動時走査省略。
- SQLite migration runner の version/checksum/排他/rollback と旧 hash 移行のメモリ使用改善。
- projection/resource/broadcast/browser-navigation/adapter-session/import の schema 定義集約、 既存データを保持した採用、条件付き列追加、schema assertion の契約テスト。
- event queue/log schema の管理、起動時ジョブ復旧と schema 処理の分離。
- 読み取り専用
schema status|checkCLI(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 を「対応済み」と表示しない。