アップグレード

アップグレード対象のバイナリは 2 つ：manager（docker-compose スタック）と edge（ホストごとに 1 つ）。両者とも概念上は同じフローに従います： 新しいアーティファクトをステージング、アトミックにスワップ、新しいものが 健全に立ち上がらなければ自動的に前バージョンにフォールバック。

TL;DR

manager：

VER=v0.7.160
gh release download "$VER" --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"
tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"
sudo ./upgrade.sh

edge（全部、並列、UI から）：

• Edges → Upgrade all —— manager が接続中の各 edge に MethodFetchPackage を push、各 edge が https://<manager>/edge/ からステージング済みバンドルをダウンロード、 ステージング、再起動、スワップ、実行。失敗は次回起動で自動ロールバック。

または単一の edge をシェルから：

sudo systemctl restart ongrid-edge
# The ExecStartPre runs apply-pending-upgrade.sh which picks up any
# staged bundle and applies it before the new agent starts.

このページの残りは、それらが実際にどう動くかを説明します。動かないときにデバッグできるように。

Manager アップグレード：upgrade.sh

upgrade.sh は各リリース tarball に同梱されており、新しく展開した新しい tarball の中 で実行することを想定しています。${ONGRID_INSTALL_DIR:-/opt/ongrid}/ に 既にインストールがあると仮定します。

順に：

1. プリフライト。 docker + compose v2 を確認し、既存の .env を探す。 なければ終了。
2. 既存の .env と新 tarball の VERSION ファイルから 新旧バージョンを決定。両方ログ —— サポートチケットに有用。
3. マイグレーションステップのためにデータボリュームを解放する docker compose down。
4. ${ONGRID_DATA_DIR}/ 配下のデータディレクトリ所有権を 再アサート （mysql、prom、loki、tempo、grafana、embeddings、qdrant）。イメージの uid は 長く変わっていませんが、これが唯一安全なデフォルト —— 再アサートは冪等です。
5. 新 tarball から /opt/ongrid/ に 設定を再ステージング： docker-compose.yml、prometheus.yml、prometheus-rules.yml、 loki-config.yaml、tempo-config.yaml、grafana/、searxng/、 nginx.conf、frontier.yaml、新しい edge/ アーティファクト、新しい VERSION ファイル。.env は保持 —— upgrade.sh はオペレーター編集 env を上書きしません。
6. 新しい docker イメージをロード（ongrid.tar、ongrid-web.tar、 frontier.tar があれば）。
7. .env の ONGRID_VERSION= をバンプ —— 次の compose-up で新しいイメージタグが選ばれるように。
8. docker compose up -d を新しい env で実行。
9. /healthz を 60 秒ポーリング。
10. バナー —— 旧 → 新バージョン、Web URL、便利な次ステップコマンド。

ステップ 8 より前で失敗した場合、原因を修正して再実行できます —— upgrade.sh は冪等です。ステップ 9 が失敗（/healthz が 200 を返さない）した場合、 docker compose logs ongrid の manager ログが何が壊れているか教えてくれます。

ゼロダウンタイムには、ロードバランサーの背後に 2 つの manager ホストの blue/green を構成。 OSS シングルホストインストールは アップグレード中の短いダウンタイム（約 30〜60 秒）。

アップグレードアーティファクトはどこから来るか：make package

これは オペレーター経路 —— リリースを pull する代わりにソースからビルドする場合の tarball の作り方。ongridio/ongrid のチェックアウトから：

make package

順序は重要。make package の動作：

1. fetch-promtail —— アップストリーム Grafana リリースから promtail-<os>-<arch>.zip をダウンロード、bin/<os>-<arch>/promtail に展開。キャッシュあり。
2. fetch-otelcol —— otelcol-contrib も同様。
3. fetch-node-exporter —— node_exporter も同様。
4. fetch-process-exporter —— process_exporter も同様。
5. build-edge-all —— ongrid-edge を linux/amd64、linux/arm64、 darwin/amd64、darwin/arm64 向けにクロスコンパイル。
6. docker-build —— ongrid:<version> イメージをビルド。
7. docker-build-broker —— $FRONTIER_SRC から singchia/frontier:<ver> をビルド （ローカルイメージストアに既にあればスキップ）。
8. docker-build-web —— ongrid-web:<version>（フロントエンド SPA + nginx）をビルド。
9. build-edge-bundle —— 単独バイナリから edge-bundle-linux-amd64-<ver>.tar.gz を組み立て。
10. dist/package.sh —— すべてを dist/stage/ongrid-<version>-linux-amd64/ にステージング、3 つのイメージを docker save、全体を tar.xz、sha256 サイドカーを計算、dist/out/ に投入。

出力：

dist/out/ongrid-v0.7.160-linux-amd64.tar.xz
dist/out/ongrid-v0.7.160-linux-amd64.tar.xz.sha256

これが本番ホストに scp して ./upgrade.sh に渡すアーティファクトです。

オフライン RAG モデル

BGE 埋め込みモデルは package の依存ではありません —— CN ネットワークから 取得が遅いので一度きりのステップに留めています。ONGRID_EMBEDDING_PROVIDER=local を箱出しで復元時に動かしたければ、make package の前に make fetch-embedding-model を一度実行してください。

Edge アップグレード：ADR-024 stage-then-swap

edge アップグレードの ユーザー経路 は「UI の Upgrade をクリック」または バンドルステージング後の systemctl restart ongrid-edge です。 実際に何が起こるか、上から下まで：

1. manager がトリガー、edge が取得

「Upgrade all edges」（または単一 edge）で：

• manager は /opt/ongrid/edge/（install.sh / upgrade.sh が配置）から dist/out/edge-bundle-<arch>-<ver>.tar.gz.sha256 を読みます。
• manager がトンネル経由でターゲット edge に MethodFetchPackage(url=https://<manager>/edge/<bundle>, sha256=<sha>, version=<ver>) を送信。
• nginx が同じ /edge/ ディレクトリからバンドルバイトを配信。

2. edge がステージング

受信側 edge：

• バンドルを /tmp/ にダウンロード。
• manager が送ったマニフェストの sha256 と検証。
• /var/lib/ongrid-edge/.upgrade/incoming/ に untar。
• MANIFEST.txt の各 <sha> <mode> <src> <dest> 行を検証（sha 一致、src 存在）。
• "ready" マーカーを書く。
• クリーンに終了。systemd が Restart=always でユニットを再起動。

3. systemd の ExecStartPre がスワップを実行

ユニットには以下が同梱：

ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge

+ プレフィックスは User=ongrid-edge にもかかわらずフックを root で 実行。 - はスクリプトの欠落/失敗で 0 終了できるようにし、ユニットをブロックせずに 事前アップグレードバイナリが常に起動するようにします。

apply-pending-upgrade.sh は順に：

1. Mode 1: auto-rollback —— 先のアップグレードが動いたものの last_upgrade_ver 一致の healthy_marker を書かなかった場合。 各 <dest>.previous を <dest> に復元。ステージングディレクトリをクリア。
2. Mode 2: bundle apply —— MANIFEST.txt の各行に対し：
   • sha256 を再検証、
   • cp -p $dest $dest.previous（ロールバック用スナップショット）、
   • 最終リネームを POSIX アトミックにするため 同じファイルシステム で cp $src $dest.new、
   • chmod $mode $dest.new、
   • mv -f $dest.new $dest。
3. Mode 3: レガシー単一ファイル apply —— まだバンドルアップグレードしていない edge（エージェントバイナリのみ、マニフェストなし）との後方互換。
4. 次起動の健全性チェック用に last_upgrade_at と last_upgrade_ver を記録。

そして ExecStart=/usr/local/bin/ongrid-edge が新しくスワップされたバイナリを実行。

4. 新エージェントが健全性を報告（しなかったり）

新エージェントは接続成功時に：

• /var/lib/ongrid-edge/.upgrade/healthy_marker に走行中のバージョンを書く。
• 新バージョンで register をトンネル経由で報告。

そのファイルが存在し 次 の起動で last_upgrade_ver と一致すれば、 apply-pending-upgrade.sh は成功を宣言し、各 .previous をプルーニング してディスクを解放、ステージングディレクトリをクリア。

そうでなければ（エージェントクラッシュ、manager に到達できないなど）、 次回起動が auto-rollback をトリガー：各 .previous を復元、 ステージングディレクトリをワイプ、edge は前の動作バージョンを再実行。 オペレーターは UI で気付きます（トリガーしたアップグレード後も edge が 「古い」バージョンを報告し続ける —— 新しいバンドルに問題があるサイン）。

バンドル不変条件

edge がスワップする各ファイルはバンドル内にあり、バンドル内の各ファイルは 自己完結型バイナリまたはスクリプト。これは譲歩できません：

• エージェントバイナリ（ongrid-edge）
• プラグインバイナリ（promtail、otelcol-contrib、 node_exporter、process_exporter）
• フックスクリプト（apply-pending-upgrade.sh）

プラグイン設定（promtail.yaml、otelcol.yaml）はバンドル内に ありません —— /etc/ongrid-edge/ にあり、トンネル経由でライブ設定として配信されます。 こうしておくとエージェントのアップグレードがオペレーター手動編集の設定を上書きしません。

バンドルを docker イメージに焼き戻さない

ソースからビルドする場合、バンドルは package 時にコンテナ内ではなく ホスト 側で dist/build-edge-bundle.sh によってビルドされます。ADR-032 がこれを強制 —— イメージに焼き戻すと圧縮できない約 120 MB のバイトを二重に詰めて sha チェーンを壊します。

ロールバックの所在

/usr/local/bin/ongrid-edge              # current
/usr/local/bin/ongrid-edge.previous     # last known good

/usr/local/lib/ongrid-edge/promtail
/usr/local/lib/ongrid-edge/promtail.previous

...etc.

/var/lib/ongrid-edge/.upgrade/
  last_upgrade_at                       # ISO timestamp
  last_upgrade_ver                      # version string
  healthy_marker                        # written by the new agent

トリガーしたアップグレード後の起動シーケンス：

boot 1 (pre-upgrade):
  apply-pending-upgrade.sh sees nothing staged; exit 0
  ongrid-edge v0.7.159 runs

(manager pushes bundle, edge stages it, edge exits clean)

boot 2 (apply):
  apply-pending-upgrade.sh
    mode 1: no healthy_marker yet, but no last_upgrade_at either → skip
    mode 2: applies bundle. /usr/local/bin/ongrid-edge.previous = v0.7.159
                            /usr/local/bin/ongrid-edge        = v0.7.160
            writes last_upgrade_at, last_upgrade_ver=v0.7.160
            clears healthy_marker
  ongrid-edge v0.7.160 runs
  v0.7.160 connects, writes healthy_marker=v0.7.160

(reboot, e.g. host updates)

boot 3 (settle):
  apply-pending-upgrade.sh
    mode 1: last_upgrade_ver=v0.7.160, healthy_marker=v0.7.160 → success
            prunes all .previous files
            clears last_upgrade_at, last_upgrade_ver
  ongrid-edge v0.7.160 runs

失敗シナリオ：

boot 2 (apply):
  apply-pending-upgrade.sh: applies bundle as above
  ongrid-edge v0.7.160 crashes immediately (e.g. config drift)
  systemd restarts repeatedly per Restart=always

boot 3 (rollback):
  apply-pending-upgrade.sh
    mode 1: last_upgrade_ver=v0.7.160, healthy_marker missing
            → roll back: restore .previous over each dest
              (ongrid-edge.previous → ongrid-edge, etc.)
            : > last_upgrade_at, rm -rf incoming/
  ongrid-edge v0.7.159 runs again (working)

ダウングレード

manager をダウングレード：古い tarball を展開し、その中で ./upgrade.sh を実行。 間のリリースで DB スキーママイグレーションがなければ動きます。ダウングレード前に リリースノートで「breaking schema change」の言及を確認してください。

edge をダウングレード：UI から古いバンドルバージョンへの「アップグレード」をトリガー。 manager ロジックはバージョンが移動する方向を気にしません。

次は

• Reference / env —— リリース間でデフォルトが変わる環境変数名。
• エアギャップインストール —— manager 自身がインターネットに ない場合でも apply-pending-upgrade.sh がバンドルを取得できるよう、アーティファクトを 内部 webserver にミラーする方法。