VPS-те Gunicorn және Nginx арқылы Python қосымшаларын қалай іске қосуға болады

Кірістірілген Flask сервері және uvicorn --reload әзірлеу үшін. Жалпыға ортақ VPS-те worker-лерді қайта іске қосатын, localhost-қа байланатын және TLS пен баяу клиенттерді өңдейтін кері прокси артында отыратын процесс менеджерін қалайсыз. Gunicorn — Flask пен Django үшін әдеттегі WSGI таңдауы. FastAPI Uvicorn worker класымен Gunicorn астында жұмыс істей алады. Nginx (немесе Caddy) HTTPS-ті аяқтап, 127.0.0.1:8000-ге жібереді.

Бұл нұсқаулық қайта жүктеуден аман қалатын орналасуды өтеді: жоба /srv/app-те, virtualenv, құпиялары бар .env, gunicorn.service бірлігі, Nginx сервер блогы, Let's Encrypt және шынымен grep ете алатын журнал файлдары. Сондай-ақ worker саны, тайм-ауттар және неге 502 Bad Gateway-дің дерлік ешқашан «Nginx сынған» емес екенін айтамыз — дерлік әрқашан Gunicorn жұмыс істемейді, қате сокетке байланған немесе импортта құлайды. Мысал Flask пайдаланады, команда өзгеше жерлерде FastAPI ескертпелерімен.

Неге осы стек

Gunicorn worker процестерін алдын ала fork етеді. Басқа worker класын пайдаланбасаңыз, әр worker бір уақытта бір сұрауды өңдейді. Nginx баяу клиенттерді буферлейді, worker-лер мобильді желіге байт жіберіп тұрып қалмасын. systemd қосымша өлсе қайта іске қосады. Бірге бұл жалықтыратын — түнгі сағат 3-те қалайтыныңыз осы.

• Gunicorn: тұрақты WSGI/ASGI процесс моделі
• systemd: жүктелуде бастау, құлағанда қайта іске қосу, journald журналдары
• Nginx: TLS, статикалық файлдар, сұрау өлшемі лимиттері, gzip
• venv: жүйелік Python таза қалады
• localhost байлау: қосымшаға Nginx арқылы ғана жетуге болады

Талаптар

Ubuntu 22.04/24.04-те Python 3.10+ жеткілікті. pip-ті root ретінде жүйелік site-packages-ке іске қоспаңыз. TLS үшін домен керек. Прокси ретінде Caddy-ді қаласаңыз, осы мақаладағы Gunicorn бірлігі сол күйінде қалады — тек фронтенд конфигі өзгереді (Caddy мақаласын қараңыз).

• Ubuntu 22.04 немесе 24.04 VPS
• requirements.txt немесе баламасы бар қосымшаңыз
• WSGI кіру нүктесі (Flask үшін: app:app) немесе ASGI (FastAPI үшін: uvicorn worker-лерімен app:app)
• HTTPS үшін домен A жазбасы

1-қадам: Жүйелік пакеттер, пайдаланушы және жоба каталогы

Интерактивті кіре алмайтын, кодқа ие және Gunicorn іске қосатын жүйелік пайдаланушы жасаңыз. python3-venv және құрастыру құралдарын орнату әлі де C кеңейтпелерін компиляциялайтын пакеттерде pip сәтсіздіктерін болдырмайды.

ssh root@YOUR_VPS_IP
apt update && apt -y upgrade
apt -y install python3 python3-venv python3-pip python3-dev build-essential nginx curl

adduser --system --group --home /srv/app appuser
mkdir -p /srv/app
chown appuser:appuser /srv/app

# Copy your code (example):
# rsync -a --delete ./myproject/ appuser@YOUR_VPS_IP:/srv/app/

2-қадам: Virtualenv және тәуелділіктер

Файл иелігі дұрыс болуы үшін venv-ті appuser ретінде жасаңыз. Өндірісте нұсқаларды бекітіңіз. Орнатқаннан кейін бір реттік gunicorn --check-config немесе Python импортымен қосымшаны импорттай алатыныңызды растаңыз. Мұндағы импорт қателері кейін 502 болатын сол қателер.

sudo -u appuser -H bash -lc '
cd /srv/app
python3 -m venv /srv/app/venv
/srv/app/venv/bin/pip install --upgrade pip
/srv/app/venv/bin/pip install -r /srv/app/requirements.txt gunicorn
'

# Flask example check:
sudo -u appuser -H /srv/app/venv/bin/python -c "from app import app; print('import ok')"

3-қадам: Орта файлы

SECRET_KEY немесе дерекқор URL-лерін systemd бірлігінде әлем оқитын git-ке түсетіндей қатты кодтамаңыз. EnvironmentFile пайдаланыңыз. chmod 640, иесі root, тобы appuser (немесе қаласаңыз иесі appuser).

cat >/srv/app/.env <<'EOF'
FLASK_ENV=production
SECRET_KEY=replace-with-openssl-rand-hex-32
DATABASE_URL=postgresql://app:password@127.0.0.1:5432/app
EOF
chown appuser:appuser /srv/app/.env
chmod 600 /srv/app/.env

4-қадам: Gunicorn systemd қызметі

Nginx-ті өткізіп жіберу себебіңіз болмаса, 0.0.0.0 емес, 127.0.0.1:8000-ге байлаңыз. Sync worker-лер үшін worker саны көбіне (2 x CPU) + 1; 2 vCPU VPS-те бұл 5, әр worker ауыр ML моделін жүктесе тым көп болуы мүмкін — сол кезде 2–3 пайдаланыңыз. FastAPI үшін --worker-class uvicorn.workers.UvicornWorker орнатып, uvicorn орнатыңыз. Тайм-ауттар ең баяу адал сұрауыңыздан асуы керек; 2 минуттық экспорттарыңыз болса 30 секунд емес.

cat >/etc/systemd/system/gunicorn.service <<'EOF'
[Unit]
Description=Gunicorn for the web app
After=network.target

[Service]
User=appuser
Group=appuser
WorkingDirectory=/srv/app
EnvironmentFile=/srv/app/.env
ExecStart=/srv/app/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 --timeout 60 --access-logfile - --error-logfile - app:app
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now gunicorn
systemctl status gunicorn --no-pager
ss -tulpn | grep 8000

5-қадам: Nginx кері прокси және TLS

Nginx 80/443-ті тыңдап, Gunicorn-ға прокси жасайды. Жүктеулер үшін client_max_body_size маңызды. proxy_read_timeout Gunicorn тайм-аутымен сәйкес келуі немесе одан асуы керек. Сервер блогы HTTP-де жұмыс істегеннен кейін Certbot-пен сертификат алыңыз (немесе фронтты Caddy-ге ауыстырыңыз). Төмендегі үзінді сынау үшін тек HTTP; содан кейін файлды өңдей алатын Certbot-ты іске қосыңыз.

cat >/etc/nginx/sites-available/app <<'EOF'
server {
    listen 80;
    server_name app.example.com;
    client_max_body_size 20m;

    location /static/ {
        alias /srv/app/static/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        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_read_timeout 90s;
    }
}
EOF

ln -sf /etc/nginx/sites-available/app /etc/nginx/sites-enabled/app
nginx -t && systemctl reload nginx

ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw enable

apt -y install certbot python3-certbot-nginx
certbot --nginx -d app.example.com

6-қадам: Статикалық файлдар, рұқсаттар және Flask/FastAPI ерекшеліктері

Мүмкін болса, статикалық файлдарды Nginx беруі керек; ол Gunicorn-нан жылдамырақ. Django collectstatic, кішкентай қосымшалар үшін Flask send_from_directory немесе кейін CDN. appuser ағашты оқи алуы керек. FastAPI пайдалансаңыз, venv-ке uvicorn[standard] орнатып, ExecStart-ты UvicornWorker пайдаланатындай өзгертіңіз. TCP орнына Unix сокеттерін пайдалансаңыз, proxy_pass-ті сокетке бағыттап, www-data жаза алатындай рұқсаттарды сәйкестендіріңіз.

# FastAPI ExecStart example:
# ExecStart=/srv/app/venv/bin/gunicorn -k uvicorn.workers.UvicornWorker --workers 2 --bind 127.0.0.1:8000 app:app

# Unix socket variant:
# --bind unix:/run/gunicorn/app.sock
# Nginx: proxy_pass http://unix:/run/gunicorn/app.sock:

chown -R appuser:appuser /srv/app

Worker-лер, жад және тоқтаусыз қайта жүктеулер

Sync Gunicorn worker-лері қарапайым және CPU-ы жеңіл сұрау/жауап API-лері үшін жеткілікті. Көп бір мезгілдегі баяу енгізу/шығару күтулері керек болса, gevent немесе ASGI worker ойлаңыз — өлшеңіз, болжамаңыз. Әр worker қосымшаңызды жүктейді; RAM ~= worker саны көбейтілген қосымша RSS. 300 МБ қосымшаның 8 worker-і бар 2 ГБ VPS своп жасайды және «кездейсоқ баяу» сезіледі. systemctl reload gunicorn (HUP) файлдарды орнында орналастырсаңыз worker-лерді жаңа кодпен қайта іске қоса алады; тәуелділіктер өзгерсе толық қайта іске қосу анығырақ.

# After git pull / rsync of new code:
sudo -u appuser -H /srv/app/venv/bin/pip install -r /srv/app/requirements.txt
systemctl restart gunicorn
curl -I https://app.example.com/health

502 және үнсіз құлауларды жою

502 Nginx-тің upstream-тен жарамды жауап ала алмағанын білдіреді. Бірінші команда — journalctl -u gunicorn -e. Жиі себептер: қате module:app атауы, жетіспейтін .env кілті, Postgres жұмыс істемейді, 127.0.0.1-ге байланған бірақ Nginx басқа хостта, SELinux (Ubuntu-да сирек) немесе қосымшаның тек IPv6 тыңдауы. 504 — тайм-аут. Қосымша X-Forwarded-Proto елемеліп HTTP-ге бағыттаса 301 циклдары болады.

• systemctl status gunicorn — белсенді ме?
• journalctl -u gunicorn -n 100 — ImportError, жетіспейтін env, дерекқор
• VPS-тен curl -v http://127.0.0.1:8000/ — бұл сәтсіз болса, Nginx кінәсіз
• nginx -t және error.log — upstream prematurely closed connection
• ss -tulpn | grep 8000 — ештеңе тыңдамайды
• Диск толы — worker-лер жұмбақ жолдармен құлайды

Қауіпсіздік

Қосымша ешқашан жалпыға ортақ байланбайды. Құпиялар .env-те қалады. venv пен ОС-ты патчталған ұстаңыз. Gunicorn-ды root ретінде іске қоспаңыз. Кірулерді өңдесеңіз, сессия cookie-лерін Secure және SameSite етіп, фреймворкты X-Forwarded-Proto-ға тек Nginx-тен сенетіндей баптаңыз. Кіру жолдарын Nginx-те немесе қосымшада жылдамдықпен шектеңіз.

• 127.0.0.1 немесе unix сокетіне байлаңыз
• chmod 600 .env
• systemd-де root емес User=
• Certbot немесе Caddy арқылы TLS
• Өндірісте debug режимін және автоматты қайта жүктеуді өшіріңіз

Кеңестер

• Compose және жүктеме балансирлері үшін ДҚ байланысын тексеретін /health жолын қосыңыз
• Статикалық активтерді Nginx-те cache-control тақырыбымен жіберіңіз
• Хаттар мен ауыр жұмыстар үшін бөлек worker немесе кезек пайдаланыңыз (Redis + systemd)
• requirements.txt ішінде gunicorn және uvicorn нұсқаларын бекітіңіз
• Бірінші өндірістік ауысудан бұрын снапшот алыңыз

VPS-тегі Python қосымшасы Gunicorn астында systemd қызметі ретінде жұмыс істегенде, тек localhost-қа байланғанда және TLS бар Nginx немесе Caddy арқылы жеткенде өндіріске дайын. Құпияларды EnvironmentFile-ға қойыңыз, worker-лерді блог формуласынан емес, RAM-ге қарай өлшеңіз және 502-ні алдымен Gunicorn журналынан жөндеңіз. Бұл жол репозиторийіңіз үшін құжатталғаннан кейін әр кейінгі орналастыру — rsync немесе git pull, pip install және systemctl restart gunicorn.