Como configurar corretamente client_max_body_size no Nginx | Solução de problemas de limite de upload

Ao implementar uploads de arquivo no Nginx, é muito comum encontrar o problema em que 「arquivos pequenos são enviados, mas arquivos grandes resultam em erro 413」. A maioria das causas é configuração insuficiente de <code>client_max_body_size</code>. No entanto, mesmo corrigindo apenas a configuração do Nginx, muitos casos não são resolvidos. É necessário entender completamente as configurações de <code>upload_max_filesize</code> e <code>post_max_size</code> do PHP, bem como configurações de timeout. Este artigo explica sistematicamente todos os itens de configuração relacionados aos limites de upload.

Valor padrão e função do client_max_body_size

O Nginx possui uma diretiva chamada <code>client_max_body_size</code> que limita o tamanho máximo do corpo da solicitação do cliente. O valor padrão é <code>1m</code> (1 MiB). Solicitações que excedem isso são imediatamente rejeitadas como erro <code>413 Request Entity Too Large</code>.

O padrão é 1m, que é extremamente pequeno, portanto o limite é atingido imediatamente mesmo ao fazer upload de uma única imagem ou PDF. Em ambientes de produção reais, este valor deve ser aumentado adequadamente dependendo do uso.

Local de configuração: diferenças entre http / server / location

<code>client_max_body_size</code> pode ser escrito em qualquer nível de configuração do Nginx (http / server / location). As configurações com escopo mais específico têm prioridade.

# 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;
        }
    }
}

É uma abordagem preferível do ponto de vista de segurança definir um valor grande apenas para o endpoint dedicado de upload e manter valores pequenos para os demais. Para permitir tamanho ilimitado, especifique <code>0</code>, mas isso não é recomendado pois aumenta o risco de ataques DoS.

Causa e solução do erro 413 Request Entity Too Large

Vamos organizar as causas e medidas para resolver o erro 413.

É necessário recarregar o Nginx após alterar a configuração.

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

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

# または systemd 経由
systemctl reload nginx

Relação entre upload_max_filesize / post_max_size do PHP

Aumentar apenas o <code>client_max_body_size</code> do Nginx não é suficiente. Quando o backend é PHP, existem limitações independentes no nível do PHP. O upload será bem-sucedido apenas quando essas três configurações tiverem valores apropriados.

; 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

A relação dos valores de configuração importantes é a seguinte.

• client_max_body_size（Nginx） ≥ post_max_size（PHP） ≥ upload_max_filesize（PHP）
• Se o Nginx rejeitar a solicitação, o processamento não chegará até o PHP
• <code>post_max_size</code> é o limite de tamanho para o corpo POST inteiro, incluindo uploads de múltiplos arquivos e campos de formulário além de arquivos

A importância de proxy_read_timeout / proxy_send_timeout

Para uploads de arquivos grandes, a configuração de timeout também é importante. O padrão <code>proxy_read_timeout</code> é de 60 segundos, e se o upload levar muito tempo, o processo será interrompido.

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;
}

É recomendado configurar valores de timeout separadamente para o endpoint de upload e o endpoint de API normal.

Configuração no Docker (mount de nginx.conf)

Em um ambiente Docker, um arquivo nginx.conf ou conf.d personalizado é montado no contêiner para refletir as configurações.

# 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;
    }
}

Comando de verificação de configuração

Para verificar qual valor <code>client_max_body_size</code> tem na configuração atual do Nginx, é conveniente expandir todas as configurações com <code>nginx -T</code> e depois usar grep.

# 全設定を展開して 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"

Erros de configuração comuns e como resolvê-los

• <strong>Erro de unidade</strong>: <code>client_max_body_size 100</code> será interpretado como bytes. Sempre adicione a unidade como em <code>100m</code>
• <strong>Negligência de hierarquia</strong>: quando você tenta sobrescrever dentro do bloco location, mas o bloco server ou http de nível superior está em vigor
• <strong>Esquecer de recarregar</strong>: as alterações no arquivo de configuração não serão refletidas sem executar <code>nginx -s reload</code>
• <strong>Múltiplos blocos server</strong>: conflito entre diferentes arquivos conf.d carregados com include
• <strong>Incompatibilidade com PHP</strong>: Mesmo aumentando o Nginx, o <code>upload_max_filesize</code> do PHP permanece baixo e gera erros além do 413