Immichのエラーがクライアントとサーバーのどちらに起因するかを見分ける方法

Eva Wong は テクニカルライター であり、 生粋の技術好き としてZimaSpaceで活動しています。ホームラボやオープンソースソフトウェア をこよなく愛する生粋のギークで、複雑な技術概念をわかりやすく、実践的なガイド にまとめることを得意としています。Evaは、セルフホスティングは難しいものではなく、楽しむものだと考えています。チュートリアルを通じて、初めてのNAS構築からDockerコンテナの使いこなしまで、コミュニティがハードウェアのセットアップをわかりやすく理解できるよう 支援しています。、初めてのNAS構築からDockerコンテナの習得まで。

失敗したリクエストの経路を追いながら、一度に1つの変数だけを変えて同じ操作を再現し、Immichのエラーがクライアント側かサーバー側かを見極めてください。

「サーバーエラー」と表示されるモバイルのバナーでも、原因はクライアントの状態、TLS、リバースプロキシ、またはサーバーが適切に拒否したリクエストにある可能性があります。同様に、ブラウザーでだけ失敗しても、ブラウザーに問題があるとは限りません。アカウント、アセット、操作を固定してクライアントと経路を比較し、ステータスコードと時刻を同期したログを使って、最初に失敗したレイヤーを特定してください。

別のクライアントでも同じ操作を再現する

ログイン、既知のアセットを開く、同じ小さな写真をアップロードする、同じ検索を実行するといった、結果を再現できる操作を1つ選んでください。ネットワーク経路は変えず、同じアカウントでブラウザーとモバイルクライアントからその操作を繰り返します。両方の試行について、正確な時刻と結果を記録してください。

他のアクセス経路を試す中でAndroidクライアントが失敗したという、現在のImmichの報告は、複数のクライアントを比較することの有用性を示しています。あるスレッドでの原因が他のケースにも当てはまるとは限りませんが、特定のクライアントだけで起こると分かれば、次に調べる箇所を大幅に絞り込めます。

すべてのクライアントで同じ操作が同時に失敗する場合は、サーバー、データベース、ストレージ、または共通のネットワーク経路を優先して調べてください。同じエンドポイントを使っているのに、あるクライアントでは失敗し、別のクライアントでは成功する場合は、クライアントのバージョン、キャッシュされた状態、権限、ローカルの証明書の信頼設定、そして異なるリクエストの内容を確認してください。

アカウントやアセットは変えず、経路だけを変える

次に、信頼できるローカル経路と、通常のリバースプロキシ、VPN、トンネル、またはリモート経路を比較します。同じアカウントで同じ操作をしてください。ローカルでは成功し、リモートでは失敗する場合、メディアレコード自体よりも、DNS、TLS、プロキシ、ファイアウォール、またはアップストリームのルーティング層に原因がある可能性が高くなります。

ZimaSpaceのローカルとリモートの経路を切り分けるガイドでは、LAN経由での成功とインターネット経由での成功が、それぞれ異なることを証明する理由を説明しています。モバイルアプリを再インストールしたり、サーバーを再構築したりする前に、この考え方をImmichにも当てはめてください。

どちらの経路でも同じように失敗するなら、プロキシ設定の変更はやめて、アプリケーション側のリクエストを調べてください。プロキシ経由の場合だけ失敗するなら、プロキシのステータス、TLSの結果、アップストリームの応答、タイムアウトを記録してください。このように変数を1つに絞って比較すれば、クライアントのメッセージに惑わされて誤ったレイヤーを調査するのを防げます。

ステータスコードは手掛かりとして使い、最終判断にはしない

HTTPステータスクラスは、調査すべき箇所を絞り込む手掛かりになりますが、問題を引き起こしたコンポーネントを自動的に特定するものではありません。多くの場合、4xxはリクエスト、認証、または認可に問題があったことを示し、5xxはサーバー側のコンポーネントがリクエストを処理できなかったことを示します。リクエストがImmichに届く前に、プロキシがどちらのクラスのステータスコードを返すこともあります。

アクセスログのフィールドガイドでは、ステータスコード、URLパス、リクエスト時間、リモートホスト、リクエスト識別子を、トラブルシューティングに役立つ項目として紹介しています。無関係な何千行ものログを確認するのではなく、失敗した操作1件についてこれらの値を記録してください。

プロキシに502またはタイムアウトが記録されていて、対応するImmichリクエストが見つからない場合は、上流への経路をたどってください。Immichがリクエストを記録し、再現性のある4xxを返す場合は、認証、権限、リクエスト内容を調べます。クライアントが失敗を報告している一方で、サーバー側のすべてのレイヤーが2xxを示している場合は、クライアントの解析処理、ローカルキャッシュ、後続リクエストを調べてください。

同じタイムスタンプでエラー率、レイテンシ、サーバーログを照合する

リクエストの失敗は外れ値の可能性があります。同じ操作を5~10回再現し、該当するサーバーとプロキシのログを確認しながら成功率とレイテンシを記録してください。リソースの逼迫やキューの急増とともにエラーが増える場合は、2回目の試行が成功しても、サーバーが断続的に利用不能になっている可能性があります。

Better Stackのエラーとレイテンシをサービスシグナルとして扱う概要では、エラー率をレイテンシやトラフィックと分けて捉えています。この考え方は、形式不正なクライアントリクエストが1件だけ発生したケースと、負荷がかかったときだけ劣化するサーバーの経路とを区別するのに役立ちます。

複数のクライアントで同じ例外がサーバーログに記録されている場合、反証されるまではサーバー側の問題として扱います。サーバーが失敗したリクエストを受信していない場合は、DNS、TLS、プロキシ、クライアントのネットワークを調査します。1つのクライアントだけが異なる形式のリクエストを生成している場合は、その違いを確認できるだけの証拠を保存してから、そのクライアントを更新またはリセットします。

2×2テストで最終判断を下す

2つのクライアントと2つの経路を使います。ブラウザー・ローカル、ブラウザー・リモート、モバイル・ローカル、モバイル・リモートです。同じアカウントとテスト用アセットを使ってください。このマトリックスにより、クライアント固有の障害、経路固有の障害、すべての組み合わせに影響するサーバー障害を切り分けられます。

一方のクライアントでは両方の経路で失敗し、もう一方では成功する場合、クライアントが原因であることが裏付けられます。両方のクライアントが一方の経路でのみ失敗する場合、経路が原因であることが裏付けられます。4つすべてで同じアプリケーションエラーが再現し、サーバーログに同じ失敗操作が記録されている場合、サーバーが原因であることが裏付けられます。

特定したレイヤーを修正したら、4つすべてのセルを再テストし、影響を受けたコンポーネントを1回再起動します。対照条件に影響を与えずに元の失敗セルが成功した時点で終了します。一般的なスクリーンショットではなく、マトリックス、タイムスタンプ、HTTPステータス、プロキシとサーバーのログ抜粋、クライアントのバージョン、再現可能なリクエストを添えてエスカレーションしてください。

サポートとヒント

続きを読む

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.