🌍 WSGI, ASGI и серверы приложений
Django, Flask и FastAPI сами не слушают порт. Сокеты, разбор HTTP и процессы берёт на себя сервер приложений: gunicorn, uvicorn, granian. С приложением он говорит через стандартный интерфейс, WSGI или ASGI. Поэтому один и тот же FastAPI запускается под uvicorn, granian или gunicorn. Отсюда два вопроса техсекции: что происходит с запросом до твоего обработчика и почему сервис запускают четырьмя процессами, а не одним
🧠 Как это устроено
WSGI: функция на один запрос
WSGI описан в PEP 333 и обновлён для Python 3 в PEP 3333. Его придумали, чтобы любой фреймворк работал с любым сервером. Приложение здесь просто вызываемый объект с двумя аргументами:
environ— словарь с запросом в стиле CGI:REQUEST_METHOD,PATH_INFO,QUERY_STRING, заголовки какHTTP_*, тело в файлоподобномwsgi.inputstart_response(status, headers)— функция, которой приложение сообщает статус и заголовки ответа
Тело ответа приложение возвращает итерируемым объектом из байтовых строк: списком или генератором
Ключевое свойство WSGI: вызов синхронный и занимает поток, пока не вернёт ответ. Поэтому сервер держит столько одновременных запросов, сколько у него потоков и процессов. WebSocket в эту модель тоже не помещается: соединение живёт минутами, а интерфейс умеет только «получил запрос, вернул ответ»
ASGI: корутина и два канала
ASGI вырос из Django Channels и решает именно эти две проблемы. Приложение — корутина с тремя аргументами:
scope— словарь с описанием соединения:type(http,websocketилиlifespan),method,path,headersи другие поляreceive— корутина, которая отдаёт следующее входящее событие: кусок телаhttp.request, сообщение из WebSocket,http.disconnectsend— корутина, через которую приложение отправляет события:http.response.startсо статусом и заголовками, затем один или несколькоhttp.response.body
Запрос и ответ превратились в поток событий, поэтому соединение может жить сколько угодно. WebSocket здесь просто другая последовательность: websocket.connect, обмен websocket.receive и websocket.send, websocket.disconnect. Стриминг ответа — несколько send с more_body=True. А раз приложение корутина, тысячи ожидающих соединений обслуживает один event loop в одном потоке
Третий тип scope, lifespan, сервер присылает один раз на процесс: lifespan.startup до первого запроса и lifespan.shutdown при остановке. На нём держится lifespan в FastAPI, о нём следующая страница
Путь запроса от сокета до обработчика
На примере uvicorn:
- Ядро принимает TCP-соединение в очередь
listen. Её длину у uvicorn задаёт--backlog, по умолчанию 2048 - Event loop воркера (uvloop, если установлен, иначе asyncio) делает
acceptи начинает читать байты из сокета - Парсер HTTP разбирает байты в метод, путь и заголовки. Это httptools (обёртка над llhttp из Node.js, на C) или h11 на чистом Python. Выбирается флагом
--http, по умолчаниюauto: httptools, если он есть - Сервер собирает
scopeи создаёт задачу с вызовомapp(scope, receive, send) - Фреймворк внутри
appнаходит маршрут, вызывает middleware и твой обработчик, сериализует результат - Приложение вызывает
send, сервер превращает события в байты ответа и пишет их в сокет. Соединение остаётся открытым для следующего запроса, без него uvicorn закроет его через 5 секунд (--timeout-keep-alive)
Пункт 5 — код фреймворка и твой, остальное делает сервер
Какие бывают серверы
| Сервер | Что это | Интерфейсы |
|---|---|---|
| gunicorn | менеджер процессов с pre-fork: мастер следит за воркерами, перезапускает упавшие | WSGI; с версии 24 есть свой ASGI-воркер |
| uvicorn | ASGI-сервер на asyncio/uvloop, умеет запускать несколько воркеров сам | ASGI, WSGI через адаптер |
| granian | сервер на Rust (hyper и tokio), сеть обслуживают потоки Rust, Python вызывается только для приложения | ASGI, WSGI, свой RSGI |
Классическая связка — gunicorn с uvicorn-воркерами: gunicorn управляет процессами, а внутри каждого работает uvicorn со своим event loop. Запустить её можно тремя способами, и первый устарел:
-k uvicorn.workers.UvicornWorkerиз самого uvicorn. Модульuvicorn.workersобъявлен устаревшим и будет удалён: при импорте он пишетDeprecationWarningи отправляет к пакетуuvicorn-worker-k uvicorn_worker.UvicornWorkerиз отдельного пакетаuvicorn-worker, это прямая замена- без gunicorn:
uvicorn main:app --workers 4. Встроенный менеджер перезапускает упавшие воркеры и убивает зависшие
Ещё в gunicorn 24 появился собственный ASGI-воркер --worker-class asgi, с версии 25.1 он стабильный. Но в проектах и туториалах пока чаще встречается связка с uvicorn
🛠️ На практике
Минимальные приложения без фреймворка
Оба приложения читают тело и отвечают методом, путём и размером тела
Python · Минимальное WSGI-приложение
# wsgi_app.py — запуск: gunicorn wsgi_app:app -w 2
def app(environ, start_response):
size = int(environ.get("CONTENT_LENGTH") or 0)
body = environ["wsgi.input"].read(size)
text = f"{environ['REQUEST_METHOD']} {environ['PATH_INFO']} body={len(body)}B\n".encode()
start_response("200 OK", [("Content-Type", "text/plain")])
return [text]Python · Минимальное ASGI-приложение
# asgi_app.py — запуск: uvicorn asgi_app:app
async def app(scope, receive, send):
if scope["type"] != "http":
return # lifespan и websocket здесь не обрабатываем
body = b""
while True:
message = await receive() # тело может прийти несколькими кусками
body += message.get("body", b"")
if not message.get("more_body"):
break
text = f"{scope['method']} {scope['path']} body={len(body)}B\n".encode()
await send({
"type": "http.response.start",
"status": 200,
"headers": [(b"content-type", b"text/plain")],
})
await send({"type": "http.response.body", "body": text})curl -X POST -d hello localhost:8000/ordersPOST /orders body=5BТак выглядит scope для GET /orders?id=7 под uvicorn. Заголовки и строка запроса остались байтами:
{'http_version': '1.1', 'method': 'GET', 'path': '/orders', 'query_string': b'id=7',
'headers': [(b'host', b'localhost:8013'), (b'user-agent', b'curl/8.7.1'), (b'accept', b'*/*')],
'client': ('127.0.0.1', 61248)}До первого запроса приложение получило {'type': 'lifespan.startup'}. Проверено на Python 3.13, uvicorn 0.54, gunicorn 27, granian 2.8
Процессы, а не потоки: замер
В CPython байткод в каждый момент выполняет один поток процесса, это GIL, он разобран на странице «GIL и free-threading». Для веб-сервера это значит простую вещь: потоки помогают, пока обработчики ждут, и не помогают, пока считают. Четыре одновременных запроса к WSGI-приложению под gunicorn, 8 ядер:
| Конфигурация | Обработчик ждёт 0,3 с (time.sleep) | Обработчик считает ~0,2 с |
|---|---|---|
-w 1 | 1,28 с | 0,88 с |
-w 1 --threads 4 | 0,34 с | 0,88 с |
-w 4 | — | 0,26 с |
На ожидании четыре потока справились за время одного запроса. На расчёте они по очереди брали GIL, и вышло как с одним воркером. Четыре процесса посчитали параллельно: у каждого свой GIL
Реальный обработчик — смесь: разобрать JSON, сходить в базу, собрать ответ. Части «посчитать» хватает, чтобы процесс упёрся в одно ядро. Поэтому в проде сервис запускают несколькими процессами-воркерами, а потоки и корутины внутри процесса закрывают ожидание
Сколько воркеров
Единой формулы нет, есть точка старта и замер под нагрузкой:
- синхронные WSGI-воркеры: документация gunicorn предлагает начинать с
(2 × ядра) + 1, чтобы пока один воркер ждёт базу, другой считал. Там же сказано, что обычно хватает 4–12 воркеров, а лишние снижают пропускную способность - async-воркеры uvicorn: один event loop и так держит тысячи ожидающих соединений, поэтому начинают с числа ядер
- память: каждый воркер загружает приложение целиком. Восемь воркеров по 300 МБ — 2,4 ГБ ещё до первого запроса
Флаги -w у gunicorn и --workers у uvicorn по умолчанию берут значение из WEB_CONCURRENCY, без неё запускается один воркер. Как оно соотносится с лимитом CPU контейнера, разберём на странице про Python в контейнере
Django и Flask под ASGI-сервером
Django умеет оба интерфейса из коробки: в проекте есть wsgi.py и asgi.py. Под ASGI асинхронные view работают в event loop и держат сотни соединений без потоков, становятся возможны long-polling и WebSocket через Channels. Синхронные view и middleware Django запускает в потоке через sync_to_async, каждый переход стоит десятки микросекунд. Поэтому документация Django советует включать ASGI, только если в проекте есть асинхронный код. Границы async ORM разобраны на странице про Django и DRF
Flask — WSGI-фреймворк. Под ASGI-сервер его заворачивают в адаптер, документация Flask рекомендует asgiref.wsgi.WsgiToAsgi. Uvicorn умеет то же через --interface wsgi и берёт пакет a2wsgi, если он установлен. Без него включается встроенная обёртка, а она устарела. Каждый запрос всё равно занимает поток в пуле адаптера, так что ускорения нет: это способ запустить старое приложение на том же сервере, что и новое
Reverse proxy перед uvicorn
В проде между интернетом и uvicorn обычно стоит nginx (или балансировщик облака, Ingress в Kubernetes). Он берёт на себя то, что Python-серверу делать невыгодно:
- принимает TLS и HTTP/2 от клиентов, а к воркерам ходит по HTTP/1.1 на localhost или через Unix-сокет (uvicorn:
--uds /run/app.sock) - буферизует медленных клиентов. Телефон на плохом 3G отправляет тело запроса десять секунд, и синхронный воркер gunicorn всё это время занят. Nginx дочитает тело сам и отдаст воркеру целиком
- отдаёт статику, ограничивает размер тела и частоту запросов, распределяет нагрузку между несколькими инстансами
У прокси есть цена: приложение видит адрес nginx, а не клиента, и http вместо https. Nginx передаёт настоящие значения в X-Forwarded-For и X-Forwarded-Proto. Uvicorn читает их только от доверенных адресов из --forwarded-allow-ips, по умолчанию это 127.0.0.1 и ::1. Nginx в соседнем контейнере приходит с другого адреса, и без него в списке rate limit по IP забанит всех пользователей разом. "*" доверяет всем, его ставят, только если прокси затирает эти заголовки от клиента
⚠️ Где ошибаются
Ставить много потоков на CPU-тяжёлый сервис. --threads 16 в одном воркере выглядит как 16-кратный запас, но на расчётах потоки не ускоряют, это видно в замере выше. Параллелизм по CPU дают процессы
Копировать uvicorn.workers.UvicornWorker из старого туториала. Работает, но модуль устарел и будет удалён. Замена — пакет uvicorn-worker с классом uvicorn_worker.UvicornWorker или встроенный uvicorn --workers
Держать в памяти воркера состояние, общее для всех запросов. Счётчик или кэш словарём в глобальной переменной расходятся между воркерами: у каждого процесса своя копия. На одном воркере в разработке всё сходится, на четырёх в проде нет. Общее состояние держат в Redis или базе
Открыть пул соединений к базе при импорте модуля. С --preload gunicorn импортирует приложение один раз в мастере до fork, и сокеты пула достаются всем воркерам сразу: несколько процессов пишут в одно соединение и могут получить чужой ответ. Uvicorn стартует воркеры через spawn, там каждый процесс импортирует всё заново. Надёжное место для пула одно: событие lifespan startup внутри каждого воркера
🎯 Вопросы с собеседований
Что такое WSGI и ASGI, зачем uvicorn и gunicorn
Это интерфейсы между сервером приложений и фреймворком. В WSGI приложение — синхронная функция app(environ, start_response), которая занимает поток до конца ответа. В ASGI это корутина app(scope, receive, send), запрос и ответ идут событиями, поэтому работают WebSocket и тысячи ожидающих соединений в одном event loop. Сервер берёт на себя сокеты, разбор HTTP и процессы. Gunicorn — менеджер процессов с pre-fork для WSGI. Uvicorn — ASGI-сервер на asyncio. Их часто связывают: gunicorn управляет процессами, внутри каждого работает uvicorn-воркер. Сейчас для этого берут пакет uvicorn-worker или просто uvicorn --workers, старый uvicorn.workers устарел
Почему для параллелизма запускают несколько процессов, а не потоки, и как выбрать число воркеров
Из-за GIL потоки одного процесса не выполняют Python-код параллельно: на ожидании базы они помогают, на разборе JSON упираются в одно ядро. Каждый процесс получает свой интерпретатор и свой GIL, поэтому N процессов используют N ядер. Для синхронных воркеров gunicorn стартовая точка (2 × ядра) + 1. Для async-воркеров начинают с числа ядер, потому что один event loop и так держит много соединений. Дальше число подбирают нагрузочным тестом и смотрят на память: каждый воркер грузит приложение целиком
Можно ли запустить Django или Flask под ASGI-сервером и что это даст
Django — да, у него есть asgi.py. Выигрыш будет, только если есть асинхронные view: они держат много соединений без потоков, появляются long-polling и WebSocket через Channels. Синхронные view под ASGI выполняются в потоке через sync_to_async, это накладные расходы без пользы, поэтому полностью синхронный проект оставляют на WSGI. Flask — WSGI-фреймворк, его заворачивают в адаптер WsgiToAsgi из asgiref или запускают через uvicorn --interface wsgi с установленным a2wsgi. Каждый запрос всё равно занимает поток, ускорения это не даст
Что такое reverse proxy перед uvicorn и зачем он
Это сервер вроде nginx, который принимает запросы клиентов и пересылает их воркерам. Он терминирует TLS, отдаёт статику, режет большие тела и частые запросы, балансирует между инстансами. Главное для Python: он буферизует медленных клиентов, и воркер получает запрос целиком, а не ждёт его десять секунд по 3G. Цена — приложение видит адрес прокси, поэтому nginx передаёт X-Forwarded-For и X-Forwarded-Proto, а в uvicorn адрес прокси добавляют в --forwarded-allow-ips
Чем granian отличается от uvicorn
Granian написан на Rust поверх hyper и tokio: сеть и разбор HTTP идут в потоках Rust, Python вызывается только для приложения. Uvicorn делает это в Python на asyncio или uvloop. В granian из коробки есть HTTP/2, менеджер воркеров с перезапуском и собственный интерфейс RSGI рядом с ASGI и WSGI. Платишь тем, что это не чистый Python: отладка сложнее, часть расширений ASGI не реализована, trio и gevent не поддерживаются. Разница в скорости видна на лёгких эндпоинтах, а когда время уходит на базу, она тонет в ожидании
📚 Что почитать
- PEP 3333 — спецификация WSGI:
environ,start_responseи правила для итерируемого ответа - ASGI: HTTP & WebSocket — все ключи scope и типы событий, плюс таблица соответствия с WSGI
- Uvicorn: Deployment — встроенные воркеры, gunicorn через
uvicorn-worker, пример конфига nginx и заголовки прокси - Django: Asynchronous support — что происходит с sync и async view под WSGI и ASGI и сколько стоит переход между ними