AI・テクノロジー

Hermes Agent v0.20.0更新実録：Docker移行とDB最適化

Hermes Agentをv0.18.2からv0.20.0へDocker環境で更新した実録です。Node.js 26への移行、設定確認、Dashboard競合の解消、SQLiteの任意最適化まで、安全に進めるための確認点をまとめます。

claude

• 6 min read
Share

Hermes Agent v0.20.0更新実録：Docker移行とDB最適化

NousResearchのAIエージェント基盤「Hermes Agent」を、Docker環境でv0.18.2からv0.20.0へ更新しました。対象のリリースはv2026.8.3です。

今回の更新は、単に新しいコンテナイメージへ差し替えるだけではありませんでした。実行環境はNode.js 22系から26系へ変わり、設定の自動移行、Dashboardのプロセス管理、SQLite全文検索インデックスの新しい保存形式など、運用面で確認すべき点が複数あります。

結論から言えば、本体更新と主要サービスの復旧は完了しました。一方、既存の大きなデータベースを新しいコンパクトなFTS形式へ変換する処理は任意であり、記事執筆時点でもバックグラウンドで継続中です。本稿では「更新完了」と「追加最適化中」を分け、実際に発生した問題と対処を記録します。

背景：v0.18.2からv0.20.0への更新

更新前のHermes Agentはv0.18.2で、Dockerイメージとしてはv2026.7.7.2相当を利用していました。更新先のv2026.8.3にはHermes Agent v0.20.0が含まれ、Node.js 26が前提になります。

v0.20.0ではA2A v1.0、音声、外向きWebhook、根拠付き引用、コンテキスト圧縮など多数の機能が追加されています。ただし既存環境の更新で重要なのは、新機能の数より、データと設定を失わずに新しいランタイムへ移せるかです。今回はバックアップ、本体更新、サービス検証、任意のDB最適化を分けて進めました。

更新前の準備：固定タグと完全バックアップ

まず、更新先のDockerイメージを起動前に取得し、Hermes Agent v0.20.0とNode.js v26.5.1が含まれることを確認しました。旧コンテナのNode.jsはv22.22.3だったため、今回はアプリだけでなくランタイム世代も変わる更新です。

Compose定義では、イメージ指定をnousresearch/hermes-agent:latestからnousresearch/hermes-agent:v2026.8.3へ変更しました。latestは次回の再作成時に意図せず別バージョンへ進む可能性があります。実運用では、検証したリリースタグへ固定した方が再現性とロールバック性を確保しやすくなります。

更新直前には、永続データのhermes-data、.env、docker-compose.ymlをタイムスタンプ付きのディレクトリへ退避しました。特にSQLiteのstate.dbはコピー元とコピー先のサイズが843,100,160バイトで一致することまで確認しています。

800MBを超えるDBでは更新後の処理に時間がかかるため、コピー成功だけでなく主要ファイルの存在とサイズまで確認することが安全網になります。

設定移行：手動マイグレーションは不要だった

更新後の設定バージョンは_config_version: 33でした。公式の設定マイグレーションでは古い構成からの自動移行が用意されており、今回の旧環境は対応範囲内です。

実際にhermes config checkを実行したところ、必須設定の不足は検出されませんでした。そのため、設定ファイルを手作業で書き換えるマイグレーションは不要でした。

ただし、自動移行があっても確認は必要です。更新後には設定チェックを実行し、新しい必須項目と既存サービス設定を検証します。同梱スキルも同期され、xlsx、docx、pdf、grounded-citationsなどが追加される一方、利用者が変更したスキルは保持されました。

起動後に発生した問題1：環境変数の引用符

最初に表面化したのはDashboardの環境変数でした。旧Composeでは値自体に二重引用符が含まれ、新バージョンの厳密な解析で正しく解釈されませんでした。そこで、実際に必要な値だけを渡す形へ修正しました。

HERMES_DASHBOARD: "1"
HERMES_DASHBOARD_HOST: "0.0.0.0"
HERMES_DASHBOARD_PORT: "9119"

YAMLの引用符と、環境変数値に含まれる引用符は別物です。更新時にはコンテナ内で実際の値を確認するのが確実です。

起動後に発生した問題2：Dashboardの二重起動

次に、9119番ポートのバインドエラーとSQLiteロックが繰り返し発生しました。原因は、旧環境で手動起動されていたDashboardプロセスと、新バージョンのs6管理下で起動するDashboardが同時に存在していたことです。

ポート競合だけを見ると単純なネットワーク問題に見えます。しかし両方のプロセスが同じ状態DBへアクセスするため、SQLiteのロックも同時に発生しました。ポートを変更して両方を生かすのではなく、サービスの管理主体を一つに統一する必要があります。

対処では、旧Dashboardプロセスを終了し、いったん新Dashboardも停止しました。その状態でGatewayにDB初期化を完了させ、その後GatewayとDashboardをs6管理下で順番に再起動しました。これにより、ポート競合とDBロックの両方を解消できました。

更新後は同一サービスが複数の方法で起動していないか、プロセス一覧とサービス管理状態の両方を確認する必要があります。

DB移行：必須の初期化と任意のFTS最適化を分ける

Gatewayの起動によるDBスキーマ初期化後、state.dbは約844MBへ増加しました。保存されている規模は、メッセージ36,294件、セッション1,639件です。また、状態情報ではfts_optimize_available=1となり、新しいFTS保存形式へ最適化できることが確認できました。

v0.20.0では、全文検索インデックスをよりコンパクトにするv23形式が用意されています。ただし、これは本体起動に必須のマイグレーションではなく、hermes sessions optimize-storage --yesで明示的に開始する任意処理です。

今回は主要サービスの復旧を確認した後に、この公式コマンドを実行しました。外側の実行セッションは15分でタイムアウトしましたが、コンテナ内の処理は停止せず継続しました。進捗は10,000件、10,500件、11,500件、12,500件と進み、記事執筆時点で最後に確認できた値は12,500／36,294件です。

したがって、「Hermes Agentの更新は完了」「FTSの追加最適化は継続中」という状態です。大規模DBでは、最適化を更新の成否判定と一体化すると、長時間処理のためにサービス復旧まで遅らせてしまいます。必須工程と任意工程を分離し、進捗マーカーを確認できる形で実行する方が安全です。

実運用で確認したエンドポイント

更新作業では、コンテナが起動状態になっただけでは完了としませんでした。実際に認証付きリクエストを送り、次の結果を確認しています。

  • Dashboardの/api/statusはHTTP 200
  • OpenAI互換APIの/v1/modelsはHTTP 200
  • A2Aの/.well-known/agent-card.jsonはHTTP 200
  • GatewayとDashboardはs6管理下で稼働
  • FTS最適化中も主要サービスは応答を継続

一部の補助ポートでは対象ルートが404だったため、サービスごとに期待するURLとステータスを決めて検証する必要があります。

今後の運用に活かす5つの要点

状態を持つAIエージェント基盤の更新では、次の5点が有効です。

  1. Dockerイメージは検証済みのリリースタグへ固定する
  2. DBだけでなく環境変数とCompose定義も同時にバックアップする
  3. 自動マイグレーション後も公式の設定チェックを実行する
  4. 手動プロセスとサービスマネージャーの二重管理を解消する
  5. 長時間のDB最適化は主要サービス復旧後の別工程にする

今後はFTS最適化の完了、DBサイズ、検索機能、再起動後のサービス状態を追加確認します。独自スクリプトやプラグインがある場合はNode.js 26との互換性確認も必要です。

よくある質問

Q1. ホスト側にもNode.js 26を導入する必要がありますか？

Docker内で動かす構成なら、基本的にホスト側のNode.js更新は不要です。ただし、ホストで関連スクリプトを直接実行する場合は別途確認が必要です。

Q2. v0.18.2からの設定ファイルは手動で移行する必要がありますか？

今回は自動移行後のhermes config checkで不足がなく、手動移行は不要でした。独自設定や古い構成では結果が異なるため確認は必要です。

Q3. optimize-storageは更新時に必須ですか？

必須ではなく、コンパクトなFTS形式を利用する任意処理です。大きなDBでは、サービス復旧後にバックアップと進捗確認を用意して実行します。

Q4. 問題が起きた場合はどう戻しますか？

旧イメージの固定タグ、更新前のhermes-data、.env、Compose定義をセットで保持します。DB変換前のバックアップが特に重要です。

まとめ

Hermes Agent v0.20.0への更新では、Node.js 26を含む新しい固定タグへ移行し、設定の自動移行と主要サービスの動作を確認できました。途中で環境変数の引用符問題、Dashboardの二重起動、SQLiteロックが発生しましたが、設定値の正常化とプロセス管理の一本化で解消しています。

本体更新と任意のDB最適化を別工程にし、サービス復旧後にFTS最適化を進めることで停止時間とリスクを抑えられます。更新は「起動したか」だけでなく、データ、設定、プロセス、公開インターフェースで判断します。

参考

公式情報

関連記事