upload: модуль NGINX для обработки загрузки файлов

Установка

Вы можете установить этот модуль в любом дистрибутиве на базе RHEL, включая, но не ограничиваясь:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и 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

Включите модуль, добавив следующее в начало /etc/nginx/nginx.conf:

load_module modules/ngx_http_upload_module.so;

Этот документ описывает nginx-module-upload v2.4.0, выпущенный 03 февраля 2026 г.

---

Модуль для nginx для обработки загрузки файлов с использованием кодировки multipart/form-data (RFC 1867) и возобновляемой загрузки в соответствии с этим протоколом.

• Описание
• Директивы
  • 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
• Пример конфигурации
• Лицензия

Описание

Модуль разбирает тело запроса, сохраняя все загружаемые файлы в каталог, указанный директивой upload_store. Затем файлы удаляются из тела запроса, и изменённый запрос передаётся в location, указанный директивой upload_pass, что позволяет произвольным образом обрабатывать загруженные файлы. Каждое поле файла заменяется набором полей, указанных директивой upload_set_form_field. Содержимое каждого загруженного файла затем можно прочитать из файла, указанного переменной $upload_tmp_path, или файл можно просто переместить в конечное место назначения. Удаление выходных файлов контролируется директивой upload_cleanup. Если запрос имеет метод, отличный от POST, модуль возвращает ошибку 405 (Method not allowed). Запросы с такими методами можно обрабатывать в альтернативном location с помощью директивы error_page.

Директивы

upload_pass

Синтаксис: upload_pass location
По умолчанию: —
Контекст: server,location

Указывает location, в который следует передать тело запроса. Поля файлов будут удалены и заменены полями, содержащими необходимую информацию для обработки загруженных файлов.

upload_resumable

Синтаксис: upload_resumable on | off
По умолчанию: upload_resumable off
Контекст: main,server,location

Включает возобновляемую загрузку.

upload_store

Синтаксис: upload_store directory [level1 [level2]] ...
По умолчанию: —
Контекст: server,location

Указывает каталог, в который будут сохраняться выходные файлы. Каталог может быть хешированным. В этом случае все подкаталоги должны существовать до запуска nginx.

upload_state_store

Синтаксис: upload_state_store directory [level1 [level2]] ...
По умолчанию: —
Контекст: server,location

Указывает каталог, который будет содержать файлы состояния для возобновляемой загрузки. Каталог может быть хешированным. В этом случае все подкаталоги должны существовать до запуска nginx.

upload_store_access

Синтаксис: upload_store_access mode
По умолчанию: upload_store_access user:rw
Контекст: server,location

Указывает режим доступа, который будет использоваться при создании выходных файлов.

upload_set_form_field

Синтаксис: upload_set_form_field name value
По умолчанию: —
Контекст: server,location

Указывает поле (поля) формы, которое следует сгенерировать для каждого загруженного файла в теле запроса, передаваемом бэкенду. И name, и value могут содержать следующие специальные переменные:

• $upload_field_name: имя исходного поля файла
• $upload_content_type: тип содержимого загруженного файла
• $upload_file_name: исходное имя загружаемого файла с удалёнными ведущими элементами пути в нотации DOS и UNIX. То есть "D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg" будет преобразовано в "Picture.jpg", а "/etc/passwd" будет преобразовано в "passwd".
• $upload_tmp_path: путь, по которому сохраняется содержимое исходного файла. Имя выходного файла состоит из 10 цифр и генерируется тем же алгоритмом, что и в директиве proxy_temp_path.

Эти переменные действительны только во время обработки одной части исходного тела запроса.

Пример использования:

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

Синтаксис: upload_aggregate_form_field name value
По умолчанию: —
Контекст: server,location

Указывает поле (поля) формы, содержащее агрегированные атрибуты, которое следует сгенерировать для каждого загруженного файла в теле запроса, передаваемом бэкенду. И name, и value могут содержать стандартные переменные nginx, переменные из директивы upload_set_form_field и следующие дополнительные специальные переменные:

• $upload_file_md5: контрольная сумма MD5 файла
• $upload_file_md5_uc: контрольная сумма MD5 файла в верхнем регистре
• $upload_file_sha1: контрольная сумма SHA1 файла
• $upload_file_sha1_uc: контрольная сумма SHA1 файла в верхнем регистре
• $upload_file_sha256: контрольная сумма SHA256 файла
• $upload_file_sha256_uc: контрольная сумма SHA256 файла в верхнем регистре
• $upload_file_sha512: контрольная сумма SHA512 файла
• $upload_file_sha512_uc: контрольная сумма SHA512 файла в верхнем регистре
• $upload_file_crc32: шестнадцатеричное значение CRC32 файла
• $upload_file_size: размер файла в байтах
• $upload_file_number: порядковый номер файла в теле запроса

Значение поля, указанного этой директивой, вычисляется после успешной загрузки файла, поэтому эти переменные действительны только в конце обработки одной части исходного тела запроса.

Предупреждение: переменные $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 и $upload_file_sha1_uc используют дополнительные ресурсы для вычисления контрольных сумм MD5 и SHA1.

Пример использования:

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

Синтаксис: upload_pass_form_field regex
По умолчанию: —
Контекст: server,location

Указывает шаблон регулярного выражения для имён полей, которые будут переданы бэкенду из исходного тела запроса. Эту директиву можно указывать несколько раз в одном location. Поле будет передано бэкенду, как только совпадёт первый шаблон. Для окружений без поддержки PCRE эта директива указывает точное имя поля для передачи бэкенду. Если директива опущена, никакие поля не будут переданы бэкенду от клиента.

Пример использования:

upload_pass_form_field "^submit$|^description$";

Для окружений без поддержки PCRE:

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Синтаксис: upload_cleanup status/range ...
По умолчанию: —
Контекст: server,location

Указывает HTTP-статусы, после генерации которых все файлы, успешно загруженные в текущем запросе, будут удалены. Используется для очистки после сбоя бэкенда или сервера. Бэкенд также может явно сигнализировать об ошибочном статусе, если ему по какой-то причине не нужны загруженные файлы. HTTP-статус должен быть числовым значением в диапазоне 400-599, ведущие нули не допускаются. Диапазоны статусов можно указывать через дефис.

Пример использования:

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Синтаксис: upload_buffer_size size
По умолчанию: размер страницы памяти в байтах
Контекст: server,location

Размер в байтах буфера записи, который будет использоваться для накопления данных файла и записи их на диск. Эта директива предназначена для использования с целью компромисса между использованием памяти и частотой системных вызовов.

upload_max_part_header_len

Синтаксис: upload_max_part_header_len size
По умолчанию: 512
Контекст: server,location

Указывает максимальную длину заголовка части в байтах. Определяет размер буфера, который будет использоваться для накопления заголовков частей.

upload_max_file_size

Синтаксис: upload_max_file_size size
По умолчанию: 0
Контекст: main,server,location

Указывает максимальный размер файла. Файлы, превышающие значение этой директивы, будут пропущены. Эта директива задаёт "мягкий" лимит, в том смысле, что после обнаружения файла, превышающего указанный лимит, nginx продолжит обработку тела запроса, пытаясь получить оставшиеся файлы. Для "жёсткого" лимита необходимо использовать директиву client_max_body_size. Значение ноль для этой директивы означает, что никакие ограничения на размер файла не применяются.

upload_limit_rate

Синтаксис: upload_limit_rate rate
По умолчанию: 0
Контекст: main,server,location

Указывает ограничение скорости загрузки в байтах в секунду. Ноль означает, что скорость не ограничена.

upload_max_output_body_len

Синтаксис: upload_max_output_body_len size
По умолчанию: 100k
Контекст: main,server,location

Указывает максимальную длину выходного тела. Это предотвращает накопление нефайловых полей формы в памяти. Всякий раз, когда выходное тело превышает указанный лимит, будет сгенерирована ошибка 413 (Request entity too large). Значение ноль для этой директивы означает, что никакие ограничения на длину выходного тела не применяются.

upload_tame_arrays

Синтаксис: upload_tame_arrays on | off
По умолчанию: off
Контекст: main,server,location

Указывает, должны ли квадратные скобки в именах полей файлов быть удалены (требуется для массивов PHP).

upload_pass_args

Синтаксис: upload_pass_args on | off
По умолчанию: off
Контекст: main,server,location

Включает перенаправление аргументов запроса в location, указанный директивой upload_pass. Неэффективно с именованными location. Пример:

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

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

## ...

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

В этом примере бэкенд получает URI запроса "/upload?id=5". В случае upload_pass_args off бэкенд получает "/upload".

Пример конфигурации

server {
    client_max_body_size 100m;
    listen 80;

    # Форма загрузки должна отправляться в этот location
    location /upload/ {
        # Передать изменённое тело запроса в этот location
        upload_pass @test;

        # Сохранять файлы в этот каталог
        # Каталог хеширован, подкаталоги 0 1 2 3 4 5 6 7 8 9 должны существовать
        upload_store /tmp 1;

        # Разрешить чтение загруженных файлов только пользователю
        upload_store_access user:r;

        # Установить указанные поля в теле запроса
        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 "$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;
    }

    # Передать изменённое тело запроса бэкенду
    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>