コンテナの更新後にハードウェアトランスコーディングへのアクセスがなくなるのはなぜですか？

エヴァ・ウォン

IceWhale author

エヴァ・ウォン は テクニカルライター であり ZimaSpaceの常駐ティンカーでもあります。 生涯のオタクであり、 ホームラボとオープンソースソフトウェアに情熱を持っています。彼女は複雑な技術的概念をわかりやすく、 実践的なガイドに翻訳することを専門としています。エヴァはセルフホスティングは楽しくあるべきで、怖がるものではないと信じています。彼女のチュートリアルを通じて、コミュニティが ハードウェアのセットアップを解明する手助けをしています。初めてのNAS構築からDockerコンテナの習得まで。

Why Does Hardware Transcoding Access Disappear After a Container Update?

ハードウェアトランスコードは、更新後に再作成されたコンテナから同じデバイス、権限グループ、ランタイム機能、または互換性のあるユーザー空間スタックが見えなくなったために、利用できなくなることがよくあります。

ホストのGPUは動作していても、イメージの置き換え後にPlex、Jellyfin、Emby、またはカメラアプリが気付かないうちにCPUへフォールバックすることがあります。まず、新しいコンテナ内にデバイスが存在するか、サービスユーザーがデバイスを開けるかを確認します。そのうえで、ランタイムのマッピングや権限の問題と、イメージ固有のコーデックまたはドライバーのリグレッションを切り分けます。

ワークロードが本当にソフトウェア処理へフォールバックしたことを確認する

トランスコードが必要なファイルを強制的に再生し、メディアサーバーのダッシュボード、FFmpegまたはトランスコーダーのログ、ホストのCPU使用率、GPUエンジンのアクティビティを記録します。ダイレクト再生ではハードウェア処理の経路をテストできません。

LinuxServerコミュニティの事例では、明示的なハードウェア指標とGPUテレメトリーを確認することが推奨されています。CPUのアクティビティだけでは判断を誤る可能性があるためです。重要な判別材料は、制御されたトランスコード中のGPUエンジンの実際の使用状況です。

ログにハードウェアエンコーダーの正常なオープンが表示される場合は、サポートされていないフィルター、字幕、トーンマッピング、または部分的なアクセラレーションを調べます。デバイスを開けない場合は、ホストの検出とコンテナからのアクセス確認に進みます。

ホストとコンテナ内のGPUデバイスを比較する

ホストと更新後のコンテナ内で、想定されるデバイスノードを一覧表示します。IntelまたはAMDのVA-APIでは、/dev/dri/card*と/dev/dri/renderD*を比較します。NVIDIAでは、ランタイムからの認識状況と管理ツールが報告するデバイスを比較します。

UnraidのQuick Syncに関する事例では、/dev/driが存在する前にホストへ適切なカーネルモジュールが必要になる場合があり、さらにコンテナにもそのデバイスを渡す必要があることが示されています。欠けている境界は、メディアライブラリやアプリのデータベースではなく、/dev/driデバイスのマッピングであることがよくあります。

ホスト上にデバイスが存在しない場合は、まずホストのドライバー、BIOS、カーネル、またはハードウェアの状態を修復します。ホストには存在するのにコンテナ内にない場合は、以前の構成と新しいComposeまたはUI生成のデバイス設定を比較します。

renderグループとvideoグループへのアクセスを確認する

ホスト上のGPUデバイスノードについて、数値の所有者IDとグループIDを記録し、コンテナ内でサービスユーザーに割り当てられているグループを確認します。renderのような名前でも、イメージごとに異なる数値IDへマッピングされる場合があります。

JellyfinのDockerトラブルシューティング事例では、ホストのrenderグループIDを明示的に一致させ、renderD128の権限を確認する構成が示されています。この数値によるrenderグループのマッピングは、イメージ内のユーザーやグループが変更されると変わる可能性があります。

デバイスを誰でも書き込み可能にするのではなく、コンテナ定義を通じて必要な補助グループを追加します。コンテナを再作成し、実際のメディアサービスユーザーとしてアクセスをテストします。

Featured

ZimaCube 2 パーソナルクラウドホームNAS

ZimaCube2

ランタイムフラグとイメージ固有の機能を確認する

以前と現在のイメージ定義について、devices、group_add、GPUランタイム設定、機能関連の変数、特権モード、コンテナマネージャーのテンプレート変更を比較します。

Embyの報告では、アプリ自体は利用できる状態のまま、Docker内でハードウェアアクセラレーションが停止しています。これは、問題を見逃しやすくするGPU喪失後のソフトウェアフォールバックの一例です。

限定的なデバイスアクセスの問題を、広範な特権アクセスの付与で解決しようとしないでください。エンコーダーの経路に必要な最小限のデバイス権限とグループ権限を復元します。

コンテナイメージのリグレッションとホスト障害を切り分ける

更新後のコンテナ内で簡単なGPUまたはFFmpegのテストを実行し、同じマウント、デバイスマッピング、メディアファイル、アプリ設定を使って、以前の固定済みイメージと比較します。

同一のランタイム状態で以前のイメージはすぐに動作し、新しいイメージだけが失敗する場合は、ログを保存し、更新によるユーザー空間、コーデック、FFmpeg、またはアプリケーションのリグレッションとして扱います。管理されたイメージ比較でバージョンが原因だと特定できている場合、権限を何度も書き換えないでください。

ログが原因を示している場合に限り、文書化された再生成可能なコーデックキャッシュだけを削除します。アプリのデータベースとメディアメタデータには触れないでください。リグレッションの原因が判明または修正されるまで、正常に動作するイメージを固定します。

修復後にパイプライン全体を検証する

ハードウェアデコード、エンコード、トーンマッピング、字幕の焼き付け、さらにトランスコードを強制するクライアントを少なくとも1つテストします。ログに想定されるGPUデバイスが表示され、ホスト上でエンジンが継続的に動作していることを確認します。

ZimaSpaceの実際のハードウェアトランスコードを検証する手順は、設定ページのトグルを確認するよりも確実な完了テストになります。

問題が解決したと言えるのは、更新後または固定済みのコンテナが再作成や再起動後もデバイスへのアクセスを維持し、意図したコーデック経路でGPUを使用し、気付かないうちにフォールバックしなくなった場合だけです。次回の更新に備え、以前のイメージダイジェストとランタイム定義をロールバックの基準として保持してください。