Nginx 502 Bad Gateway エラーの修正: ステップバイステップガイド
設定、アップストリームの健全性、ログ、ソケット、Docker ネットワーク、タイムアウトの症状を確認して Nginx 502 エラーを追跡します。
Nginx 502 Bad Gateway エラーの修正: ステップバイステップガイド
Nginx 502 Bad Gateway エラーの修正は、Nginx が通常はメッセンジャーであり、障害の原因ではないことを理解することから始まります。502 は、Nginx がアップストリームサービスと通信しようとしたが、有効な応答が得られなかったことを意味します。
そのアップストリームサービスは、Node.js アプリ、PHP-FPM、Gunicorn、Puma、コンテナ、または別の HTTP サーバーである可能性があります。あなたの仕事は、ハンドオフがどこで失敗するかを見つけることです。
Nginx における 502 Bad Gateway の意味
Nginx は通常、アプリケーションサーバーの前に配置されます。パブリックトラフィックを受け入れ、TLS を処理し、静的ファイルを提供し、動的リクエストをアップストリームに転送します。
502 は、アップストリーム接続が失敗したか、Nginx が使用できないものを返した場合に表示されます。一般的な原因は次のとおりです。
- アプリケーションプロセスが停止している。
- Nginx が間違ったポートまたはソケットを指している。
- Unix ソケットの権限が間違っている。
- リクエスト中にアップストリームサービスがクラッシュする。
- ファイアウォールまたはコンテナネットワークが接続をブロックしている。
- アップストリームが無効な HTTP 応答を送信する。
失敗する正確なリクエストパスから始めます。/api のみが 502 を返し、静的ページが読み込まれる場合、静的ファイルの提供は問題なく、プロキシまたはアプリバックエンドが問題の可能性があります。すべてのページが失敗する場合、問題はより広範な Nginx、DNS、またはアップストリームの可用性の問題である可能性があります。
ステップ 1: Nginx のステータスと設定を確認する
まず、Nginx が実行されていることを確認します。
systemctl status nginx
次に、設定をテストします。
nginx -t
設定テストが失敗した場合は、アプリケーションを追跡する前に修正してください。Nginx は古い設定で引き続き実行されているか、リロード時に失敗する可能性があります。
設定テストが成功したら、Nginx をリロードします。
systemctl reload nginx
影響を理解していない限り、ビジーなサーバーで盲目的に再起動しないでください。リロードは通常、設定変更後は十分であり、中断が少なくなります。
次に、アクティブなサーバーブロックを検査します。proxy_pass、fastcgi_pass、または uwsgi_pass を探します。典型的なリバースプロキシには次のものが含まれる場合があります。
location / {
proxy_pass http://127.0.0.1:3000;
}
これは、Nginx がローカルポート 3000 でアプリケーションを期待していることを意味します。アプリが実際に 3001 でリッスンしている場合、または Docker ネットワーク内でのみリッスンしている場合、Nginx は失敗します。
よりコマンド中心のチェックについては、Nginx 設定テストコマンド を参照してください。
ステップ 2: アップストリームサービスを確認する
次に、Nginx ホストからアップストリームを直接テストします。Nginx が 127.0.0.1:3000 にプロキシする場合は、次を実行します。
curl -i http://127.0.0.1:3000/
これが失敗した場合、問題はブラウザまたはパブリック DNS ではありません。バックエンドがダウンしている、別の場所でリッスンしている、またはリクエストを拒否しているため、Nginx はバックエンドに到達できません。
アプリケーションプロセスを確認します。
ss -ltnp
期待されるポートを探します。サービスが Unix ソケットを使用する場合は、ソケットパスを確認します。
ls -l /run/app/app.sock
Nginx ワーカーユーザーはそのソケットにアクセスできる必要があります。多くの Linux システムでは、Nginx は www-data、nginx、またはサービス固有のユーザーとして実行されます。ソケットが別のユーザーによって所有されており、必要に応じてグループ読み取り可能または書き込み可能でない場合、Nginx は権限エラーをログに記録し、502 を返す可能性があります。
PHP-FPM セットアップの場合は、プールが実行されていることを確認します。
systemctl status php-fpm
サービス名には、ディストリビューションに応じて php8.2-fpm などのバージョンが含まれる場合があります。
ステップ 3: Nginx エラーログを読む
Nginx エラーログは通常、どの障害モードに対処しているかを示します。一般的なログメッセージは次のとおりです。
connect() failed (111: Connection refused) while connecting to upstream
これは、Nginx がホストに到達したが、そのポートで接続を受け入れるものがないことを意味します。
upstream timed out while reading response header from upstream
これは、Nginx が接続したが、バックエンドが時間内に応答しなかったことを意味します。
permission denied while connecting to upstream
これは多くの場合、Unix ソケットの権限または SELinux などのセキュリティ制御を指します。
最近のエラーを確認するには、次を使用します。
tail -n 100 /var/log/nginx/error.log
systemd ベースのシステムでは、次を確認することもできます。
journalctl -u nginx -n 100
ログのタイムスタンプをブラウザリクエストの時間と一致させます。これにより、関連性のなくなった古いエラーを追跡することを防げます。
より詳細なログワークフローについては、Nginx エラーログの分析 を参照してください。
ステップ 4: 最も一般的な根本原因を修正する
障害モードがわかったら、それに一致する最小の修正を適用します。
アプリが実行されていない場合は、アプリケーションサービスを開始または再起動します。
systemctl restart your-app
次に、Nginx を介してテストする前に、curl でアップストリームをテストします。
Nginx が間違ったポートを指している場合は、proxy_pass ターゲットを更新し、Nginx をリロードします。アプリと Nginx が IPv4 と IPv6 についても一致していることを確認してください。127.0.0.1 でリッスンしているアプリは、::1 のみでリッスンしているアプリと同じではありません。
Docker が関係している場合は、Nginx がホスト上で実行されているか、コンテナ内で実行されているかを確認します。コンテナ内の 127.0.0.1 は、そのコンテナを指し、ホストを指しません。Docker サービス名、ブリッジネットワーク、または公開ポートが必要になる場合があります。
アップストリームがタイムアウトした場合は、アプリケーションログを確認します。バックエンドがデータベースクエリ、外部 API 呼び出し、または起動作業でスタックしている可能性があります。Nginx のタイムアウトを増やすと症状が隠れる可能性がありますが、壊れたり過負荷になったアプリは修正されません。
専門家に依頼するタイミング
502 エラーが本番環境に影響を与え、ログ、アップストリームステータス、および最近のデプロイを確認しても原因が明らかでない場合は、シニアエンジニアまたはホスティングプロバイダーに依頼してください。また、問題がロードバランサー、コンテナオーケストレーション、SELinux ポリシー、または高トラフィックのタイムアウトチューニングに関係する場合も支援を求めてください。
本番システムでは、繰り返しランダムに再起動しないでください。証拠が消去され、障害の理解が難しくなる可能性があります。
502 Bad Gateway エラーは、リクエストパスを順番に追跡すれば修正可能です。Nginx が有効であることを確認し、アップストリームを直接テストし、正確なエラーログ行を読み、障害に一致する修正を適用します。このアプローチは、タイムアウトを変更したり、サービスを盲目的に再起動したりするよりも高速で安全です。