چرا صف لاراول اجرا نمی‌شود؟ راهنمای بررسی Queue Worker روی VPS

اگر ایمیل‌ها، گزارش‌ها یا کارهای پس‌زمینه اجرا نمی‌شوند، وضعیت صف لاراول، Worker و خطاهای سرور را به‌ترتیب بررسی کنید.

۲۴ آبان ۱۴۰۵ · ۷ دقیقه مطالعه
چرا صف لاراول اجرا نمی‌شود؟ راهنمای بررسی Queue Worker روی VPS

ابتدا مشخص کنید کارها وارد صف می‌شوند اما پردازش نمی‌شوند، یا اصلاً به صف نمی‌رسند. این تفاوت مسیر بررسی را روشن می‌کند: در حالت اول، وضعیت Worker و اتصال آن مهم است؛ در حالت دوم، باید ارسال Job و تنظیمات برنامه را بررسی کنید.

نشانه معمول این مشکل، انجام نشدن کارهایی مانند ارسال ایمیل سفارش، ساخت گزارش یا پردازش فایل است؛ در حالی که صفحه سایت ظاهراً باز می‌شود. گاهی هم کار اجرا شده، اما به دلیل خطای سرویس ایمیل یا کد برنامه به نتیجه نرسیده است.

پیش از بررسی چه اطلاعاتی جمع کنیم؟

نام عملیاتی را که انجام نشده، زمان تقریبی آن و محیط مربوط را یادداشت کنید. اگر فقط ایمیل یک سفارش ارسال نشده، شماره سفارش را در اختیار مسئول فنی قرار دهید؛ اما اطلاعات پرداخت، رمزها و محتوای حساس را در پیام‌های پشتیبانی منتشر نکنید.

مشخص کنید اختلال از چه زمانی شروع شده است: پس از انتشار نسخه جدید، راه‌اندازی مجدد سرور، تغییر تنظیمات صف یا بدون تغییر مشخص. بررسی تعداد کارهای منتظر و نام صف مورد استفاده نیز، اگر در پنل یا ابزار نظارتی شما نمایش داده می‌شود، مفید است.

اگر قرار است تنظیمات، سرویس‌ها یا داده‌ها را تغییر دهید، ابتدا بکاپ بگیرید. دستورهای بررسی وضعیت در ادامه برای خواندن اطلاعات هستند؛ با این حال، اجرای آن‌ها به دسترسی مناسب سرور نیاز دارد.

نشانه‌ها را از هم جدا کنید

  • کارها در صف منتظر می‌مانند: ممکن است Worker اجرا نباشد، به اتصال یا صف دیگری گوش دهد یا به سرویس صف دسترسی نداشته باشد.
  • کارها وارد بخش کارهای ناموفق می‌شوند: Worker احتمالاً آن‌ها را دریافت کرده، اما اجرای Job با خطا روبه‌رو شده است. جزئیات خطا مسیر بررسی را مشخص می‌کند.
  • هیچ اثری از کار دیده نمی‌شود: ممکن است بخش ارسال Job اجرا نشده باشد، اتصال صف در برنامه متفاوت باشد یا خطا پیش از ثبت کار رخ داده باشد.
  • فقط یک نوع کار مشکل دارد: وابستگی همان کار، مانند سرویس ایمیل، فضای ذخیره‌سازی یا داده ورودی را بررسی کنید.

نبود کار در صف همیشه به معنی موفقیت نیست. ممکن است کار فوراً اجرا شده، به صف دیگری رفته یا پس از خطا از صف خارج شده باشد.

وضعیت Worker را روی سرور بررسی کنید

با حسابی که اجازه مشاهده فرایندها را دارد به VPS وصل شوید و دستور زیر را اجرا کنید:

ps aux | grep '[q]ueue:work'

اگر خروجی مربوط به برنامه خود را می‌بینید، به مسیر پروژه، کاربر اجراکننده و گزینه‌های دستور توجه کنید. وجود فرایند به‌تنهایی ثابت نمی‌کند که کارها درست پردازش می‌شوند. از طرف دیگر، نبود نتیجه هم قطعی نیست: ممکن است پروژه از روش دیگری مانند Horizon استفاده کند یا دستور با شکل متفاوتی اجرا شده باشد.

برای بررسی اینکه مدیریت فرایند بر عهده چه سرویسی است، ابتدا تنظیمات استقرار پروژه را ببینید. اگر از Supervisor استفاده می‌کنید، وضعیت برنامه‌های ثبت‌شده را با دستور زیر بخوانید:

sudo supervisorctl status

وضعیت برنامه مربوط به پروژه را با نامی که در تنظیمات سرور ثبت شده تشخیص دهید. اگر سرویس متوقف یا در حال خطای مکرر است، پیام وضعیت و گزارش همان سرویس را بررسی کنید. ممکن است کاربر شما اجازه اجرای این دستور را نداشته باشد یا Supervisor اصلاً نصب نشده باشد.

اگر مدیریت با systemd انجام می‌شود، این دستور فهرست سرویس‌ها را نشان می‌دهد:

systemctl list-units --type=service --all

نام سرویس صف در هر سرور به تنظیمات آن بستگی دارد. اگر از Horizon استفاده می‌کنید، وضعیت آن را نیز با ابزار و گزارش‌های مربوط به همان نصب بررسی کنید؛ نتیجه جست‌وجوی فرایند عادی برای قضاوت درباره Horizon کافی نیست.

اگر تشخیص سرویس یا دسترسی به گزارش‌ها برایتان دشوار است، می‌توانید از خدمات پشتیبانی وب‌دیتا ۲۴ برای بررسی تنظیمات و خطاها کمک بگیرید.

اتصال و نام صف را با تنظیمات پروژه تطبیق دهید

Worker باید از همان اتصال و صفی کار بگیرد که برنامه Job را به آن می‌فرستد. برای مثال، اگر برنامه کار را در صف مخصوص ایمیل ثبت کند اما Worker فقط صف پیش‌فرض را بخواند، آن کار منتظر می‌ماند؛ حتی اگر فرایند Worker فعال باشد.

نوع اتصال می‌تواند پایگاه داده، Redis یا روش دیگری باشد. تنظیمات فایل محیطی و فایل تنظیمات صف پروژه را با گزینه‌های اجرای Worker مقایسه کنید. در پروژه‌های مختلف ممکن است نام متغیر محیطی یا تنظیمات سفارشی متفاوت باشد. مقدار sync هم یعنی کار به‌صورت هم‌زمان اجرا می‌شود و لزوماً منتظر Worker نمی‌ماند.

اگر تنظیمات تغییر کرده اما رفتار برنامه عوض نشده است، وجود کش تنظیمات و روش استقرار پروژه را بررسی کنید. مقدار فایل محیطی به‌تنهایی ثابت نمی‌کند که برنامه و Worker اکنون همان مقدار را می‌خوانند. تغییر کش یا راه‌اندازی مجدد را بدون هماهنگی انجام ندهید، چون ممکن است بر سرویس در حال استفاده اثر بگذارد.

برای صف مبتنی بر پایگاه داده، دسترسی برنامه به پایگاه و وجود جدول‌های موردنیاز را بررسی کنید. در اتصال Redis نیز وضعیت سرویس، دسترسی شبکه و تنظیمات اتصال اهمیت دارد. برای دیدن تنظیمات واقعی، رمزها یا کلیدهای اتصال را در خروجی عمومی و تیکت‌های غیرامن منتشر نکنید.

خطاهای Job و گزارش‌ها را بخوانید

از پوشه اصلی پروژه، در صورت وجود فایل گزارش پیش‌فرض، می‌توانید آخرین بخش آن را ببینید:

tail storage/logs/laravel.log

محل گزارش ممکن است در پروژه شما متفاوت باشد. زمان خطا را با زمان اجرای عملیات مقایسه کنید و به پیام اصلی و نام Job توجه کنید. خطای اتصال به سرویس ایمیل با خطای دسترسی به فایل یا نبود داده سفارش، راه‌حل یکسانی ندارد. مراقب باشید گزارش‌ها ممکن است اطلاعات شخصی داشته باشند.

بسته به تنظیمات پروژه، فهرست کارهای ناموفق را نیز می‌توانید بررسی کنید:

php artisan queue:failed

اگر این دستور خطا داد، ممکن است روش نگهداری کارهای ناموفق یا ساختار موردنیاز در پروژه متفاوت باشد. خالی بودن فهرست نیز اجرای موفق همه کارها را ثابت نمی‌کند؛ شاید ثبت کار ناموفق غیرفعال باشد یا کار هنوز در صف مانده باشد.

کارهای ناموفق را بدون بررسی دوباره اجرا نکنید. تکرار برخی کارها ممکن است ایمیل تکراری بفرستد، موجودی را تغییر دهد یا عملیات مالی را دوباره آغاز کند. ابتدا بکاپ بگیرید و پیش از هر اقدام، ایمن بودن اجرای مجدد همان Job را با مسئول فنی و کسب‌وکار بررسی کنید.

تغییر را کنترل‌شده اعمال و نتیجه را بررسی کنید

پس از مشخص شدن علت، اصلاح باید متناسب با همان مشکل باشد: برای نمونه، تنظیم صف شنیده‌شده توسط Worker با صف مقصد، رفع دسترسی سرویس صف یا اصلاح خطای کد Job. ابتدا بکاپ بگیرید و تغییر را ترجیحاً در محیط آزمایشی بررسی کنید. اجرای دستی Worker روی محیط اصلی نیز می‌تواند کارهای واقعی و منتظر را پردازش کند؛ آن را صرفاً برای آزمون و بدون بررسی صف اجرا نکنید.

پس از انتشار نسخه جدید، Workerهای قدیمی ممکن است همچنان کد قبلی را در حافظه داشته باشند. روش راه‌اندازی مجدد آن‌ها به ابزار مدیریت پروژه بستگی دارد؛ پیش از این کار مطمئن شوید سرویس مدیریت فرایند، Worker را دوباره بالا می‌آورد و وقفه در پردازش قابل قبول است.

برای تأیید رفع مشکل، یک کار آزمایشی کم‌خطر با ورودی مشخص ثبت کنید. بررسی کنید کار به صف موردنظر رسیده، از حالت انتظار خارج شده و نتیجه مورد انتظار واقعاً ایجاد شده است. سپس گزارش خطا و وضعیت سرویس را بررسی کنید تا مطمئن شوید خطای تازه یا توقف مجدد رخ نداده است.

اگر صف همچنان رشد می‌کند، سرویس مدام متوقف می‌شود، خطای دسترسی نامشخص است یا احتمال تکرار تراکنش وجود دارد، بررسی تخصصی لازم است. در این شرایط می‌توانید از تیم پشتیبانی وب‌دیتا ۲۴ کمک بگیرید.

اگر خطا فقط در ارسال ایمیل فروشگاه ووکامرس دیده می‌شود، راهنمای بررسی ایمیل سفارش و تنظیمات SMTP مراحل تشخیص همان مشکل را توضیح می‌دهد.

مقاله‌های مرتبط