Загрузки в Nginx: буферизация тела запроса и лимиты

При загрузке большого файла Nginx может занять место на диске и задержать передачу данных приложению — даже если само приложение готово принять файл сразу. В этой практике для Nginx Open Source 1.24 и новее разберём два режима передачи тела запроса, настройку лимита размера и проверку поведения без выдуманных цифр производительности.

Сначала разделите три разных настройки

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

• client_max_body_size задаёт максимально допустимый размер тела запроса. При превышении Nginx отвечает ошибкой 413.
• client_body_buffer_size задаёт буфер для тела запроса в памяти. Если тело не помещается в него целиком или частично, Nginx может записать данные во временный файл.
• proxy_request_buffering определяет, передаёт ли Nginx тело запроса upstream-серверу после полной буферизации или по мере чтения от клиента.

proxy_buffering относится к ответам upstream-сервера клиенту, а не к загружаемому файлу. Изменять его ради ускорения загрузки — значит настраивать не тот поток.

Буферизация не отменяет лимит: она определяет, где и когда Nginx хранит тело запроса, а не какой размер файла разрешён.

Upstream — сервер приложения, которому Nginx передаёт запрос, например сервис загрузки файлов.

Выберите, кто будет ждать: клиент или приложение

По умолчанию proxy_request_buffering включён. Nginx сначала читает тело запроса целиком; если оно не помещается в буфер в памяти, может использовать временный файл. Затем Nginx передаёт запрос приложению. При медленном клиенте приложение не начинает обработку файла, пока Nginx ждёт окончания загрузки.

При proxy_request_buffering off Nginx передаёт тело приложению по мере чтения. Это может уменьшить ожидание перед началом обработки и сократить потребность во временном диске на стороне Nginx. Но медленный клиент теперь дольше занимает соединение приложения, а начать передачу запроса повторно после отправки тела upstream Nginx уже не сможет.

Настройте лимит и временные файлы

Пример для Nginx Open Source 1.24 и новее: приложение доступно через upstream с именем app, а обработчик загрузки — по пути /upload/. Значение лимита — 200 мегабайт; замените его на ограничение, которое поддерживают приложение, хранилище и тариф сервера. Это не универсальная рекомендация.

http {
    client_max_body_size 200m;
    client_body_temp_path /var/lib/nginx/client_body_temp 1 2;

    upstream app {
        server 127.0.0.1:8000;
    }

    server {
        listen 80;
        server_name example.test;

        location /upload/ {
            proxy_pass http://app;
            proxy_http_version 1.1;
            proxy_request_buffering on;
            client_body_timeout 60s;
        }
    }
}

Укажите в client_body_temp_path каталог, доступный на запись пользователю Nginx и расположенный на томе с достаточным свободным местом. Параметры 1 2 задают уровни подкаталогов внутри этого пути, а не лимит размера. Убедитесь, что указанный путь существует или Nginx может создать необходимые каталоги при запуске.

client_body_timeout ограничивает время между последовательными операциями чтения тела от клиента, а не продолжительность всей загрузки. Значение в примере не означает, что любая загрузка оборвётся через 60 секунд.

Если приложение принимает поток

Для передачи тела по мере поступления добавьте в нужный location директиву proxy_request_buffering off;. Оставьте proxy_http_version 1.1; явно: это важно для предсказуемой передачи потокового тела, особенно при чанкированном запросе. Проверьте также, что само приложение не буферизует файл целиком и способно долго обрабатывать открытое соединение.

Отключать буферизацию для всех адресов сразу рискованно: обычные API-запросы тоже могут занять соединения приложения на всё время отправки медленным клиентом.

Проверьте конфигурацию и поведение

1. Проверьте доступное место на файловой системе с временным каталогом и права пользователя Nginx на запись. Успех: каталог доступен, а место не заканчивается при тестовой загрузке.
2. Проверьте синтаксис командой nginx -t и перечитайте конфигурацию штатным способом вашей установки. Успех: проверка завершается сообщением об успешном тесте, без ошибки пути или директивы.
3. Загрузите файл меньше установленного лимита через реальный адрес сервиса. Успех: приложение получает файл и завершает обработку, а клиент получает ожидаемый ответ.
4. Повторите запрос с телом больше лимита. Успех: Nginx возвращает 413, а приложение не принимает этот запрос.
5. Сравните оба режима на тестовом стенде: время от начала отправки до первого события в приложении, занятое место во временном каталоге, длительность соединений upstream и итоговую ошибку или ответ. Успех: вы видите, кто ждёт окончания передачи, а не только общее время запроса.

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

Что ломается на границах

• Приложение отвечает раньше, но загрузка всё равно ждёт. Проверьте, что proxy_request_buffering off задан именно в нужном location, а приложение действительно обрабатывает входящий поток, не копируя всё тело в память.
• Крупный файл заканчивается ошибкой 413. Сверьте client_max_body_size в фактически применяемом контексте. Лимит может отличаться в других блоках конфигурации; кроме того, собственное ограничение может быть у приложения или другого прокси перед Nginx.
• Появляется ошибка записи во временный файл. Проверьте свободное место, права доступа и путь client_body_temp_path. Отключение буферизации не исправит ситуацию, если временные файлы создаёт другой слой системы.
• Потоковая передача не сработала для чанкированного тела. Проверьте используемую версию протокола между Nginx и upstream и настройки приложения. Не считайте заголовок запроса доказательством того, что весь путь действительно работает без буферизации.
• Запрос обрывается на медленной сети. client_body_timeout отсчитывает паузу между операциями чтения. Сверьте его с поведением клиентов; отдельно проверьте ограничения балансировщика, приложения и таймауты на ответ upstream.

Что делать дальше

Начните с маршрута загрузки, а не со всей конфигурации: измерьте размер файлов, скорость отправки и время обработки приложения, затем проверьте запас места во временном каталоге при одновременных запросах. Если важнее изоляция приложения от медленных клиентов, оставьте буферизацию включённой и контролируйте диск. Если приложение принимает поток и выигрыш подтверждён измерениями, отключайте её точечно и следите за длительностью соединений upstream и долей ошибок загрузки. Настройка времени хранения файла и очистки загруженного контента — отдельная тема.