Если ты когда-нибудь пытался выкатить свой Python веб-проект в продакшен, то наверняка сталкивался с тем, что стандартный Flask или Django runserver — это так, только для локальной разработки. В проде нужен надежный WSGI сервер, который умеет крутить приложение под нагрузкой, правильно работать с процессами и не падать от первого же кривого запроса. И вот тут на сцену выходит Gunicorn — один из самых популярных WSGI серверов для Python. В этом посте расскажу, как его готовить, ставить, запускать и не облажаться.

Возможности Gunicorn

• Легко запускает любые WSGI-приложения (Flask, Django, FastAPI и т.д.).
• Работает на Unix-подобных системах (Linux, macOS, BSD).
• Мультипроцессная архитектура: можно указать сколько воркеров будет обслуживать запросы.
• Гибкая настройка через командную строку или конфиг-файл.
• Поддержка graceful reload/restart (перезапуск без дропов запросов).
• Легко интегрируется с системами типа systemd, supervisor, docker.
• Открытый исходный код: https://github.com/benoitc/gunicorn

Что требуется

• ОС: Linux (Ubuntu, CentOS, Alpine и др.), macOS, BSD (Windows не поддерживается официально, не мучайся).
• Python: 3.6+ (на момент 2024 года лучше 3.8+).
• Железо: Любой сервер, где есть несколько ядер — Gunicorn умеет их использовать. Для продакшена лучше минимум 2 CPU и 512MB+ RAM.
• Права: Обычный пользователь, root не нужен (только если хочешь слушать порт <1024).

Установка — пошаговая инструкция

1. Создай виртуальное окружение (по желанию, но очень советую):

   python3 -m venv venv
   source venv/bin/activate

2. Установи Gunicorn через pip:

   pip install gunicorn

   Проверь, что всё встало:

   gunicorn --version

3. Проверь, что у тебя есть WSGI-приложение.

   Например, для Flask:

   # app.py
   from flask import Flask
   app = Flask(__name__)
   
   @app.route("/")
   def hello():
       return "Hello, Gunicorn!"

4. Запусти Gunicorn:

   gunicorn app:app

   Здесь app:app — это имя_файла:имя_объекта (без .py).

5. Проверь, что сервер работает:

   curl http://127.0.0.1:8000/

   Должно вернуть Hello, Gunicorn!

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

Базовый запуск:

gunicorn myproject.wsgi:application

Часто используемые параметры:

• -w N — количество воркеров (обычно 2-4 x CPU ядра):
  gunicorn -w 4 app:app
• -b HOST:PORT — на каком адресе слушать:
  gunicorn -b 0.0.0.0:8000 app:app
• --reload — автоматический перезапуск при изменении кода (только для разработки!):
  gunicorn --reload app:app
• --timeout SEC — сколько ждать ответа от воркера:
  gunicorn --timeout 60 app:app
• --access-logfile - — лог запросов в stdout:
  gunicorn --access-logfile - app:app
• --daemon — запуск в фоне (демон):
  gunicorn --daemon app:app
• --pid PIDFILE — писать PID в файл:
  gunicorn --pid gunicorn.pid app:app
• -c CONFIG — указать конфиг-файл Python:
  gunicorn -c gunicorn.conf.py app:app

Все параметры: https://docs.gunicorn.org/en/stable/settings.html

Ошибки и как делать не надо

• Не запускай Gunicorn как root! Лучше используй отдельного пользователя, иначе рискуешь безопасностью.
• Не ставь Gunicorn за прямой фронт в интернет. Он не умеет отдавать статику, не защищает от DDoS, не делает SSL — ставь перед ним Nginx или Apache.
• Не ставь слишком много воркеров. Если у тебя 2 CPU, не надо запускать 16 воркеров — будет только хуже.
• Не используй —reload в проде. Это для разработки, в продакшене воркеры могут падать и перезапускаться бесконечно.
• Не храни секреты и пароли в коде. Gunicorn не виноват, но это частая ошибка.

Пример реального использования в окружении

Вот как обычно выглядит запуск Flask приложения на сервере Ubuntu c Nginx:

1. Создаём сервис systemd для Gunicorn:

   [Unit]
   Description=Gunicorn instance to serve myapp
   After=network.target
   
   [Service]
   User=www-data
   Group=www-data
   WorkingDirectory=/home/myuser/myapp
   Environment="PATH=/home/myuser/myapp/venv/bin"
   ExecStart=/home/myuser/myapp/venv/bin/gunicorn -w 4 -b unix:/home/myuser/myapp/myapp.sock app:app
   
   [Install]
   WantedBy=multi-user.target
   

2. Настраиваем Nginx на проксирование:

   server {
       listen 80;
       server_name myapp.example.com;
   
       location / {
           proxy_pass http://unix:/home/myuser/myapp/myapp.sock;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   }
   

3. Запускаем сервис:

   sudo systemctl start gunicorn
   sudo systemctl enable gunicorn
   sudo systemctl status gunicorn

Всё, теперь твое приложение работает через Gunicorn, а наружу его защищает Nginx.

Заключение

Gunicorn — это реально must-have для любого Python веб-приложения в продакшене. Легко ставится, просто настраивается, стабильно работает. Главное — не забывай про best practices: не открывай его в интернет, не запускай как root, не забывай про логи и мониторинг. И если что — всегда можно найти помощь и документацию по адресу: https://docs.gunicorn.org/en/stable/

Если есть вопросы или хочется поспорить — welcome в комменты!