Загрузка файлов в Nginx: практические настройки без сюрпризов

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

Сначала определите, кто принимает файл

Nginx сам по себе не разбирает форму загрузки и не сохраняет пользовательские файлы в бизнес-хранилище. Обычно он принимает HTTP-запрос, проверяет его размер, временно хранит тело на диске или в памяти и передаёт запрос приложению через upstream — сервер, указанный в proxy_pass.

От этого зависят настройки:

• если приложение принимает multipart-запрос и само сохраняет файл, настройте лимит, таймаут и место для временных данных Nginx;
• если приложение умеет обрабатывать тело запроса частями, можно отключить буферизацию запроса;
• если файл должен сразу попасть в объектное хранилище, лучше рассмотреть загрузку напрямую из браузера по временной ссылке, а Nginx оставить для API.

Термин: upstream — сервер или группа серверов, куда Nginx передаёт запрос после своей обработки.

Главная настройка загрузки — не «поднять лимит до гигабайта», а согласовать размер, таймауты, свободное место и поведение приложения.

Базовая конфигурация для приложения

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

Пример для Nginx 1.25–1.27:

http {
    proxy_temp_path /var/cache/nginx/proxy_temp 1 2;

    server {
        listen 80;
        server_name example.com;

        location /upload/ {
            client_max_body_size 100m;
            client_body_timeout 120s;
            client_body_temp_path /var/cache/nginx/client_temp 1 2;

            proxy_pass http://app_backend;
            proxy_request_buffering on;
            proxy_read_timeout 180s;
        }
    }
}

client_max_body_size ограничивает весь размер тела HTTP-запроса, а не только один файл в multipart-форме. Если лимит превышен, Nginx обычно отвечает кодом 413 ещё до обращения к приложению. Значение 100m — пример, а не универсальная рекомендация: поставьте его немного выше разрешённого размера файла с учётом полей формы и служебных данных multipart.

client_body_timeout задаёт максимальную паузу между чтением двух частей тела запроса. Это не общее время загрузки: медленный, но непрерывный клиент может передавать данные дольше 120 секунд. Такой лимит помогает не держать соединение бесконечно.

После изменения проверьте конфигурацию до перезагрузки:

sudo nginx -t
sudo systemctl reload nginx

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

Буферизация или потоковая передача

Ключевая настройка здесь — proxy_request_buffering. При значении on, установленном по умолчанию, Nginx сначала читает запрос от клиента и сохраняет его во временное хранилище, если тела не помещается в буфер. При off Nginx передаёт тело upstream по мере получения.

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

Когда имеет смысл отключить буферизацию

Минимальная настройка выглядит так:

location /stream-upload/ {
    client_max_body_size 1g;
    client_body_timeout 600s;

    proxy_pass http://streaming_app;
    proxy_request_buffering off;
    proxy_read_timeout 600s;
}

Такой вариант не превращает приложение в потоковый обработчик автоматически. Если backend ждёт полностью загруженный multipart-файл, отключение буферизации не даст выигрыша: приложение всё равно будет накапливать данные само, но рабочий процесс будет занят дольше.

Отдельно проверьте ограничения upstream. Фреймворк, веб-сервер приложения или сам обработчик могут иметь собственный лимит размера тела и таймаут. Если Nginx разрешает 1 ГБ, а приложение — 50 МБ, пользователь всё равно получит отказ, только позже и с другим текстом ошибки.

Что ломается чаще всего

413 Request Entity Too Large

Сначала найдите, кто вернул ответ. Если в заголовках и теле виден стандартный ответ Nginx, увеличьте client_max_body_size в том server или location, который реально обрабатывает URL. Если ответ формирует приложение, ищите его собственный лимит. Не поднимайте значение вслепую: большой лимит увеличивает потенциальный расход диска, трафика и времени обработки.

Нет места или прав во временном каталоге

При буферизации Nginx может писать тело запроса в каталог, заданный client_body_temp_path. Проверьте свободное место именно на разделе, где находится этот путь, и права пользователя, от которого работает Nginx. Ошибки в журнале обычно содержат слова Permission denied или No space left on device.

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

Загрузка обрывается по таймауту

Проверьте сразу три участка цепочки: клиент до Nginx, Nginx до приложения и обработчик в самом приложении. client_body_timeout отвечает за паузы во входящем запросе, а proxy_read_timeout — за ожидание данных от upstream после передачи запроса. Увеличение только одного из них часто не меняет результат.

Приложение начинает отвечать 502 или 504

Это уже не обязательно проблема лимита файла. Посмотрите error log Nginx и журнал приложения: процесс мог завершиться из-за нехватки памяти, upstream мог закрыть соединение, а обработка могла превысить допустимое время. Для проверки сначала загрузите небольшой файл и сравните поведение, затем повторите тест на границе установленного лимита.

Файл загружается, но оказывается повреждённым

Проверьте, не изменяет ли приложение тело запроса, не включён ли повторный разбор multipart-данных и совпадает ли способ отправки клиента с тем, который ожидает backend. Nginx не должен использоваться как средство проверки содержимого файла: тип, расширение, размер после распаковки и антивирусную проверку контролируйте на уровне приложения или отдельного сервиса.

Безопасность и эксплуатация

• Ограничьте размер запроса в конкретном location, а не на всём сервере, если разные эндпоинты принимают разные объёмы.
• Не сохраняйте пользовательское имя файла как имя на диске. Приложение должно генерировать собственный идентификатор и хранить исходное имя отдельно.
• Не отдавайте каталог временных файлов напрямую через статический URL.
• Следите за свободным местом, количеством временных файлов, кодами 413, 499, 502 и 504, а также временем загрузки по перцентилям.
• Проверяйте лимит не только для обычного POST, но и для всех путей, через которые можно загрузить файл: API, админка, импорт и фоновые callback-запросы.

Сжатие запроса не заменяет лимит размера. Архив на несколько мегабайт может распаковаться в гигабайты, поэтому защиту от zip-бомб и проверку содержимого реализуют после приёма файла, на уровне приложения или отдельного воркера.

Когда какой вариант выбирать

Для файлов до сотен мегабайт и обычного веб-приложения начинайте с включённой буферизации, отдельного временного каталога и измеряемого лимита. Если пользователи отправляют гигабайтные файлы, а backend умеет потоково писать их в хранилище, тестируйте proxy_request_buffering off на staging под несколькими параллельными загрузками.

Если основная проблема — пропускная способность API, а не обработка файла, вынесите загрузку в объектное хранилище по временной ссылке. Инвалидация таких ссылок и очистка незавершённых объектов — отдельная тема; здесь важно не маскировать её настройкой Nginx.

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

Снимите базовые показатели: размер временного файла, свободное место на разделе, время загрузки, долю ответов 413 и 5xx. Затем протестируйте три сценария: файл чуть меньше лимита, файл больше лимита и медленная загрузка с паузами. После этого согласуйте ограничения Nginx и приложения и только затем решайте, нужна ли потоковая передача или прямая загрузка в объектное хранилище.