Refactor architecture into eight components and consolidate reliability work
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s

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.
This commit is contained in:
Anya Tokugawa committed 2026-11-01 15:23:31 +09:00
1 parent 9dd425f765
commit d5d21b7841
302 files changed
+20037 -3492

No files matched your search

@@ -0,0 +1,64 @@
# 2026-11-01:City閲覧導線とpages-cliの反映
## 反映対象
2026-11-01 12:39 JST頃、Compose `app` / `app2` を切り替えた。連携アダプタは再作成していない。
- City検索結果とサジェストから、設定画面ではなく対応Pageまたは配下のブラウザ一覧へ遷移。
- 生成された未整理Spotの既定名を親Streetの表示名へ射影。内部名・UUID・Path境界と独自タイトルは維持。
- 親階層を含む閲覧権限の確認、匿名表示名の再計算、検索画面のモバイル幅調整。
- `pages-cli` ソースをイメージの `/src/pages-cli/` に収録。CLIはホストの `/home/anya/.local/bin/pages` に配置。
直前のcommand版をベースに選択した31ファイルのみをCOPYしてビルドした。作業ツリー全体は含めない。電話連絡先、SQLite初期接続の後続変更は引き続き未反映。DBスキーマ・正本形式・認証設定の変更はない。
## イメージ・復旧点
- 反映版:`pageswiki-app:city-pages-cli-20261101`
- ID:`sha256:bed6b2d3e497e72c26feba4edf225fd9c57d49546fec43db2f88f297fcd989ee`
- 直前版:`pageswiki-app:rollback-before-city-pages-cli-20261101`
- 直前版ID:`sha256:d6c059486c238a1af0c9ebb2b2f3ed51c005a9670a703c55c077ef5a56ca1ec2`
- 限定ビルドレシピと配布ソース:`.deployment-backups/prod-city-pages-cli-20261101/{Dockerfile,overlay/}`
- 同ディレクトリの `reference/` は直前イメージのソース、`verify/` は反映対象を合成したテスト用ソース。どちらも本番データではない。
- 既存の停止時整合バックアップは保持。今回はデータ契約が不変のため、新たな全データコピーは取得していない。
`pageswiki-app:latest` を反映版へ変更。Git commit/push、レジストリpush、バージョンタグ追加は行っていない。
## 検証
- 限定ソースと候補イメージそれぞれで `go test ./... -count=1` 成功。イメージの試験はネットワーク無効、CPU 2、メモリ2GiB。
- Python単体テスト12件成功。ホストの限定ソースで `TestRemoteCLIHTTPIntegration` の実行・成功を個別に確認。ログイン/既定設定/一覧/編集/競合拒否/ログアウトを合成データで検証。イメージ内にPythonは追加しておらず、イメージ内の同テストはskipする。
- 限定ソースのCity系・検索結果・コマンドバー/ハイライトのChromium試験成功。検索結果は1440px/390pxを検査。
- 既存バックアップのリハーサル専用コピー2系統を、ネットワーク無効・workers無効で起動。healthおよび管理対象8コンポーネントのschema check成功。リハーサルコンテナは切替前に削除。
- 本番2台のイメージID一致、両方running/再起動回数0、app healthy。
- localhost3000/3001と公開HTTPSのhealth、公開ログインが200。
- 公開HTTPSのCity関連JS3ファイルと検索CSSのSHA-256が配布元と一致。
- 本番2台の管理対象schema check成功。切替直後のログでpanic/fatal/job failed/database locked/scheduler claim failedの該当0件。
外部取り込みカレンダーの内容にはアクセスしていない。上記は長期負荷試験や本番の全データ完全性検査を意味しない。
## CLIの利用
配置前に既存 `pages` コマンドがないことを確認。ユーザーPATHに含まれる `/home/anya/.local/bin/pages` に0755で配置し、helpとソースとのSHA-256一致を確認した。
SHA-256:`1a6feb7349a5b1b5b25fbb46cab1c7ac7dd7a46cbaab5aea803151305ac9da77`
```sh
pages configure --origin https://pages.anya.jp --username anya
pages login
pages
```
利用者のプロファイルや資格情報は作成していない。本番資格情報による編集試験も行っていない。クライアントはPython 3.9以降のUnix系環境向け。別端末へのインストールは [pages-cli README](../../../pages-cli/README.md) を参照。OIDC引き継ぎ・Ctrl+P fuzzy UI・新規Page作成は後続。
## 今回の切り戻し
今回の変更にDB/正本の移行はない。データを戻さず、直前のcommand版イメージへ切り替える。
```sh
docker image tag pageswiki-app:rollback-before-city-pages-cli-20261101 pageswiki-app:latest
docker compose up -d --no-deps --no-build app app2
```
両イメージID、health、ログイン、再起動回数を確認する。これは今回の変更専用の手順で、保存基盤変更前の古い版には適用しない。
CLIはサーバから独立しているため、サーバ切り戻しで削除する必要はない。利用停止時も保存済みセッションや設定を無断で削除しない。
@@ -0,0 +1,45 @@
# 2026-11-01:コマンドバーと共通シンタックス色の本番反映
## 反映対象
2026-11-01 07:14 JST頃、Compose `app` / `app2` に反映。関連アダプタのコンテナは再作成しない。
- ブラウザ左下の `cd` / `vi` / `view` バー、文字入力によるフォーカス、TabによるPath補完。
- 共通ナビがあるホーム以外の画面での `g` コマンドモード。編集中の入力/Vim操作は保護。
- ブラウザのPathアドレス欄をtopbarへ統合。狭い画面では非表示。
- エディタ、読み取りコードビューア、言語指定付きコードブロックのテーマ連動シンタックス色。
イメージは稼働版fix2をベースに、限定した26ファイルをCOPYして再ビルド。全作業ツリーをCOPYしない。電話連絡先およびSQLite初期接続の後続変更は含まない。今回の変更はスキーマ、正本形式、認証設定を変更しない。
## イメージと復旧点
- 反映版:`pageswiki-app:command-20261101`
- 反映版ID:`sha256:d6c059486c238a1af0c9ebb2b2f3ed51c005a9670a703c55c077ef5a56ca1ec2`
- 直前版:`pageswiki-app:rollback-before-command-20261101`(元タグ `pageswiki-app:ux-20261101-fix2`)
- 直前版ID:`sha256:aa4336dd677b27966df8732054a27b3544560c6fffb18b232e89d4f764b1551e`
- 限定ビルドレシピ:`.deployment-backups/prod-command-20261101/Dockerfile`
- 直前版ソース参照コピー:同ディレクトリの `reference/`。本番データではない。
- 前回の停止時整合バックアップ/オンラインDBバックアップは保持。今回はDB変更がないため、新たな全データバックアップは取得していない。
現在の `pageswiki-app:latest` は反映版。Git commit/push、レジストリpush、リリースタグ追加は行っていない。
## 検証
- 候補イメージ内で `go test ./... -count=1` 成功。ネットワーク無効、CPU 2、メモリ2GiBで実行し、テストは合成データを使用。
- 既存の本番バックアップのリハーサル用コピー2系統を使用。ネットワーク無効、workers無効で起動。両方のhealthと管理対象8コンポーネントのschema check成功。外部取り込みカレンダーの内容は開かない。検証コンテナは切替前に削除。
- 実装時にChromiumの1440px/375px操作試験、ホーム・エディタ回帰試験済み。実機iPhone Safariやソフトウェアキーボードは未確認。
- 本番両コンテナのイメージIDが反映版と一致。app healthy、両方running/再起動回数0。
- localhost3000/3001および公開HTTPSのhealthが200。公開ログイン200。匿名の `/e/` は正規化後にログインページへ遷移。
- 公開URLのコマンドJS、アドレスJS、ハイライトJS、コマンドCSS、テーマbase CSS、CodeMirror bundleのSHA-256がローカル配布ファイルと一致。
- 切替後の両インスタンスで管理対象スキーマ検査成功。これは全データ完全性検査や長期負荷試験を意味しない。
## この反映だけを切り戻す場合
DB/正本の変更がないため、fix2へはデータを巻き戻さずイメージだけで戻す。ユーザの新しい書き込みを削除しない。
```sh
docker image tag pageswiki-app:rollback-before-command-20261101 pageswiki-app:latest
docker compose up -d --no-deps --no-build app app2
```
切り戻し後は両イメージID、health、公開ログイン、再起動回数を確認する。この手順は今回のcommand版からfix2への切り戻し専用であり、保存基盤変更前の古い版には適用しない。
@@ -0,0 +1,58 @@
# 2026-11-01:優先UXの本番反映
## 対象と復旧点
- 対象:Compose `app` / `app2`。最新のUXに加え、作業ツリーにあった保存基盤・スキーマ管理・DR・エディタ復旧の変更を含む。
- 旧イメージ:`sha256:3ee1b6b5ff24154c05990f02f112db7052b5a9bfb9894e5e9020a55fbb539d8c`。
- 旧版タグ:`pageswiki-app:rollback-before-ux-20261101`。
- 初回候補:`pageswiki-app:ux-20261101`、`sha256:1efb6fa94ae447e4769fa1056eb88fd34274cd17264646ad22a13327e05567b7`。隔離検証で旧索引との不一致を検出したため本番へは適用しない。
- 修正候補:`pageswiki-app:ux-20261101-fix1`、`sha256:1cae0988fdc2a9d008fe971ed7f92bff9e4831b1798d080e4551b9efeca31958`。
- 停止時整合バックアップ:`.deployment-backups/prod-ux-20261101/before/{data,data2}`。親ディレクトリ0700。アプリ2台を停止して全データをコピーし、DB本体の一致とsyncを確認。
- ソースの復旧点:`.deployment-backups/dev-priority-20261031/`。Gitの未コミット変更は保持し、commit/push/tagは行わない。
## 実行基盤の障害と復旧
整合コピー後、旧コンテナの再開が `failed to create TTRPC connection: unsupported protocol` で失敗した。新コード起動・新migration適用の前に発生。
起動中のDocker 29.5.0 / containerd 2.2.3と、インストール済みDocker 29.8.2 / containerd-shim 2.3.6が不一致だった。実行中の `/proc/.../exe` は削除済み旧バイナリを参照していた。
このrootless Dockerの稼働コンテナがPagesWiki関連のみであることを確認し、`systemctl --user restart docker` で更新済み実行基盤へ切り替え、既存コンテナを再開。rootful Dockerやホスト全体の再起動は行っていない。旧アプリの起動中、一時的にapp2のenroll接続が拒否されたが、app起動後に回復した。
旧版復旧後、公開URLとlocalhostの3000/3001双方の `/health` が200、appのDocker healthがhealthyであることを確認した。
## 検証・反映の進捗
- [x] 全Goテスト成功、候補イメージのビルド成功。
- [x] 旧版・停止時の正本/DB/鍵を保全。
- [x] バックアップのコピーを `--network none`、workers無効で起動し、migration/backfillを検証。
- [x] 管理対象8 componentがcurrent。双方のSQLite quick_check、メインDBのintegrity_check成功。本文backfillはメイン1,928件・外部側0件で完了。
- [x] オブジェクト1,598/Revision1,928/Path1,093/Principal1件が移行前後で一致(外部側は各0件)。認証画面と新規静的アセットの応答を確認。
- [x] 05:55 JST頃、停止時の追加バックアップ `cutover/{data,data2}` を取得(beforeから変更のないファイルのみrsync --link-destで共有、ライブデータへのhardlinkではない)。DB一致とsync後、fix1をlatestに付け替え、app/app2のみ再作成。
- [x] 両インスタンスのヘルス200、app healthy、公開HTTPSのヘルス200・ログイン200・匿名エディタ303。ホーム入力検索/ブラウザアドレスJSの公開URLとローカルのSHA-256一致。両DBのschema check成功。
- [x] 切替直後の監視で両アプリの再起動回数0。外部カレンダーの内容は開かずに確認。継続監視では05:59:59 JSTにscheduler claimのSQLITE_BUSYを1件検出(下記)。
外部取り込み済みカレンダーの内容は検証対象にしない。リハーサル用データから外部同期・通知送信を行わない。
この反映に電話連絡先の後続開発は含めない。最終反映済みイメージはfix2に固定し、以後の作業ツリーと区別する。追加機能の本番反映は別途検証して行う。
### スケジューラの継続検証
05:59:59 JSTに `event scheduler claim failed: database is locked (5)` が1件発生。以後の直近5分では38ジョブが成功しており、停止/ジョブ失敗ではなかった。旧版にもあった、deferred read transactionからwriteへの昇格競合を除去するため、`ClaimDueEvent` を `UPDATE ... WHERE uuid=(SELECT ...) RETURNING ...` の単一statementへ変更。優先度/実行可能時刻/attemptsを保持し、同時取得をSQLiteが直列化する。
8つの独立DBハンドル+並行する別書き込み、64ジョブの重複なし全件取得を10回検証。race検査も成功。新規schemaなし。fix1ベースに `internal/store/event_jobs.go` だけを差し替えた `pageswiki-app:ux-20261101-fix2`(`sha256:aa4336dd677b27966df8732054a27b3544560c6fffb18b232e89d4f764b1551e`)を構築。イメージ内の全Goテストと隔離データ2系統の起動・schema checkが成功。
fix2には電話連絡先/新規SQLite初期接続の後続変更は含まない。`Dockerfile.scheduler` はバックアップディレクトリに保存。切替前のオンラインSQLiteバックアップは `before-scheduler/` に保管(DB単体であり、全正本の整合復旧点はcutover)。fix2→fix1は同一schema/データ契約のためイメージのみで戻せる。cutoverへの全データ復旧とは区別する。
06:06 JST頃、fix2をlatestとしてapp/app2を再作成。両方の実行イメージIDを照合し、公開HTTPS/localhost3001のヘルス200、app healthy、再起動回数0を確認。初回確認期間でpanic/job failed/database locked該当ログ0件。長期負荷検証を完了した意味ではなく、過長な別writerによるSQLITE_BUSYまで根絶したとの主張ではない。
後続開発ソースの保全先:`.deployment-backups/dev-followup-20261101/source-after-contacts.tar.gz`。全Goテスト、電話連絡先のChromium操作、初期接続の反復試験はローカルで実施。アプリケーションDBと外部取り込みカレンダーの実データを後続機能テストには使用しない。
### リハーサルで修正した問題
旧DBの `idx_event_jobs_due(status,run_at_ms,created_at_ms)` が残るため、`CREATE INDEX IF NOT EXISTS` だけではpriority付き索引にならず、`event-jobs/2 assertion 12` に失敗した。未リリースの採用migrationで、この非一意索引をtransaction内で一度再構築する。両本番バックアップに既存の `schema_migration_steps` がないことを確認し、適用履歴を削除する回避は行っていない。
`TestEventJobsAdoptLegacyDueIndex` で旧索引からの移行、再実行、job本文・status・attempts・時刻の保持を検証。変更後の全Goテストも成功。
## ロールバック
データ形式の互換性を確認する前に旧イメージだけへ戻さない。書き込みを停止し、新版稼働後のデータも別途保全したうえで、切替直前のDB・正本・鍵と旧イメージの組み合わせへ復元する。ユーザの新規書き込みを無断で破棄しない。詳細は [保存基盤反映手順](../storage-schema-rollout.md)。
+124
View File
@@ -0,0 +1,124 @@
# 保存基盤のスキーマ変更・反映手順
2026-09-27。保存基盤の段階移行に関する運用メモ。
本書の作成時点では開発用の一時 DB で検証しており、本番 DB への適用を意味しない。
詳細は [保存基盤の設計](../design/storage-portability-and-operations.md) を参照。
## 今回の変更と別の DB 操作との関係
別の DB 修正、復旧、import、DB-only CLI 書き込みと同時に適用しない。
先に使用するバイナリ・スキーマ・保存先の組み合わせを決め、整合バックアップを取得する。
ソースの実装完了と、本番への migration 適用完了は別の状態である。
アプリケーションを新しいコードで起動すると、以下を実行する。
1. `schema_migration_steps` に component/version/name/checksum/適用時刻を記録する。
2. `document_backfills` と保存先の `.document-store-id` により、本文移行の進捗を管理する。
3. プレビューのメタデータ、リソース履歴、アナウンス、ブラウザナビゲーション、
アダプタセッション、インポート履歴、イベントキュー/ログを migration 管理下へ取り込む。
4. 古い DB で不足していれば `browser_navigation_links.is_directory`、
`adapter_sessions.root_path` / `principal_uuid`、`import_journal.completed` を追加する。
`event_jobs` の既知の追加列も存在を検査してから追加し、ALTER の失敗を握りつぶさない。
5. イベントキューのスキーマ検証後、通常起動時のみ中断ジョブを再キューイングする。
読み取り専用の事前チェックではこの復旧処理を呼ばない。
現在の既存コードですでに追加済みの列は重複して追加しない。
対象テーブルの再作成、既存行の削除、本文の一括書き換えは行わない。
旧式の `schema_migrations` は削除/リネームしない。
認証・ACL、City、タスク、カレンダーを今回の 7 component に含めない。
別に `document-store` component が本文移行の進捗テーブルを管理する(合計 8 component)。
これらの既存起動時処理まで無変更になる、という意味ではない。
## 反映前の確認
- SQLite の整合バックアップと Document / calendar 正本 / 鍵を同じ復旧点として保全する。
稼働中の DB ファイルだけをコピーして完了としない。
- DB とファイルを隔離したコピーを作り、新しいバイナリで起動試験する。
本番の FQDN、外部同期先、通知送信先へ接続しない環境で実施する。
- 新旧スキーマからの採用テストと全体回帰テストの結果を確認する。
- migration 定義の checksum 不一致、必要な列/索引/一意性制約の欠落があれば、
適用履歴を削除して回避せず、定義の変更か既存 DB の不整合かを調べる。
- 長い SQL transaction、DB-only writer、旧プロセスによる保守操作を停止してから反映する。
SQLite の `BEGIN IMMEDIATE` による短時間の排他が必要で、ロック競合はエラーになり得る。
- 初回 backfill は保存先内の未移行データを検証するため時間がかかることがある。
起動前に完了させ、通常の配信を先に始めない。完了後の起動では全 Revision を走査しない。
## 読み取り専用で確認できる情報
### schema CLI
新しいバイナリを用意した段階で、Web サーバーを起動せず実行できる。
```sh
./pageswiki schema status --data-dir /path/to/data
./pageswiki schema check --db /path/to/data/pages.db --json --timeout 30s
```
`--data-dir` を省略した場合は `PAGESWIKI_DATA_DIR`、未設定なら `./data` を使う。
`--db` と明示的な `--data-dir` は同時指定しない。
- `status`:管理対象 component の適用済み/最新 version、未適用 step、契約検査結果を表示する。
読み取りに成功すれば終了コード 0。監視などで判定する場合は `check` を使う。
- `check`:管理対象すべてが current なら 0、pending があれば 2、
blocked/unknown があれば 1。DB 読み取り失敗や不正な引数も 1。
- `blocked`:履歴の欠落・checksum 不一致・対応 version より新しい履歴、
または適用済みスキーマが最新契約を満たしていない。
- `unknown`:DB に記録された component をこのバイナリが認識しない。
- `pending`:未適用の定義がある。まだ作られていない列/テーブルによる assertion の失敗も
併記するが、DDL の実行成功・失敗を予測した結果ではない。
`mode=ro` と `query_only` による読み取り専用接続、一つの読み取り transaction を使う。
DB/データディレクトリの作成、通常起動処理、鍵生成、本文 backfill、ジョブ復旧を実行しない。
稼働中 DB の committed WAL も参照する。SQLite の WAL/SHM ファイルのアクセス要件は必要で、
ファイルシステム上の一切のメタデータ変更がないことまで保証するモードではない。
**このコマンドは完全な移行リハーサルでも、全 DB の健全性検査でもない。**
出力の `coverage=managed-components-only` と `legacy_areas` を確認する。
終了コード 0 でも、未移行の従来初期化処理、正本ファイル、データ依存の移行、
外部接続の正常性は証明しない。隔離コピー上での起動試験を省略しない。
### SQL による補助確認
DB のパスは実際の起動設定で確認し、SQLite クライアントを read-only モードで使用する。
次の SQL は状態確認用で、テーブルを作成しない。
```sql
SELECT name FROM sqlite_master
WHERE type='table'
AND name IN ('schema_migration_steps', 'document_backfills');
```
テーブルが存在する場合のみ、続けて確認する。
```sql
SELECT component, version, name, checksum, applied_at_ms
FROM schema_migration_steps ORDER BY component, version;
SELECT store_id, last_uuid, processed, completed, updated_at_ms
FROM document_backfills ORDER BY updated_at_ms DESC;
```
`completed=1` は「その保存先への初回移行が完了した」ことを示す。
すべての正本の現在の健全性を証明する値ではない。欠落や破損は verify/repair の対象とする。
`.document-store-id` は復旧対象に含める。空の保存先へ入れ替えた場合に、このファイルだけを
コピーして完了状態を引き継がせない。
## ロールバック・失敗時
DDL と migration 履歴の記録は同じ transaction で rollback する。
Document backfill はバッチ単位で進捗を確定し、失敗したバッチは次回再実行する。
すでに保存した不変 Document が残っていても、検証して再利用する。
起動失敗時には component/version とエラーを保存し、旧バイナリへの切り戻しを
無条件に行わない。旧バイナリが新しい migration 履歴を理解しない可能性があるため、
DB と正本のバックアップからの復旧か、互換性を検証済みの切り戻しを選ぶ。
DR standby ではこれらの schema 作成・採用を実行しない。
## 残件
- 全 Ensure*Schema の集約と、型/CHECK/照合順序/外部キーまで含む schema 契約の拡充。
- DB ごとの差異を切り分け、PostgreSQL / MySQL の共通機能テストを整備。
- 本文の健全性/backfill 状態の専用診断、保守 CLI、進捗 UI と event queue の接続。
- 初回 backfill の非同期化に先立つ、未移行データの配信と readiness の設計。
外部 DB への接続や、本番 DB の移行は上記を完了・検証した段階で別途実施する。