</>
halfcoder

Гайды

Деплой FastAPI: Docker, Nginx и healthchecks

Dockerfile и workers, compose, reverse proxy с TLS, proxy headers, liveness/readiness и логи.

~10 мин чтения

BackendPythonFastAPIДеплойDockerNginx

Деплой FastAPI: Docker, Nginx и healthchecks

Типичный прод: Docker-образ с приложением, uvicorn (или gunicorn + uvicorn workers) за Nginx как reverse proxy с TLS и лимитами. См. также CORS и лимиты запросов и Быстрый старт с FastAPI.

1. Dockerfile (одностадийный пример)

dockerfile
FROM python:3.12-slim

WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1

RUN pip install --no-cache-dir uvicorn fastapi pydantic-settings

COPY . .
# pip install -r requirements.txt при наличии

EXPOSE 8000
USER nobody
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

--workers — несколько процессов; каждый со своим event loop. Подбирайте под CPU. Для async часто 1–2× ядра; профилируйте.

2. Multi-stage (кратко)

Стадия builder: pip wheel в каталог. Стадия runtime: только wheels + slim image — меньше attack surface.

3. docker-compose

yaml
services:
  api:
    build: .
    env_file: .env
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata: {}

Не коммитьте секреты; в проде — secrets orchestrator.

4. Nginx: reverse proxy

nginx
upstream api {
    server api:8000;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/ssl/fullchain.pem;
    ssl_certificate_key /etc/ssl/privkey.pem;

    client_max_body_size 5m;

    location / {
        proxy_pass http://api;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

Запускайте uvicorn с --proxy-headers и --forwarded-allow-ips (или настройка Uvicorn) чтобы request.client и схемы URL были корректны.

5. WebSockets

Nginx:

nginx
location /ws/ {
    proxy_pass http://api;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Практический разбор — WebSockets и чат на FastAPI; официально — раздел FastAPI.

6. Health для оркестратора

python
from fastapi import Request

@app.get("/health/live")
def liveness():
    return {"ok": True}

@app.get("/health/ready")
async def readiness(request: Request):
    pool = request.app.state.db  # пул asyncpg из lifespan
    await pool.execute("SELECT 1")
    return {"ok": True}

Liveness не должен ходить в БД; readiness — да. Пул и lifespan — в гайде по asyncpg.

7. Логи

Структурированный JSON в stdout → сборщик (Loki, CloudWatch). Уровень логирования через env.

8. Чек-лист

  • Несколько worker'ов или горизонтальный scale + sticky sessions только если нужно.
  • TLS на границе; внутри кластера mTLS по политике.
  • Таймауты proxy согласованы с долгими запросами.
  • Образ не под root.

Дальше: asyncpg · тег Docker