VPS для FastAPI: uvicorn и gunicorn workers

FastAPI — асинхронный фреймворк на ASGI. Для production его запускают через uvicorn, а для использования всех ядер — под gunicorn с uvicorn-воркерами. Разберём деплой, systemd, nginx и подбор числа воркеров.

ASGI, uvicorn и gunicorn

FastAPI построен на ASGI — асинхронном стандарте, который позволяет эффективно обслуживать множество одновременных соединений. Запускает приложение ASGI-сервер, чаще всего uvicorn.

Один процесс uvicorn использует одно ядро. Чтобы задействовать все ядра, uvicorn запускают как воркеры под управлением gunicorn: gunicorn держит пул процессов, каждый из которых — асинхронный uvicorn-воркер.

• uvicorn — быстрый ASGI-сервер.
• gunicorn + UvicornWorker — несколько ядер под нагрузкой.
• async — много соединений при малом числе процессов.

Установка и окружение

Создаём виртуальное окружение и ставим FastAPI со связкой серверов.

sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx
sudo mkdir -p /opt/fastapi && cd /opt/fastapi
python3 -m venv venv
source venv/bin/activate
pip install fastapi "uvicorn[standard]" gunicorn

Минимальное приложение для проверки:

# main.py
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def root():
    return {"status": "ok"}

Проверка через uvicorn

Перед настройкой systemd убедитесь, что приложение поднимается. Для production не используйте флаг --reload.

uvicorn main:app --host 127.0.0.1 --port 8000
curl http://127.0.0.1:8000/

Одиночный uvicorn годится для теста, но на боевой нагрузке лучше запускать его воркерами под gunicorn. Если у вас Python 3.11+ и не нужен gunicorn, свежие версии uvicorn умеют сами разводить несколько воркеров флагом --workers, но менеджер процессов gunicorn всё же надёжнее для graceful-рестартов.

uvicorn main:app --host 127.0.0.1 --port 8000 --workers 4

gunicorn с uvicorn-воркерами под systemd

Ключевой класс воркера — uvicorn.workers.UvicornWorker. Число воркеров подбирают по ядрам: разумный старт — 2 × ядра + 1.

[Unit]
Description=FastAPI via gunicorn
After=network.target

[Service]
User=appuser
WorkingDirectory=/opt/fastapi
ExecStart=/opt/fastapi/venv/bin/gunicorn main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind unix:/opt/fastapi/fastapi.sock
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now fastapi
journalctl -u fastapi -f

Если приложение выполняет тяжёлые синхронные операции — обращение к внешнему API или CPU-bound вычисления, — выносите их из основного event loop через run_in_executor или отдельную очередь задач. Иначе один медленный вызов заблокирует весь асинхронный воркер и уронит пропускную способность.

nginx и TLS

nginx проксирует запросы в сокет. Для FastAPI важно пробросить заголовки и включить keepalive для производительности.

server {
    listen 80;
    server_name api.example.com;
    location / {
        proxy_pass http://unix:/opt/fastapi/fastapi.sock;
        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;
    }
}

sudo nginx -t && sudo systemctl reload nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.example.com

Подбор воркеров, железо и ошибки

Число воркеров стоит соотносить с ядрами и характером нагрузки: для CPU-bound задач больше процессов, для I/O-bound хватает async в одном воркере. AMD EPYC + NVMe у MAATRIX дают высокую производительность на ядро — а значит меньше воркеров при той же пропускной способности. Тарифы от $8/мес, локации UK/США/РФ и оплата из России (карта РФ, СБП, крипта, MAAT) удобны для API-сервисов.

• --reload на проде — лишний рестарт и утечки, флаг только для разработки.
• Обычный воркер вместо UvicornWorker — gunicorn не поймёт ASGI-приложение.
• Слишком много воркеров — конкуренция за CPU и рост потребления RAM.
• Блокирующий код в async — один медленный вызов тормозит весь event loop.

Частые вопросы