diff --git a/docs/design/implementation-roadmap.md b/docs/design/implementation-roadmap.md index 8236668..1bc9bc7 100644 --- a/docs/design/implementation-roadmap.md +++ b/docs/design/implementation-roadmap.md @@ -52,10 +52,16 @@ deployment separately; a source checkpoint includes the pre-existing dirty workt See [component names, boundaries and acceptance criteria](ja/component-names.md). All eight initial component extractions are implemented; unchecked items describe remaining capabilities. +Released and deployed as [v0.2.0](../operations/deployments/2026-11-01-v0.2.0.md) on 2026-11-01. + +- [ ] Priority follow-up: eliminate AddEventLog deferred read-to-write transaction contention; + preserve atomic raw-log/bucket writes and test independent concurrent writers. Production + start-log failures are now observable; job execution succeeded, but log completeness is not guaranteed. ### Storage portability and operations (2026-09-27) -Implemented and fixture-tested in the working tree; **not deployed**. +Implemented and fixture-tested; included in the [v0.2.0 production release](../operations/deployments/2026-11-01-v0.2.0.md). +This does not mark the unchecked backend/HA capabilities below as implemented. - [x] Immutable local Document Store contract, bounded materialization and streaming archive access. - [x] Resumable document backfill with store identity, UUID cursor and batch checkpoints. diff --git a/docs/design/ja/component-names.md b/docs/design/ja/component-names.md index 7477bf3..737f1d3 100644 --- a/docs/design/ja/component-names.md +++ b/docs/design/ja/component-names.md @@ -210,3 +210,7 @@ Grammaratur から server/store/db/render/compiler へ戻る依存は作らな - 本番DB・本番ネットワーク・取り込み済み外部カレンダーへのアクセスは行っていない。 8部品の初期分離はソース変更と検証まで完了。commit・push・本番展開は本作業に含めていない。 + +その後の明示的なリリース依頼により、同日 `v0.2.0` としてcommit・push・CI・本番反映を完了した。 +[配布digest・移行・復旧点・開始ログ競合の継続課題](../../operations/deployments/2026-11-01-v0.2.0.md) +は初期分離の検証記録と分けて管理する。 diff --git a/docs/operations/deployments/2026-11-01-v0.2.0.md b/docs/operations/deployments/2026-11-01-v0.2.0.md new file mode 100644 index 0000000..42d1cce --- /dev/null +++ b/docs/operations/deployments/2026-11-01-v0.2.0.md @@ -0,0 +1,119 @@ +# PagesWiki v0.2.0 のリリースと本番反映 + +2026-11-01 15:38:54 JST、Giteaでビルドした `v0.2.0` を本番へ反映した。 +対象は `app`、`app2`、`adaptor-gateway`、`excalidraw-viewer` の4サービス。 +code-server、Kroki、Mermaidは再作成していない。 + +## ソースと配布物 + +- リリースcommit:`d5d21b78418683bc81ed384e0264102e39cd44ab`。 +- 注釈付きGitタグ:`v0.2.0`。タグobject:`43b66076a98aa9730e722f8f788dcaaa7647498f`。 +- [イメージビルド run 12](https://git.anya.jp/anya/wikipages/actions/runs/12):全工程成功。 +- [リリース昇格 run 13](https://git.anya.jp/anya/wikipages/actions/runs/13):全工程成功。 +- 公開済み `v0.1.1` から、機能追加を含むためSemVer運用規則に従いMINORを更新した。 + +8部品の初期分離に加え、未コミットだったエディタ復旧、ナビゲーション・テーマ、CLI、 +保存基盤・schema管理・DR関連の実装と設計書を含む。 +各設計書の未チェックTODOまで実装されたことを意味しない。 +本書の記録用commitはリリースcommitと区別し、公開タグは付け替えない。 + +registry prefixは `git.anya.jp/anya/`。以下はmanifest digestであり、ローカルimage IDとは別。 + +| イメージ | v0.2.0 のdigest | +| --- | --- | +| pageswiki-app | `sha256:35096c46310c5e5d02c1cf56cf94f21f1b6917067c9689c4824c971af9fec1d7` | +| pageswiki-adaptor-gateway | `sha256:11f93ae28d00e82a92a0c32be7daee85f569b5b975decd8812be0dbe2baac482` | +| pageswiki-excalidraw-viewer | `sha256:ec42a59d47ef731df1492c3db35b44ac9717b2235c8ece3360017d38bbf25f07` | + +3種類すべてでSHAタグとリリースタグのdigestが一致し、OCI revisionラベルもリリースcommitと一致した。 +昇格時の再ビルドは行っていない。 + +## 検証と移行 + +commit前に全Goテストをキャッシュなしで実行、全Go vet、8部品のrace検査、 +主要Chromiumテスト11本、Nodeテスト、Python CLIテスト19件が成功した。 +エディタ再ビルド後の配布物は既存bundle・map・CSSとSHA-256が一致した。 +Giteaのtestステージでも全Goテストが成功した。 + +本番旧版の管理対象8 componentはcurrent。候補版では `profile-contacts` のみpendingだった。 +新しいprivate連絡先テーブルとmigration履歴の追加であり、Page本文の変換や既存行の削除はない。 +確定済みバックアップの独立コピー2系統を、実際のCIイメージで起動した。 +network none、CPU 2、メモリ2GiB、検証コピーだけのDR設定でworkersを無効にし、 +外部enroll引数も省略した。本番への同期・通知送信・外部カレンダー同期は検証から実行しない。 + +外部インスタンスの検証を最初に `--no-default-campus` 単独で起動した際は、既存の引数制約で終了した。 +この引数はenroll指定との併用が必要なため、隔離起動ではenrollを含め引数を省略して再試験した。 +2系統ともhealthと追加後9 componentのschema checkが成功し、起動エラーはなかった。 +外部enrollの実接続経路は隔離試験の対象外とし、本番起動時の結果を別に確認した。 + +本番切替後は次を確認した。 + +- 4コンテナのrevisionラベルがリリースcommitと一致。アプリ2台のimage IDも一致。 +- localhost 3000/3001のhealth、公開HTTPSのhealth・ログインが200。 +- 匿名エディタはURL正規化後にログイン画面へ誘導される。 +- gatewayとExcalidrawのhealth成功、4コンテナの再起動回数0。 +- アプリ2台とも管理対象9 componentがcurrent。 +- 公開HTTPSから取得したeditor.js、command-bar.js、theme-picker.js、CodeMirror bundle、base CSSが配布元と一致。 + +これは全データの完全性検査、実機Safariの操作、長期負荷試験、外部認証providerの実ログインを完了した意味ではない。 +外部から取り込んだカレンダーの内容は開いていない。 + +## バックアップと起動設定 + +保全先は `.deployment-backups/release-v0.2.0-20261101/`。親ディレクトリは0700。 + +- `before/data`・`before/data2`:事前保全。先行コピー後、アプリ2台とgatewayを停止して差分同期し、DBバイト一致・syncを確認して旧版を再開した。 +- `cutover/data`・`cutover/data2`:15:38:47 JSTに確定した切替直前の整合コピー。 +- `config/`:旧Composeファイルと `.env`。秘密値を設計書・Gitへ転記しない。 +- 未変更ファイルのhardlink共有はbeforeとcutoverの間だけ。本番データとのhardlink共有はない。 +- 隔離検証コピーと検証コンテナは削除済み。before/cutoverと既存バックアップは保持した。 + +初回事前同期では稼働中に変更されたDB等約6GBの再コピーが必要になり、停止時間が延びた。 +切替直前の停止中同期は約30MB。今後はデータ量に応じた停止時間を事前に見積もる。 +切替後のホスト空き容量は約33GB。バックアップ世代削除は別途判断し、自動pruneは行わない。 + +ローカルのGit無視対象 `.env.release` に `PAGESWIKI_IMAGE_TAG=v0.2.0` を記録した。 +通常の秘密設定 `.env` と合わせて明示的に利用する。 + +```sh +docker compose --env-file .env --env-file .env.release \ + -f docker-compose.yml -f docker-compose.registry.yml \ + up -d --no-build --no-deps app app2 adaptor-gateway excalidraw-viewer +``` + +`pageswiki-app:latest`、`pageswiki-adaptor-gateway:latest`、`pageswiki-excalidraw-viewer:latest` の +ローカル互換タグもリリースイメージへ合わせた。registryのlatestは作成・更新していない。 +再ビルドによる混在を避け、本番操作では上のregistry overlayと `--no-build` を使う。 + +## 復旧点 + +旧イメージはそれぞれ `rollback-before-v0.2.0-20261101` タグで保持した。 + +| ローカルrepository | 旧image ID | +| --- | --- | +| pageswiki-app | `sha256:bed6b2d3e497e72c26feba4edf225fd9c57d49546fec43db2f88f297fcd989ee` | +| pageswiki-adaptor-gateway | `sha256:b1ed3051eb63c17da8eee6632a7823423707568dd5bd92c77d47de4d85cfae75` | +| pageswiki-excalidraw-viewer | `sha256:7fee6cc8c18a6fd6fe9adec91047332f5591d0a90081a8e32e629f4e9437d3d3` | + +profile-contactsのschema追加があるため、旧版へのimage差替えだけで安全とは扱わない。 +復旧時は新規書込みを停止し、切替後データも保全してからデータ契約の互換性を確認する。 +cutoverへ戻す場合は切替後の書込みが失われるため、別途承認と復旧対象の確認が必要。 +schema履歴を削除して旧版のcheckを通す回避はしない。 + +## 継続課題 + +15:38:47〜15:40:47 JSTの観察で、appのイベント開始ログ保存に +`database is locked (517)` を6件検出した。他3サービスは0件。 +すべて `component=dregarnuhr ... start-log failed` で、claimやfinishの失敗ではなかった。 +該当する先頭2ジョブは1回目でsucceeded、観察時点の切替後作成ジョブ16件もすべてsucceededだった。 +panic・fatal・ジョブ失敗・再起動は検出していない。 + +`AddEventLog` の実装は直前の本番イメージと同一であることを比較確認した。 +読み取り後に書き込むdeferred transactionの競合が残っており、DregarnuhrのReportで失敗が可視化された。 +ジョブ本体が継続しても、開始ログと対応する集約値が欠落するリスクはある。 +今回のリリースでこの不具合を解消したとは扱わない。 + +- [ ] 優先修正:AddEventLogの読取→書込昇格を避けるtransaction方式と、有界な取消・待機・再試行を整備する。 +- [ ] 独立DB接続・複数writerで、ログと集約値の原子性・重複なし・取りこぼしを検証する。 +- [ ] 完了ログ等の既存呼出し元で握りつぶしている保存失敗も、本文・秘密を露出しない形で可視化する。 +- [ ] 修正は新しいPATCH版としてビルド・検証・公開する。v0.2.0タグやdigestは付け替えない。