Flask + Gunicorn + Nginx на Debian 12

Зачем так связка: кратко

Flask — лёгкий Python-фреймворк для веб-приложений и API. Короткий и понятный, без встроенного ORM. Отлично подходит для небольших и средних проектов.
Gunicorn — WSGI HTTP-сервер с предфорковыми рабочими процессами; распределяет нагрузку между рабочими процессами Python.
Supervisor — демон для управления фоновыми процессами; рестартует приложение при падении и даёт удобный CLI.
Nginx — надёжный обратный прокси и статический CDN; принимает внешние запросы и проксирует их к Gunicorn через UNIX-сокет или TCP.

Важно: в продакшне отключайте режим отладки (debug) в Flask и используйте отдельного пользователя для приложения.

Основной сценарий (primary intent)

Развернуть Flask-приложение на Debian 12 с Gunicorn, Supervisor и Nginx, чтобы приложение работало устойчиво, было доступно по домену и имело базовую безопасность.

Похожие варианты намерений: развернуть Flask на Debian, настроить Gunicorn с Nginx, управлять Flask через Supervisor, настроить UNIX-сокет для Flask, базовая безопасность для Flask в Debian.

Предварительные условия

Сервер с Debian 12 (Server/Desktop). Руковводство ориентировано на shell-доступ по SSH.
Непривилегированный пользователь с sudo.
Базовые знания командной строки Linux и работы с текстовыми редакторами (nano/vi).

Список задач: что вы получите

Установите Python 3, pip, venv, Nginx, Supervisor.
Создадите виртуальное окружение и установите Flask + Gunicorn.
Напишите простое приложение Flask и точку входа wsgi.py.
Настроите Supervisor для автозапуска Gunicorn через UNIX-сокет.
Настроите Nginx как обратный прокси к UNIX-сокету.
Проверите доступность через доменное имя и приведёте базовые рекомендации по безопасности и отладке.

Установка зависимостей

Обновите индекс пакетов и установите необходимые пакеты:

sudo apt update
sudo apt install python3 python3-pip python3-venv nginx supervisor

Подтвердите установку клавишей y, если потребуется.

установка зависимостей

Установите альтернативу для команды python (если нужно):

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10

Проверьте версии:

python --version
pip --version
python -m venv -v

Пример ожидаемого вывода (индикатор корректной установки Python и venv):

проверка python

Проверьте сервисы Nginx и Supervisor:

sudo systemctl is-enabled nginx
sudo systemctl status nginx
sudo systemctl is-enabled supervisor
sudo systemctl status supervisor

Если is-enabled возвращает enabled, значит служба будет запускаться при старте системы; статус active (running) подтверждает, что служба запущена.

проверка nginx

проверка supervisor

Создание проекта и виртуального окружения

Создайте каталог проекта и перейдите в него:

mkdir -p ~/testapp; cd ~/testapp

Создайте виртуальное окружение venv:

python -m venv venv

Активируйте окружение:

source venv/bin/activate

В командной строке вы увидите префикс (venv).

создание venv

Установите Flask и Gunicorn:

pip install flask gunicorn

Ожидаемый вывод установки:

установка flask gunicorn

Для выхода из venv используйте:

deactivate

Создание первого приложения Flask

Создайте файл testapp.py:

nano testapp.py

Вставьте этот код (проверенная версия):

# testapp.py
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def hello():
    return render_template('index.html')

if __name__ == "__main__":
    app.run(debug=True)

Примечание: в продакшне debug=True отключайте.

Создайте директорию шаблонов и index.html:

mkdir -p templates
nano templates/index.html

Содержимое index.html:


    
        Hello Flask - Nginx and Gunicorn Debian 12!

Запустите приложение локально (в виртуальном окружении):

flask --app testapp run

Оно слушает 127.0.0.1:5000 по умолчанию. Проверьте с другого терминала:

curl http://localhost:5000/

Если всё корректно, вы увидите исходный HTML-шаблон.

проверка flask

Интеграция с Gunicorn (WSGI)

Создайте wsgi.py рядом с testapp.py:

nano wsgi.py

Вставьте этот код:

# import testapp Flask application
from testapp import app

if __name__ == "__main__":
    app.run(debug=True)

Проверьте запуск через Gunicorn (в виртуальном окружении):

gunicorn -w 4 --bind 0.0.0.0:8080 wsgi:app

-w 4 — четыре рабочих процесса (зависит от CPU и памяти).
–bind 0.0.0.0:8080 — привязка к порту 8080 на всех интерфейсах.

Откройте http://:8080 и проверьте страницу. Завершите процесс Ctrl+C.

gunicorn run

Совет: для продакшна предпочтительнее UNIX-сокет, чтобы Nginx и Gunicorn общались локально без TCP-оверхеда.

Управление Gunicorn через Supervisor

Supervisor удобен для управления процессом Gunicorn. Приведённый ниже пример настраивается под пользователя alice и директорию /home/alice/testapp. Адаптируйте пути и пользователя под свой сервер.

Создайте конфиг Supervisor:

sudo nano /etc/supervisor/conf.d/testapp.conf

Вставьте шаблон (поменяйте user и пути):

[program:testapp]
command=/bin/bash -c 'source /home/alice/testapp/venv/bin/activate; exec gunicorn -w 3 --bind unix:/home/alice/testapp/testapp.sock wsgi:app'
directory=/home/alice/testapp
user=alice
group=www-data
autostart=true
autorestart=true
stdout_logfile=/home/alice/testapp/testapp.log
stderr_logfile=/home/alice/testapp/error.log

Важно: используйте exec перед gunicorn, чтобы Supervisor отслеживал правильный PID процесса, и указывайте абсолютные пути до виртуального окружения.

Примените конфигурацию Supervisor:

sudo systemctl restart supervisor
sudo systemctl status supervisor
sudo supervisorctl status

Ожидается, что testapp будет в состоянии RUNNING и создаст UNIX-сокет /home/alice/testapp/testapp.sock.

Проверка сокета:

ss -pl | grep testapp.sock

supervisor config

проверка supervisor apps

Конфиг Nginx как обратного прокси

Создайте блок сервера:

sudo nano /etc/nginx/sites-available/testapp

Пример конфигурации (замените server_name и пути):

server {
    listen 80;
    server_name testapp.local;

    location / {
        include proxy_params;
        proxy_pass http://unix:/home/alice/testapp/testapp.sock;
    }
}

Активируйте серверный блок и проверьте конфигурацию:

sudo ln -s /etc/nginx/sites-available/testapp /etc/nginx/sites-enabled/
sudo nginx -t

Если тест синтаксиса успешен (Syntax is OK), перезапустите Nginx:

sudo systemctl restart nginx
sudo systemctl status nginx

nginx reverse proxy

Доступ к приложению по домену

Если вы тестируете локально или в приватной сети, добавьте запись в /etc/hosts на клиентской машине:

192.168.10.15   testapp.local

После этого откройте http://testapp.local/ в браузере и проверьте страницу.

Проверка и отладка: список команд и советы

Общие проверки:

Проверить статусы сервисов:

sudo systemctl status nginx
sudo systemctl status supervisor

Просмотреть логи Supervisor и Gunicorn:

tail -n 200 /home/alice/testapp/testapp.log
tail -n 200 /home/alice/testapp/error.log
sudo journalctl -u nginx -e

Частые проблемы и решения:

502 Bad Gateway в Nginx:
- Проверьте, что Gunicorn слушает на том же сокете, что указан в proxy_pass.
- Проверьте права на сокет (владелец/группа/права).
- Проверьте, запущен ли процесс Gunicorn через supervisorctl status.
Gunicorn падает при старте:
- Проверьте виртуальное окружение и зависимости.
- Убедитесь, что в command в конфиге Supervisor используется абсолютный путь к activate и gunicorn.
Проблемы с импортом модулей:
- Проверьте, что current working directory (directory=) у Supervisor совпадает с местом, где находится wsgi:app.

Полезные команды для Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart testapp
sudo supervisorctl tail -f testapp

Альтернативный способ: systemd unit для Gunicorn

Некоторым администраторам удобнее использовать systemd вместо Supervisor. Пример systemd unit (замените пользователь и пути):

[Unit]
Description=Gunicorn instance to serve testapp
After=network.target

[Service]
User=alice
Group=www-data
WorkingDirectory=/home/alice/testapp
Environment="PATH=/home/alice/testapp/venv/bin"
ExecStart=/home/alice/testapp/venv/bin/gunicorn -w 3 --bind unix:/home/alice/testapp/testapp.sock wsgi:app

[Install]
WantedBy=multi-user.target

Сохраните как /etc/systemd/system/testapp.service и выполните:

sudo systemctl daemon-reload
sudo systemctl start testapp
sudo systemctl enable testapp
sudo systemctl status testapp

Это простой и надёжный подход, особенно когда вы хотите интегрировать сервис с systemd-триггерами и таймерами.

Контроль качества: критерии приёмки

Приложение отвечает по HTTP 200 на корневой URL через Nginx: curl -I http://testapp.local/
Nginx не возвращает 502/504 при нагрузке при типичной нагрузке тестового окружения.
Gunicorn запущен и управляется Supervisor или systemd, автозапуск включён.
Логи пишутся и ротируются, права на сокет корректны (доступ только нужным пользователям).
Debug режим в Flask отключён в продакшн-конфигурации.

Ролевые чеклисты

Разработчик:

Писать конфигурации в переменных окружения (порт, база данных, секреты).
Проверять, что debug выключён перед деплоем.
Поддерживать requirements.txt или Pipfile.

Операционный инженер (DevOps/Sysadmin):

Настроить Supervisor или systemd для автозапуска.
Настроить Nginx и TLS (Let’s Encrypt).
Настроить мониторинг (например, Prometheus/Alertmanager) и логирование.

Тестировщик:

Проверить HTTP-ответы на основных эндпоинтах.
Прогнать smoke-тесты и простую нагрузку (ab, hey, wrk).

Отказоустойчивость и масштабирование: когда это не подойдёт

Когда связка может не подойти:

Очень высоконагруженные приложения, где требуется горизонтальное масштабирование и балансировщик нагрузки уровня L4/L7 (нужна корректная архитектура с несколькими инстансами и балансировщиком перед Nginx).
Если приложение требует сложного управления процессами, контейнеризация (Docker, Kubernetes) будет предпочтительнее.

Альтернативы:

Systemd вместо Supervisor (см. раздел выше).
Использовать контейнеры и оркестрацию (Docker + Kubernetes) для большей портируемости.

Методология быстрого развёртывания (мини-подход)

Подготовка сервера: обновления, создание пользователя, базовые утилиты.
Установка Python и создание venv.
Разработка и локальное тестирование приложения.
Настройка Gunicorn и проверка работы через порт.
Настройка Supervisor/systemd и перевод на UNIX-сокет.
Настройка Nginx и проверка доступа по домену.
Настройка TLS, логирования и ротации.
Мониторинг и аварийные процедуры.

Короткая методичка по тестам и приёмке

Unit-тесты: запускать при сборке (pytest).
Smoke-тест: curl /status или / - ожидается 200.
Интеграционный тест: проверить подключение к БД (если есть) и успешный ответ на несколько ключевых запросов.
Приёмочное тестирование: нагрузочная проверка на 95-й перцентиль времени ответа приложения.

Шаблоны и примеры (сводные)

Supervisor конфиг (шаблон) — уже приведён выше. Убедитесь, что в command используется exec и абсолютные пути.

Nginx server block (шаблон) — приведён выше. Для HTTPS добавьте redirect и include /etc/letsencrypt options.

Systemd unit — пример выше.

Пример .gitignore для проекта Flask:

venv/
*.pyc
__pycache__/
instance/
.env
*.log

Отладочные сценарии и диагностическая галерея

Если Nginx отвечает 502: проверить sudo tail -n 50 /var/log/nginx/error.log, sudo supervisorctl status, права сокета.
Если Gunicorn не стартует из Supervisor: проверить stdout_logfile/stderr_logfile на ошибки импорта.
Если приложение отвечает, но медленно: снизьте число воркеров или увеличьте число (по правилу 2xCPU+1) и проведите нагрузочный тест.

Риски и смягчения

Риск: запуск в debug-режиме раскрывает отладочную панель. Смягчение: отключать debug в конфиге окружения.
Риск: неправильные права на сокет — Nginx не сможет подключиться. Смягчение: выставлять группу www-data и права 660.
Риск: отсутствие TLS — трафик незащищён. Смягчение: настроить Let’s Encrypt.

Полезные ссылки и примечания

Документация Flask: источник по API и конфигурации.
Документация Gunicorn: параметры воркеров и рекомендации по конфигурации.
Документация Nginx: проксирование и безопасность.

Заключение

Вы завершили развёртывание простого Flask-приложения на Debian 12 с Gunicorn, Supervisor и Nginx. Вы научились создавать виртуальное окружение, запускать приложение в фоновом режиме, проксировать запросы из Nginx и базово защищать сервис. Дальше можно добавить БД (MySQL/MariaDB/PostgreSQL), настроить TLS, CI/CD и мониторинг.

Важное: не используйте debug в продакшне и храните секреты вне кода (переменные окружения или секрет-менеджер).

Краткий список для следующего шага: добавить HTTPS, логирование в централизованную систему, настроить автоматические обновления зависимостей и CI.

итоговая схема развёртывания

Описание изображения: схема архитектуры развёртывания Flask с Gunicorn, Supervisor и Nginx на Debian 12, показывающая клиент, Nginx, UNIX-сокет и фоновые рабочие процессы Gunicorn.

Критерии приёмки

Приложение отвечает по домену через Nginx со статусом 200.
Supervisor или systemd запускают Gunicorn автоматически после перезагрузки.
Логи доступны оператору и ротируются.
Debug режим отключён.

Конец статьи.

Развёртывание Flask с Gunicorn, Supervisor и Nginx на Debian 12