Kaynak: hafiz.dev
Bir multi-tenant Laravel uygulamanız geliştirme ortamında mükemmel çalışıyor. Tüm testler geçiyor. Üretime geçiriyorsunuz, ilk on müşterinizi alıyorsunuz ve her şey yolunda görünüyor. Sonra bir sabah, bir müşteri başka birinin gösterge panelindeki verileri içeren bir ekran görüntüsüyle size e-posta atıyor.
Bu bir varsayım değil, doğru önlemler olmadan multi-tenancy ve queue sistemlerinin çakışması durumunda başınıza gelebilecek bir durum. Queue worker’lar uzun süreli daemon’lar olduğundan, HTTP taleplerinin aksine (her ziyaretçi için taze başlayan), bir queue worker bir kez çalışır ve yüzlerce işi sırayla işler. Bir işten kalan herhangi bir tenant durumu, bir sonraki işe sızar.
Multi-tenant Laravel SaaS uygulamalarında karşılaştığım üç özel hata var. Bunlar sessizdir, yerel geliştirme ortamında istisna fırlatmazlar, test setinizi başarısız kılmazlar. Ancak üretim ortamında tenantlar arasında veri sızdırabilirler. İşte bunlar ve bunların nasıl düzeltileceği hakkında bilgiler.
Hata 1: Queued Job’larda Tenant Bağlamı Kaybolur
Hata 1: Queued Job’larda Tenant Bağlamı Kaybolur
Bu klasik bir hatadır ve en korkutucu olanıdır çünkü sessizce başarısız olur.
Bir controller’dan bir iş (job) gönderdiğinizde Tenant A aktif durumdadır. Job sıraya alınır. Bir worker birkaç saniye sonra bunu alır. Ancak worker süreci, o işi hangi tenant’ın gönderdiğini bilmez. Merkez (landlord) bağlamında çalışıyor ya da daha kötüsü, önceki işten kalan geçersiz bir bağlamı tutmaya devam ediyor.
Veri sızıntısına neden olan akış şu şekildedir:
Problem, SerializesModels kullanıyorsanız daha da kötüleşir. Laravel’in model serileştirmesi, modelin kimliğini ve sınıf adını saklar, ardından job çalıştığında modeli yeniden doldurur. Ancak yeniden doldurma işlemi newQueryForRestoration() çağrısını yapar ve bu da tüm küresel kapsayıcıları uygular, bunlar arasında BelongsToTenant kapsayıcınız bulunur. Bu kapsayıcı tenant_id ile filtrelemeye çalışır, ancak tenant_id null olduğu için (henüz aktif bir tenant yoksa) sorgu hiçbir şey döndürmez. ModelNotFoundException. İşiniz başarısız olur, ancak gerçek neden yanıltıcı bir hata mesajının altında gömülüdür.
En kötü kısım? Bu hata testlerde asla ortaya çıkmaz. Çoğu test paketi Queue::fake() veya sync sürücüsünü kullanır, bu da işleri tanımlayıcı dönüşüm olmadan çalıştırır. Hata sadece gerçek bir queue worker ile ortaya çıkar.
Üretimde de bunun tespit edilmesi zordur. Eğer modelleriniz tenant-scope’lı küresel kapsayıcıları kullanmıyorsa, istisnalar bile almayacaksınız. İş, merkez veritabanında sorgu yapmaya devam eder, hiçbir şey bulamaz (ya da yanlış tenant’ın verisini bulur) ve “başarıyla” tamamlanır. Sorunun yalnızca bir müşteri, kendisine ait olmayan verileri gördüğünde fark edilecektir. Daha kötüsü, bu durumu fark etmeyip rapor etmeyen müşteriselere sahip olursunuz.
Bunu bir müşteri fark etmeden önce tespit etmenin yolu, üretim aşamasında her tenant işinin handle() metodunun başına bir doğrulama kontrolü eklemektir:
public function handle(): void
{
if (! tenant()) {
report(new \RuntimeException(
"Job " . static::class . " ran without tenant context. "
. "Expected tenant: {$this->tenantId}"
));
$this->fail();
return;
}
// Gerçek iş mantığıyla devam et...
}
Bu, hata izleyicinizde sessiz veri sızıntısı yerine erken bir uyarı sağlar. Bootstrapper’ınızın düzgün çalıştığını doğruladıktan sonra bunu kaldırabilirsiniz.
Çözüm
Çözüm
Çözüm
İki büyük tenancy paketi bununla başa çıkabiliyor, ancak bunu açık bir şekilde etkinleştirmeniz gerekiyor.
stancl/tenancy (v3.10) ile:
QueueTenancyBootstrapper‘ı config/tenancy.php dosyanızda etkinleştirin:
'bootstrappers' => [
Stancl\Tenancy\Bootstrappers\DatabaseTenancyBootstrapper::class,
Stancl\Tenancy\Bootstrappers\CacheTenancyBootstrapper::class,
Stancl\Tenancy\Bootstrappers\QueueTenancyBootstrapper::class, // Bunu ekleyin
],
Bu, mevcut tenant’ın kimliğini iş yüküne serileştirir ve iş başlamadan önce tenant bağlamını geri getirir. Ancak bir sorun var. Bootstrapper, SerializesModels modelinizi yeniden doldurmaya çalışmadan sonra ateşlenir. Bu nedenle, tenant-scope’lı Eloquent modelleri doğrudan iş constructor’larına geçmeyin. Bunun yerine ID’yi geçin:
// Kötü: model yeniden doldurma, tenant bağlamı geri getirilmeden önce çalışır
class ProcessInvoice implements ShouldQueue
{
public function __construct(public Invoice $invoice) {}
}
// İyi: ID'yi geçin, handle() içinde sorgulayın
class ProcessInvoice implements ShouldQueue
{
public function __construct(public int $invoiceId) {}
public function handle(): void
{
// Bu noktada tenant bağlamı aktiftir
$invoice = Invoice::findOrFail($this->invoiceId);
// İşle...
}
}
spatie/laravel-multitenancy (v4.1) ile:
queues_are_tenant_aware_by_default ayarını true olarak config/multitenancy.php dosyasında ayarlayın. Ya da bireysel işlerde TenantAware işaretçi arayüzünü uygulayın:
use Spatie\Multitenancy\Jobs\TenantAware;
class ProcessInvoice implements ShouldQueue, TenantAware
{
// Bu iş otomatik olarak doğru tenant bağlamında çalışacaktır
}
Merkezi bağlamda kesinlikle çalışması gereken işler NotTenantAware arayüzünü uygulayabilir. Aynı SerializesModels uyarısı burada da geçerlidir: kimlikleri geçin, modelleri değil.
Hata 2: Tenantlar Arasında Cache Anahtar Çatışmaları
Hata 2: Tenantlar Arasında Cache Anahtar Çatışmaları
Bu hata, ilk olandan daha sessizdir. Hiçbir istisna, başarısız iş yok. Sadece kimsenin fark etmediği haftalarca yanlış sayılar.
Bir gösterge paneli istatistiğini кешediğinizi düşünün:
Cache::put('monthly_revenue', $total, now()->addHour());
O anahtar, monthly_revenue, her tenant için aynı dizedir. Eğer Tenant A’nın bir queue işi bir raporu işleyip sonucu önbelleğe alıyorsa, Tenant B aynı önbellek anahtarını okuduğunda Tenant A’nın gelir rakamını görür.
Görünür çözüm, her cache anahtarını tenant kimliği ile manüel olarak ön eklemektir. Ancak bu, en az bir yerde unuttuğunuzda hataya yol açabilir. Daha iyi bir çözüm, tenancy paketinin ön eklemeyi küresel olarak yönetmesine izin vermektir.
Çözüm
Çözüm
Çözüm
stancl/tenancy ile:
CacheTenancyBootstrapper (Hata 1’de gösterilen konfigürasyon) otomatik olarak tüm cache anahtarlarının başına tenant’ın kimliğini ekler. Her Cache::get() ve Cache::put() çağrısı şeffaf bir şekilde kapsamlandırılır. Uygulama kodunuzu hiç değiştirmezsiniz.
Ama bu otomatik olarak yakalanmayan bazı kenar durumlarına dikkat edin:
// Bu şekilde manüel tenant kapsamı gereklidir:
// 1. Redis kilitleri
Cache::lock("report_generation_{$tenant->id}", 30);
// 2. Oran sınırlandırma anahtarları
RateLimiter::attempt("api_{$tenant->id}_{$user->id}", 60, fn() => true);
// 3. Laravel Scout arama dizinleri
// Tenant'e özel dizin adları veya filtrelenebilir tenant_id özelliği kullanın
// 4. spatie/laravel-permission önbelleği
// config/permission.php'de tenant'a özel bir önbellek anahtarı ayarlayın
spatie/laravel-multitenancy ile:
Tenant anahtarlarını öneklemek için PrefixCacheTask‘ı geçiş tenant görevlerinize ekleyin:
// config/multitenancy.php
'switch_tenant_tasks' => [
\Spatie\Multitenancy\Tasks\SwitchTenantDatabaseTask::class,
\Spatie\Multitenancy\Tasks\PrefixCacheTask::class, // Bunu ekleyin
],
Bu, hafıza tabanlı depolama için cache anahtarlarını önekler, örneğin Redis ve APC. Aynı kenar durumları yine geçerlidir: kilitler, oran sınırlayıcılar ve üçüncü taraf paket önbellekleri için manüel dikkat gereklidir.
Bir şey daha. Eğer bir multi-tenant yapılandırmasında Laravel Octane çalıştırıyorsanız, ek bir riskiniz var. Octane, aynı uygulama örneğini talepler arasında yeniden kullanır. Önceki talebin tenant’ının geçersiz bir cache ön eki, bir sonraki talebe sızabilir, eğer bootstrapper talepler arasında düzgün sıfırlanmazsa.
Ön bellek, tenant’lar arasında sızıntılara yol açan tek yer değildir. Wildcard alan adlarında (örneğin *.yourapp.com) oturum çerezleri bir tenant’ın alt alanındaki oturumun diğer tenant’ın alt alanında çalışmasına izin verebilir. Doğrulama kuralları gibi Rule::unique('users', 'email') tam tabloyu kontrol eder, bunun için bir where koşulu ile kapsamlandırmalısınız. Aynı kurumsal proxy arkasındaki tenant’lar, IP adreslerine dayalı oran sınırlama anahtarlarında oran sayaçlarını paylaşır. Bunlar doğrudan queue’ya özgü hatalar değildir, ancak bir queued job bir oturumdan okuduğunda veya tenant kapsamı olmadan bir doğrulama kuralı uyguladığında karmaşıklaşır.
Hata 3: Başarısız Job Yeniden Denemeleri Yanlış Tenant’ta Çalıştırılır
Hata 3: Başarısız Job Yeniden Denemeleri Yanlış Tenant’ta Çalıştırılır
Tenancy bootstrapper’ınız, tenant kimliğini iş yüküne serileştirir. İşler doğru bir şekilde gönderilir ve işlenir. Kapsamınızın bitmiş olduğunu düşünürsünüz. Sonra bir iş başarısız olur.
Bu hatanın özellikle kötü olduğunu belirtmek gerekir, çünkü görünmesi zaman alır. Hata 1 ve 2, dikkat ederseniz hemen ortaya çıkabilir. Ama Hata 3 yalnızca bir iş gerçekten başarısız olduğunda ve ardından yalnızca birisi bunu yeniden denediğinde tetiklenir. Çoğu SaaS uygulaması, ilk birkaç ayında sağlam bir yeniden deneme çalışma akışına sahip değildir. İşlerin çalışması için odaklanırlar, hatalardan kurtarma üzerine değil. Yani bu hata, ilk dış API zaman aşımında veya bir veritabanı bağlantısının kesilmesinde bekleyerek uğursuz bir şekilde ortaya çıkar.
Laravel, başarısız işleri failed_jobs tablosuna kaydeder. php artisan queue:retry 5 şeklide yeniden çalıştırmak istediğinizde, yapı çerçevesi serileştirilmiş yükü alır, tüm işi yeniden oluşturur ve tekrar gönderir. Ama işte sorun şu: yeniden deneme mekanizması, ilk gönderim yapıldığı gibi tenant bootstrapper’ın ateşlenmesini sağlamaz.
spatie/laravel-multitenancy ile: Bu, önceki sürümlerde onaylanmış bir hata‘ydı. Tenant kimliği yük içinde yer alıyordu, ancak yeniden deneme yolu iş, tenant bağlamını geri yükleme işlemini gerçekleştirmedi. İş, worker’ın o sırada hangi tenant bağlamında çalıştığı ile çalışır, bu da merkezi veritabanı ya da tamamen farklı bir tenant olabilir.
Çözüm
Çözüm
Çözüm
Düzeltme, uyguladığınız paket sürümüne bağlı olarak değişir.
stancl/tenancy v3.10 ile: QueueTenancyBootstrapper son sürümlerde yeniden denemeleri doğru bir şekilde ele alır. Tenant kimliği, iş yükünün en üst düzeyinde saklanır ve yeniden deneme sırasında geri yüklenir. Bir başarısız iş yükünün yüküne bakarak bunu doğrulayın:
$failed = DB::table()->find(5);
$payload = json_decode($failed->payload, true);
// Yükün en üst düzeyinde bir tenant_id anahtarının olması gerektiğini göreceksiniz
dd($payload[]); // Null olmamalıdır
Eğer tenant_id yükten eksikse, bootstrapper’ınız doğru bir şekilde yapılandırılmamış demektir. Hata 1’e geri dönün ve QueueTenancyBootstrapper‘ın bootstrapper dizinizde olduğunu doğrulayın.
spatie/laravel-multitenancy v4.1 ile: V4’de MakeQueueTenantAwareAction bunu doğru bir şekilde ele alır. Ancak daha eski bir sürümde iseniz, yeniden deneme olayını manüel olarak dinleyebilirsiniz:
// Bir servis sağlayıcısında
use Illuminate\Queue\Events\JobRetryRequested;
Event::listen(JobRetryRequested::class, function ($event) {
$payload = $event->payload();
$tenantId = $payload[] ?? null;
if ($tenantId) {
$tenant = Tenant::find($tenantId);
$tenant?->makeCurrent();
}
});
Yeniden denemeleri doğru bir şekilde test etme:
Bu, çoğu ekibin atladığı kısımdır. Queue::fake() kullanarak yeniden denemeleri test edemezsiniz. Gerçek bir queue sürücüsü kullanan bir entegrasyon testi yapmanız gerekir, bir iş göndermeniz ve kasıtlı olarak başarısız olmasını sağlamanız, ardından bunu yeniden denemeniz ve tenant bağlamını doğrulamanız gerekir:
it(, function () {
$tenant = Tenant::factory()->create();
$tenant->makeCurrent();
// İlk denemede başarısız olacak bir iş gönderin
dispatch(new FailOnceJob($tenant->id));
// Kuyruğu işleyin (iş başarısız olur)
Artisan::call(, [=> true]);
// Başarısız işi yeniden deneme
Artisan::call(, [=> ]);
// Tekrar işleyin (doğru tenant bağlamında başarılı olmalı)
Artisan::call(, [=> true]);
// İşin doğru tenant'ta çalıştığını doğrula
expect(DB::connection()->table()->count())->toBe(1);
});
Denetim Kontrol Listesi
Denetim Kontrol Listesi
Eğer bir multi-tenant Laravel uygulaması çalıştırıyorsanız, hemen yapabileceğiniz hızlı bir denetim:
Job’lardaki tenant bağlamı: Tenant bağlamında bir iş gönderin, database veya redis sürücüsü (değil sync). İşin doğru tenant’ın verileri üzerinde çalıştığını kontrol edin. Eloquent modellerini job constructor’larına geçiriyorsanız, ID’leri geçmekte geçiş yapın.
Önbellek izolasyonu: Tenant A olarak tinker açın, Cache::put('test', 'tenant-a') çalıştırın. Tenant B’ye geçin, Cache::get('test') çalıştırın. Eğer tenant-a alıyorsanız, önbelleğiniz kapsamlı değildir. Önbellek bootstrapper’ını veya prefix görevini etkinleştirin.
Başarısız iş yeniden denemeleri: Kasıtlı olarak bir tenant işini başarısız hale getirin, bir dakika bekleyin, queue:retry all çalıştırın. Yeniden denenen işin hangi tenant veritabanını vurduğunu kontrol edin. Yanlışsa, paket sürümünüzü ve bootstrapper yapılandırmasını kontrol edin.
Kuyruk topolojisi: Eğer bir tenant büyük bir CSV ihracatı işini başlatıyorsa, bu diğer tüm tenantların işlerindeki engellemeyi sağlar mı? Bir tenant’ın yükünü diğerlerini aç bırakmaktan kaçınmak için ağır işlemler için ayrı kuyruklar ayırmayı düşünün.
Worker yeniden başlatma sıklığı: Kuyruk worker’lar bellekte durumu tutar. Eğer bir tenancy yapılandırma değişikliği yayımlarsanız ama worker’ları yeniden başlatmazsanız, eski yapılandırma aktif kalır. Her zaman dağıtım sırasında php artisan queue:restart çalıştırın. Üretimde, dağıtımda worker’ları nazikçe yeniden başlatabilen bir süreç yöneticisi (örneğin Supervisor) kullanın.
SSS
SSS
Bu sorunlar için stancl/tenancy veya spatie/laravel-multitenancy’ye ihtiyacım var mı?
Kesinlikle gerekli değil. Tenant’a özel queuelar oluşturmak için her işin içinde tenant kimliğini saklayarak ve handle()‘da bağlamı geri getirerek bunu manuel olarak oluşturabilirsiniz. Ancak, paketler bunun serileştirilmesi, bağlamın geri yüklenmesi ve önbellek kapsamının ayarlanmasını otomatikleştirir. Çoktan bunlardan birini multi-tenancy uygulamanız için kullanıyorsanız, kuyruk desteğini etkinleştirmek birkaç satırlık konfigürasyon gerektirir.
Bu hataları önlemek için sync kuyruk sürücüsünü kullanabilir miyim?
Teknik olarak evet, çünkü sync sürücüsü işleri aynı talepten işleyerek, bu yüzden tenant bağlamı her zaman mevcut olur. Ancak, sync sürücüsü talepten iş tamamlanana kadar bekler, bu da queue kullanmanın amacını bozar. Bu hatalar yalnızca asenkron sürücülerle (veri tabanı, Redis, SQS) ortaya çıkıyor ki bunlar, üretimde kullanacağınız türlerdir.
Laravel Horizon, tenant’a özel kuyruklar için yardımcı olur mu?
Horizon, kuyruklarınızda neler olduğunu görmemize olanak tanır, ancak tenant bağlamını kendisi işleme almaz. Hala bağlamın geri yüklenmesi için tenancy paketinin kuyruk bootstrapper’ına ihtiyacınız vardır. Ancak, Horizon’un kuyruk dengelemesi ve izlenmesi, bir tenant’ın işlerindeki yoğunluğun ne zaman baskın çıktığını görmek için faydalıdır.
Veritabanı başına tenant yapıları için? İş tablosu her tenant için mi yoksa merkezi mi?
jobs ve failed_jobs tablolarını merkezi (landlord) veritabanında tutun. Eğer tenant veritabanlarında tutarsanız, kuyruk worker’ı bir işi aldığında hangi tenant veritabanına bağlanacağını önceden bilmez. Hem stancl/tenancy hem de spatie/laravel-multitenancy, yüklenmiş tenant bağlamı ile merkezi iş depolamasını önerir.
Her tenant için ayrı kuyruk worker’ları mı çalıştırmalıyım?
Çoğu uygulama için hayır. Tenant bağlamında yük altında paylaşımcı bir worker havuzu iyi çalışır. Her tenant için ayrı worker’ların yalnızca katı kaynak izolasyonu gereksinimleriniz olduğunda veya bir tenant’ın aşırı farklı iş hacmi olduğunda anlam kazandığını düşünebilirsiniz. Düzensizliği yönetmek genellikle ilk yıl içindeki karmaşıklıktan daha değerli değildir.
Sonuç
Sonuç
Multi-tenancy ve kuyruklar, bireysel olarak çözümleri olan durumlardır. Hatalar, “tenant bağlamı HTTP talebi sırasında mevcuttur” ile “tenant bağlamının arka planda çalışan bir worker’da da mevcut olması gerekir” arasındaki kesitte bulunur. Üç hata da aynı temel nedenden kaynaklanır: queue worker’lar uzun ömürlü süreçlerdir ve web taleplerinin yaptığı gibi taze bir bağlam almazlar.
İyi bir haber ise, stancl/tenancy (v3.10) ve spatie/laravel-multitenancy (v4.1) bu üçü için de mükemmel çözümler sunar. Ancak, bunu etkinleştirmeniz, gerçek bir kuyruk sürücüsü ile test etmeniz ve önbellek anahtarlarınızı denetlemeniz gerekiyor. Eğer Laravel üzerinde multi-tenant bir SaaS geliştiriyorsanız ve kuyruk katmanınızı doğru yapmak istiyorsanız, bizimle iletişime geçebilirsiniz.
Kaynak: Orijinal Makale
