
VDS'te FastAPI Yayına Alma: Uvicorn ve Nginx
FastAPI uygulamasını Linux VDS'te Uvicorn ile çalıştırıp Nginx arkasında HTTPS ile yayına almak için izlemeniz gereken adımları ve kaynak planlamasını anlatıyoruz.
FastAPI uygulamasını VDS'te yayına almak için uygulamayı Uvicorn ile çalıştırıp systemd ile yönetmek, önüne Nginx reverse proxy koymak ve HTTPS eklemek temel adımlardır. Bu düzen, uygulama sürecini ayrı tutar; dışarıya yalnız Nginx açılır ve VDS sunucu seçerken bu ayrımı koruyacak yapılandırmayı hedefleyin.
Kısa cevap:
- Yönetici erişimli Linux VDS, Python sanal ortamı ve systemd gerekir.
- Uvicorn uygulamayı yerel adreste dinler; Nginx 80 ve 443 portlarını karşılar.
- HTTPS için alan adı ve Certbot; güncelleme için sağlık kontrolü ve geri dönüş planı gerekir.
FastAPI VDS deploy sürecinde önce FastAPI uygulamaları için VDS sunucu seçimini netleştirin; ardından adımları sırayla uygulayın.
FastAPI İçin Linux VDS ve Yönetici Erişimi Gereksinimi
FastAPI, Python tabanlı bir web çerçevesidir; çalışması için süreç başlatabileceğiniz, bağımlılık kurabileceğiniz ve ters proxy tanımlayabileceğiniz bir sunucu gerekir. Paylaşımlı Linux hosting paketlerinde çoğunlukla SSH, terminal ve komut satırı erişimi bulunmaz; bu nedenle Uvicorn gibi süreçleri yönetmek ve systemd servisi tanımlamak sınırlı kalır. Dolayısıyla Uvicorn, systemd ve Nginx adımları için yönetici erişimli Linux VDS kullanın; bu erişim, süreç ve servis yönetimini doğrudan yapmanıza ve ters proxy yapılandırmasını yönetmenize olanak verir.
VDS'te root veya sudo yetkili bir kullanıcıyla oturum açın. Uygulamayı root olarak çalıştırmayın; ayrı bir sistem kullanıcısı açın, dosya izinlerini yalnız bu kullanıcının erişebileceği biçimde sınırlayın ve systemd biriminde bu kullanıcıyı tanımlayın. Sunucuya bağlandıktan sonra paket listelerini güncelleyin ve Python ile Nginx'in kurulu olduğunu doğrulayın. Dağıtımınıza göre paket yöneticisi değişebilir; Debian/Ubuntu tabanlı sistemlerde aşağıdaki komutlar yol gösterir.
ssh kullanici@sunucu-ip
sudo apt update
python3 --version
nginx -v
Güvenlik duvarında yalnız ihtiyaç duyduğunuz portları açın: SSH için 22, HTTP için 80, HTTPS için 443. 8000 gibi uygulama portunu dışarıya açmayın; Uvicorn yalnız yerel adreste dinlesin. Alan adınızın A kaydını sunucu IP adresine yönlendirin; sertifika adımı buna bağlıdır. Kurulumun genel adımları için VDS sunucu kurulumu yazısına bakabilirsiniz.
Python Sanal Ortamı ve Uygulama Bağımlılıkları
Uygulama dosyalarını /srv/fastapi/app gibi ayrı bir dizinde tutun. Sanal ortamı aynı dizin ağacında oluşturun; böylece sistem Python paketleriyle karışmaz ve proje bağımlılıkları ayrı kalır. Bağımlılıkları requirements.txt dosyasına yazın; kurulumu bu dosyadan yapmak sürümlerin izlenmesini ve yeni ortamda aynı paketlerin kurulmasını kolaylaştırır.
sudo mkdir -p /srv/fastapi/app
sudo useradd --system --home /srv/fastapi --shell /usr/sbin/nologin fastapi
sudo chown -R fastapi:fastapi /srv/fastapi
sudo -u fastapi python3 -m venv /srv/fastapi/venv
sudo -u fastapi /srv/fastapi/venv/bin/pip install --upgrade pip
sudo -u fastapi /srv/fastapi/venv/bin/pip install fastapi "uvicorn[standard]"
Uygulamanızın giriş dosyası main.py ve FastAPI nesnesi app ise Uvicorn'a main:app biçiminde yol verirsiniz. ASGI (Asynchronous Server Gateway Interface) uygulaması bu adla yüklenir. Bağımlılıkları güncellerken sanal ortamın pip'ini kullanın veya önce sanal ortamı etkinleştirin, sonra requirements.txt ile kurulum yapın; böylece kurulum doğru Python yorumlayıcısına uygulanır. Sistem genelinde pip kullanmayın; farklı projelerin sürümleri birbirini etkilemesin.
Ortam değişkenlerini koda yazmayın; bu değerleri kod deposundan ayrı tutun. Veritabanı parolası ve uygulama anahtarı gibi değerleri ayrı bir dosyada tutun; dosyayı systemd biriminde EnvironmentFile= ile tanımlayın veya uygulamanın açıkça yüklemesini sağlayın ve izinleri yalnız uygulama kullanıcısına verin. Sanal ortamı yeniden oluşturduğunuzda aynı bağımlılık sürümlerini kurabilmek için çalışan sürümleri requirements.txt içinde sabitleyin.
Uvicorn Sürecini systemd ile Yönetme
Uvicorn'u terminalde elle başlatmak, oturum kapandığında sürecin de sonlanmasına yol açabilir; bu nedenle üretimde süreci systemd servisi olarak çalıştırın. systemd, uygulamayı açılışta başlatır ve hata durumunda yeniden dener; böylece süreç terminal oturumundan bağımsız olarak servis biçiminde izlenir. /etc/systemd/system/fastapi.service dosyasını oluşturun.
[Unit]
Description=FastAPI Uvicorn
After=network.target
[Service]
User=fastapi
Group=fastapi
WorkingDirectory=/srv/fastapi/app
ExecStart=/srv/fastapi/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Restart=on-failure
Environment=PYTHONUNBUFFERED=1
[Install]
WantedBy=multi-user.target
Ardından servisi yükleyin, açılışta etkinleştirin ve durumunu kontrol edin.
sudo systemctl daemon-reload
sudo systemctl enable --now fastapi
sudo systemctl status fastapi
journalctl -u fastapi -f
Durum çıktısında servisin çalıştığını ve son satırlarda hata kaydı olmadığını kontrol edin. Uygulama kodunda değişiklik yaptığınızda servisi yeniden başlatın. Kod değişikliklerini otomatik izlemek için geliştirme modunu üretimde açık tutmayın; değişiklik sonrası servisi yeniden başlatın. Servis sürekli yeniden başlıyorsa önce journalctl çıktısındaki son hatayı okuyun; ardından sanal ortam yolunu ve main:app tanımını kontrol edin.
Nginx Reverse Proxy ve HTTPS Yapılandırması
Nginx, dışarıdan gelen isteği 127.0.0.1:8000 adresindeki Uvicorn sürecine iletir. Böylece TLS sonlandırma, alan adı yönlendirmesi ve istek başlıkları tek yerde yönetilir; uygulama portunun doğrudan dışarıya açılması da önlenir. Önce alan adının sunucu IP adresine yönlendirildiğinden emin olun.
Nginx sitesi için /etc/nginx/sites-available/fastapi dosyasına aşağıdakine benzer bir blok ekleyin; alan adını kendi alan adınızla değiştirin.
server {
listen 80;
server_name example.com www.example.com;
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;
}
}
Etkinleştirme için dosyayı sites-enabled dizinine bağlayın, yapılandırmayı sınayın ve Nginx'i yeniden yükleyin.
sudo ln -s /etc/nginx/sites-available/fastapi /etc/nginx/sites-enabled/fastapi
sudo nginx -t
sudo systemctl reload nginx
Dosya yükleme kabul eden uygulamalarda Nginx'in istek gövdesi sınırını uygulamanın ihtiyacına göre ayarlayın. WebSocket kullanıyorsanız ilgili Upgrade ve Connection başlıklarını proxy bloğuna ekleyin. Bu ayarların ayrıntıları için Nginx reverse proxy yapılandırması yazısını izleyin.
HTTPS için Certbot kullanabilirsiniz; önce Certbot ve Nginx eklentisinin kurulu olduğunu doğrulayın veya kurun. Alan adı DNS kaydı hazır olduktan sonra sertifikayı alın ve Nginx yapılandırmasını güncelleyin.
sudo certbot --nginx -d example.com -d www.example.com
Sertifika yenilemesini Certbot'un zamanlanmış görevi yönetir; yine de yenileme sonrası Nginx'in çalıştığını ve sertifikanın geçerliliğini kontrol edin. HTTP adreslerinin HTTPS'e yönlendiğini tarayıcıda doğrulayın; yönlendirme yoksa Nginx yapılandırmasında tanımlayın. Ayrıntılı anlatım için Certbot ile SSL kurulumu yazısına bakabilirsiniz.
Worker Sayısı, Zaman Aşımı ve Kaynak Planlama
Uvicorn worker sayısını sunucunun CPU ve bellek kapasitesine göre belirleyin. CPU çekirdeği başına 1–2 worker bir başlangıç noktasıdır; uygun sayıyı yük altında ölçün. Çok sayıda worker, bellek tüketimini artırır; veritabanı bağlantı havuzunu da buna göre planlayın.
| Ayar | Başlangıç yaklaşımı | Kontrol |
|---|---|---|
| Uvicorn worker | CPU çekirdeği başına 1–2; ölçerek artırın | CPU, bellek, yanıt süresi |
| systemd Restart | on-failure | journalctl kayıtları |
| Nginx timeout | Uzun işlerin süresine göre ayarlayın | 502 ve 504 kayıtları |
| Bellek | Worker başına tüketimi ölçün | free, top |
Uzun süren istekler için Nginx'te proxy_read_timeout değerini toplam işlem süresine göre değil, upstream'den ardışık okumalar arasındaki bekleme süresine göre ayarlayın; bu değer uygulamanın veri göndermeden geçirebileceği süreyi sınırlar. Çok kısa süre, arkada çalışan işi kesmez; yalnız bağlantıyı erken kapatır. Uvicorn tarafında keep-alive süresini de ters proxy ile uyumlu tutun. Kaynak artışı yanıt süresini iyileştirmiyorsa worker sayısını düşürün.
Uygulama kodu async uyumlu değilse worker sayısını artırmak tek başına çözüm olmaz; bloklayan işlemleri ayrı görevlere veya kuyruğa taşıyın ve worker sayısını yük altında ölçün. CPU, bellek ve disk gecikmesini düzenli aralıklarla izleyin; darboğazı ölçmeden yeni kaynak eklemeyin.
Sağlık Kontrolü, Loglar ve Güvenli Güncelleme
Uygulamaya basit bir sağlık uç noktası ekleyin. Bu uç nokta, veritabanı gibi dış bağımlılıkları zorlamadan sürecin yanıt verdiğini göstermelidir.
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health():
return {"status": "ok"}
Nginx ve Uvicorn loglarını ayrı okuyun. Uygulama hataları için journalctl, HTTP hataları için Nginx erişim ve hata kayıtları yol gösterir. Güncellemede önce yeni sürümü ayrı bir dizine açın, sanal ortamı ve bağımlılıkları kurun; servis yollarını yeni sürüme yönlendirdikten sonra servisi yeniden başlatıp /health adresini kontrol edin.
- Yeni sürümü ayrı dizine kopyalayın.
- Yeni sürümün bağımlılıklarını kurun; servis dosyasındaki
WorkingDirectoryveExecStartyollarını yeni sürüme yönlendirin, dosya değiştiysedaemon-reloadçalıştırın ve servisi yeniden başlatın. systemctl status fastapiile servisin durumunu kontrol edin./healthyanıtını vejournalctlçıktısını kontrol edin.- Sorun varsa
WorkingDirectoryveExecStartyollarını önceki sürüme yönlendiripsudo systemctl daemon-reloadvesudo systemctl restart fastapiçalıştırın.
Süreç ve servis yönetimi alışkanlıkları için systemctl süreç yönetimi yazısına bakın. Sonraki adımda /health adresini izlemeye alın ve dağıtım sonrası ilk dakikalarda hata kayıtlarını okuyun. Böylece güncelleme sırasında sorun çıkarsa önceki sürüme dönebilirsiniz.
Sık Sorulan Sorular
FastAPI için hangi VDS özellikleri gerekir?
Yönetici erişimi, yeterli CPU ve bellek, yeterli disk alanı ve kararlı bir ağ bağlantısı temel gereksinimdir. Uygulamanın veritabanı ve dosya işlemleri kaynak tüketimini belirler. Başlangıçta ölçüm yapabileceğiniz bir paket seçin; CPU, bellek ve yanıt süresini izleyerek kaynakları artırın. Paylaşımlı hostingde çoğunlukla SSH bulunmadığı için bu adımlar VDS gerektirir.
Uvicorn'u doğrudan 80 portunda çalıştırabilir miyim?
Teknik olarak mümkün olsa da üretim ortamında önerilmez. 80 ve 443 portlarını Nginx yönetmeli; Uvicorn yalnız yerel adreste dinlemelidir. Bu düzen TLS, alan adı yönlendirmesi ve istek başlıklarının tek noktadan yönetilmesini sağlar. Ayrıca uygulama portunun dışarıya açılmasını engellersiniz.
Nginx 502 hatası alırsam ne kontrol etmeliyim?
Önce Uvicorn servisinin çalıştığını systemctl status fastapi ile kontrol edin. Ardından journalctl -u fastapi çıktısında uygulama hatası arayın. Nginx yapılandırmasındaki proxy_pass adresinin Uvicorn'un dinlediği adres ve portla aynı olduğundan emin olun. Son olarak Nginx hata kaydını okuyun.
HTTPS'i ücretsiz almak mümkün mü?
Alan adı doğrulaması yapılabilen sertifikalar için Certbot ve Let's Encrypt kullanılabilir. Önce alan adının doğru IP adresine yönlendirilmesi gerekir. Sertifika alındıktan sonra Nginx yapılandırması güncellenir ve yenileme görevi kontrol edilir. Kurulum adımlarını sunucunuzda doğrulayın.
Worker sayısını nasıl belirlerim?
Önce CPU çekirdeği başına 1–2 worker ile başlayın. Yük altında CPU, bellek ve yanıt süresini izleyin. Worker artışı yanıt süresini iyileştirmiyorsa sayıyı düşürün. Veritabanı bağlantı sınırını da worker sayısıyla birlikte planlayın; aksi halde bağlantı havuzu darboğaz oluşturabilir.
Sunucu Yönetimi İlgili Hizmetlerimiz
Bu yazıda anlatılan teknik konuyu profesyonel altyapıyla deneyimleyin
Etiketler:

