Запуск FastAPI с помощью Uvicorn: настройка и деплой сервера

Раздел: Деплой -> Запуск сервера

Основные способы запуска FastAPI через Uvicorn

Оптимальное решение: простая команда uvicorn

Самым эффективным способом запуска FastAPI-приложения является выполнение команды uvicorn main:app --host 0.0.0.0 --port 8000. Здесь main - имя файла (без расширения .py), а app - экземпляр FastAPI. Параметр --host 0.0.0.0 делает сервер доступным из сети, --port 8000 задаёт порт. После запуска приложение будет принимать запросы по адресу http://0.0.0.0:8000.

uvicorn main:app --host 0.0.0.0 --port 8000

Python uvicorn fastapi (запуск fastapi с помощью uvicorn)

Эта команда подходит для большинства случаев локальной разработки и простого деплоя.

Как сделать автоматическую перезагрузку при изменении кода?

Для разработки удобно использовать флаг --reload. В этом случае Uvicorn будет отслеживать изменения в файлах проекта и перезапускать сервер автоматически.

uvicorn main:app --reload

Примечание: следует избегать использования --reload в production-среде, так как это снижает производительность.

Как изменить хост и порт для доступа извне?

Параметры --host и --port позволяют явно указать адрес и порт. Значение 0.0.0.0 открывает доступ для всех сетевых интерфейсов.

uvicorn main:app --host 0.0.0.0 --port 8080

Как запустить приложение из Python-скрипта (не через командную строку)?

Можно использовать вызов uvicorn.run() внутри Python-кода. Это особенно удобно, когда нужно передавать параметры динамически или запускать несколько приложений.

from uvicorn import run
from main import app

if __name__ == "__main__":
    run(app, host="0.0.0.0", port=8000, reload=True)

Как объединить Uvicorn с Gunicorn для многопроцессорного запуска?

Gunicorn выступает менеджером процессов, а Uvicorn используется в качестве воркера. Это даёт возможность масштабировать приложение на несколько ядер CPU.

gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000

Ключ -w задаёт количество воркеров (процессов).

Как запустить FastAPI в Docker-контейнере?

В Dockerfile команда запуска указывается в инструкции CMD. Пример для production:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Типичные ошибки и их решение

Ошибка: Address already in use - порт уже занят. Решение: сменить порт или завершить процесс, использующий его (kill в Linux, netstat -ano в Windows).

Ошибка: ModuleNotFoundError: No module named 'uvicorn' - не установлен Uvicorn. Решение: выполнить pip install uvicorn.

Ошибка: Can't connect to server - сервер не отвечает. Возможные причины: хост указан как 127.0.0.1 (только локальный доступ), брандмауэр блокирует порт, приложение не импортируется корректно. Проверить имя модуля и экземпляра FastAPI.

Расширенные примеры запуска Uvicorn с FastAPI

1. Запуск с отладкой и детальными логами

Флаг --log-level debug включает подробное логирование, а --access-log выводит информацию о каждом запросе.

Пример 
uvicorn main:app --reload --log-level debug --access-log
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
DEBUG:    Loaded ASGI app in 0.002s
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
DEBUG:    Application startup complete.

2. Ограничение перезагрузки конкретной директорией

Параметр --reload-dir указывает, за какой папкой следить. Это полезно, когда проект содержит статические файлы, изменения которых не требуют перезапуска.

Пример 
uvicorn main:app --reload --reload-dir ./app

3. Запуск с поддержкой HTTPS (SSL)

Для этого понадобятся файлы сертификата и ключа. Пример:

Пример 
uvicorn main:app --ssl-keyfile ./key.pem --ssl-certfile ./cert.pem --host 0.0.0.0 --port 443

4. Настройка таймаутов соединения и завершения

Параметр --timeout-keep-alive задаёт время удержания keep-alive соединения (по умолчанию 5 секунд). --timeout-graceful-shutdown - время на завершение текущих запросов при остановке.

Пример 
uvicorn main:app --timeout-keep-alive 30 --timeout-graceful-shutdown 10

5. Многопроцессорный запуск с помощью --workers

Uvicorn может запускать несколько рабочих процессов без Gunicorn. Рекомендуется для сред с одним приложением.

Пример 
uvicorn main:app --workers 4

Важно: при использовании --workers не следует одновременно указывать --reload.

6. Запуск через python -m uvicorn

Эквивалентный вызов с использованием модуля Python:

Пример 
python -m uvicorn main:app --host 0.0.0.0

7. Интеграция с Docker Compose

Файл docker-compose.yml позволяет задать переменные окружения и упростить деплой.

Пример 
version: '3.8'
services:
  fastapi-app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - UVICORN_HOST=0.0.0.0
      - UVICORN_PORT=8000
    command: uvicorn main:app --host 0.0.0.0 --port 8000

8. Запуск через uvicorn.run() с полным набором параметров

Пример 
from uvicorn import run
from main import app

if __name__ == "__main__":
    run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True,
        log_level="info",
        workers=2,
        ssl_keyfile="./key.pem",
        ssl_certfile="./cert.pem"
    )

9. Запуск двух экземпляров на разных портах

Например, для A/B тестирования или разделения версий API:

Пример 
uvicorn main:app --port 8000
uvicorn main:app --port 8001
Два процесса Uvicorn, обслуживающие одно и то же приложение на разных портах.

10. Использование переменных окружения для конфигурации

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

Пример 
import os
from uvicorn import run
from main import app

if __name__ == "__main__":
    host = os.getenv("UVICORN_HOST", "0.0.0.0")
    port = int(os.getenv("UVICORN_PORT", "8000"))
    run(app, host=host, port=port)

Результат: приложение запускается с параметрами, заданными через переменные окружения.

Запуск FastAPI с помощью Uvicorn - comments

En
Python uvicorn fastapi (python)