Wie man client_max_body_size in Nginx richtig konfiguriert | Behebung von Upload-Limit-Problemen

Bei der Implementierung von Datei-Uploads in Nginx ist es sehr häufig, auf das Problem zu stoßen, dass 「kleine Dateien gesendet werden können, aber große Dateien zu einem 413-Fehler führen」. Die meisten Ursachen sind unzureichende Konfiguration von <code>client_max_body_size</code>. Allerdings führt das alleinige Beheben der Nginx-Konfiguration in vielen Fällen nicht zur Lösung. Es ist notwendig, ein umfassendes Verständnis der PHP-Einstellungen <code>upload_max_filesize</code> und <code>post_max_size</code> sowie Timeout-Einstellungen zu haben. Dieser Artikel erläutert systematisch alle Konfigurationselemente im Zusammenhang mit Upload-Limits.

Standardwert und Funktion von client_max_body_size

Nginx hat eine Direktive namens <code>client_max_body_size</code>, die die maximale Größe des Anfragetexts vom Client begrenzt. Der Standardwert ist <code>1m</code> (1 MiB). Anfragen, die diesen überschreiten, werden sofort als <code>413 Request Entity Too Large</code>-Fehler abgelehnt.

Der Standard ist 1m, was extrem klein ist, daher wird das Limit sofort erreicht, selbst beim Hochladen eines einzelnen Bildes oder PDF. In echten Produktionsumgebungen muss dieser Wert je nach Verwendungszweck angemessen erhöht werden.

Konfigurationsort: Unterschiede zwischen http / server / location

<code>client_max_body_size</code> kann auf jeder Ebene der Nginx-Konfiguration (http / server / location) eingestellt werden. Einstellungen mit spezifischerem Umfang haben Vorrang.

# http ブロック（全サーバー共通）
http {
    client_max_body_size 10m;

    server {
        listen 80;
        server_name example.com;

        # server ブロック（このバーチャルホスト全体）
        client_max_body_size 50m;

        location /upload {
            # location ブロック（このパスのみ）
            # より大きなファイルを許可したい場合
            client_max_body_size 200m;

            proxy_pass http://app;
        }

        location /api {
            # APIエンドポイントはデフォルト（1m）のままにする例
            client_max_body_size 1m;
        }
    }
}

Es ist ein sicherheitstechnisch vorzuziehender Ansatz, nur dem dedizierten Upload-Endpunkt einen großen Wert zu setzen und andere auf kleine Werte zu beschränken. Um unbegrenzte Größe zu ermöglichen, geben Sie <code>0</code> an, dies wird jedoch nicht empfohlen, da es das DoS-Angriffsrisiko erhöht.

Ursache und Lösung des Fehlers 413 Request Entity Too Large

Wir werden die Ursachen und Gegenmaßnahmen für den Fehler 413 organisieren.

Nach einer Konfigurationsänderung in Nginx ist ein Reload erforderlich.

# 設定の文法チェック
nginx -t

# 設定のリロード（サービス停止なし）
nginx -s reload

# または systemd 経由
systemctl reload nginx

Beziehung zwischen upload_max_filesize / post_max_size in PHP

Es ist nicht ausreichend, nur <code>client_max_body_size</code> von Nginx zu erhöhen. Wenn das Backend PHP ist, gibt es unabhängige Beschränkungen auf PHP-Ebene. Der Upload ist erfolgreich, wenn alle drei Einstellungen angemessene Werte haben.

; php.ini の設定
; 1ファイルあたりの上限
upload_max_filesize = 100M

; POSTリクエスト全体の上限（upload_max_filesize より大きくする）
; multipart/form-data のオーバーヘッド分を見込んで多めに設定
post_max_size = 110M

; メモリ上限（post_max_size より大きくする）
memory_limit = 256M

; アップロード処理の実行時間（大容量ファイル用に延ばす）
max_execution_time = 300
max_input_time = 300

Die Beziehung der wichtigen Konfigurationswerte ist wie folgt.

• client_max_body_size（Nginx） ≥ post_max_size（PHP） ≥ upload_max_filesize（PHP）
• Wenn Nginx die Anfrage ablehnt, wird die Verarbeitung nicht bis zu PHP durchgeführt
• <code>post_max_size</code> ist das Größenlimit für den gesamten POST-Body, einschließlich mehrerer Datei-Uploads und Formularfelder neben Dateien

Die Bedeutung von proxy_read_timeout / proxy_send_timeout

Bei großen Datei-Uploads ist auch die Timeout-Konfiguration wichtig. Der Standard <code>proxy_read_timeout</code> beträgt 60 Sekunden, und wenn der Upload zu lange dauert, wird der Prozess unterbrochen.

location /upload {
    client_max_body_size 500m;

    proxy_pass http://app_backend;

    # バックエンドからのレスポンス待機時間
    # 大容量ファイルの処理には長めに設定
    proxy_read_timeout 600s;

    # クライアントへのデータ送信待機時間
    proxy_send_timeout 600s;

    # バックエンドへの接続タイムアウト
    proxy_connect_timeout 60s;

    # クライアントのリクエストボディ受信タイムアウト
    # 2回の連続した読み取り操作の間の時間
    client_body_timeout 120s;
}

Es wird empfohlen, Timeout-Werte separat für den Upload-Endpunkt und den regulären API-Endpunkt zu konfigurieren.

Konfiguration in Docker (nginx.conf-Mount)

In einer Docker-Umgebung wird eine benutzerdefinierte nginx.conf- oder conf.d-Datei im Container bereitgestellt, um die Konfiguration widerzuspiegeln.

# Dockerfile でのカスタム設定追加
FROM nginx:alpine

# カスタム設定ファイルをコピー
COPY ./nginx/conf.d/upload.conf /etc/nginx/conf.d/upload.conf

# デフォルト設定を完全に置き換える場合
# COPY ./nginx/nginx.conf /etc/nginx/nginx.conf

# docker-compose.yml でのボリュームマウント
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    volumes:
      # ディレクトリごとマウント（変更が即反映される）
      - ./nginx/conf.d:/etc/nginx/conf.d
      # または特定ファイルだけマウント
      # - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"

# nginx/conf.d/upload.conf
server {
    listen 80;
    server_name localhost;

    # グローバルのアップロード上限
    client_max_body_size 100m;

    location / {
        proxy_pass http://app:9000;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }

    location /upload {
        client_max_body_size 500m;
        proxy_pass http://app:9000;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Konfigurationsüberprüfungsbefehl

Um zu überprüfen, welcher Wert <code>client_max_body_size</code> in der aktuellen Nginx-Konfiguration hat, ist es praktisch, alle Konfigurationen mit <code>nginx -T</code> zu erweitern und dann grep zu verwenden.

# 全設定を展開して client_max_body_size を検索
nginx -T | grep -i body_size

# 出力例:
#   client_max_body_size 1m;   ← デフォルト（http ブロック）
#   client_max_body_size 100m; ← カスタム設定（server ブロック）

# 設定ファイルのパスも確認
nginx -T | grep "# configuration"

# 特定の設定ファイルだけチェック
nginx -t -c /etc/nginx/nginx.conf

# 現在読み込まれている設定のダンプ
nginx -T 2>/dev/null | grep -A1 "client_max"

Häufige Konfigurationsfehler und deren Lösungen

• <strong>Einheitsfehler</strong>: <code>client_max_body_size 100</code> wird als Bytes angegeben. Fügen Sie immer die Einheit wie in <code>100m</code> hinzu
• <strong>Hierarchieübersicht</strong>: Wenn Sie versuchen, im location-Block zu überschreiben, aber der übergeordnete server- oder http-Block wirksam ist
• <strong>Reload vergessen</strong>: Änderungen in der Konfigurationsdatei werden nicht wirksam, wenn Sie <code>nginx -s reload</code> nicht ausführen
• <strong>Mehrere server-Blöcke</strong>: Konflikt zwischen verschiedenen conf.d-Dateien, die mit include geladen werden
• <strong>Nichtübereinstimmung mit PHP</strong>: Selbst wenn Sie Nginx erhöhen, bleibt das <code>upload_max_filesize</code> von PHP niedrig und erzeugt andere Fehler als 413