DevOpsナレッジハブ
DevOpsナレッジハブ

Nginxの一般的なエラーのトラブルシューティング：実践ガイド

Nginxのエラーに遭遇しましたか？この実践ガイドは、一般的な問題の診断と解決を支援します。設定の問題、パーミッション拒否エラー、接続拒否、502/504ゲートウェイエラーなどに対処する方法を学びます。サイトがアクセス可能でスムーズに動作し続けるように、明確な説明、実用的な解決策、および必須のNginxコマンドを提供します。

65 ビュー

Nginxの一般的なエラーのトラブルシューティング：実践ガイド

Nginxは強力で多用途なWebサーバーですが、他の複雑なソフトウェアと同様に、時には問題が発生することがあります。エラーに遭遇すると、特にサイトの可用性に影響がある場合、イライラすることがあります。このガイドでは、設定の問題、権限の問題、タイムアウト、クライアント関連のエラーなどを網羅し、最も一般的なNginxエラーの診断と解決のための実践的なアプローチを提供します。これらの一般的な落とし穴を理解し、それらに対処する方法を学ぶことで、Nginxサーバーをスムーズに実行し、ウェブサイトをユーザーがアクセス可能な状態に保つことができます。

この記事は、Nginxの効果的なトラブルシューティングに必要な知識とツールを身につけることを目的としています。典型的なエラーシナリオを段階的に説明し、その根本原因を解説し、具体的な解決策と例を提供します。初心者でも経験豊富なNginx管理者でも、このガイドはWebサーバーを最適な状態に保つための貴重なリソースとなるでしょう。

Nginxのエラーの一般的なカテゴリ

Nginxのエラーは、根本原因に基づいて大まかに分類できます。これらのカテゴリを理解することは、問題領域を絞り込むのに役立ちます。

  • 設定エラー: nginx.conf またはインクルードされた設定ファイルの間違い。これらはしばしば最も頻繁な原因です。
  • 権限エラー: Nginxのワーカープロセスが、ファイルやディレクトリにアクセスするために必要な権限を持っていない場合。
  • タイムアウトエラー: サーバーが予想される時間枠内に応答しない問題。バックエンドアプリケーションの問題やネットワーク遅延が原因であることがよくあります。
  • クライアントエラー: クライアント側から発生する問題ですが、サーバー側の問題として誤解されることもあります。
  • リソースエラー: メモリ、CPU、ファイルディスクリプタなどのリソースをサーバーが使い果たしている場合。

Nginxエラーの診断

トラブルシューティングの最初のステップは、エラーメッセージとその場所を特定することです。Nginxのログは情報の主な情報源です。

Nginxログの確認

Nginxは通常、2つの主要なファイルにエラーを記録します。

  • エラーログ (error.log): Nginxがすべてのアラートと警告を記録する場所です。Linuxシステムでは、通常 /var/log/nginx/error.log がデフォルトの場所です。
  • アクセログ (access.log): 主にリクエストの追跡用ですが、HTTPステータスコード、特にエラーのコンテキストを提供することもあります。

エラーログの最新のエントリを表示するには、tail コマンドを使用できます。

tail -f /var/log/nginx/error.log

このコマンドはログファイルをリアルタイムでストリームし、エラーが発生するとすぐに表示できます。

Nginx設定の検証

設定変更後にNginxを再起動する前に、構文エラーがないか設定をテストすることが重要です。

sudo nginx -t

このコマンドは設定ファイルをチェックし、検出された構文エラーとそのエラーが発生した行番号を報告します。テストが成功すると、次の出力が表示されます。

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Nginxの一般的なエラーと解決策

具体的なエラーシナリオとその解決策について説明します。

1. (13: Permission denied) エラー

Nginxのワーカープロセスが、提供するはずのファイルやディレクトリを読み取る権限を持っていない場合に、error.log によく表示されるエラーです。

原因: nginx.conf の user ディレクティブ（多くの場合 www-data または nginx）が、Webルートディレクトリまたはその中のファイルに対する読み取り権限を持っていない。

解決策: NginxユーザーがWebコンテンツディレクトリに対して適切な読み取り権限を持っていることを確認してください。これには chown と chmod コマンドを使用します。

例：

Webルートが /var/www/html で、Nginxユーザーが www-data の場合：

# 所有権を nginx ユーザーとグループに付与
sudo chown -R www-data:www-data /var/www/html

# ディレクトリが実行可能で、ファイルが読み取り可能であることを確認
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

ヒント: 静的ファイルを配信していて、特定のディレクトリへの直接アクセスを防ぎたい場合は、Nginxユーザーがディレクトリをトラバースするための実行権限を持っていることを確認してください。ただし、ディレクトリの内容が一覧表示されることを意図していない場合は、その内容に対する読み取り権限は必ずしも必要ありません。

2. (111: Connection refused) エラー

これは、Nginxサーバーが別のサービス（Node.js、Python/Gunicorn、PHP-FPMなどのバックエンドアプリケーションサーバー）に接続しようとしましたが、ターゲットによって接続が積極的に拒否されたことを示します。

原因: バックエンドアプリケーションサービスが実行されていない、Nginxが想定しているポートまたはIPアドレスとは異なるポートまたはIPアドレスでリッスンしている、またはファイアウォールが接続をブロックしている。

解決策:

  • バックエンドサービスの状態を確認: アプリケーションサーバー（例：Gunicorn、Node.js、PHP-FPM）が実行されていることを確認してください。
    • systemdサービスの場合: sudo systemctl status <service_name> （例：php8.1-fpm、gunicorn）。
    • その他のプロセスの場合: ps aux | grep <process_name>。
  • リスニングアドレス/ポートを確認: バックエンドサービスが、Nginxの proxy_pass または fastcgi_pass ディレクティブで指定されたIPアドレスとポートでリッスンしていることを確認してください。
    bash # 例：Node.jsがポート3000でリッスンしているか確認 sudo ss -tulnp | grep 3000
  • ファイアウォールルール: Nginxとバックエンドサービス間の接続をファイアウォールがブロックしていないことを確認してください。

Nginx設定スニペットの例: 

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

この場合、アプリケーションが実行されており、http://127.0.0.1:3000 でリッスンしていることを確認してください。

3. 502 Bad Gateway エラー

502 Bad Gateway エラーは、Nginxがゲートウェイまたはプロキシとして機能し、アップストリームサーバーから無効な応答を受け取ったことを意味します。

原因: Connection refused と似ていますが、アップストリームサーバーには到達可能だが、無効または不完全な応答を返した。これは以下のような原因が考えられます。
* バックエンドアプリケーションがクラッシュしたか、内部エラーが発生した。
* バックエンドアプリケーションの応答に時間がかかりすぎた。
* Nginxとアップストリーム間のネットワーク問題。
* proxy_pass または fastcgi_pass の設定ミス。

解決策:

  • バックエンドアプリケーションログを確認: バックエンドアプリケーションのログでエラーまたは例外を調べます。これは根本原因を見つけるための最も直接的な方法であることがよくあります。
  • タイムアウトの延長: アプリケーションが長時間かかる操作を実行している場合、Nginxのタイムアウト値を増やす必要があるかもしれません。
    nginx proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; fastcgi_send_timeout 60s; fastcgi_read_timeout 60s;
    これらの値を慎重に調整してください。過度に長いタイムアウトはワーカープロセスを占有する可能性があります。
  • アップストリーム設定の確認: proxy_pass または fastcgi_pass ディレクティブが正しいか再確認してください。

4. 413 Request Entity Too Large エラー

クライアントがNginxで設定されたサイズ制限を超えるリクエストボディを送信した場合に発生するエラーです。

原因: クライアントが、Nginxが受け入れるように設定されているサイズよりも大きいファイルをアップロードしようとしているか、データを送信しようとしている。

解決策: Nginx設定の client_max_body_size ディレクティブを調整します。このディレクティブは通常、http、server、または location ブロック内に設定されます。

例：

リクエストを100MBまで許可する場合：

http {
    # ... その他の http 設定 ...
    client_max_body_size 100M;
}

変更後は sudo nginx -t を実行し、Nginxをリロード（sudo systemctl reload nginx）することを忘れないでください。

5. 403 Forbidden エラー

403 Forbidden エラーは、サーバーがリクエストを理解したが、それを承認することを拒否したことを意味します。静的ファイルの場合、これは通常、Nginxが要求されたファイルまたはディレクトリにアクセスする権限を持っていないことを意味します。

原因: Permission denied エラーに似ていますが、HTTP 403ステータスコードの結果となります。ディレクトリリストが無効になっていて index ファイルが見つからない場合にも発生する可能性があります。

解決策:

  • ファイル権限を確認: Nginxユーザーが、要求されたファイルに対する読み取り権限と、そこに至るすべての親ディレクトリに対する実行権限を持っていることを確認してください。(13: Permission denied) エラーの解決策を参照してください。
  • index ディレクティブを確認: ディレクトリが要求された場合（例：http://example.com/some/directory/）、Nginxは index ファイル（index.html または index.php など）を探します。 index ファイルが存在せず、ディレクトリリストが無効になっている場合、403 Forbidden エラーが発生します。
    nginx location / { root /var/www/html; index index.html index.htm; }
  • autoindex ディレクティブを確認: ディレクトリリストを許可したい場合は、autoindex on; が設定されていることを確認してください。ただし、セキュリティ上の理由から、これは一般的に推奨されません。

6. 504 Gateway Timeout エラー

これは、Nginxがゲートウェイとして機能し、アップストリームサーバーから適時応答を受信できなかったことを示します。

原因: アップストリームアプリケーションがリクエストの処理に時間がかかりすぎ、Nginxで設定されたタイムアウト制限を超えた。これは 502 Bad Gateway と非常に似ていますが、特にタイムアウトを強調しています。

解決策:

  • Nginxタイムアウトの延長: 502 エラーと同様に、proxy_read_timeout、proxy_send_timeout、および fastcgi_read_timeout を増やすことで解決できる場合があります。
  • バックエンドアプリケーションの最適化: 最も効果的な長期的な解決策は、バックエンドアプリケーションのパフォーマンスを最適化して、より速く応答させることです。
  • バックエンドログの確認: アプリケーションのログで、長時間実行されているプロセスまたはエラーを探してください。

7. SSL/TLSエラー

SSL証明書に関連するエラーは、ユーザーがサイトに安全にアクセスするのを妨げる可能性があります。

原因: 証明書パスの間違い、証明書の有効期限切れ、ドメイン名の不一致、またはSSLディレクティブの不適切な設定。

解決策:

  • 証明書パスの確認: ssl_certificate および ssl_certificate_key ディレクティブが、正しい既存のファイルを参照していることを確認してください。
    nginx ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  • 証明書の有効期限を確認: openssl などのツールを使用するか、証明書プロバイダーのダッシュボードで、証明書が期限切れでないことを確認してください。
    bash openssl x509 -in /path/to/your/certificate.pem -noout -dates
  • ドメインの一致を確認: 証明書のサブジェクト代替名（SAN）または共通名（CN）に、ユーザーがアクセスしているドメイン名が含まれていることを確認してください。
  • ssl_protocols および ssl_ciphers を確認: 最新の安全なプロトコルと暗号スイートを使用していることを確認してください。

クライアントサイドエラー

Nginxはサーバーですが、特定クライアントの動作や設定が、サーバー関連の問題のように見える問題として現れることがあります。

  • ERR_CONNECTION_RESET: ネットワークの問題（クライアントとサーバー間）や、どちらかのエンドのファイアウォールが接続を積極的に切断していることがよくあります。サーバーアプリケーションがクラッシュして接続を突然閉じることを指す場合もあります。
  • 400 Bad Request: 通常、クライアントがサーバーで理解できないリクエスト（例：不正な形式のヘッダー）を送信したことを意味します。標準的なブラウザではまれですが、カスタムクライアントまたはボットで発生する可能性があります。

エラーを最小限に抑えるためのベストプラクティス

  • 設定管理: Nginx設定ファイルのバージョン管理を使用してください。デプロイ前に設定を徹底的にテストしてください（nginx -t）。
  • ロギング: 包括的なロギングを設定し、異常がないか error.log を定期的にレビューしてください。
  • 監視: Nginxサーバーとバックエンドアプリケーションの監視を実装してください。これにより、ユーザーに影響を与える前に問題をプロアクティブに検出できます。
  • Nginxの更新: Nginxを最新の安定バージョンに定期的に更新して、バグ修正とセキュリティパッチの恩恵を受けてください。
  • アプリケーションの理解: バックエンドアプリケーションの動作、リソース要件、および一般的な障害モードについて深く理解してください。

結論

Nginxエラーのトラブルシューティングは、信頼性の高いWebプレゼンスを維持するために不可欠なスキルです。ログを体系的にチェックし、設定を検証し、権限の問題、接続拒否、タイムアウトなどの一般的なエラーパターンを理解することで、効率的に問題を診断および解決できます。常に設定変更をテストし、パフォーマンスと安定性の向上のためにバックエンドアプリケーションの最適化を検討してください。これらのプラクティスにより、Nginxサーバーをスムーズに実行し、すべてのユーザーがウェブサイトにアクセスできるように保つことができます。