İçeriğe geç
Muhammet Şafak
en

Laravel Queue ve Supervisor ile Asenkron İşlemler

Laravel'de Queue ve Supervisor ile asenkron iş kuyruğu kurulumu: kuyruk sürücüsü seçimi, iş tanımlama, işleri yürütme ve worker'ı ayakta tutmak.

Kısaca

Laravel'in varsayılan kuyruk sürücüsü olan sync işleri aynı istekte çalıştırır; sürücüyü değiştirmeden Queue'dan fayda gelmez. Bu yazıda database sürücüsünü kuruyor, worker'ları Supervisor altında çalıştırıyor ve her deploy'dan sonra yeniden başlatıyorum.

Sunucu odasındaki kavisli ekranda Supervisor worker yapılandırması, üç queue:work süreci ve ProcessOrder günlükleri

Bir web isteğinin tek bir görevi vardır: kullanıcıya hızlı yanıt dönmek. Ama bazı işler hızlı değildir — e-posta göndermek, bir görseli işlemek, üçüncü parti bir API’yi beklemek. Bu işleri istek-yanıt döngüsünün içinde yaparsanız, kullanıcı sizin yavaş işinizi bekler. Laravel Queue tam burada devreye giriyor: işi şimdi sıraya koy, yanıtı hemen dön, asıl işi arka planda yap.

Bu yazıda Laravel’de bir iş kuyruğunu nasıl kurduğumu ve onu production’da ayakta tutmak için Supervisor’ı nasıl kullandığımı anlatıyorum.

Hangi kuyruk sürücüsü seçilmeli?

Laravel Queue; veritabanı, Redis, Amazon SQS gibi farklı sürücülerle çalışır. Sürücü, sıraya alınan işlerin nerede saklanacağını belirler. .env dosyasındaki QUEUE_CONNECTION değeri bunu kontrol eder ve Laravel 10.x Queue dokümanının belirttiği gibi yeni uygulamalarda varsayılan sürücü sync’tir — yani iş hiç sıraya alınmaz, anında çalışır. Geliştirme sırasında pratiktir; ama production’da gerçek bir sürücüye geçmeden Queue’nun hiçbir faydasını görmezsiniz.

Bu yazıda veritabanı sürücüsünü kullanıyorum. Küçük ve orta yükte yeterli, ek bir altyapı gerektirmiyor. İşler jobs tablosunda saklanır; dokümanın tarif ettiği gibi tabloyu oluşturmak için:

php artisan queue:table
php artisan migrate

Bir iş tanımlamak

Kuyruğa atılacak her iş bir sınıftır. Örnek olarak arka planda e-posta gönderen bir SendMailJob oluşturuyorum:

php artisan make:job SendMailJob

Üretilen sınıfı, alacağı parametreleri ve yapacağı işi netleştirerek dolduruyorum:

<?php
namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendMailJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private string $name,
        private string $mail,
    ) {}

    public function handle(): void
    {
        $subject = 'Merhaba ' . $this->name;
        $msg = 'Sitemize üye olduğunuz için teşekkür ederiz!';
        if (!mail($this->mail, $subject, $msg)) {
            throw new \Exception('Mail gönderilemedi.');
        }
    }
}

İki nokta önemli. Birincisi: __construct ile aldığım veriyi sınıfın özelliklerinde saklıyorum — Laravel bu veriyi serialize edip kuyrukta tutuyor, iş çalışınca geri yüklüyor. Bu yüzden constructor’a koca nesneler değil, sade değerler (id’ler, kısa string’ler) vermek iyi bir alışkanlıktır. İkincisi: handle içinde işin başarısız olduğu durumda bir exception fırlatıyorum. Bu isteğe bağlı değil. Doküman şöyle diyor: iş işlenirken bir exception fırlarsa, iş otomatik olarak kuyruğa geri bırakılır ve izin verilen deneme sayısına ulaşana kadar tekrar denenir. İşi kuyruğa elle geri bırakmanın bir yolu daha var — release() — ama sessizce return eden bir job ikisini de yapmaz: kuyruk onu bitmiş kabul eder, başarısız olduğunda bile başarılı sayılır.

İşi kuyruğa atmak tek satır:

\App\Jobs\SendMailJob::dispatch('Muhammet', 'info@muhammetsafak.com');

İşleri yürütmek

Kuyruğa atılan işler kendiliğinden çalışmaz; onları işleyen bir worker gerekir:

php artisan queue:work

Bu komut kuyruğu sürekli dinler ve yeni iş geldikçe işler. Farklı öncelikteki işleri ayırmak isterseniz onQueue() ile adlandırılmış kuyruklar kullanabilir, worker’ı da o kuyruğa yönlendirebilirsiniz:

\App\Jobs\SendMailJob::dispatch($name, $mail)->onQueue('medium');
php artisan queue:work --queue=high,medium,default

Buradaki sıralama önceliği belirler: doküman, bu biçimde başlatılan worker’ın high kuyruğundaki işlere “higher processing priority” verdiğini söylüyor.

Worker’ların ayakta kalması için neden Supervisor gerekir?

queue:work uzun ömürlü bir süreçtir — ve uzun ömürlü süreçler ölür. Bir hata, bir bellek sınırı, bir deploy… worker durur ve kimse fark etmezse kuyruk sessizce birikir. Production’da bu kabul edilemez.

Supervisor, Unix sistemlerde arka plan süreçlerini izleyen ve durduklarında onları yeniden başlatan bir araçtır. Laravel worker’ları için tam da bunu istiyorum.

sudo apt-get update
sudo apt-get install supervisor -y

/etc/supervisor/conf.d/ altına bir yapılandırma dosyası açıyorum:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /proje/yolu/artisan queue:work --queue=default --tries=3
autostart=true
autorestart=true
user=deploy
numprocs=8
redirect_stderr=true
stdout_logfile=/proje/yolu/storage/logs/worker.log
stopwaitsecs=3600

Birkaç satır kritik. autorestart=true, worker öldüğünde onu geri getirir. numprocs=8 sekiz paralel worker çalıştırır — bu sayıyı yükünüze göre ayarlayın. stopwaitsecs=3600, deploy sırasında çalışan bir işin yarıda kesilmemesi için ona bitmesi adına süre tanır: Supervisor dokümanına göre bu değer, sürece durdurma sinyali gönderildikten sonra kapanmasını beklemek için tanınan saniye sayısıdır ve varsayılanı 10’dur — bir saatlik bir işi on saniyede öldürürsünüz. Laravel’in kendi örnek yapılandırması da aynı sebeple 3600 kullanıyor. Yapılandırmayı tanıtıp başlatmak için:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Son bir not

Kod değiştirip deploy ettiğinizde, çalışan worker’lar eski kodu bellekte tutmaya devam eder. Doküman bunu ayrı bir başlık altında uyarıyor: worker’lar uzun ömürlü süreçler olduğu için yeniden başlatılmadıkça kodunuzdaki değişiklikleri fark etmezler. Her deploy’dan sonra php artisan queue:restart çalıştırmayı dağıtım adımlarınıza ekleyin — yoksa “kodu güncelledim ama hâlâ eski davranıyor” diye saatlerce uğraşırsınız. Bunu birkaç kez yaşadıktan sonra öğrendim.

Laravel Queue ve Supervisor birlikte, basit ama sağlam bir asenkron işleme katmanı veriyor: Laravel işi tanımlar ve sıraya koyar, Supervisor da o işi yapan süreçlerin hiç durmamasını sağlar. İkisi de tek başına eksik; değer, birlikte çalışmalarında.

Kuyruk, yukarıdaki Supervisor yapılandırmasındaki --tries=3 ayarında olduğu gibi başarısız işleri yeniden denediğinde, aynı iş birden fazla kez çalışabilir. Güvenilir Event-Driven Sistemler Tasarlamak kitabımın “Retry’ı Doğru Yapmak” ve “Idempotency” bölümleri tam bu noktadan devam ediyor.


Kaynaklar

Sık sorulanlar

6 soru

  • Hangi kuyruk sürücüsü seçilmeli?

    Laravel Queue database, Redis, Amazon SQS ve daha fazlasını destekler; seçim QUEUE_CONNECTION anahtarıyla yapılır. Yeni uygulamalarda varsayılan sync'tir ve işleri anında, aynı istek içinde çalıştırır; yani gerçek bir sürücüye geçene kadar production'da Queue'dan hiçbir fayda görmezsiniz. Ben küçük ve orta ölçekli yükler için ek altyapı gerektirmediğinden database sürücüsünü kullanıyorum.

  • Worker'ların ayakta kalması için neden Supervisor gerekir?

    queue:work uzun süre çalışan bir süreçtir ve uzun süre çalışan süreçler ölür: bir exception, bellek sınırı, bir deployment. Kimse fark etmezse kuyruk sessizce birikir. Supervisor, Unix sistemlerinde arka plan süreçlerini izler ve durduklarında yeniden başlatır.

  • Supervisor'daki temel ayarlar ne işe yarar?

    autorestart=true, ölen worker'ı geri getirir. numprocs=8 sekiz paralel worker çalıştırır; bu sayıyı yükünüze göre ayarlayın. stopwaitsecs=3600, deployment sırasında çalışan bir işe bitmesi için bir saate kadar süre tanır. Supervisor'ın varsayılanı 10 saniyedir ve bir saatlik bir işi öldürürdü.

  • Yeni kod deploy ettikten sonra ne yapmalı?

    Deployment adımlarınıza php artisan queue:restart ekleyin. Worker'lar uzun ömürlü süreçlerdir ve eski kodu bellekte tutar; yeniden başlatmazsanız kodu güncelledim ama davranış hâlâ eski diye saatler harcarsınız.

  • Laravel bir işin başarısız olduğunu nasıl anlar?

    İş başarısız olduğunda handle içinde bir exception fırlatın. Bu isteğe bağlı değil: exception, işin kuyruğa geri bırakılmasını ve izin verilen deneme sayısına ulaşana kadar tekrar denenmesini sağlar. Sessizce return eden bir iş bitmiş sayılır, gerçekte başarısız olsa bile.

  • İşlere nasıl öncelik verilir?

    onQueue() ile adlandırılmış kuyruklar kullanın ve worker'ı --queue=high,medium,default gibi sıralı bir listeyle başlatın. Sıra önceliği belirler; high kuyruğundaki işler daha yüksek işlem önceliği alır.

Bu konuda sorulanlar

Bu konudaki deneyler

Devrazzi'de 0–100 puanı formül veriyor; model yalnızca doğrulama kapısının ardında Türkçe açıklamayı yazıyor. Kararın gerekçesi ve yapım notları.

Şu an ne yapıyor

Yazılım ekosistemindeki release ve güvenlik açığı duyurularını tek akışta toplayıp her olaya 0-100 arası bir önem puanı veriyor ve etkisini Türkçe açıklıyor; deprecation/EOL ve RFC duyurularını da izliyor. Yığınındaki değişikliği her gün yüzlerce kaynağı elle taramadan görmek isteyen yazılım mühendislerinin işine yarar.

Web Laravel PHP PostgreSQL +8 daha
Ekim 2026 — Ekim 2026

Ad-hoc üretim SQL'i onaya, maskelemeye ve değiştirilemez bir ize bağlandı; parola paylaşmak gereksiz kaldı. Yapım notları; deneme QueryProxy oldu.

Şu an ne yapıyor

Geliştiricinin yazdığı SQL'i üretim veritabanında doğrudan değil, bir onaydan geçirerek çalıştırıyor; sonuçlar diske yazılırken maskeleniyor ve her istek değiştirilemez bir kayda düşüyor. Prod erişimi tek kişide toplanmış ekipler kurabilir.

Open-Source Web PHP Laravel Livewire +5 daha
Eylül 2026 — Eylül 2026

Yorumlar

Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.

İlgili Yazılar

Sitede Ara

Yazı, proje ve sayfalarda arama yapmak için yazmaya başlayın.

Esc ile kapat Pagefind ile güçlendirildi