Nginx для Django и FastAPI: что выбрать на практике

Nginx не выбирает между Django и FastAPI: он принимает HTTP-запросы и передаёт их приложению. Разница начинается за прокси — Django часто запускают через WSGI-сервер, FastAPI работает как ASGI-приложение, а WebSocket и долгие соединения требуют отдельного внимания. Ниже — два рабочих шаблона для Nginx 1.24 и новее и критерии, по которым выбрать нужный.

Сначала определите, что именно принимает запрос

В конфигурации Nginx важно не название веб-фреймворка, а адрес и протокол сервера приложения. Для Django это может быть WSGI-сервер, например Gunicorn, или ASGI-сервер. FastAPI обычно обслуживает ASGI-сервер. Nginx в обоих случаях проксирует HTTP-запросы, но сам по себе не превращает WSGI в ASGI и не запускает Python-код.

Примеры ниже предполагают, что приложение слушает локальный порт 8000, а TLS уже настроен на Nginx или завершается перед ним. Если у вас Unix-сокет, контейнерная сеть или отдельный балансировщик, замените адрес upstream на свой. Не открывайте порт приложения наружу, если доступ к нему должен идти только через Nginx.

• Django через WSGI: подходит для обычных HTTP-страниц и API, если приложение не требует ASGI-возможностей.
• FastAPI через ASGI: штатный путь для асинхронных обработчиков, потоковых ответов и WebSocket.
• Django через ASGI: уместен, если проекту действительно нужны асинхронные возможности Django; наличие ASGI-сервера само по себе не делает синхронный код асинхронным.

Для Nginx Django и FastAPI чаще отличаются не настройкой прокси, а тем, что происходит после передачи запроса: какой сервер принимает его и какие протоколы поддерживает приложение.

Два базовых варианта проксирования

Django: WSGI-сервер за Nginx

Обычная схема для Django — Nginx принимает запрос, а WSGI-сервер обслуживает приложение на внутреннем адресе. В примере ниже upstream указан как localhost:8000; его нужно согласовать с фактическим запуском сервера.

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Заголовок Host помогает приложению получить исходное имя хоста, а X-Forwarded-Proto передаёт схему внешнего запроса. Если TLS завершается на другом прокси, схема в этой конфигурации может быть не HTTPS: тогда передавайте фактическое значение от доверенного балансировщика и настройте доверие к прокси на стороне приложения. Не доверяйте таким заголовкам от произвольных клиентов.

FastAPI: ASGI-сервер за Nginx

Для FastAPI базовая конфигурация почти та же. Поменяется не Nginx, а команда запуска и сервер приложения: ASGI-приложение должно быть запущено сервером, который умеет его обслуживать. Не направляйте Nginx на порт, где приложение не слушает HTTP.

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Само проксирование HTTP не требует отдельного набора директив из-за того, что приложение написано на FastAPI. Отличия проявляются на длинных запросах, потоковой передаче и WebSocket. Для них проверьте таймауты, буферизацию и передачу Upgrade-заголовков по документации вашего ASGI-сервера и Nginx. Не копируйте настройки таймаутов из чужого проекта: допустимая длительность запроса зависит от продукта и нагрузки.

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

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

Когда конфигурация начинает ломаться

Самые частые проблемы связаны не с выбором Django или FastAPI, а с несовпадением адресов, заголовков и ожиданий приложения.

• 502 Bad Gateway. Nginx не может подключиться к upstream: приложение не запущено, слушает другой порт или недоступно из сетевого пространства контейнера. Сверьте адрес и журнал Nginx, затем проверьте доступность приложения с самого хоста или контейнера Nginx.
• Редирект зациклился или приложение считает запрос HTTP. Проверьте X-Forwarded-Proto и настройки доверия к прокси в приложении. Особенно часто ошибка возникает, когда TLS завершается не на том сервере, где работает Nginx.
• Большая загрузка получает 413 Request Entity Too Large. Запрос превышает допустимый размер тела запроса в Nginx. Увеличивайте лимит только до размера, который нужен продукту, и учитывайте ограничения приложения и хранилища.
• Долгий запрос обрывается. Сопоставьте таймауты Nginx, сервера приложения и вызываемых сервисов. Увеличение таймаута не исправит зависший обработчик и может удерживать соединения дольше.
• WebSocket не подключается. Обычного HTTP-проксирования недостаточно для корректной передачи Upgrade. Настройте передачу заголовков и проверьте, что весь путь от клиента до ASGI-приложения поддерживает WebSocket.

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

Когда что выбирать

Если у вас обычный Django-сайт без WebSocket и требований к асинхронным обработчикам, выбирайте WSGI-схему, которую уже поддерживает ваша команда и инфраструктура. Для FastAPI используйте ASGI-сервер. Для Django на ASGI переходите не ради моды, а когда конкретная функция или профиль нагрузки оправдывают дополнительную сложность.

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

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

Следующий шаг — провести тест через публичный адрес, а не только открыть порт приложения локально. Проверьте обычную страницу или API, передачу исходной схемы, загрузку файла нужного размера и, если используются, WebSocket и потоковый ответ. В проде наблюдайте за долей 502/504, временем ответа Nginx и числом занятых процессов приложения: эти показатели быстрее покажут, где именно образовалось узкое место.

Upstream — сервер или группа серверов, которым Nginx передаёт запросы. В примерах выше это приложение на 127.0.0.1:8000.