خطای ۵۰۲ Bad Gateway و ۵۰۴ Gateway Timeout؛ علت‌ها و رفع

خطاهای 502 Bad Gateway و 504 Gateway Timeout معمولاً در بدترین زمان ظاهر می‌شوند: وسط یک کمپین فروش یا وقتی سایت شلوغ است. هر دو یک پیام مشترک دارند: سروری که درخواست را دریافت کرده (معمولاً Nginx، CDN یا Reverse Proxy) نتوانسته پاسخ درستی از سرویس پشت خود بگیرد. در این راهنما تفاوت این دو خطا، علت‌های رایج و روش قدم‌به‌قدم رفع آن‌ها را روی VPS و هاست توضیح می‌دهیم.

۵۰۲ و ۵۰۴ چه تفاوتی دارند؟

• 502 Bad Gateway: واسطه پاسخ نامعتبر گرفته یا اصلاً نتوانسته وصل شود؛ مثلاً PHP-FPM خاموش است، کرش کرده یا اتصال را رد کرده است.
• 504 Gateway Timeout: واسطه وصل شده، اما سرویس پشتی در زمان مجاز پاسخ نداده؛ مثلاً یک کوئری سنگین دیتابیس یا یک API خارجی کند.

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

خطا از کدام لایه است؟

یک درخواست ممکن است از چند واسطه عبور کند: CDN › Nginx › PHP-FPM یا اپلیکیشن Node.js › دیتابیس. صفحه خطا معمولاً نشان می‌دهد کدام لایه آن را تولید کرده است:

• صفحه خطای با برند CDN یعنی CDN نتوانسته به سرور شما برسد یا پاسخ درستی بگیرد.
• صفحه ساده «nginx» یعنی Nginx سرور شما نتوانسته از سرویس پشتی پاسخ بگیرد.

با مفهوم این واسطه‌ها در مقایسه وب‌سرورها آشنا شوید.

لاگ‌ها چه می‌گویند؟

sudo tail -n 50 /var/log/nginx/error.log

علت ۱: PHP-FPM متوقف یا اشباع شده

systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50
sudo grep -i "max_children" /var/log/php8.3-fpm.log

• اگر سرویس متوقف است، آن را ری‌استارت کنید و علت توقف را در لاگ پیدا کنید؛ اغلب کمبود حافظه است.
• پیام «server reached pm.max_children» یعنی همه فرایندهای PHP مشغول‌اند و درخواست‌های جدید پشت صف می‌مانند.

افزایش pm.max_children فقط وقتی درست است که RAM کافی داشته باشید: حداکثر تعداد ≈ RAM آزاد برای PHP تقسیم بر مصرف میانگین هر فرایند. افزایش بی‌حساب باعث تمام شدن حافظه و کرش کل سرور می‌شود. محاسبه RAM در راهنمای انتخاب VPS. راه بهتر، کاهش تعداد درخواست‌هایی است که به PHP می‌رسند؛ یعنی کش صفحه.

علت ۲: سرویس پشتی پایین است

اگر Nginx جلوی یک اپلیکیشن Node.js، Python یا یک کانتینر Docker است:

sudo ss -tlnp | grep 3000        # آیا روی پورت گوش می‌دهد؟
curl -I http://127.0.0.1:3000     # پاسخ مستقیم از خود سرویس
docker ps                         # آیا کانتینر در حال اجراست؟

مطمئن شوید آدرس و پورت proxy_pass با سرویس یکی است. اپلیکیشن‌ها باید با مدیر فرایندی مثل systemd یا سیاست ری‌استارت Docker اجرا شوند تا پس از کرش خودکار بالا بیایند؛ نمونه در اجرای دائمی سرویس روی VPS.

علت ۳: درخواست‌های طولانی و Timeout

برخی عملیات واقعاً طولانی‌اند؛ مثل خروجی گرفتن گزارش بزرگ یا درون‌ریزی محصولات. اگر لازم است، Timeout را فقط برای همان مسیر افزایش دهید:

location /wp-admin/admin-ajax.php {
    fastcgi_read_timeout 300s;
    # بقیه تنظیمات fastcgi
}

مقدار متناظر max_execution_time در PHP و request_terminate_timeout در PHP-FPM را هم هماهنگ کنید. اما افزایش Timeout برای همه سایت راه‌حل نیست؛ کارهای طولانی را به صف و پردازش پس‌زمینه منتقل کنید. اگر پشت CDN هستید، CDN هم سقف Timeout خودش را دارد.

علت ۴: دیتابیس کند

بسیاری از ۵۰۴ها در واقع یک کوئری کند دیتابیس‌اند که PHP را منتظر نگه داشته:

sudo mysql -e "SHOW FULL PROCESSLIST;"

کوئری‌هایی که چند ثانیه در حال اجرا هستند را شناسایی و با ایندکس مناسب بهینه کنید. Slow Query Log را فعال کنید. روش‌ها در بهینه‌سازی MySQL و MariaDB.

علت ۵: CDN و ارتباط با سرور اصلی

• فایروال سرور، IPهای CDN را مسدود کرده است (مثلاً Fail2ban یا محدودیت نرخ که IP واقعی کاربران را نمی‌بیند).
• تنظیم SSL بین CDN و سرور اشتباه است؛ مثلاً CDN با HTTPS وصل می‌شود اما سرور گواهی معتبر ندارد.
• سرور اصلی کند است و از Timeout CDN عبور می‌کند.

برای تشخیص، سایت را مستقیم از IP سرور (با فایل hosts) باز کنید؛ اگر بدون CDN درست کار کرد، مشکل در ارتباط CDN و سرور است.

پیشگیری

• کش صفحه و Object Cache تا بیشتر درخواست‌ها به PHP و دیتابیس نرسند.
• تنظیم PHP-FPM بر اساس RAM واقعی.
• محدودیت نرخ برای ربات‌ها و مسیرهای سنگین.
• پایش و هشدار برای نرخ خطاهای ۵xx؛ مقدمات در مانیتورینگ سرور چیست.
• ظرفیت کافی برای اوج ترافیک و تست بار پیش از کمپین‌ها.

سوالات متداول