Статья 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 updateapt 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/appchown -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 должны быть как минимум:
fastapiuvicorn[standard]Создайте venv от имени пользователя приложения и установите зависимости:
cd /srv/fastapi/appsudo -u fastapi python3 -m venv .venvsudo -u fastapi .venv/bin/pip install --upgrade pipsudo -u fastapi .venv/bin/pip install -r requirements.txtПеременные окружения
Заголовок раздела «Переменные окружения»Секреты храните в файле /srv/fastapi/app/.env, а не в коде:
APP_NAME=myappDATABASE_URL=postgresql://myapp:ДЛИННЫЙ_ПАРОЛЬ@127.0.0.1:5432/myappSECRET_KEY=СЛУЧАЙНАЯ_СТРОКАchmod 600 /srv/fastapi/app/.envchown fastapi:fastapi /srv/fastapi/app/.envecho ".env" >> /srv/fastapi/app/.gitignoresystemd прочитает этот файл сам, и переменные будут доступны через os.getenv(). Кавычки и export в файле не нужны.
Сервис systemd
Заголовок раздела «Сервис systemd»Создайте /etc/systemd/system/fastapi.service:
[Unit]Description=FastAPI appAfter=network.target
[Service]User=fastapiGroup=fastapiWorkingDirectory=/srv/fastapi/appEnvironmentFile=/srv/fastapi/app/.envExecStart=/srv/fastapi/app/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 --workers 2 --proxy-headersRestart=alwaysRestartSec=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-reloadsystemctl enable --now fastapisystemctl 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
Заголовок раздела «Вариант с Gunicorn»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/defaultnginx -t && systemctl reload nginxcurl -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.comCertbot сам добавит в конфиг блок с сертификатом и редирект с 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/appsudo -u fastapi git pullsudo -u fastapi .venv/bin/pip install -r requirements.txtsystemctl 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 нужен только при разработке |