アップグレード中に Immich の設定が失われるのを防ぐ方法
アップグレード中のImmichの設定消失を防ぐには、Composeファイル、環境変数、データベース、アップロードライブラリ、外部ライブラリのマウント定義を、それぞれ個別の永続アセットとして扱い、まとめて取得・復元する必要があります。
コンテナは置き換え可能ですが、その周囲にある設定はそうではありません。相対バインドマウントが別のプロジェクトディレクトリから解決されたり、環境変数の編集が再作成されたコンテナに反映されなかったり、新しいスタックが空のデータベースに対して起動したりすると、アップグレードによってImmichが消えたように見えることがあります。まず稼働中のデプロイメントを一覧化し、ホスト外にバージョン管理したコピーを保管してから、本番切り替え前に制御された再作成を実証してください。
アップグレード前に稼働中のデプロイメントを取得する
シークレットを伏せた有効なCompose設定をエクスポートし、イメージのバージョンまたはダイジェストを記録して、Composeファイルと環境変数ファイルをバージョン管理されたストレージにコピーします。エディターで開いているファイルが現在のコンテナを起動したものだと決めつけず、実行中のマウントを確認してください。合格条件は、各ランタイムパスが既知のホスト上の場所に対応していることです。
外部ライブラリのパス、リバースプロキシの設定、機械学習URL、データベース接続値、ユーザーとグループの識別情報、ネットワーク名、ハードウェアアクセラレーション用デバイスを記録します。ここで抜けた項目は、後のアップグレード後に原因不明の差異となります。
コミュニティのアップグレードに関する質問では、どの世代のComposeや環境変数の構成を適用すべきか分からなくなった運用担当者の例が繰り返し示されています。あるアップグレード設定に関するディスカッションから得られる有用な教訓は、現在動作している定義を、変換する前に保存しておくことです。
データベース、メディア、デプロイメントファイルを個別にバックアップする
データベース固有のバックアップに加え、アップロードライブラリとデプロイメントディレクトリのファイルシステムバックアップまたはスナップショットを取得します。開始時刻と完了時刻、アーカイブサイズ、チェックサムを記録してください。Compose YAMLだけを含むバックアップではコンテナを再構築できても、アカウント、メタデータ、アルバム、アセットのレコードは復元できません。
最も単純な整合性の境界を確保するには停止中にバックアップを取るか、稼働中のデータベースダンプとストレージスナップショットを調整して取得し、両者の関係を記録します。外部ライブラリは、元のファイルをImmichが管理していない場合でも一覧に残してください。パスとアクセス規則は復元後のサービスに影響するためです。
コミュニティが管理するメジャーバージョンアップグレード手順では、データベース、メディア、Compose、環境変数の入力を保持することが強調されています。この手順は運用経験として扱い、実際にデプロイするリリースごとに各手順を確認してください。
固定したバージョンでアップグレードをステージングする
スキップしたすべてのバージョンについてリリースノートを読み、保存済みのデプロイメント定義を意図的に更新します。対象リリースを固定し、古いイメージを削除せずにプルして、レンダリング後のCompose設定を検証します。未知の変数、空のマウント、サービス間のバージョン混在があれば、ステージングの合格条件を満たしません。
容量に余裕がある場合は、異なるポートを使用し、本番環境への書き込みアクセスを持たない隔離テストスタックにバックアップを復元します。対象バージョンで起動し、マイグレーション、ユーザー、ストレージパス、バックグラウンドジョブを確認してください。コンテナが正常に起動しただけでは、元のライブラリが接続されていることの証明にはなりません。
関連するZimaSpaceの安全なセルフホストNASガイドは、アップグレードによって損なわれる可能性がある単一ホストと認証情報の境界の外側に、デプロイメントファイルとバックアップを配置するのに役立ちます。
再作成後も設定が保持されることを実証する
切り替え前に、テストコンテナをその場で再起動するのではなく、保存済みのファイルから再作成します。ユーザー、サーバー設定、ストレージテンプレート、ライブラリ、ジョブ、プロキシ経由のアクセス、有効な環境変数の値を確認してください。合格条件は、設定が文書化された永続コンポーネントに保存されているため、置き換え後も維持されることです。
本番環境へ切り替えた後、テスト用アセットを1つアップロードし、検索を実行し、元のファイルを開いて、新しいデータベースバックアップを作成します。スタックとホストを再起動してから、同じ手順を繰り返してください。通常のワークロードが観察期間を通じて安定するまで、旧バージョン、バックアップ、デプロイメント定義を保持します。
アップグレードがすでに空の状態で開始されている場合は、ユーザー登録や新規アップロードによって状態の競合が生じる前に停止します。検証済みの永続パスだけを再接続するか、クリーンな対象環境に復元してください。想定したユーザーやアセットが存在しない場合はロールバックし、識別情報が依然として不明確なら、サニタイズ済みの有効なCompose設定、マウント、バージョン、バックアップ時刻を添えてエスカレーションします。
おすすめ商品
サポートとヒント
もっと読む
同時稼働するコンテナ向けに Immich のデータベース接続を最適化する方法
まず max_connections を増やさないでください。Immich のセッション数を測定し、すべてのコンテナの需要を合計し、管理用の余裕を確保したうえで、実証されたボトルネックだけを調整してください。
Immichでジョブやインポートの重複を防ぐ方法
重複するジョブと重複アセットを分離します。正規の取り込み経路を1つに統一し、再試行とパス変更を制御してから、小規模なコホートで再エントリーをテストします。
データベースのボリュームがいっぱいになった後に Immich を修復する方法
空き容量を確保するためにPostgreSQLのWALを削除しないでください。Immichへの書き込みを停止し、データベースの状態を保持したまま安全に容量を追加し、PostgreSQLを復旧してから、再発を防止してください。
