Большие файлы в Nginx: как настроить client_max_body_size

Ошибка 413 при загрузке файла часто появляется ещё до того, как запрос попадёт в приложение: Nginx отклоняет тело, которое больше разрешённого лимита. В Nginx 1.24.x директива client_max_body_size по умолчанию ограничивает его одним мегабайтом. Увеличьте лимит в подходящем контексте, проверьте конфигурацию и перечитайте её без остановки сервера — но сначала выясните, не ограничивает ли запрос другой слой.

Сначала определите, где срабатывает лимит

Если сайт работает через прокси, путь загрузки обычно выглядит так: клиент → Nginx → приложение, а иногда перед ними стоит ещё балансировщик или CDN. Ошибка 413 означает, что один из этих узлов не принял тело запроса. Настройка Nginx поможет только в том случае, если отказывает именно он.

Посмотрите ответ в браузере и журналы Nginx и приложения. В журнале ошибок Nginx при превышении лимита обычно появляется сообщение о слишком большом теле запроса. Если Nginx запрос переслал, проверьте лимит загрузки в приложении и настройки промежуточных сервисов. Если перед Nginx есть CDN, запрос может быть отклонён ещё до вашего сервера.

Тело запроса — данные, которые клиент передаёт серверу; при загрузке файла это сам файл и, например, дополнительные поля формы.

Задайте лимит в нужном контексте

Директива client_max_body_size доступна в контекстах http, server и location. Значение наследуется от вышестоящего уровня, если ниже не задано своё. Поэтому ограничение на уровне отдельного location может отличаться от лимита всего виртуального хоста.

Ниже — пример для Nginx 1.24.x. Он разрешает запросы размером до 100 мегабайт для всего сайта. Поместите директиву внутрь соответствующего блока server в конфигурации виртуального хоста:

server {
    listen 80;
    server_name example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

Замените example.com и адрес приложения на значения вашей конфигурации. Пример задаёт лимит именно для этого виртуального хоста; если файл загружается через отдельный location, проверьте, не переопределён ли лимит там.

Измените конфигурацию безопасно

1. Найдите активный конфигурационный файл нужного виртуального хоста. Если не знаете, откуда Nginx читает настройки, проверьте параметры запуска службы и подключаемые файлы конфигурации. Проверка: вы нашли блок server, который обслуживает нужное доменное имя.
2. Добавьте client_max_body_size 100m; в этот блок или в нужный location. Выбирайте область действия по маршрутам загрузки, а не наугад. Проверка: директива стоит внутри фигурных скобок нужного блока и заканчивается точкой с запятой.
3. Проверьте синтаксис командой nginx -t. Если у службы нестандартный путь к конфигурации, используйте параметры запуска именно вашей установки. Проверка: Nginx сообщает, что синтаксис корректен и проверка конфигурации успешна.
4. Перечитайте конфигурацию: например, через nginx -s reload для соответствующего экземпляра Nginx. В системе с управлением через systemd используйте принятую у вас команду перечитывания службы. Проверка: команда завершилась без ошибки; затем повторите загрузку и проверьте журнал.

Не начинайте с перезапуска службы, если достаточно перечитать конфигурацию: ошибка в файле может помешать запуску. Сначала всегда выполняйте nginx -t.

Как выбрать значение и область действия

Лимит должен покрывать ожидаемый размер запроса, а не просто быть «очень большим». Форма с файлом может передавать вместе с ним дополнительные данные, поэтому запрос иногда немного больше самого файла. При этом значение лимита не является резервированием памяти такого объёма на каждый запрос: поведение зависит и от буферизации, и от остальной конфигурации.

Для одного сайта разумная отправная точка — лимит на уровне server; для специально выделенного маршрута — на уровне location. Общий лимит в http удобен, но может невольно разрешить крупные запросы сайтам, которым они не нужны.

Увеличить лимит Nginx — не то же самое, что обеспечить загрузку файла. Запрос должен пройти все ограничения по пути до приложения и обратно.

Почему 413 может остаться после изменения

Ограничение стоит в другом месте

Значение в location может переопределять ожидаемое поведение. И наоборот: вы могли изменить конфигурацию не того виртуального хоста или файла, который реально подключён. Сверьте домен, маршрут, активную конфигурацию и результат nginx -t.

Отказывает приложение или промежуточный узел

У фреймворка, приложения, балансировщика или CDN может быть свой лимит. Сравните журналы: если в журнале Nginx нет отказа, а приложение получает запрос, ищите ограничение дальше по цепочке. Если запрос не доходит до Nginx, проверьте узлы перед ним.

Лимит запросов путают с буферизацией

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

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

Что проверить после настройки

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

Учитывайте производственную нагрузку. Одновременные загрузки создают сетевой трафик, занимают соединения и могут влиять на место для временных файлов и возможности приложения. Наблюдайте за временем загрузки, числом одновременных запросов, свободным диском и ошибками upstream-сервиса. Не используйте значение 0 как способ «разрешить большие файлы»: в Nginx оно отключает проверку размера тела запроса.

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

После настройки составьте короткую карту пути загрузки: CDN или балансировщик, Nginx, приложение, хранилище. Для каждого звена запишите действующий лимит и ответственного за него. Затем проверьте загрузку на граничном размере и под параллельными запросами. Отдельная тема — возобновляемая загрузка больших файлов: один только client_max_body_size её не реализует.