خطای ۵۰۲ در لاراول و VPS؛ علت‌های رایج و روش بررسی

خطای ۵۰۲ را از وضعیت وب‌سرور و PHP-FPM تا گزارش‌های لاراول بررسی کنید و نشانه‌های هر علت را بشناسید.

۲۸ آبان ۱۴۰۵ · ۷ دقیقه مطالعه

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

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

خطای ۵۰۲ در لاراول و VPS چه معنایی دارد؟

در یک تنظیم رایج، درخواست ابتدا به Nginx می‌رسد و برای اجرای کد لاراول به PHP-FPM فرستاده می‌شود. اگر Nginx نتواند با PHP-FPM ارتباط برقرار کند یا پاسخ معتبری از آن بگیرد، ممکن است خطای ۵۰۲ نمایش دهد. البته بسته به تنظیمات، ممکن است وب‌سرور یا واسط دیگری مسئول پاسخ باشد.

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

از روی نشانه‌ها علت احتمالی را محدود کنید

  • اگر همه صفحه‌های پویا هم‌زمان خطا دارند، وضعیت PHP-FPM و ارتباط آن با وب‌سرور را بررسی کنید. اگر فایل‌های ثابت مانند تصاویر نیز در دسترس نیستند، خود وب‌سرور، شبکه یا واسط جلوی آن هم باید بررسی شود.
  • اگر خطا فقط بعد از استقرار نسخه جدید یا تغییر تنظیمات شروع شده است، تغییرهای اخیر در تنظیمات وب‌سرور، PHP و برنامه را در اولویت بگذارید.
  • اگر خطا هنگام گزارش‌گیری یا پردازش درخواست سنگین رخ می‌دهد، به مصرف منابع و گزارش‌های سرویس توجه کنید. البته درخواست طولانی در بسیاری از تنظیمات ممکن است به خطای ۵۰۴ منجر شود، نه الزاماً ۵۰۲.
  • اگر سایت برای بعضی کاربران یا فقط از یک مسیر دسترسی خطا دارد، شبکه، سرویس واسط یا تنظیمات همان مسیر را نیز در نظر بگیرید.

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

مرحله نخست: وضعیت سرویس‌ها را ببینید

اگر به سرور دسترسی ندارید، از شرکت میزبان یا مسئول فنی بخواهید وضعیت وب‌سرور و PHP-FPM را بررسی کند. در صورت دسترسی خط فرمان و استفاده از Nginx، این دستور وضعیت آن را نشان می‌دهد:

sudo systemctl status nginx

برای پیدا کردن سرویس‌های PHP-FPM ثبت‌شده در سرور، از دستور زیر استفاده کنید:

systemctl list-units --type=service --all 'php*-fpm.service'

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

توقف PHP-FPM یک سرنخ مهم است، اما روشن کردن مجدد آن بدون بررسی علت ممکن است فقط مشکل را موقتاً پنهان کند. نشانه‌هایی مانند توقف دوباره سرویس یا خطای تکرارشونده را برای بررسی تخصصی نگه دارید.

مرحله دوم: گزارش‌ها را بخوانید

گزارش وب‌سرور معمولاً نشان می‌دهد ارتباط با سرویس پشت آن چگونه شکست خورده است. برای دیدن گزارش اخیر Nginx در سرورهایی که از systemd استفاده می‌کنند، می‌توانید این دستور را اجرا کنید:

sudo journalctl -u nginx -n 100 --no-pager

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

گزارش لاراول نیز معمولاً در پوشه storage/logs پروژه قرار دارد، هرچند مسیر و روش ثبت گزارش ممکن است تغییر کرده باشد. اگر هم‌زمان با خطا، گزارشی درباره اجرای برنامه وجود دارد، آن را با زمان درخواست مقایسه کنید. نبود گزارش لاراول هم ممکن است نشان دهد درخواست اصلاً به برنامه نرسیده است.

گزارش‌ها می‌توانند اطلاعات حساس داشته باشند. آن‌ها را به‌صورت عمومی منتشر نکنید و پیش از ارسال به فرد پشتیبان، اطلاعات محرمانه را بررسی و حذف کنید.

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

مرحله سوم: ارتباط وب‌سرور و PHP را بررسی کنید

Nginx ممکن است درخواست‌های PHP را از طریق سوکت یا یک آدرس و درگاه محلی به PHP-FPM بفرستد. اگر مسیر تنظیم‌شده در Nginx با مسیر واقعی سرویس یکسان نباشد، یا مجوز دسترسی به سوکت درست نباشد، ارتباط برقرار نمی‌شود.

از مسئول فنی بخواهید مقدار fastcgi_pass در تنظیمات سایت را با تنظیمات سرویس PHP-FPM همان سایت تطبیق دهد. این بررسی به‌ویژه پس از ارتقای PHP، جابه‌جایی سرور یا تغییر فایل تنظیمات اهمیت دارد. تغییر نسخه پیش‌فرض خط فرمان PHP به‌تنهایی ثابت نمی‌کند وب‌سرور نیز از همان نسخه استفاده می‌کند.

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

sudo nginx -t

موفق بودن این آزمون فقط ساختار تنظیمات را تأیید می‌کند؛ ثابت نمی‌کند ارتباط با PHP یا عملکرد سایت درست است. اعمال تنظیمات و بررسی دوباره اتصال باید متناسب با شیوه مدیریت همان سرور انجام شود. برای رفع مشکل سوکت نیز مجوزها را بدون شناخت تغییر ندهید؛ دسترسی بیش از حد می‌تواند امنیت سرور را کاهش دهد.

مرحله چهارم: فضای دیسک و حافظه را کنترل کنید

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

df -h
free -h

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

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

مرحله پنجم: تغییرهای اخیر و واسط‌ها را بررسی کنید

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

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

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

از کجا بفهمیم مشکل حل شده است؟

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

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

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