フォトサーバーのRAWおよびHEICプレビューのトラブルシューティングガイド

エヴァ・ウォン

IceWhale author

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

RAW and HEIC Preview Troubleshooting Guide for Photo Servers

一括で再生成する前に、元のバイト列、デコーダー、ワーカー、派生ファイル、クライアントをたどって、失敗しているRAWまたはHEICアセットを1つ特定します。

オリジナルはダウンロードできるのにプレビューに失敗する場合、原因はカメラ固有のエンコード、デコーダーの不一致、ジョブの停止、書き込み不能なサムネイルパス、またはクライアントが別のアセットを要求していることかもしれません。失敗するサンプル1つと既知の正常ファイル1つを組み合わせ、一度に1つのレイヤーだけを変更し、両方のオリジナルを保持します。同じカナリアがワーカーの再起動後も維持され、対象範囲内のすべてのクライアント経路で読み込めることを確認して初めて、ライブラリ全体の再構築が正当化されます。

失敗するアセットを1つ選び、オリジナルを検証する

失敗するRAWまたはHEICファイルを1つと、同じカメラまたはスマートフォンで撮影した正常なファイルを1つ選びます。拡張子、コーデックプロファイル、寸法、ビット深度、サイズ、撮影デバイス、アプリケーションのバージョン、クライアントを記録します。オリジナルをダウンロードし、そのハッシュとバイトサイズをソースまたはバックアップと比較します。

HEIC画像の読み込みエラー事例に関する解決済みのコミュニティレポートでは、サムネイルジョブを何度も開始した後でも「画像の読み込みエラー」が続くことが示されています。この症状はパイプラインを追跡する根拠としてのみ使用し、ファイル、デコーダー、キューのいずれかが普遍的な原因だと証明するものではありません。

両方のオリジナルを独立したデコーダーで開きます。失敗するオリジナルが破損または途中で切れている場合は、プレビューに手を加える前に復元します。両方のオリジナルをデコードできる場合は、読み取り専用で保持して先に進みます。派生ファイルの問題を理由に、唯一のソースファイルを変換または削除してはなりません。

デコーダーの対応とジョブの実行を切り分ける

アプリケーションが使用するものと同じデコーダーまたはメタデータ抽出スタックを、両方のサンプルに対して実行し、標準エラー出力と終了ステータスを記録します。一方のカメラプロファイル、圧縮方式、またはHEICのバリエーションだけで失敗する場合は、形式対応の範囲が限定されていることを示します。両方が成功する場合、エラーはデコード後に発生しています。

RAWサンプルがキュー処理の前に失敗する場合は、デコーダーの失敗またはサムネイルワーカーのエラーについてZimaSpaceの手順を使用します。これにより、カメラ固有のデコードを、ジョブを取得しない、または出力を書き込めないワーカーの問題から切り離せます。

デコーダーのアップグレードまたは変更はテストコンテナ内だけで行い、まったく同じサンプルを再実行します。変更後にオリジナルをデコードできた場合は、プレビューを1つ生成し、色、向き、寸法を確認します。それでも失敗する場合はロールバックし、サンプルとコマンド出力を保持してプラットフォームサポートに提供します。

ワーカー、キュー、派生ファイルの経路を追跡する

カナリアだけをキューに追加し、ジョブID、ワーカーの割り当て、開始時刻と終了時刻、再試行回数、エラー、出力パス、所有者、空き容量、inodeの利用可能数を記録します。ホストとコンテナのパスが同じ書き込み可能な場所を指していること、バックアップまたはクリーンアップタスクがそこをロックしていないことを確認します。

独立したオリジナルの欠落とサムネイルの失敗に関する資料では、オリジナルの欠落を、サムネイルジョブ、ストレージマウント、権限、クライアント経路の問題から切り分けています。こうしたパスレベルの区別を利用しますが、修正方法は自分のログで最初に失敗した観測結果に合わせます。

クリアまたは再試行するのはカナリアのジョブだけにします。成功すれば、期待されるパスに派生ファイルが生成され、キューは正常な状態を保ちます。デコーダーが成功しているのに失敗する場合は、原因をワーカーの識別、キューの状態、メモリ、出力ストレージ、またはデータベースの状態に絞り込めます。1つのジョブを進めるために、すべてのサムネイルレコードを削除してはいけません。

-15% OFF

ZimaBoard 2 - あなたの大きなアイデアのためのミニホームサーバー

Single board computer zimaboard2

クライアントを比較し、一括再生成の前に検証する

対象範囲内のWeb、iOS、Android、およびリバースプロキシ経由の各経路でカナリアを読み込みます。それぞれがサムネイル、プレビュー、オリジナルのどれを要求しているかを記録し、レスポンスコードとコンテンツタイプを比較します。保存済みの派生ファイルが正常なのに1つのクライアントだけが失敗する場合、それはソースデコーダーではなく、配信またはクライアント互換性の問題です。

原因に対応した修正を1つ適用し、影響を受けたワーカーを1回だけ再起動して、同じ失敗ファイルと、同じカメラで撮影した新しいファイルをテストします。その後、他の形式もサンプリングし、JPEG、動画、HDR、または色処理が壊れていないことを確認します。

カナリアが再起動後も維持され、ストレージに十分な余裕があり、バックアップがジョブの実行時間外にある場合にのみ、一括再生成を開始します。オリジナルが変更された場合、正常に動作していた形式にもエラーが広がった場合、またはキューの再試行が加速した場合は停止します。サンプル、デコーダー出力、ジョブID、クライアントのレスポンスを保持したままエスカレーションします。