Blog’a Dön

Python Uygulamasını Sunucuda Yayınlama: Gunicorn ve Nginx

Python uygulaması sunucuya nasıl yüklenir? Flask ve Django için venv, Gunicorn, systemd servisi, Nginx, statik dosyalar, HTTPS, güncelleme ve sık hatalar.

Nodesty Ekibi6 dk okumaSunucular
Koyu Nodesty arka planında Python Deploy yazısı ile Gunicorn, Nginx ve systemd ifadeleri

Bir Python uygulamasını sunucuya yüklemek, örneğin Flask ya da Django projenizi yayına almak, geliştirme sunucusunu çalıştırmaktan fazlasını ister: Bağımlılıklar için bir sanal ortam, uygulama sunucusu olarak Gunicorn, onu ayakta tutan systemd ve önünde HTTPS ile statik dosyalardan sorumlu Nginx. Bu yapı bir kez kurulduğunda her güncelleme birkaç komuta iner.

Bu rehberde temiz bir Ubuntu sunucuda Flask ya da Django uygulamasını yayınlamayı anlatıyoruz: Sunucuyu hazırlamak, Gunicorn'u test etmek, systemd servisini yazmak, Nginx'i yapılandırmak, Django üretim ayarları, HTTPS, güncellemeler ve en sık karşılaşılan hatalar.

Gereksinimler

  • Sunucu: Root erişimli bir Ubuntu sunucu. Bu rehberde Ubuntu 24.04 kullanıyoruz.
  • Uygulama: Git deposunda duran ve requirements.txt dosyası olan bir Flask ya da Django projesi.
  • Veritabanı: Uygulamanız kullanıyorsa PostgreSQL kurulumu rehberimize bakın.
  • Alan adı: Sunucunuzun IP adresini gösteren bir A kaydı.

1. Adım: Python, venv ve Nginx

Sunucunuza SSH ile bağlandıktan sonra:

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

AlmaLinux'ta karşılığı sudo dnf install python3 python3-pip nginx git komutudur; orada venv modülü python3 ile birlikte gelir. Nginx, www-data yerine nginx kullanıcısıyla çalışır ve site dosyaları /etc/nginx/conf.d/ klasörüne konur. Temel bilgiler için Nginx kurulumu rehberimize bakın.

2. Adım: Kullanıcı, kod ve sanal ortam

Uygulamayı root olarak çalıştırmayın. Onun için bir kullanıcı, /srv altında bir klasör ve içinde bir sanal ortam oluşturun:

sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /srv/app
sudo chown deploy:deploy /srv/app
sudo -iu deploy
git clone git@github.com:user/app.git /srv/app
cd /srv/app
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt gunicorn

Sanal ortam paketlerinizi sistemin Python'undan ayrı tutar; Ubuntu 24.04 zaten venv dışında pip install komutunu engeller ("externally-managed-environment" hatası). Django ile PostgreSQL kullanıyorsanız psycopg paketinin requirements.txt içinde olduğundan emin olun. Deploy anahtarlarını Git ile deploy rehberimizde, kullanıcı yönetimini Linux'ta kullanıcı ekleme yazımızda anlatıyoruz. Sonraki adımlardaki komutları, sudo ile başlamıyorsa deploy kullanıcısıyla çalıştırın.

3. Adım: Gunicorn'u test edin

Servis dosyası yazmadan önce Gunicorn'un uygulamayı yükleyebildiğini kontrol edin. Argüman modül:değişken biçimindedir:

# Flask: app.py içinde app = Flask(__name__) var
gunicorn --bind 127.0.0.1:8000 app:app

# Django: wsgi.py dosyasını içeren proje klasörü
gunicorn --bind 127.0.0.1:8000 project.wsgi:application

İkinci bir SSH oturumundan curl -I http://127.0.0.1:8000 komutu bir cevap döndürmelidir. Flask uygulamanız uygulama fabrikası kullanıyorsa "app:create_app()" yazın. Gunicorn'u Ctrl+C ile durdurun.

Üretimde iki ayar önemlidir:

  • İşçi sayısı: Pratik kural 2 × CPU çekirdeği + 1 şeklindedir; çekirdek sayısını nproc ile görebilirsiniz. Her işçi ayrı bir süreç olduğu için daha fazla işçi daha fazla RAM demektir.
  • Zaman aşımı: Gunicorn varsayılan olarak 30 saniye içinde cevap vermeyen işçiyi yeniden başlatır. Bunu --timeout 60 ile yalnızca gerçekten yavaş istekleriniz varsa artırın; uzun işler arka plan kuyruğuna aittir.

4. Adım: Ortam değişkenleri

Gizli bilgileri koddan ve depodan uzak tutun. Dosyada sorun çıkaran karakterleri içermeyen bir gizli anahtarı python3 -c "import secrets; print(secrets.token_urlsafe(50))" komutuyla üretin ve yönetici hesabınızla /etc/app.env dosyasını oluşturun:

DJANGO_SECRET_KEY=urettiginiz-degeri-buraya-yapistirin
DB_PASSWORD=guclu-bir-parola

Her satıra bir ANAHTAR=değer yazın; export kullanmayın ve = işaretinin etrafına boşluk koymayın. Ardından dosyayı sudo chown root:deploy /etc/app.env ve sudo chmod 640 /etc/app.env komutlarıyla koruyun; değerleri kodunuzda os.environ ile okuyun.

5. Adım: Django üretim ayarları

Flask kullanıyorsanız bu adımı atlayın. settings.py dosyasında en azından şu değerleri değiştirin:

import os

DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
ALLOWED_HOSTS = ["example.com", "www.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://example.com", "https://www.example.com"]
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
  • DEBUG = False: Hata ayıklama açıkken hata sayfaları ayarlarınızı ve kodunuzu ziyaretçilere gösterir.
  • ALLOWED_HOSTS: Başka bir alan adıyla gelen istekler 400 hatası (DisallowedHost) alır.
  • CSRF_TRUSTED_ORIGINS ve SECURE_PROXY_SSL_HEADER: Nginx'in arkasında Django istekleri düz HTTP olarak görür. Bu ayarlar X-Forwarded-Proto başlığına güvenmesini sağlar ve formlar HTTPS üzerinde çalışır. Başlık ayarını yalnızca aşağıdaki gibi Nginx bu başlığı gönderiyorsa kullanın.

Ardından değişkenleri kabuğunuza yükleyip veritabanını ve statik dosyaları hazırlayın:

set -a; . /etc/app.env; set +a
python manage.py migrate
python manage.py collectstatic --noinput

6. Adım: Gunicorn için systemd servisi

deploy kabuğundan exit ile çıkın ve /etc/systemd/system/app.service dosyasını oluşturun:

[Unit]
Description=Gunicorn for app
After=network.target

[Service]
User=deploy
Group=www-data
WorkingDirectory=/srv/app
EnvironmentFile=/etc/app.env
RuntimeDirectory=app
ExecStart=/srv/app/venv/bin/gunicorn --workers 3 --timeout 60 \
    --access-logfile - --bind unix:/run/app/gunicorn.sock project.wsgi:application
Restart=always

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now app

ExecStart, venv içindeki gunicorn dosyasının tam yolunu kullandığı için hiçbir şeyi etkinleştirmeniz gerekmez. RuntimeDirectory, her açılışta /run/app klasörünü oluşturur. Flask için son argümanı app:app ile değiştirin. TCP tercih ediyorsanız burada --bind 127.0.0.1:8000, Nginx'te ise proxy_pass http://127.0.0.1:8000; kullanın. Servis dosyalarını systemd servisi oluşturma rehberimizde anlatıyoruz.

7. Adım: Nginx ters vekil sunucusu

/etc/nginx/sites-available/app dosyasını oluşturun:

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    client_max_body_size 20M;

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

    location / {
        proxy_pass http://unix:/run/app/gunicorn.sock;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
  • alias, statik dosyaları Python'a uğramadan doğrudan diskten sunar. İki taraftaki sondaki eğik çizgileri koruyun.
  • client_max_body_size: Nginx varsayılan olarak 1 MB yüklemeye izin verir; daha büyük dosyalar 413 hatası alır.
  • Flask'ta, URL oluştururken bu başlıklara güvenmesi için uygulamayı Werkzeug'un ProxyFix sınıfıyla sarın.

Güvenlik duvarında yalnızca web portlarını sudo ufw allow 'Nginx Full' ile açın; 8000 portu kapalı kalır. Ayrıntılar için UFW kullanımı rehberimize bakın.

8. Adım: HTTPS

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Certbot sertifikayı alır, HTTPS sunucu bloğunu ekler ve otomatik yenilemeyi ayarlar. Ayrıntılar için SSL sertifikası nedir? yazımıza bakın.

Güncellemeleri yayınlamak

sudo -iu deploy
cd /srv/app
git pull
source venv/bin/activate
pip install -r requirements.txt
set -a; . /etc/app.env; set +a
python manage.py migrate
python manage.py collectstatic --noinput
exit
sudo systemctl restart app

Gunicorn, yeniden başlatılana kadar eski kodu bellekte tutar. Veriyi değiştiren migration'lardan önce veritabanını yedekleyin; sunucu yedekleme rehberimize bakın.

Günlükler ve sık karşılaşılan hatalar

Gunicorn çıktısı journal'a gider (sudo journalctl -u app -f), Nginx ise /var/log/nginx/error.log dosyasına yazar.

HataSık görülen neden
502 Bad GatewayGunicorn çalışmıyor ya da Nginx sokete erişemiyor (örneğin /home/deploy içindeki soket)
Statik dosyalar 404 veriyorcollectstatic çalıştırılmamış ya da alias yolu STATIC_ROOT ile eşleşmiyor
400 Bad Request, DisallowedHostAlan adı ALLOWED_HOSTS içinde yok
403 CSRF verification failedCSRF_TRUSTED_ORIGINS içinde https:// kaynağı eksik
ModuleNotFoundErrorPaket venv içinde yok ya da servis /srv/app/venv dışındaki bir gunicorn ile çalışıyor

Servis açılmıyorsa journalctl çoğu zaman Python hata izini gösterir; KeyError: 'DJANGO_SECRET_KEY' hatası, EnvironmentFile dosyasının yüklenmediği anlamına gelir. 502 hatasını adım adım çözmek için 502 Bad Gateway hatası rehberimize bakın.

FastAPI hakkında bir not

FastAPI ve diğer ASGI uygulamaları bir ASGI işçisine ihtiyaç duyar. Venv içine uvicorn kurun ve Gunicorn komutunu gunicorn -k uvicorn.workers.UvicornWorker main:app olarak değiştirin; yeni Uvicorn sürümleri bu işçiyi ayrı uvicorn-worker paketine taşır (-k uvicorn_worker.UvicornWorker). Doğrudan uvicorn main:app --workers 4 --uds /run/app/gunicorn.sock komutunu da çalıştırabilirsiniz. Nginx ve systemd tarafı aynı kalır.

Python uygulamaları için Nodesty sunucuları

Nodesty AMD Ryzen 9 9950X VDS paketleri yüksek tek çekirdek hızıyla Python isteklerine düşük cevap süresi sağlar; AMD EPYC 7763 VDS paketleri ise daha fazla Gunicorn işçisi, veritabanı ve arka plan işlerini aynı sunucuda çalıştırmak için bol çekirdek ve RAM sunar. Tam root erişimi, NVMe disk, nShield DDoS koruması ve 7 gün saklanan ücretsiz günlük yedeklemeyle Flask, Django ya da FastAPI projelerinizi güvenle yayına alabilirsiniz.

Sıkça Sorulan Sorular

Sunucuda neden doğrudan python app.py ya da manage.py runserver çalıştırmıyorum?

Flask'ın yerleşik sunucusu ve Django'nun runserver komutu geliştirme sunucularıdır; gerçek trafik altında güvenlik ve performans için tasarlanmamıştır. Gunicorn birden fazla işçi süreci çalıştırır, çöken işçileri yeniden başlatır ve HTTPS, statik dosyalar ve yavaş istemcilerle ilgilenen Nginx'in arkasında sorunsuz çalışır.

Kaç Gunicorn işçisi kullanmalıyım?

Yaygın başlangıç noktası CPU çekirdeği başına iki işçi artı birdir; 2 çekirdekli bir sunucuda 5 işçi gibi. Her işçi kendi belleği olan ayrı bir süreçtir; bu yüzden RAM kullanımını izleyin ve sunucu swap kullanmaya başlarsa sayıyı düşürün. Gerçek yük altında ölçüp buna göre ayarlayın.

Gunicorn Unix soketinde mi yoksa 127.0.0.1:8000 adresinde mi dinlemeli?

İkisi de çalışır. Unix soketi TCP katmanını atlar ve ağdan hiç erişilemez; 127.0.0.1:8000 ise curl ile test etmesi daha kolaydır ve soket izni sorunlarını ortadan kaldırır. Üretimde Gunicorn'u asla 0.0.0.0 adresine bağlamayın; internete yalnızca Nginx açık olsun.

Sitem neden 502 Bad Gateway hatası veriyor?

Nginx, Gunicorn'a ulaşamıyor demektir. Ya Gunicorn servisi çalışmıyordur, ya açılırken çökmüştür ya da Nginx'in sokete erişim izni yoktur. Önce Gunicorn servisi için systemctl status ve journalctl çıktısına, ardından /var/log/nginx/error.log dosyasındaki Nginx hata günlüğüne bakın.

FastAPI uygulamasını da aynı şekilde yayınlayabilir miyim?

Evet. FastAPI bir ASGI çatısıdır; bu yüzden Gunicorn altında Uvicorn işçileriyle ya da doğrudan Uvicorn ile çalıştırılır. Kurulumun geri kalanı, yani sanal ortam, systemd servisi, Nginx ters vekil sunucusu ve HTTPS aynı kalır.

Nodesty

Yazar hakkında

Nodesty Ekibi · Altyapı ve Destek

Nodesty ekibi sunucularımızı, ağımızı ve DDoS korumamızı her gün işletir ve müşteri destek taleplerini 7/24 yanıtlar. Bu rehberler o deneyimden yazılır.

İlgili yazılar

Sunucunuzu şimdi başlatın.

Nodesty'nin üstün altyapısı ile projelerinizi özgürce inşa edin ve sınır tanımadan ölçeklendirin.

                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                             ············································                                                   
                                                ··································································································..........···························                                     
                                       ················..........................................................................................................................··············                             
                                  ·············.................::::::::::::::::::::::::::::::::::::::::::::::....................:::::::::::::::::::::::::::::::::::::::................···········                        
                             ············................:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::............·········                     
                         ············.................:::::::::::::::::::::::::::::::::::::::::::::::::::------------::::::::::::::::::::::::::::::----------------:::::::::::::::::::::..........········                  
                    ············......................::::::::::::::::::::::::::::::::::::------------------------------------------------------------------------------------:::::::::::::.........········                
                ··········.............................................::::::::::::::::::-------------==========================================-----------------------------------:::::::::::........·······               
             ········..................:.....................................::::::::::--------=======+++++++++++++++++++++++++++++++++++++=========================------------------::::::::::.......·······              
           ······.........::::::::::::::::::::................................:::::::-----=====++++xxxxxx**************************xxxxxxxxx++++++++++++++===================------------::::::::.......·······             
          ·····.......:::::::::::::::::::::::::::.............................:::::----===+++xxx****%%%%&&&&&&#############&&&&&&&%%%%%*******xxxxxxxx++++++++++++++==============----------:::::::......······             
         ····......::::::::-------------:::::::::::..........................::::---===+++xx***%%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@####&&&&&%%%%*******xxxxxxxxx+++++++++++++===========--------::::::......·····             
        ····.....:::::::--------------------:::::::::.......................::::---===++xxx**%%&&&###@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&%%%%%********xxxxxxxxxxx++++++++++++========------::::::.....······            
        ····.....:::::--------------------------::::::::....................::::---===++xx***%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&&%%%%%**********xxxxxxxxxxxxx+++++++++=======------:::::.....·····            
        ····....::::::-------=============---------:::::::::................:::::---===+++xx***%%%&&&#####@@@@@@@@@@@@@@@@@@@@@@@@@#####&&&&&%%%%%%*************xxxxxxxxxxxxxx+++++++++======-----:::::....·····            
         ····....:::::-------================---------:::::::::...............:::::----===++++xxx***%%%%&&&&&&#################&&&&&&%%%%%%%*******************xxxxxxxxxxxxxxxxx++++++++======----:::::....·····            
         ·····....:::::--------=================---------::::::::::..............:::::::-----====+++++xxxxxx**************************xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx++++++++=====-----::::....·····            
          ·····.....:::::--------=================----------:::::::::::.................:::::::::-------=============++++++++++++++++++++++++++++++++++++xxxxxxxxxxxxxxxxxxxxxxx++++++++======-----::::....·····            
            ·····.....:::::::----------===========-------------::::::::::::.........................::::::::::::::::::------------------=============+++++++++++++++++++++++++++++++++=======-----::::.....·····            
              ······......:::::::---------------------------------:::::::::::::........................................:::::::::::::::-----------============+++++++++++++++++++++========------:::::.....·····             
                 ······........:::::::::---------------------------:::::::::::::::::...........................................:::::::::::::------------=============================--------::::::.....······              
                    ·········.........:::::::::::::::-------------::::::::::::::::::::::::.......................................::::::::::::::::--------------------------------------::::::::......·······                
                          ··········............::::::::::::::::::::::::::::::::::::::::::::::::::................................::::::::::::::::::::::::::-------------:::::::::::::::.........········                   
                                  ············..................:::::::::::::::::::::::::::::::::::::::::::.........................:::::::::::::::::::::::::::::::::::::................···········                        
                                             ················.............................................................................................................·················                                 
                                                           ······················................................................................···························                                                
                                                                               ·········································································