Как масштабировать FastAPI-приложение (Uvicorn workers, Gunicorn)?

Горизонтальное масштабирование

Основной способ масштабирования API — запуск нескольких одинаковых экземпляров FastAPI за reverse proxy или cloud load balancer. Каждый экземпляр должен быть stateless: нельзя хранить сессии, кэш, загруженные файлы или состояние WebSocket-комнат только в памяти одного процесса.

Uvicorn workers

Uvicorn может запускать несколько worker-процессов. Каждый worker имеет собственный event loop и независимо обрабатывает запросы.

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Gunicorn и Uvicorn workers

Gunicorn часто используют как process manager: он управляет жизненным циклом воркеров, перезапускает упавшие процессы и поддерживает graceful restart. В качестве worker class применяют асинхронный Uvicorn worker.

gunicorn app.main:app \
  --bind 0.0.0.0:8000 \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --access-logfile - \
  --error-logfile -

Как выбирать число workers

Формулы могут быть стартовой точкой, но окончательное число workers определяют измерениями. Нужно учитывать выделенные CPU и память контейнера, долю CPU-bound работы, число одновременных соединений, задержки внешних сервисов и лимит подключений к базе данных.

Внешнее состояние

• кэш и rate limiting — Redis или другой общий backend;

• сессии и токены — общая база или внешний identity provider;

• файлы — object storage;

• фоновые задачи — отдельная очередь и workers;

• WebSocket-сообщения между экземплярами — Redis Pub/Sub, message broker или специализированный gateway.

Production-практики

Нужны health и readiness checks, graceful shutdown, централизованные логи, метрики, трассировка и ограничение ресурсов контейнера. Также важно согласовать количество web workers с размером database connection pool: суммарное число соединений всех реплик не должно превышать возможности базы данных.

Как ответить на собеседовании

Я масштабирую FastAPI горизонтально через несколько stateless-реплик за балансировщиком. На узле могу использовать Uvicorn workers или Gunicorn с Uvicorn worker class; число процессов и пул подключений подбираю нагрузочным тестом с учётом лимитов CPU, памяти и базы. Общее состояние выношу в Redis, БД, object storage и очередь задач.