Laravel Queue Çalışmıyor: Supervisor ile Kalıcı Worker Kurulumu

Laravel’de mail veya arka plan işi kuyruğa düşüyor ama sayfa yenilenmeden çalışmıyorsa genellikle worker süreci açık değildir. Terminalde php artisan queue:work çalıştırınca düzelip SSH bağlantısı kapanınca tekrar durması da aynı sorunun işaretidir.

Üretimde worker’ı terminal oturumuna bağlı bırakmak yerine Supervisor gibi bir süreç yöneticisi kullanıyorum. Ubuntu’da kurulum:

sudo apt update
sudo apt install supervisor

Örnek /etc/supervisor/conf.d/laravel-worker.conf dosyası:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/proje/artisan queue:work --sleep=3 --tries=3 --timeout=120
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/proje/storage/logs/worker.log
stopwaitsecs=3600

Yolları ve kullanıcıyı kendi sunucunuza göre düzenledikten sonra:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

Worker çalışıyor göründüğü halde işler ilerlemiyorsa .env içindeki QUEUE_CONNECTION değerini ve ilgili sürücüyü kontrol etmek gerekiyor. Database queue kullanılıyorsa jobs tablosu, Redis kullanılıyorsa bağlantı ve parola ayarları doğru olmalı. Yapılandırma değiştirdikten sonra eski cache yüzünden worker hâlâ önceki değeri kullanabilir:

php artisan optimize:clear
php artisan queue:restart

Deploy sırasında queue:restart çalıştırmak önemli. Queue worker uzun yaşayan bir PHP sürecidir; yeni kodu her istekte yeniden yüklemez. Restart sinyali mevcut işi güvenli biçimde tamamladıktan sonra sürecin yenilenmesini sağlar, Supervisor da tekrar ayağa kaldırır.

Başarısız işleri görmek için:

php artisan queue:failed
php artisan queue:retry all

Retry yapmadan önce gerçek hatayı logdan düzeltmek gerekir; aksi halde aynı iş tekrar tekrar düşer. timeout, retry_after ve işin kendi çalışma süresi birbiriyle uyumlu olmalı. Aksi durumda aynı job iki kez işlenebilir.

cPanel ortamında Supervisor erişimi yoksa cron ile queue:work --stop-when-empty çalıştırmak geçici bir seçenek olabilir, fakat yoğun sistemlerde gerçek process manager daha güvenilir.

Queue süreçlerini yalnızca “running” durumuyla takip etmek yeterli değil. Kuyrukta bekleyen iş sayısı, en eski işin yaşı ve failed job artışı için alarm kurmak gerekiyor. Worker çalışıyor görünürken belirli bir job sonsuz retry döngüsüne girebilir. İşleri idempotent tasarlamak, aynı ödeme veya bildirim görevinin iki kez çalışması halinde veri bozulmasını önleyen önemli bir güvenlik ağıdır.

Siz queue için Redis mi database sürücüsü mü kullanıyorsunuz? Worker durduğunda Supervisor logunda hangi hata görünüyor?