【完全保存版】Immichを安全にアップデートする完全ガイド｜TrueNAS SCALE更新前チェックリスト

Immichのアップデートは、ボタンを押すだけで終わることもあります。しかし、データベースのメジャーバージョン変更やストレージ構成の変更が含まれると、普段どおりの更新が復旧作業に変わることがあります。

このシリーズでは、TrueNAS SCALE Community Apps版Immichの更新でPostgreSQL 15から18への移行に失敗し、serverコンテナが再起動を繰り返した事例を扱ってきました。

第3弾は、個別の復旧コマンドを繰り返す記事ではありません。実際の障害から得た判断基準を、次回の更新前にそのまま使える「安全なアップデート手順」と「確認チェックリスト」にまとめます。

この記事は2026年8月4日時点の公式資料と公開Issueを確認して作成しています。TrueNAS Appの項目名やImmichのバックアップ画面は更新で変わる可能性があるため、実行時点のRelease NotesとChangelogも必ず確認してください。

今回の障害を4段階で振り返る
更新前チェックリスト
Snapshot・DBバックアップ・Appロールバックの違い
安全なアップデート手順
トラブル発生時の判断フロー
今回学んだこと
今後のおすすめ運用
まとめ
参考資料

今回の障害を4段階で振り返る

今回の流れを短く整理すると、次の4段階でした。

段階	状態	判断
1. 更新	Immich v2.4.1／PostgreSQL 15から、Immich v3.0.3／PostgreSQL 18へ更新	PostgreSQLのメジャーバージョン変更を含む更新だった
2. 起動失敗	`no pg_hba.conf entry`などが出て`server`が再起動	エラー1行だけを原因と断定せず、DBの存在と移行状態も確認した
3. 一時復旧	App 1.11.8／Immich v2.4.1／PostgreSQL 15へロールバック	まず写真へアクセスできる正常な移行元を取り戻した
4. 最終移行	PG15の論理バックアップを新規PG18へ復元	24,501件の`asset`レコード、Web UI、写真表示、検索を確認した

no pg_hba.conf entryは重要な手掛かりでしたが、それだけが直接原因だったとは断定していません。今回の最終解決は、正常なPG15を正本として固定し、論理バックアップから新しいPG18を作り直す方法でした。

障害発生から一時復旧までの判断は第1弾、PG18を作り直して検証した実作業は第2弾で詳しく説明しています。

更新前チェックリスト

更新ボタンを押す前に、次の項目を上から確認します。すべてを同じ種類の「バックアップ」と考えないことが重要です。

現在の状態を記録する

[ ] TrueNAS SCALEのバージョンを記録した
[ ] Immichの上流バージョンを記録した
[ ] TrueNAS Appのカタログバージョンを記録した
[ ] PostgreSQLのメジャーバージョンを確認した
[ ] Immichが更新前に正常稼働している
[ ] Web UIへログインできる
[ ] 複数の写真・動画・サムネイルを開ける
[ ] 検索結果が返る
[ ] 可能ならasset件数など、更新後に比較する基準値を記録した

更新前から壊れている状態で更新を始めると、更新が原因なのか、既存障害なのかを切り分けにくくなります。

変更内容を確認する

[ ] ImmichのRelease Notesを読んだ
[ ] Breaking Changesを確認した
[ ] TrueNAS AppのChangelogを開いた
[ ] PostgreSQLのメジャーバージョンが変わらないか確認した
[ ] VectorChordなどDB拡張機能の変更を確認した
[ ] Immichサーバーとモバイルアプリの対応バージョンを確認した
[ ] Immich GitHub Issuesで同じ更新経路の未解決報告を検索した
[ ] TrueNAS Apps GitHub IssuesでImmichの更新障害を検索した
[ ] TrueNAS Community Forumで同様の報告を確認した

Immich公式は、新しいリリースへ進む前にRelease NotesとBreaking Changesを確認するよう案内しています。また、サーバーは同じメジャーバージョンのクライアントとの組み合わせが前提です。

戻るための材料を用意する

[ ] Immichの手動DBバックアップを作成した
[ ] 作成された.sql.gzの日時とファイルサイズを確認した
[ ] 写真・動画を含むUPLOAD_LOCATIONを別媒体または別システムへバックアップした
[ ] PostgreSQLデータセットの更新直前Snapshotを作成した
[ ] Immichデータセットの更新直前Snapshotを作成した
[ ] Host PathとiXvolumeのどちらを使っているか記録した
[ ] TrueNAS Appのロールバック候補が表示されることを確認した
[ ] DBパス、データパス、バージョン、設定値を記録した
[ ] バックアップの保存先が更新対象と同じ障害領域だけに偏っていない

ImmichのDBバックアップに写真・動画は含まれません。一方、写真ファイルだけを残しても、Immichはライブラリフォルダを読み直してDBを自動再構築する仕組みではないため、メタデータを持つDBも必要です。

作業条件を整える

[ ] 大量アップロードやライブラリ取込が動いていない
[ ] 家族や利用者に停止時間を伝えた
[ ] 作業中に新規書き込みが入らない時間帯を選んだ
[ ] ログを確認できる端末を用意した
[ ] ストレージ空き容量を確認した
[ ] その日にTrueNAS本体とImmichを同時更新しない方針にした
[ ] 復旧に必要な時間を確保した

同じ日に複数の大きな変更を重ねると、失敗時の原因候補が増えます。セキュリティ上の緊急性や依存関係がない限り、TrueNAS本体、Immich App、ストレージ変更は1つずつ実施します。

Snapshot・DBバックアップ・Appロールバックの違い

「バックアップ済み」という言葉だけでは、何を戻せるのか分かりません。更新前に役割を分けて確認します。

保全手段	主に守るもの	強み	注意点
ZFS Snapshot	対象データセットのある時点の状態	高速で、更新直前の状態を残しやすい	同じプール上だけでは機器故障への独立バックアップにならない。Rollbackは現在データを置き換える
Immich DBバックアップ	ファイルパス、ユーザー情報、アルバムなどのDB情報	PostgreSQLの論理復元に使える	写真・動画そのものは含まれない
`UPLOAD_LOCATION`のバックアップ	オリジナル写真・動画と生成物	実ファイルを保全できる	DBがなければImmichの状態を完全には戻せない
TrueNAS Appロールバック	以前のApp版とAppデータの一部	UIから旧版へ戻せる	Host Path上のデータはロールバック対象外
別筐体・別媒体へのコピー	NAS全体の障害に備えるコピー	プール故障や誤操作への耐性が上がる	定期的な実行と復元テストが必要

TrueNAS公式は、Appロールバック用SnapshotがHost Path上のデータを戻さないと説明しています。また、データセットのRollbackは現在データや関連Snapshotを失う可能性があるため、実行前に別のバックアップが必要です。

安全なアップデート手順

ここからは、初心者でも判断を飛ばさないよう、作業順を固定します。

1. 更新前の正常性を確認する

理由：更新前の不具合を、更新後の障害と混同しないためです。

確認ポイント：AppがRunningであることに加え、Web UI、写真表示、検索、アップロード状況を確認します。可能ならDB件数も控えます。

失敗した場合：更新しません。まず現在の構成を復旧し、正常な基準点を作ります。

2. 更新範囲と互換性を調べる

理由：通常更新に見えても、DBメジャー更新や拡張機能変更が含まれる場合があるためです。

確認ポイント：現在版から更新先までのRelease Notes、Breaking Changes、TrueNAS App Changelog、同じバージョン経路のIssueを確認します。

失敗した場合：同じ経路の未解決Issueがある、または移行条件を理解できない場合は更新を延期します。更新通知があることと、今すぐ安全に更新できることは同義ではありません。

3. DBと写真ファイルを別々に保全する

理由：ImmichはDBと実ファイルの両方がそろって初めて完全な復旧に近づくためです。

確認ポイント：Immichの手動DBバックアップを作成し、UPLOAD_LOCATION/backupsに生成されたファイルの日時とサイズを確認します。写真・動画を含むデータ側も、Snapshotだけでなく復旧方針に応じた別コピーを確保します。

失敗した場合：バックアップの生成や確認に失敗した状態では更新しません。保存先、空き容量、権限を確認します。

4. 更新直前Snapshotを作成する

理由：直前状態へ素早く戻る選択肢を残すためです。

確認ポイント：ImmichデータとPostgreSQLデータが別データセットなら、それぞれの対象・作成時刻・再帰設定を確認します。名前だけでなく、正しいデータセットに存在することを確認します。

失敗した場合：Snapshotが作れない理由を解消するまで進みません。Snapshotを作成できたという表示だけでなく、一覧に実在することまで確認します。

5. 書き込みを止めてから1つだけ更新する

理由：作業中にDBと写真ファイルの時点がずれることを避け、障害原因を絞るためです。

確認ポイント：アップロードやジョブが止まっていることを確認し、今回変更する対象を1つに限定します。TrueNAS App画面では更新前後の上流App版とカタログ版を記録します。

失敗した場合：更新ダイアログの再実行を繰り返さず、表示されたエラーとログを保存します。

6. Running表示の前にログを見る

理由：DB移行やインデックス再構築には時間がかかり、途中のStartingと再起動ループを見分ける必要があるためです。

確認ポイント：TrueNASのWorkloadsからserverとPostgreSQL関連コンテナのログを確認します。同じエラーが周期的に繰り返されていないか、コンテナの再起動回数が増えていないかを見ます。

失敗した場合：pg_hba.confなどを推測で編集する前に、エラー全文、発生コンテナ、DBの存在、現在のPostgreSQLバージョンを記録します。Immich公式は大規模ライブラリの再インデックスに時間がかかる場合があると説明しているため、エラーがない単なる処理中と、失敗ループを区別します。

7. DB・Web UI・実データを段階的に確認する

理由：Appが緑色でも、DBや写真閲覧が正常とは限らないためです。

確認ポイント：次の順で確認します。

PostgreSQLが想定したメジャーバージョンで起動している
immichデータベースが存在する
更新前に記録したasset件数と大きな不一致がない
serverが再起動ループへ戻らない
Web UIへログインできる
新旧日付の複数写真・動画を開ける
検索結果が返る
必要に応じて新規アップロードを1件試す

失敗した場合：どの段階まで成功したかを記録し、それ以降の操作を止めます。DBが不完全なまま新規アップロードを続けないことが重要です。

8. 成功後も旧データをすぐ消さない

理由：更新直後には気づきにくい検索・サムネイル・動画変換の問題が残る可能性があるためです。

確認ポイント：一定期間、更新前Snapshot、旧DB、DB dumpを保持し、日常利用で問題がないことを確認します。

失敗した場合：保持している正常な基準点へ戻します。削除は復旧確認の最後の工程です。

トラブル発生時の判断フロー

flowchart TD
    A[Immichを更新] --> B{Appは安定してRunning?}
    B -->|はい| C{Web UI・写真・検索・DB確認OK?}
    C -->|はい| D[更新成功・バックアップを保持]
    C -->|いいえ| E[新規書き込みを止めてログ保存]
    B -->|いいえ| E
    E --> F{更新前DBとSnapshotは残っている?}
    F -->|いいえ| G[破壊的操作を止めて復元材料を確認]
    F -->|はい| H{旧構成へ安全に戻せる?}
    H -->|はい| I[旧App・旧DBへ一時復旧]
    H -->|いいえ| G
    I --> J{PostgreSQLメジャー移行の失敗?}
    J -->|いいえ| K[Issue・Changelogを確認して対策]
    J -->|はい| L[正常な旧DBから論理バックアップ]
    L --> M[新しいDBへ復元して段階検証]
    K --> N[再更新または修正版を待つ]
    M --> C
    N --> A

最初に行うのは「エラーを消す操作」ではなく、新規書き込みの停止と復元材料の確認です。SnapshotのRollbackやDBディレクトリ削除は後戻りを難しくするため、対象と影響範囲を確認するまで実行しません。

今回学んだこと

1種類のバックアップでは足りない

Snapshotは高速ですが、同じプールの障害には弱く、論理DBバックアップの代わりにもなりません。DB dumpには写真・動画が入りません。AppロールバックはHost Pathを戻しません。それぞれの穴を別の保全手段で埋める必要があります。

エラーメッセージは「原因」ではなく「観測事実」

今回のno pg_hba.conf entryは接続拒否を示しましたが、同時にDBの存在や移行完了も確認する必要がありました。目立つ1行だけを直そうとすると、別の失敗を見落とします。

ロールバックは敗北ではなく、正常な移行元を取り戻す工程

PostgreSQL 15へ一時復旧したことで、Web UIと写真表示を確認できるDBを正本として固定できました。その後に論理バックアップを取得したため、壊れた移行先を触り続けずに済みました。

PostgreSQLのメジャー更新は通常のコンテナ差し替えではない

PostgreSQL公式は、メジャーバージョン間では内部ストレージ形式が変わり得るため、pg_dump／pg_dumpallによる論理移行やpg_upgradeなどが必要だと説明しています。旧データディレクトリを新バージョンへそのまま渡す前提では考えません。

成功判定はRunning以外にも持つ

今回の成功条件は、PG18起動、24,501件のassetレコード一致、再起動ループ解消、Web UI、複数写真、サムネイル、検索でした。1つの表示ではなく、DBと利用者目線の両方で確認します。

今後のおすすめ運用

次回からは、更新を単発作業ではなく定例の保守手順として扱います。

タイミング	実施内容	確認する証拠
毎日	Immich自動DBバックアップ	最新の`.sql.gz`の日時とサイズ
定期	Immich／PostgreSQLデータセットのSnapshot	対象データセット、保持期間、最新実行結果
定期	写真・動画とDBバックアップを別筐体・別媒体へ複製	コピー履歴と復元できるファイルの存在
更新候補が出た時	Release Notes、Breaking Changes、App Changelogを読む	現在版から更新先までの変更点メモ
更新直前	手動DBバックアップ、手動Snapshot、正常性記録	ファイル、Snapshot、バージョン、基準件数
更新中	コンテナ状態とログを監視	エラー全文、発生時刻、対象コンテナ
更新後	DB・Web UI・写真・検索・アップロード確認	更新前後の比較結果
安定確認後	古いSnapshotや退避DBを整理	保持方針に基づく削除記録

Immichの自動DBバックアップは、公式ドキュメント上の初期値では毎日2時に実行し、直近14件を保持します。ただし、設定されていることと実ファイルが作成されていることは別です。定期的にバックアップ一覧と保存先を確認します。

更新日は固定の曜日・時間帯にまとめ、作業記録を残す運用がおすすめです。ただし、未解決Issueがある更新を予定どおり実行する必要はありません。セキュリティ修正の緊急性と、移行障害の報告を分けて判断します。

まとめ

このシリーズで最も大きかった学びは、「アップデート前の準備が、復旧方法の選択肢を決める」ということです。

第1弾では、PostgreSQL 15から18への自動移行に失敗し、serverコンテナの再起動ループからPG15へ一時復旧するまでを追いました。第2弾では、正常なPG15を正本として論理バックアップを取り、新しいPG18へ復元してImmich v3.0.3を正常稼働させました。

次回の更新前に覚えておくポイントは、次の5つです。

Release Notesと同じ更新経路のIssueを先に読む
DB、写真ファイル、Snapshotを別々に保全する
TrueNAS本体とImmichなど、大きな変更を同時に重ねない
失敗したら書き込みを止め、復元材料を残す
Runningだけでなく、DB・Web UI・写真・検索まで確認する

このチェックリストをすべて確認してから、はじめて更新ボタンを押します。