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

Установка для Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-upload, предоставляемому репозиторием GetPageSpeed Extras.

1. Настройте репозиторий APT, как описано в настройке репозитория APT.
2. Установите модуль:

sudo apt-get update
sudo apt-get install nginx-module-upload

Показать дистрибутивы и архитектуры

| Дистрибутив | Версия            | Компонент   | Архитектуры   |
|-------------|-------------------|-------------|---------------|
| debian      | bookworm          | main        | amd64, arm64  |
| debian      | bookworm-mainline | main        | amd64, arm64  |
| debian      | trixie            | main        | amd64, arm64  |
| debian      | trixie-mainline   | main        | amd64, arm64  |
| ubuntu      | focal             | main        | amd64, arm64  |
| ubuntu      | focal-mainline    | main        | amd64, arm64  |
| ubuntu      | jammy             | main        | amd64, arm64  |
| ubuntu      | jammy-mainline    | main        | amd64, arm64  |
| ubuntu      | noble             | main        | amd64, arm64  |
| ubuntu      | noble-mainline    | main        | amd64, arm64  |

---

Модуль для 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

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