docs: record v0.2.1 logging hotfix rollout [skip ci]

This commit is contained in:
Anya Tokugawa committed 2026-11-01 20:03:38 +09:00
1 parent a36934e72c
commit 2af87b4f58
3 files changed
+97 -4

No files matched your search

+4 -3
View File
@@ -76,7 +76,8 @@ SQLiteの単一 `UPDATE ... RETURNING` で選択とclaimを行い、同じジョ
## v0.2.0後の優先修正:ログ保存競合
2026-11-01、ソース実装・合成データ検証。本番未反映。基点は `0f686aa`。
2026-11-01、ソース実装・合成データ検証。基点は `0f686aa`。
同日20:00 JST、[v0.2.1として本番反映](../../operations/deployments/2026-11-01-v0.2.1.md)した。
v0.2.0本番観察で開始ログ保存のSQLITE_BUSY_SNAPSHOT(517)が発生したため、
読取transactionをwriterへ昇格させる `AddEventLog` を修正した。
@@ -110,7 +111,7 @@ readonly、空ID誤分類、policy読取失敗、主キー利用、完了/retr
長時間ロックで保存できなかったログの自動回収、完了状態とログ自体の一体commit、
event-only fallback検索や保持処理の最適化は後続。v0.2.0タグは変更せず、
本番反映時は新しいPATCH版として別途検証・公開する。
新しいPATCH版v0.2.1として別途検証・公開した。
## 未実装:リース・HA・終了処理
@@ -126,7 +127,7 @@ exactly-onceの配送・実行は保証しない。外部副作用の冪等性
- [ ] 成功後・完了保存前の障害、lease更新停止、旧workerの遅延完了を障害注入試験する。
- [ ] アプリケーションの停止contextをschedulerに接続し、受付停止・実行中処理のdrain・期限付き終了を実装する。
- [ ] 各業務ハンドラーへcontextを伝播する。現状は独自のBackground/timeoutを使う処理も残る。
- [x] 開始/進捗/完了ログのcontext伝播、有界writer取得、ログ保存失敗の診断(ソース実装。本番未反映)。
- [x] 開始/進捗/完了ログのcontext伝播、有界writer取得、ログ保存失敗の診断(v0.2.1で本番反映)。
- [ ] 古い設定DB呼出しをcontext対応にする。完了保存失敗・欠落ログの回収方針も定義する。
コアのLoop/Runnerはキャンセルを受け付けるが、現行アプリケーションは従来どおり
@@ -122,4 +122,5 @@ panic・fatal・ジョブ失敗・再起動は検出していない。
`0f686aa` を基点に、上記ログ競合の修正をソースへ実装した。
契約と検証範囲は [Dregarnuhrのログ保存競合修正](../../design/ja/dregarnuhr.md#v020後の優先修正ログ保存競合) を参照。
この追記は本番修正済みを意味しない。v0.2.0のイメージ・タグは変更していない。
修正は同日20:00 JSTに [v0.2.1として本番反映](2026-11-01-v0.2.1.md)した。
上記の継続課題・観察結果はv0.2.0切替時点の記録である。v0.2.0のイメージ・タグは変更していない。
@@ -0,0 +1,91 @@
# PagesWiki v0.2.1 のログ保存修正と本番反映
2026-11-01 20:00:00 JST、イベントログのSQLite書込競合を修正した `v0.2.1` を本番へ反映した。
対象は `app`、`app2`、`adaptor-gateway`、`excalidraw-viewer`。code-server、Kroki、Mermaidは再作成していない。
別作業で進行中のCLI認証変更は含めず、イベントログ関連の9ファイルだけをリリースした。
## リリース対象
- ソースcommit:`a36934e72cd68e4ce6ea27b944d00378ef316e8d`。
- 注釈付きGitタグ:`v0.2.1`。タグobject:`1ab0aca388cb24fc52edf4d6ac8dfadec526f6a7`。
- [ビルド run 14](https://git.anya.jp/anya/wikipages/actions/runs/14):全工程成功。
- [リリース昇格 run 15](https://git.anya.jp/anya/wikipages/actions/runs/15):全工程成功。
- SemVerのPATCH更新。v0.2.0のタグ・配布物は変更していない。
`AddEventLogContext` が読み取り前に `BEGIN IMMEDIATE` で書込権を取得し、
rawログと集約bucketを同じtransactionで保存する。書込権取得の待機と再試行を有界にし、
取消後はrollbackと接続設定の復元を行う。開始・進捗・完了ログの保存失敗は秘密を含まない分類で診断する。
完了ログだけの失敗で、成功済みの業務処理を再実行しない。
契約と残件は [Dregarnuhr](../../design/ja/dregarnuhr.md#v020後の優先修正ログ保存競合) を参照。
registry prefixは `git.anya.jp/anya/`。3種類ともSHAタグとリリースタグのmanifest digestが一致し、
OCI revisionラベルはソースcommitと一致した。タグ昇格時の再ビルドは行っていない。
| イメージ | v0.2.1 manifest digest |
| --- | --- |
| pageswiki-app | `sha256:8b789f8f28a987bcb6f5ba2828fb00222716cce251a5b159a5e0bf7adba2cf46` |
| pageswiki-adaptor-gateway | `sha256:c7a288c6c01e1509d7e3dbbd22ded464747fc05d56ccb45410bed0ce8c1cd5b7` |
| pageswiki-excalidraw-viewer | `sha256:c08569a0a8a170067952e0e427154882da0e076454deb130143ef57b821071c7` |
## 検証
未コミットのCLI認証変更を含まない独立ソースコピーで、次を確認した。
- `go test ./... -count=1`:全件成功。
- `go test -race ./internal/store ./internal/server -run 'TestEvent(Log|Completion|Logging)' -count=3`:成功。
- `go vet ./...`:成功。
- Gitea CIの全Goテストとリリースツール試験:成功。
整合バックアップの独立コピー2系統をCIイメージで起動した。
network none、CPU 2、メモリ2GiB、コピーだけのDR設定でworkersを無効化し、外部enroll引数を省略した。
両方とも設定済みポート3000でhealthが成功し、起動ログのerror・failed・panic・fatalは0件だった。
管理対象9コンポーネントのschema checkはすべてcurrent。DBスキーマ追加・データ変換はない。
検証コピーと検証コンテナは削除し、整合バックアップは保持した。
本番切替後も、4サービスのrevision一致・再起動0回、アプリ2台のhealth、
公開HTTPSのhealth・ログインの200、gateway・Excalidrawのhealth、
アプリ2台の管理対象9コンポーネントcurrentを確認した。
外部から取り込んだカレンダーの内容は開いていない。
## ログ競合の観察
切替準備前のv0.2.0では、直近2分にappの開始ログ保存競合が7件発生し、ジョブ本体の失敗は0件だった。
切替後の確認は19:59:53 JSTを起点とし、composeログの失敗件数と、
読み取り専用DB接続によるジョブ状態・定型の開始/完了ログの件数だけを取得する。
payloadやイベント本文は出力しない。
19:59:53〜20:03:21 JSTの約3分28秒で、4サービスとも開始/進捗/完了ログ保存失敗、
SQLiteロック、ジョブ失敗、panic・fatalは0件だった。4サービスとも再起動0回を維持した。
この間に作成され完了したジョブはappで30件、app2で27件、すべてsucceededであり、
57件すべてに開始ログと完了ログが存在した。観察範囲では、修正前に発生していた開始ログの欠落は再現していない。
## 保全と起動設定
保全先は `.deployment-backups/release-v0.2.1-20261101/`。親ディレクトリは0700。
- `cutover/data`・`cutover/data2`:19:59:53 JSTに確定した切替直前の整合コピー。
- `config/`:切替前のCompose、`.env.release`、秘密値を含む `.env`。秘密設定は0600で保持し、Gitへ入れない。
- アプリ2台とgatewayを停止し、最終差分約6.22GBを同期。DBバイト一致とfilesystem sync後に新版を起動した。
- 未変更ファイルのhardlink共有はバックアップ間のみ。本番とのhardlink共有はない。既存バックアップは削除していない。
- 検証コピー削除後・本番切替後のホスト空き容量は約28GB。バックアップ世代の整理は別途判断する。
Git無視対象 `.env.release` の `PAGESWIKI_IMAGE_TAG` を `v0.2.1` に更新した。
```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` もv0.2.1へ合わせた。registryのlatestは更新していない。
## 復旧点と後続監視
旧版v0.2.0は、上記3種類のローカルrepositoryの `rollback-before-v0.2.1-20261101` タグで保持した。
v0.2.0のregistryタグも利用できる。このPATCH版にschema変更はないが、復旧前には切替後の状態と互換性を確認する。
イメージ切替とデータ復元は別操作であり、バックアップへデータを戻すと切替後の書込みが失われる。
データ復元は別途承認・保全の上で行う。schema履歴を削除してcheckを通す回避はしない。
長時間ロックやI/O障害で保存できなかったログの自動回収、業務完了状態とログの一体commit、
リース・HA・終了処理は後続課題として残る。短時間の本番観察は長期負荷試験の代替ではない。