Lorixen.
AR

رسائل Laravel لا تُرسل: الطابور يعمل بلا عامل queue:work

باختصار: إذا كان موقعك المبني بـ Laravel لا يرسل رسائل تأكيد الطلب أو تقارير PDF أو إشعارات الموظفين، مع أن الكود «يعمل» على جهاز المطور، فتحقق أولاً من وجود عامل طوابير يعمل على الخادم. عندما يضع التطبيق مهمة في الطابور، فهي تنتظر حتى يلتقطها أمر queue:work. توثيق Laravel يوضح أن هذا الأمر يستمر حتى يُوقف يدوياً أو يُغلق الطرفية، وأن تشغيله الدائم في الخلفية يحتاج مراقب عمليات مثل Supervisor. وبعد كل نشر للكود يجب إعادة تشغيل العمال، لأنهم لا يلاحظون التغييرات بعد بدء تشغيلهم.

القصة المعتادة

متجر أدوات منزلية في عمّان أطلق موقعه الجديد. على جهاز المطور كانت رسالة «تم استلام طلبك» تصل فوراً. بعد النقل إلى الخادم، بدأت الشكاوى: زبائن لم تصلهم أي رسالة، وموظف المستودع لا يستلم إشعار الطلبات الجديدة. لا توجد رسالة خطأ في الموقع، والطلب نفسه محفوظ في لوحة التحكم.

عندما فتح المطور قاعدة البيانات وجد جدول المهام ممتلئاً بمئات المهام التي لم تُنفذ. الرسائل لم تفشل، بل لم يحاول أحد إرسالها أصلاً.

هذا مثال توضيحي لحالة شائعة، وليس وصفاً لمتجر حقيقي.

كيف تعمل الطوابير في Laravel؟

بدلاً من إرسال البريد أثناء ضغط الزبون على زر «تأكيد الطلب»، يضع التطبيق مهمة اسمها مثلاً «أرسل رسالة التأكيد» في طابور. الصفحة تنتهي بسرعة، والزبون لا ينتظر. ثم يأتي «عامل» يعمل في الخلفية، يأخذ المهام واحدة واحدة وينفذها.

هذا يعني أن هناك جزأين يجب أن يعملا معاً:

  1. الطابور نفسه: مكان تُخزن فيه المهام، مثل جدول في قاعدة البيانات أو خدمة Redis. التوثيق يذكر أن جدول المهام لمحرك قاعدة البيانات موجود عادة في ملفات الترحيل الافتراضية، وإذا لم يكن موجوداً يمكن إنشاؤه بأمر make:queue-table ثم تشغيل الترحيل.
  2. العامل: عملية تعمل باستمرار بأمر php artisan queue:work.

إذا كان الجزء الأول موجوداً والثاني غائباً، تتراكم المهام بصمت.

لماذا كانت تعمل عند المطور؟

هناك احتمالان شائعان. الأول أن المطور كان يشغل queue:work في نافذة طرفية مفتوحة على جهازه أثناء التجربة، والتوثيق يقول إن هذا الأمر يستمر حتى يُوقف يدوياً أو تُغلق الطرفية. على الخادم، لم يشغله أحد.

الاحتمال الثاني أن إعداد الطابور على جهاز المطور كان «متزامناً»، أي أن المهام تُنفذ فوراً داخل الطلب نفسه دون طابور حقيقي. على الخادم تغير الإعداد إلى قاعدة البيانات أو Redis، فأصبحت المهام تحتاج عاملاً منفصلاً. التوثيق يشير إلى فرق مهم هنا: المهام المتزامنة التي تفشل لا تُخزن في جدول المهام الفاشلة، بل تُعالج أخطاؤها فوراً في التطبيق. لذلك قد لا تلاحظ نفس الأعطال في البيئتين.

الإصلاح: عامل يعمل دائماً، ويعود إذا توقف

لا يكفي أن يدخل المطور إلى الخادم ويكتب الأمر مرة واحدة. عند انقطاع الاتصال أو إعادة تشغيل الخادم سيتوقف العامل. توثيق Laravel يوصي باستخدام مراقب عمليات مثل Supervisor لضمان ألا يتوقف العامل، ويصف Supervisor بأنه مراقب عمليات لنظام لينكس يكتشف خروج عمليات queue:work ويعيد تشغيلها تلقائياً، ويسمح أيضاً بتحديد عدد العمال الذين يعملون في الوقت نفسه.

اطلب من المطور أو من مزود الاستضافة:

  • تأكيد نوع الطابور المستخدم على الخادم: قاعدة بيانات أم Redis أم غيره.
  • إعداد مراقب عمليات يشغل queue:work باستمرار، وفق قسم إعداد Supervisor في التوثيق.
  • تحديد عدد العمال المناسب لحجم الطلبات، دون مبالغة على خادم صغير.
  • إضافة خطوة إعادة تشغيل العمال إلى خطوات النشر.

لا تنسَ إعادة التشغيل بعد كل نشر

هذه نقطة يغفل عنها كثيرون. التوثيق يذكر أن عمال الطوابير عمليات طويلة العمر تحفظ حالة التطبيق في الذاكرة، وبالتالي لا تلاحظ التغييرات في الكود بعد بدء تشغيلها. لذلك يجب إعادة تشغيلهم أثناء النشر، والطريقة الأبسط هي أمر php artisan queue:restart، الذي يطلب من كل العمال الخروج بهدوء بعد إنهاء المهمة الحالية.

مثال توضيحي لما يحدث عند نسيان هذه الخطوة: المطور يعدّل نص رسالة التأكيد ليضيف رقم هاتف خدمة العملاء، وينشر التعديل، ثم يختبر بنفسه فيجد الرسالة القديمة. السبب أن العامل ما زال يعمل بالنسخة القديمة من الكود في ذاكرته. وإذا كان التعديل يغير شكل البيانات، قد تبدأ المهام بالفشل بطريقة يصعب فهمها.

راقب المهام الفاشلة بدل أن تكتشفها من الزبائن

حتى مع وجود عامل، بعض المهام ستفشل: خادم البريد لا يرد، أو ملف ناقص. التوثيق يشرح أن المهمة غير المتزامنة التي تتجاوز عدد المحاولات المسموح تُدرج في جدول failed_jobs، وأن أمر queue:failed يعرض المهام الفاشلة مع معرفها واتصالها والطابور ووقت الفشل. ويمكن تحديد عدد المحاولات بخيار ‎--tries‎ عند تشغيل العامل، ما لم تحدد المهمة عدداً خاصاً بها.

اقتراح عملي: اطلب أن يُراجع جدول المهام الفاشلة بانتظام، أو أن يُرسل تنبيه داخلي عندما يظهر فيه شيء جديد. الأفضل أن تعرف أنت قبل أن يتصل بك زبون يسأل أين رسالته.

علامات مبكرة تدل على المشكلة

لا تنتظر شكوى زبون. هذه علامات يمكن أن يلاحظها صاحب العمل أو موظف خدمة العملاء:

  • طلبات جديدة تظهر في لوحة التحكم، لكن موظف المستودع لم يستلم إشعارها.
  • رسائل تصل دفعة واحدة بعد ساعات، عندما يشغل أحدهم العامل يدوياً.
  • تقارير يومية تُطلب من النظام ولا تصل إلا بعد تدخل المطور.
  • تعديلات على نصوص الرسائل لا تظهر إلا بعد إعادة تشغيل الخادم.

إذا لاحظت واحدة منها، فاسأل عن العامل قبل أي شيء آخر.

كيف تتحقق من الإصلاح؟

  1. اطلب طلباً تجريبياً من الموقع.
  2. تأكد أن المهمة لم تبقَ معلقة في جدول المهام.
  3. تأكد أن الرسالة وصلت إلى بريدك فعلاً.
  4. أعد تشغيل الخادم في وقت مناسب، ثم كرر التجربة لتتأكد أن العامل عاد للعمل وحده.
  5. انشر تعديلاً صغيراً على نص الرسالة، وتأكد أن النص الجديد هو ما يصل.

ماذا عن الاستضافة المشتركة؟

بعض خطط الاستضافة المشتركة لا تسمح بعمليات تعمل باستمرار في الخلفية، أو لا تتيح تثبيت مراقب عمليات. في هذه الحالة، اسأل مزود الاستضافة عن الخيارات المتاحة قبل الاعتماد على الطوابير في رسائل مهمة. قد يكون الأنسب نقل التطبيق إلى خادم يسمح بذلك، أو تقليل الاعتماد على الطوابير في الرسائل الحرجة إلى أن تُحل المسألة. المهم أن يكون القرار واضحاً، لا أن تكتشف بعد الإطلاق أن نصف رسائلك لا تخرج.

أسئلة شائعة

ليش إيميلات تأكيد الطلب ما بتوصل من موقع Laravel؟

قد تكون المهام في الطابور ولا يوجد عامل يشغلها. تحقق من وجود queue:work يعمل باستمرار على الخادم.

شغّلت queue:work وبعدين وقف، ليش؟

لأنه يستمر فقط حتى تُغلق الطرفية أو يُوقف. التوثيق يوصي بمراقب عمليات مثل Supervisor ليبقى يعمل.

عدّلت نص الرسالة وما تغيّر، ليش؟

العمال لا يلاحظون تغييرات الكود بعد تشغيلهم. أعد تشغيلهم بأمر queue:restart بعد النشر.

وين بشوف الرسائل اللي فشلت؟

في جدول failed_jobs، ويعرضها أمر queue:failed مع وقت الفشل وتفاصيل أخرى.

إذا كانت رسائل موقعك المبني بـ Laravel تتأخر أو لا تخرج أبداً، تواصل معنا ونفحص الطوابير والعمال معك.

المصادر

WhatsAppاحجز مكالمة