Laravel Dağıtımını Ölçülebilir Bir Süreç Olarak Kurmak
Bir kampanya yayındayken kod güncellemek, yalnız yeni dosyaları kopyalamaktan ibaret değildir. Devam eden istekler, kuyruktaki işler ve veritabanı aynı anda eski ve yeni kodla karşılaşabilir. Kesintiyi azaltmak için sürümü ayrı hazırlamak, uyumluluğu doğrulamak ve başarısızlıkta hangi duruma dönüleceğini önceden belirlemek gerekir.
Bu rehber Laravel’i bir VPS üzerinde Nginx, PHP-FPM ve Redis kuyrukları için Horizon ile yayımlama düzenini açıklar. releases/current/shared yapısını; izinler, önbellekler, işçi geçişi, sağlık kontrolü ve geri dönüş koşullarıyla birlikte ele alır. “Sıfır kesinti” otomatik sonuç değildir; uygulamanın ve dağıtımın test edilmesi gereken hedefidir.
VPS’in Üzerine İnşa
Alan Adı, DNS ve İlk Adımlar
Desteklenen işletim sistemi, ayrı dağıtım hesabı ve SSH anahtarıyla başlayın. CI bağlantısında sunucu parmak izini ayrı güvenilir kanaldan doğrulayıp known_hosts’a kaydedin; StrictHostKeyChecking=yes kullanın. Dağıtım hesabına yalnız gereken servis işlemleri için dar yetki verin. Alan adının A/AAAA kayıtlarını hedefe yöneltin; kendi DNS sunucunuzu işletmek Laravel için şart değildir. Gerekiyorsa özel ad sunucusu ve glue record rehberi ayrı DNS konusunu açıklar.
Nginx’in belge kökü Laravel proje kökü değil current/public olmalıdır. .env, vendor ve uygulama kaynaklarını web üzerinden sunmayın. PHP sürümünü composer.lock ve kullanılan Laravel sürümüyle eşleştirin; örneğin 13.x en az PHP 8.3 ister. CLI ve FPM’in aynı uzantıları ve uygun sürümü kullandığını ayrıca kontrol edin.
Nginx Belge Kökü ve PHP Giriş Noktası
Dosya olarak bulunmayan uygulama isteklerini index.php’ye yönlendirin ve yalnız bu ön denetleyiciyi PHP-FPM’e aktarın. Diğer PHP yollarını ve gizli dosyaları reddedin; özellikle public/storage altındaki bir upload çalıştırılmamalıdır. SCRIPT_FILENAME için gerçek sürüm yolunun çözümlenmesi, tek isteğin aynı sürümden yürütülmesine yardımcı olur. TLS ve Brotli rehberi protokol katmanını tamamlar; OCSP desteği sertifika sağlayıcısına bağlıdır.
Statik dosya kurallarını gerçek ve herkese açık asset dizinleriyle sınırlayın. Uzun cache yalnız içerik değişince URL’si de değişen dosyalara uygundur; eski HTML’in başvurduğu dosyalar geçişte kalmalıdır. Nginx’te alt location içinde add_header eklemek varsayılan davranışta üst güvenlik başlıklarını miras almayı kesebilir. Son yanıt başlıklarını ve bulunmayan dosyaların 404 davranışını test edin.
SSL/HTTPS ve Zarif Yeniden Yüklemeler
Sertifika veya Nginx yapılandırması değiştiğinde önce nginx -t, sonra uygun hizmet yöneticisiyle reload uygulayın. Nginx süreç kontrolü belgesi, yeni işçilerin başlatılıp eskilerin kontrollü kapatılmasını açıklar. Bu davranış bütün bağlantılar için kesintisizlik garantisi değildir. Yalnız current bağı değişiyorsa Nginx yapılandırması değişmediği için reload zorunlu değildir.
PHP-FPM Kapasitesi ve Kod Önbelleği
Neden PHP‑FPM ve Ne Zaman Takılır?
PHP-FPM web isteklerini işler; Laravel kuyruk işçileri ve Horizon ayrı CLI süreçleridir. Aynı VPS’te CPU, RAM ve veritabanı kaynakları için rekabet edebilirler. FPM max_children değerini gerçek işçi bellek dağılımı, kuyruk beklemesi ve downstream kapasitesiyle seçin; PHP memory_limit tek başına süreç RAM bütçesi değildir.
Kısa trafik artışında önbellek ve statik sunum ancak gerçekten paylaşılabilir yanıtlardaki işi azaltır. Kişisel veya oturumlu sayfalar cache’e gelişigüzel alınmamalıdır. Hem sıcak hem soğuk cache altında gecikme, hata oranı ve FPM bekleme kuyruğunu ölçün. İşçi sayısını artırmak RAM veya veritabanı sınırını aşarsa performansı kötüleştirebilir.
OPcache ve Laravel’in Önbellekleri
Üretim ortamı ve paylaşılan dosya bağlantıları hazırlandıktan sonra yeni sürümün config/route/view cache’lerini üretin. bootstrap/cache sürüme özel kalmalıdır. Bütün storage paylaşılıyorsa Laravel’in varsayılan derlenmiş görünüm dizini de paylaşılır; view:cache önce burayı temizleyebilir. Uygulamanın config/view.php içindeki compiled değerini örneğin base_path(‘bootstrap/cache/views’) olarak sürüme özel bir yola ayarlayıp dizini önceden oluşturun. OPcache için gerçek sürüm yollarını ve FPM yaşam döngüsünü doğrulayın; CLI’da cache sıfırlamak FPM cache’ini temizlediğinizi kanıtlamaz.
Performans ayarlarını dağıtım doğruluğundan ayrı ölçün. Laravel üretim optimizasyonu rehberi FPM, OPcache ve uzun ömürlü süreçlerin ek koşullarını ele alır. Hızlı bir test, sürüm değişiminde eski kodun kalmadığını doğrulayan testin yerine geçmez.
Queue ve Horizon Süreçlerini Yönetmek
Arka Plan İşleri Neden Hayat Kurtarır?
E-posta, rapor veya görsel işleme gibi ertelenebilir işler asenkron kuyruğa taşınabilir. sync bağlantısı işi arka plana taşımaz; çalışan CLI işçileri ve uygun kuyruk altyapısı gerekir. Kuyruk, toplam işi ortadan kaldırmaz ve başarının hemen kullanıcıya gösterilmesi gereken her işlem ertelenemez. İşin tamamlanma, hata ve yeniden deneme durumları uygulamada tanımlı olmalıdır.
Horizon yalnız Redis tabanlı Laravel kuyruklarını yönetir; genel bir kuyruk hizmeti veya FPM havuzu değildir. Panel erişimini yetkilendirin. Bekleyen iş sayısıyla birlikte en eski işin yaşı, çalışma süresi, hata ve tamamlanma hızını izleyin. Bu ölçümler birikimin nedenini araştırmayı sağlar, tek başına yeniden başlatma önermez.
Horizon’ı Dağıtımın Bir Parçası Yapmak
Horizon’ı systemd veya Supervisor gibi bir süreç yöneticisiyle çalıştırın. Koordineli geçişte yeni sürüm hazırlandıktan sonra hizmeti yönetici üzerinden durdurun, devam eden işlerin bitmesini ve duruş sonucunu doğrulayın; bağı çevirdikten sonra hizmeti yeni current yolundan başlatın. Yalnız horizon:terminate komutunu geçişten önce çalıştırmak, otomatik yeniden başlatma nedeniyle eski sürümün tekrar açılmasına yol açabilir. Duruş süresi ve sinyal işleme, en uzun geçerli işe göre test edilmelidir.
Horizon belgesini kurulu sürümünüzle birlikte kullanın. Supervisor/systemd Horizon’ın alternatifi değil onu çalışır tutan süreç yöneticileridir. auto dengelemede kuyruk sırası katı öncelik sağlamaz; farklı hizmet hedefleri için ayrı ve sınırlı işçi kapasitesi tanımlayın. job timeout, Horizon timeout ve retry_after birbiriyle uyumlu olmalı; tekrar denenebilen dış etkiler idempotent tasarlanmalıdır.
Sürüm Dizinleriyle Kontrollü Dağıtım
Her dağıtımı releases altında yeni ve değiştirilmeyen bir dizinde hazırlayın. current canlı kodu gösteren sembolik bağdır; shared kalıcı dosyaları tutar. Geçişte aynı ana dizinde geçici bir bağ oluşturup GNU mv -T ile current üzerine yeniden adlandırmak, bağın arada kaybolmasını önler. ln -nfs aynı atomiklik garantisini vermez. Bu dosya sistemi işlemi veritabanını, cache’i veya birden çok isteği tek atomik işlem yapmaz.
Dağıtım, geri dönüş ve temizlik aynı kilidi kullanmalıdır; tek VPS’te uygun yerel dosya sisteminde flock bunun için kullanılabilir. Birden çok sunucuda ortak koordinasyon gerekir. Eski sürümü devam eden istekler, CLI işler ve scheduler süreçleri tamamlanana, ayrıca geri dönüş süresi dolana kadar saklayın. Bağı geri çevirmek kodu değiştirir; işlenmiş veriyi ve dış sistem etkilerini geri almaz.
Hazırlama, Sağlık Kontrolü ve Geçiş Sırası
Önce kilidi alın ve mevcut sürümü kaydedin. Temiz CI çıktısını yeni dizine aktarın; yerel .env, vendor ve eski bootstrap cache çıktıları taşınmamalıdır. Paylaşılan .env/storage bağlantılarını ve yazma izinlerini Composer uygulama betikleri çalışmadan önce hazırlayın. Kilitli bağımlılıkları ve sürümlü varlıkları kurun; sürüme özel önbellekleri üretin. Yalnız eski kodla uyumlu, incelenmiş migration’ları yürütün. Yeni sürümü kendi gerçek yoluna bağlı özel test vhost’u/FPM ile sağlık kontrolünden geçirin; sonra işçileri durdurup bekleyin, bağı atomik çevirin, gereken FPM geçişini yapın ve işçileri yeni yoldan başlatın. Geçiş sonrası HTTP, veri ve kuyruk kontrollerini tamamlayın.
Şema değişimini genişlet-daralt yaklaşımıyla planlayın: önce eski kodla uyumlu sütun/tablo ekleyin, yeni kodu yayımlayın ve veriyi sınırlı partilerle doldurun. NOT NULL gibi kısıtlamadan önce eski NULL kayıtlar tamamlanmalı ve eski web/kuyruk süreçleri artık NULL yazmamalıdır. Son daraltma, eski sürüme geri dönüş ihtiyacı sona erdikten sonra yapılır. Kuyruğa alınan backfill de kilit ve I/O yükü oluşturabilir; ilerleme, tekrar çalıştırma ve hata kurtarma planı gerekir. migrate –force yalnız üretim onayını atlar, güvenli veya kilitsiz migration modu değildir.
Bakım Modu mu, Sıfır Kesinti mi?
Kod/şema uyumluluğu korunamıyorsa planlı bakım gerekebilir. Laravel bakım modu tek başına bütün harici üreticileri, çalışan işleri veya scheduler’ı durdurmaz; veri değiştiren aktörleri ayrıca koordine edin. Geri dönüş için yedek bulunması yeterli değildir; geri yükleme süresi ve sonradan yazılan verilerin ne olacağı bilinmelidir. Kesinti hedefini uygulamanın bu sınırlarına göre belirleyin.
Güvenlik, İzleme ve Yedek: Kırılgan Anlar Önceden Çözülürse Çok Rahat
HTTPS ve Saldırı Önlemleri
HTTPS, sertifika yenileme ve güvenli oturum çerezleri yayın öncesi hazır olmalıdır. Sertifikayı doğru alan adıyla doğrulayın, APP_DEBUG=false kullanın ve CSRF/yetkilendirme kontrollerini koruyun. Nginx TLS ve Brotli rehberi ayrı TLS katmanını açıklar; Let’s Encrypt güncel sertifikaları OCSP stapling kullanmaz.
Rate limit ve WAF kurallarını gerçek uygulama trafiğiyle test edin. Nginx yalnız herkese açık dosyaları doğrudan sunmalıdır; özel indirmeler uygulama yetkilendirmesinden geçmelidir. Upload dizinindeki PHP dosyalarını çalıştırmayın; aktif HTML/SVG gibi içerikler için de dosya türü, ayrı alan adı veya indirme politikası gereksinimini değerlendirin.
İzlemezsen Göremezsin: Loglar, Paneller ve Sessiz Alarmlar
Örneğin kaynak kullanımı normal görünürken belirli saatlerde kuyruk yaşı ve kullanıcı gecikmesi artabilir. Sürüm kimliğiyle ilişkilendirilmiş loglar, HTTP hata/gecikme ölçümleri ve kuyruk göstergeleri bu ilişkiyi bulmaya yardım eder. VPS izleme ve alarm rehberi başlangıç sağlar; bir 200 sağlık yanıtı tüm iş akışlarının doğru olduğunu kanıtlamaz.
Kuyruk büyürse iş süresi, bağımlılık gecikmesi, veritabanı kilitleri ve geliş hızını inceleyin. İşçi sayısını ancak CPU/RAM ve downstream kapasitesi izin veriyorsa artırın. Duruşta süre aşımı yaşanmış bir işi tamamlanmış saymayın; yeniden teslim ve idempotency kayıtlarıyla uzlaştırın.
Yedekleriniz Kibar Dursun, Geri Dönüşünüz Kolay Olsun
Yedek kapsamına veritabanı, yüklenen dosyalar, gerekli sır/anahtarlar ve yapılandırmayı dahil edin. Uzak kopya, şifreleme, saklama ve geri yükleme testleri ayrı gereksinimlerdir. Restic ve Borg uzak yedekleme rehberi seçenekleri açıklar. Sürüm dizini saklamak, veritabanı veya kullanıcı dosyası yedeği değildir.
Ortam, İzinler ve Uzun Ömürlü Süreçler
Env, İzinler ve Paylaşımlı Klasörler
.env dosyasını public dışında tutun; her sürüm onu bağlayabilir, ancak config:cache tamamlandıktan sonra normal .env okuması yapılmaz. env() çağrılarını config dosyalarıyla sınırlayın ve config cache’i yeni ortamla yeniden üretin. Kalıcı storage paylaşılabilir; bootstrap/cache ve derlenmiş görünümler sürüme özel olmalıdır. Gerçek shared hedeflerine erişimi doğrulayın; sembolik bağ üzerinde kör recursive chmod kullanmayın. Dizin arama, dosya okuma/yazma ve yeni dosyalara miras kalan izinleri deploy ile web/queue hesaplarında test edin; 777 veya bütün dosyalara +x vermeyin.
Sürüm kimliği çakışmayacak biçimde oluşturulmalı ve manifest ile eşleştirilmelidir. Temizlikte current, geri dönüş için korunan sürüm ve hâlâ süreçlerin kullandığı dizinler hariç tutulmalıdır. Eski asset URL’lerini kullanan cache’li HTML ve açık tarayıcılar için dosya saklama süresi daha uzun olabilir. Tarihe göre ls/tail/xargs ile otomatik silme, bu koşulları doğrulamaz; temizlik ayrı, kilitli ve yol doğrulamalı bir adımdır.
Nginx ve FPM’e Kibarca Haber Vermek
Nginx yalnız bağ değişimi için reload istemez. FPM’in yeni kodu görmesi gerçek dosya yolları, OPcache, realpath cache ve varsa preload politikasına bağlıdır. validate_timestamps=0 seçiliyorsa değişen kod için doğrulanmış geçiş zorunludur. Reload komutunun dönmesini yeterli saymayın; yeni işçilerin sürüm kimliği ve gerçek HTTP yanıtını kontrol edin. Devam eden isteklerin bitmesine yetecek kaynak ve süre bırakın.
Horizon ve diğer uzun ömürlü süreçleri açıkça yeni sürümden başlatın. WorkingDirectory ve artisan yolu current üzerinden yeniden çözülmeli; yalnız eski çalışma dizinindeki uygulamayı reload etmek eski kodu koruyabilir. Eski ve yeni süreçler örtüşüyorsa kuyruk payload’ları, şema ve cache formatları iki sürümle de uyumlu olmalıdır. Kısa tüketim molası HTTP kesintisiyle aynı değildir ama kuyruk gecikme hedefini etkiler.
Geri Dönüş ve Sorun Tanılama
Geri Alma Planı (Rollback) Olmadan Dağıtım, Dağıtım Değildir
Geri dönüşten önce eski sürümün mevcut şema, veri, cache, sırlar ve kuyruktaki payload’larla çalışabildiğini kontrol edin. Aynı dağıtım kilidi altında işçileri durdurup bekleyin, bağı atomik eski sürüme yöneltin ve ilgili süreçleri o yoldan başlatın; ardından sağlık ve iş akışı kontrollerini tekrarlayın. down() migration’ı veriyi güvenle kurtarma garantisi değildir; otomatik şema geri alma yerine planlı düzeltme gerekebilir.
Örnek bir cache formatı değişiminde eski ve yeni kod aynı anahtarı farklı yorumlayabilir. Geri dönüşte de geçerli olacak sürümleme veya uyumlu okuma stratejisi tasarlayın. optimize:clear gibi geniş komutlar kullanılan Laravel sürümünde ortak cache anahtarlarını da silebilir; dağıtımda gelişigüzel çalıştırmayın. Oturum ve kuyruk restart sinyalleri gibi ortak verileri yanlışlıkla kaldırmayın.
Belirtileri Okumak: Yavaşlık mı, Zıplamalar mı?
CPU, bellek veya gecikme artışı tek başına belirli bir nedeni kanıtlamaz. Sürüm kimliği, istek oranı, yavaş sorgu/lock ölçümleri, FPM kuyruğu ve iş yaşını birlikte inceleyin. Yeni kodu suçlamadan önce aynı zaman dilimindeki dış servis ve bakım yükünü de kontrol edin; sonuçları geri dönüş kararına bağlayın.
Laravel ve Dağıtım Araçlarının Belgeleri
Sürümle Eşleşen Referanslar
Laravel dağıtım belgesi için kurulu sürümü seçin. Public kök, cache, yazılabilir dizinler ve uzun ömürlü süreç koşullarını o sürüme göre doğrulayın. Deployer Laravel tarifi hazırlık, kilit, ortak dosyalar ve yayın sırasını otomatikleştirebilir; uygulamaya özel sağlık, görünüm cache’i ve migration uyumluluğu yine tanımlanmalıdır.
Yeni sürümün sağlık kontrolü canlı current adresini değil aday sürümü ölçmelidir. Ayrı test vhost’u/FPM veya uygun yalıtılmış test hizmetiyle gerçek yolu hedefleyin; uygulama açılışını, kritik bağımlılıkları ve yan etkisiz bir isteği sınayın. Laravel’in varsayılan /up yanıtı tek başına veritabanı, Redis ve bütün kuyrukların sağlıklı olduğunu göstermez. Geçiş sonrasında ziyaretçinin gördüğü yolu da yeniden test edin.
Kaynak Bütçesi ve Büyüme
Kaynak Seçimi ve Ufak Sürprizler
Yeni sürüm hazırlanırken Composer/build işleri, eski ve yeni FPM işçileri ve kuyruklar aynı VPS’i paylaşabilir. Bu geçici tepeyi CPU, RAM ve disk bütçesine ekleyin. NVMe etiketi tek başına gecikme garantisi değildir; gerçek I/O ve sağlayıcı kotalarını ölçün. Log döndürme ve release saklama planı disk dolmasını önlemeye yardımcı olur; aktif sürümü silmek çözüm değildir.
Uygulama büyüdükçe gecikme, hata ve kuyruk yaşı eşiklerini yeniden değerlendirin. VPS izleme ve uyarı rehberi metrik seçimini destekler. Her alarmın bir sorumlu ve uygulanabilir tanılama/geri dönüş adımı olmalıdır.
Dağıtımı Doğrulanabilir Hale Getirin
Bir Sonraki Dağıtımın Kabul Ölçütleri
Başarılı geçiş; ayrı hazırlanmış sürüm, kalıcı verinin korunması, sürüme özel cache, uyumlu şema ve doğru işçi yaşam döngüsünün birlikte çalışmasıdır. current bağının atomik değişmesi yalnız bu sürecin bir adımıdır. Kullanıcı işlemlerini, kuyruk sonuçlarını ve geri dönüş yolunu test ederek kesinti hedefinin karşılandığını gösterin.
Hazırlama, sağlık kontrolü, işçi duruşu, atomik geçiş, yeni süreçlerin açılması ve geçiş sonrası doğrulamayı tek kilit altında sıraya koyun. Eski sürümleri ancak drain ve saklama koşulları sağlanınca temizleyin. Performans için üretim optimizasyonu rehberini kullanın; değişikliklerin doğruluk testlerini hız testlerinden ayrı tutun.
Sürüm manifesti, kaynak ve kodlama ayarları, sağlık sonuçları ve geri dönüş adımları birlikte kaydedilmelidir. Staging’de başarısız dağıtım ve geri dönüşü de prova edin. Böylece sonraki güncelleme, kişisel deneyime veya “hiç kimse fark etmez” varsayımına değil tekrarlanabilir kanıta dayanır.
