Files
pages/docs/operations/deployments/2026-11-01-v0.2.0.md
T

127 lines
8.6 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.
# 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は付け替えない。
### 後続作業(リリース済み内容とは別)
`0f686aa` を基点に、上記ログ競合の修正をソースへ実装した。
契約と検証範囲は [Dregarnuhrのログ保存競合修正](../../design/ja/dregarnuhr.md#v020後の優先修正ログ保存競合) を参照。
修正は同日20:00 JSTに [v0.2.1として本番反映](2026-11-01-v0.2.1.md)した。
上記の継続課題・観察結果はv0.2.0切替時点の記録である。v0.2.0のイメージ・タグは変更していない。