Перейти к содержимому

Статья 55 из 141

Гайды

Как развернуть FastAPI на VPS: Uvicorn, Gunicorn, systemd и Nginx с HTTPS

Встроенный сервер разработки FastAPI (fastapi dev) не подходит для работы в интернете. На сервере приложение запускают так: Uvicorn с несколькими воркерами слушает только локальный порт, systemd следит за процессом, а Nginx принимает HTTPS и передаёт запросы приложению.

Схема проверена на Ubuntu 24.04 с Python 3.12, FastAPI 0.164, Uvicorn 0.54 и Gunicorn 27 (ноябрь 2026).

Ресурс Минимум Комментарий
vCPU 1 число воркеров обычно равно числу ядер
RAM 1 ГБ простой API с двумя воркерами занял около 80 МБ
Диск 10 ГБ код, venv, логи
Домен api.example.com A-запись на IP сервера (DNS)

Подключитесь к серверу по SSH.

Окно терминала
apt update
apt install -y python3 python3-venv python3-pip git nginx certbot python3-certbot-nginx

Приложение не должно работать от root. Создайте системного пользователя без пароля и без входа в shell:

Окно терминала
adduser --system --group --home /srv/fastapi --shell /usr/sbin/nologin fastapi

Склонируйте код в /srv/fastapi/app и передайте каталог пользователю:

Окно терминала
git clone https://github.com/ваш_аккаунт/ваш_проект.git /srv/fastapi/app
chown -R fastapi:fastapi /srv/fastapi

Для примера ниже используется минимальное приложение main.py:

import os
from fastapi import FastAPI, Request
app = FastAPI(title=os.getenv("APP_NAME", "myapp"))
@app.get("/")
def root(request: Request):
return {"app": app.title, "client": request.client.host, "scheme": request.url.scheme}
@app.get("/health")
def health():
return {"status": "ok"}

В requirements.txt должны быть как минимум:

fastapi
uvicorn[standard]

Создайте venv от имени пользователя приложения и установите зависимости:

Окно терминала
cd /srv/fastapi/app
sudo -u fastapi python3 -m venv .venv
sudo -u fastapi .venv/bin/pip install --upgrade pip
sudo -u fastapi .venv/bin/pip install -r requirements.txt

Секреты храните в файле /srv/fastapi/app/.env, а не в коде:

APP_NAME=myapp
DATABASE_URL=postgresql://myapp:ДЛИННЫЙ_ПАРОЛЬ@127.0.0.1:5432/myapp
SECRET_KEY=СЛУЧАЙНАЯ_СТРОКА
Окно терминала
chmod 600 /srv/fastapi/app/.env
chown fastapi:fastapi /srv/fastapi/app/.env
echo ".env" >> /srv/fastapi/app/.gitignore

systemd прочитает этот файл сам, и переменные будут доступны через os.getenv(). Кавычки и export в файле не нужны.

Создайте /etc/systemd/system/fastapi.service:

[Unit]
Description=FastAPI app
After=network.target
[Service]
User=fastapi
Group=fastapi
WorkingDirectory=/srv/fastapi/app
EnvironmentFile=/srv/fastapi/app/.env
ExecStart=/srv/fastapi/app/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 --workers 2 --proxy-headers
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
  • --host 127.0.0.1 закрывает порт 8000 снаружи. Доступ будет только через Nginx.
  • --workers 2 запускает два процесса. Начните с числа ядер vCPU.
  • --proxy-headers разрешает читать X-Forwarded-For и X-Forwarded-Proto. По умолчанию Uvicorn доверяет этим заголовкам только от 127.0.0.1, то есть от Nginx на этом же сервере.
Окно терминала
systemctl daemon-reload
systemctl enable --now fastapi
systemctl status fastapi

Результат на тестовом сервере:

● fastapi.service - FastAPI app
Loaded: loaded (/etc/systemd/system/fastapi.service; enabled; preset: enabled)
Active: active (running) since Wed 2026-11-18 15:09:49 UTC; 4s ago
Main PID: 2664 (uvicorn)
Memory: 81.5M (peak: 82.0M)

Проверьте ответ локально:

Окно терминала
curl http://127.0.0.1:8000/health
{"status":"ok"}

Gunicorn удобен, если нужны его настройки: таймауты, перезапуск воркеров после N запросов, плавная перезагрузка по HUP. Модуль uvicorn.workers устарел, используйте отдельный пакет uvicorn-worker:

Окно терминала
sudo -u fastapi .venv/bin/pip install gunicorn uvicorn-worker

Строка запуска в сервисе:

ExecStart=/srv/fastapi/app/.venv/bin/gunicorn main:app -k uvicorn_worker.UvicornWorker -w 3 -b 127.0.0.1:8000 --forwarded-allow-ips 127.0.0.1 --access-logfile -

Проверено: Gunicorn 27.0.1 с uvicorn-worker 0.4.0 поднимает три воркера и отвечает через Nginx.

Создайте /etc/nginx/sites-available/fastapi:

server {
listen 80;
server_name api.example.com;
client_max_body_size 20M;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
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;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}

Заголовки Upgrade и Connection нужны, если приложение использует WebSocket.

Окно терминала
ln -s /etc/nginx/sites-available/fastapi /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx
curl -H "Host: api.example.com" http://127.0.0.1/
{"app":"myapp","client":"127.0.0.1","scheme":"http"}

Подробнее о Nginx: Nginx на VPS.

Окно терминала
certbot --nginx -d api.example.com

Certbot сам добавит в конфиг блок с сертификатом и редирект с HTTP. После этого request.url.scheme в приложении станет https, а в request.client.host будет IP посетителя. Подробнее: Let’s Encrypt и Certbot.

Откройте https://api.example.com/docs, чтобы проверить Swagger UI. Если документация API не должна быть публичной, отключите её: FastAPI(docs_url=None, redoc_url=None).

Uvicorn пишет в stdout, systemd сохраняет это в журнал:

Окно терминала
journalctl -u fastapi -f # в реальном времени
journalctl -u fastapi --since "1 hour ago"
journalctl -u fastapi -p err # только ошибки

Пример записи о запросе:

Nov 18 15:09:53 server uvicorn[2668]: INFO: 127.0.0.1:33166 - "GET /health HTTP/1.1" 200 OK

Журнал Nginx лежит в /var/log/nginx/access.log и /var/log/nginx/error.log.

Окно терминала
cd /srv/fastapi/app
sudo -u fastapi git pull
sudo -u fastapi .venv/bin/pip install -r requirements.txt
systemctl restart fastapi

Если используете миграции Alembic, выполните их перед перезапуском: sudo -u fastapi .venv/bin/alembic upgrade head.

  • Откройте в файрволе только 22, 80 и 443. Порт 8000 наружу не нужен.
  • Базу данных держите на 127.0.0.1: PostgreSQL.
  • Сохраняйте .env и дамп базы за пределами сервера: бэкапы.
Симптом Причина и решение
502 Bad Gateway в Nginx сервис не запущен или слушает другой порт: systemctl status fastapi, ss -ltnp | grep 8000
Сервис перезапускается по кругу ошибка импорта или нет зависимости: journalctl -u fastapi -n 50
ModuleNotFoundError: No module named 'main' неверный WorkingDirectory или имя модуля в main:app
Редиректы ведут на http:// Nginx не передаёт X-Forwarded-Proto или Uvicorn запущен без --proxy-headers
В логах IP всегда 127.0.0.1 то же самое: проверьте заголовки в Nginx и --forwarded-allow-ips у Gunicorn
--reload и --workers не работают вместе это ожидаемо: --reload нужен только при разработке