upload: Módulo NGINX para lidar com uploads de arquivos

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

• RedHat Enterprise Linux 7, 8, 9 e 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 e Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 and Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upload

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upload

Habilite o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_upload_module.so;

Este documento descreve o nginx-module-upload v2.4.0 lançado em 03 de fevereiro de 2026.

---

Um módulo para nginx para lidar com uploads de arquivos usando codificação multipart/form-data (RFC 1867) e uploads retomáveis de acordo com este protocolo.

• Descrição
• Diretivas
  • upload_pass
  • upload_resumable
  • upload_store
  • upload_state_store
  • upload_store_access
  • upload_set_form_field
  • upload_aggregate_form_field
  • upload_pass_form_field
  • upload_cleanup
  • upload_buffer_size
  • upload_max_part_header_len
  • upload_max_file_size
  • upload_limit_rate
  • upload_max_output_body_len
  • upload_tame_arrays
  • upload_pass_args
• Exemplo de configuração
• Licença

Descrição

O módulo analisa o corpo da requisição armazenando todos os arquivos sendo enviados para um diretório especificado pela diretiva upload_store. Os arquivos são então removidos do corpo e a requisição alterada é então passada para um local especificado pela diretiva upload_pass, permitindo assim o tratamento arbitrário dos arquivos enviados. Cada um dos campos de arquivo é substituído por um conjunto de campos especificados pela diretiva upload_set_form_field. O conteúdo de cada arquivo enviado pode então ser lido de um arquivo especificado pela variável $upload_tmp_path ou o arquivo pode ser simplesmente movido para o destino final. A remoção dos arquivos de saída é controlada pela diretiva upload_cleanup. Se uma requisição tiver um método diferente de POST, o módulo retorna o erro 405 (Method not allowed). Requisições com tais métodos podem ser processadas em um local alternativo através da diretiva error_page.

Diretivas

upload_pass

Sintaxe: upload_pass location
Padrão: —
Contexto: server,location

Especifica o local para o qual passar o corpo da requisição. Os campos de arquivo serão removidos e substituídos por campos, contendo as informações necessárias para lidar com os arquivos enviados.

upload_resumable

Sintaxe: upload_resumable on | off
Padrão: upload_resumable off
Contexto: main,server,location

Habilita uploads retomáveis.

upload_store

Sintaxe: upload_store directory [level1 [level2]] ...
Padrão: —
Contexto: server,location

Especifica um diretório no qual os arquivos de saída serão salvos. O diretório pode ser com hash. Neste caso, todos os subdiretórios devem existir antes de iniciar o nginx.

upload_state_store

Sintaxe: upload_state_store directory [level1 [level2]] ...
Padrão: —
Contexto: server,location

Especifica um diretório que conterá os arquivos de estado para uploads retomáveis. O diretório pode ser com hash. Neste caso, todos os subdiretórios devem existir antes de iniciar o nginx.

upload_store_access

Sintaxe: upload_store_access mode
Padrão: upload_store_access user:rw
Contexto: server,location

Especifica o modo de acesso que será usado para criar os arquivos de saída.

upload_set_form_field

Sintaxe: upload_set_form_field name value
Padrão: —
Contexto: server,location

Especifica um ou mais campos de formulário a serem gerados para cada arquivo enviado no corpo da requisição passado para o backend. Tanto name quanto value podem conter as seguintes variáveis especiais:

• $upload_field_name: o nome do campo de arquivo original
• $upload_content_type: o tipo de conteúdo do arquivo enviado
• $upload_file_name: o nome original do arquivo sendo enviado com os elementos de caminho iniciais em notação DOS e UNIX removidos. Ou seja, "D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg" será convertido para "Picture.jpg" e "/etc/passwd" será convertido para "passwd".
• $upload_tmp_path: o caminho onde o conteúdo do arquivo original está sendo armazenado. O nome do arquivo de saída consiste em 10 dígitos e é gerado com o mesmo algoritmo da diretiva proxy_temp_path.

Estas variáveis são válidas apenas durante o processamento de uma parte do corpo da requisição original.

Exemplo de uso:

upload_set_form_field $upload_field_name.name "$upload_file_name";
upload_set_form_field $upload_field_name.content_type "$upload_content_type";
upload_set_form_field $upload_field_name.path "$upload_tmp_path";

upload_aggregate_form_field

Sintaxe: upload_aggregate_form_field name value
Padrão: —
Contexto: server,location

Especifica um ou mais campos de formulário contendo atributos agregados a serem gerados para cada arquivo enviado no corpo da requisição passado para o backend. Tanto name quanto value podem conter variáveis padrão do nginx, variáveis da diretiva upload_set_form_field e as seguintes variáveis especiais adicionais:

• $upload_file_md5: checksum MD5 do arquivo
• $upload_file_md5_uc: checksum MD5 do arquivo em letras maiúsculas
• $upload_file_sha1: checksum SHA1 do arquivo
• $upload_file_sha1_uc: checksum SHA1 do arquivo em letras maiúsculas
• $upload_file_sha256: checksum SHA256 do arquivo
• $upload_file_sha256_uc: checksum SHA256 do arquivo em letras maiúsculas
• $upload_file_sha512: checksum SHA512 do arquivo
• $upload_file_sha512_uc: checksum SHA512 do arquivo em letras maiúsculas
• $upload_file_crc32: valor hexadecimal do CRC32 do arquivo
• $upload_file_size: tamanho do arquivo em bytes
• $upload_file_number: número ordinal do arquivo no corpo da requisição

O valor de um campo especificado por esta diretiva é avaliado após o upload bem-sucedido do arquivo, portanto estas variáveis são válidas apenas no final do processamento de uma parte do corpo da requisição original.

Aviso: as variáveis $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 e $upload_file_sha1_uc usam recursos adicionais para calcular os checksums MD5 e SHA1.

Exemplo de uso:

upload_aggregate_form_field $upload_field_name.md5 "$upload_file_md5";
upload_aggregate_form_field $upload_field_name.size "$upload_file_size";

upload_pass_form_field

Sintaxe: upload_pass_form_field regex
Padrão: —
Contexto: server,location

Especifica um padrão regex para nomes de campos que serão passados para o backend a partir do corpo da requisição original. Esta diretiva pode ser especificada múltiplas vezes por local. O campo será passado para o backend assim que o primeiro padrão corresponder. Para ambientes sem PCRE, esta diretiva especifica o nome exato de um campo a ser passado para o backend. Se a diretiva for omitida, nenhum campo será passado para o backend pelo cliente.

Exemplo de uso:

upload_pass_form_field "^submit$|^description$";

Para ambientes sem PCRE:

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Sintaxe: upload_cleanup status/range ...
Padrão: —
Contexto: server,location

Especifica os status HTTP após a geração dos quais todos os arquivos enviados com sucesso na requisição atual serão removidos. Usado para limpeza após falha do backend ou do servidor. O backend também pode sinalizar explicitamente um status de erro se não precisar dos arquivos enviados por algum motivo. O status HTTP deve ser um valor numérico no intervalo 400-599, sem zeros à esquerda permitidos. Intervalos de status podem ser especificados com um hífen.

Exemplo de uso:

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Sintaxe: upload_buffer_size size
Padrão: tamanho da página de memória em bytes
Contexto: server,location

Tamanho em bytes do buffer de escrita que será usado para acumular dados de arquivo e gravá-los em disco. Esta diretiva destina-se a ser usada para equilibrar o uso de memória versus a taxa de chamadas de sistema.

upload_max_part_header_len

Sintaxe: upload_max_part_header_len size
Padrão: 512
Contexto: server,location

Especifica o comprimento máximo do cabeçalho da parte em bytes. Determina o tamanho do buffer que será usado para acumular os cabeçalhos das partes.

upload_max_file_size

Sintaxe: upload_max_file_size size
Padrão: 0
Contexto: main,server,location

Especifica o tamanho máximo do arquivo. Arquivos maiores que o valor desta diretiva serão omitidos. Esta diretiva especifica um limite "soft", no sentido de que, após encontrar um arquivo maior que o limite especificado, o nginx continuará a processar o corpo da requisição, tentando receber os arquivos restantes. Para um limite "hard", a diretiva client_max_body_size deve ser usada. O valor zero para esta diretiva especifica que nenhuma restrição de tamanho de arquivo deve ser aplicada.

upload_limit_rate

Sintaxe: upload_limit_rate rate
Padrão: 0
Contexto: main,server,location

Especifica o limite de taxa de upload em bytes por segundo. Zero significa que a taxa é ilimitada.

upload_max_output_body_len

Sintaxe: upload_max_output_body_len size
Padrão: 100k
Contexto: main,server,location

Especifica o comprimento máximo do corpo de saída. Isso evita o acúmulo de campos de formulário que não são de arquivo na memória. Sempre que o corpo de saída exceder o limite especificado, o erro 413 (Request entity too large) será gerado. O valor zero para esta diretiva especifica que nenhuma restrição ao comprimento do corpo de saída deve ser aplicada.

upload_tame_arrays

Sintaxe: upload_tame_arrays on | off
Padrão: off
Contexto: main,server,location

Especifica se os colchetes nos nomes dos campos de arquivo devem ser removidos (necessário para arrays PHP).

upload_pass_args

Sintaxe: upload_pass_args on | off
Padrão: off
Contexto: main,server,location

Habilita o encaminhamento de argumentos de consulta para o local especificado por upload_pass. Ineficaz com locais nomeados. Exemplo:

<form action="/upload/?id=5">
<!-- ... -->

location /upload/ {
    upload_pass /internal_upload/;
    upload_pass_args on;
}

## ...

location /internal_upload/ {
    # ...
    proxy_pass http://backend;
}

Neste exemplo, o backend recebe a URI da requisição "/upload?id=5". No caso de upload_pass_args off, o backend recebe "/upload".

Exemplo de configuração

server {
    client_max_body_size 100m;
    listen 80;

    # Upload form should be submitted to this location
    location /upload/ {
        # Pass altered request body to this location
        upload_pass @test;

        # Store files to this directory
        # The directory is hashed, subdirectories 0 1 2 3 4 5 6 7 8 9 should exist
        upload_store /tmp 1;

        # Allow uploaded files to be read only by user
        upload_store_access user:r;

        # Set specified fields in request body
        upload_set_form_field $upload_field_name.name "$upload_file_name";
        upload_set_form_field $upload_field_name.content_type "$upload_content_type";
        upload_set_form_field $upload_field_name.path "$upload_tmp_path";

        # Inform backend about hash and size of a file
        upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
        upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";

        upload_pass_form_field "^submit$|^description$";

        upload_cleanup 400 404 499 500-505;
    }

    # Pass altered request body to a backend
    location @test {
        proxy_pass http://localhost:8080;
    }
}

<form name="upload" method="POST" enctype="multipart/form-data" action="/upload/">
<input type="file" name="file1">
<input type="file" name="file2">
<input type="hidden" name="test" value="value">
<input type="submit" name="submit" value="Upload">
</form>