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.3.0, выпущенный 2 августа 2018 года.

---

Модуль для 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. Затем файлы удаляются из тела запроса, и измененный запрос передается в местоположение, указанное директивой upload_pass, что позволяет произвольно обрабатывать загруженные файлы. Каждое поле файла заменяется набором полей, указанным директивой upload_set_form_field. Содержимое каждого загруженного файла затем может быть прочитано из файла, указанного переменной $upload_tmp_path, или файл может быть просто перемещен в конечное место назначения. Удаление выходных файлов контролируется директивой upload_cleanup. Если запрос имеет метод, отличный от POST, модуль возвращает ошибку 405 (Метод не разрешен). Запросы с такими методами могут обрабатываться в альтернативном местоположении через директиву error_page.

Директивы

upload_pass

Синтаксис: upload_pass location
По умолчанию: —
Контекст: server,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_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

Указывает шаблон regex для имен полей, которые будут переданы на бэкенд из оригинального тела запроса. Эта директива может быть указана несколько раз для каждого местоположения. Поле будет передано на бэкенд, как только первое совпадение шаблона будет найдено. Для сред, не поддерживающих 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 (Сущность запроса слишком велика). Значение ноль для этой директивы указывает, что ограничения на длину выходного тела не должны применяться.

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

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

<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 /upload/ {
        # Передать измененное тело запроса в это местоположение
        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>

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-upload.