خطای 504 Gateway Timeout

خطای 504 Gateway Timeout یکی از رایج‌ترین خطاها برای قطعی سایت است. این خطا زمانی رخ می‌دهد که سرور شما برای پردازش یک درخواست، بیش از حد منتظر پاسخ از یک سرور دیگر می‌ماند و در نهایت «زمانش به پایان می‌رسد» (Timeout).

خطای 504 به زبان ساده به چه معناست؟

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

خطای 504 Gateway Timeout دقیقا همین سناریو است. در معماری مدرن وب، سرور اصلی شما (گارسون) اغلب برای پردازش یک درخواست، نیاز به دریافت پاسخ از یک سرویس دیگر (آشپزخانه) دارد. این سرویس می‌تواند دیتابیس، یک سرور PHP-FPM، یا یک API خارجی باشد. اگر آن سرویس پشتیبان در زمان مشخصی پاسخ ندهد، سرور اصلی از انتظار خسته شده و با نمایش خطای 504 به کاربر اعلام می‌کند که نتوانسته پاسخ را دریافت کند.

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

 

رایج ترین دلایل بروز خطای 504

برخلاف خطای 503 Service Unavailable که مستقیما به ظرفیت سرور مربوط است، خطای 504 بیشتر به «زمان» و «کندی» پردازش‌ها ارتباط دارد.

1. کوئری‌های سنگین و بهینه نشده دیتابیس (رایج ترین علت):یک کوئری پیچیده در سایت وردپرسی یا فروشگاه آنلاین شما می‌تواند چندین ثانیه (یا حتی دقیقه) طول بکشد تا اجرا شود. در این مدت، پردازش PHP منتظر پاسخ از دیتابیس می‌ماند و این انتظار طولانی، منجر به خطای 504 می‌شود.
2. اسکریپت‌های PHP با زمان اجرای طولانی: اسکریپت‌هایی که کارهای سنگینی مانند پردازش تصویر، تولید فایل‌های PDF حجیم یا ارسال ایمیل‌های انبوه را انجام می‌دهند، می‌توانند از حداکثر زمان مجاز اجرای PHP (max_execution_time) عبور کرده و باعث این خطا شوند.
3. مشکلات در ارتباط با APIهای خارجی: اگر سایت شما برای دریافت اطلاعات (مانند نرخ ارز، آب و هوا، یا اطلاعات محصول) به یک سرویس یا API خارجی متصل است و آن سرویس کند باشد یا پاسخ ندهد، سرور شما منتظر مانده و در نهایت با خطای 504 مواجه می‌شود.
4. تنظیمات پایین Timeout در وب‌سرور: وب‌سرورهایی مانند Nginx دارای تنظیماتی به نام p.roxy_read_timeout هستند که مشخص می‌کند چه مدت باید منتظر پاسخ از سرویس PHP-FPM بمانند. اگر این مقدار خیلی کم باشد، حتی پردازش‌های عادی نیز ممکن است باعث بروز خطا شوند، زیرا این زمان انتظار مستقیما به نحوه بهینه‌سازی و تنظیمات PHP-FPM بستگی دارد.
5. کمبود منابع سرور (CPU و RAM): اگر سرور شما به دلیل کمبود منابع به شدت کند شده باشد، زمان لازم برای پردازش هر درخواست افزایش می‌یابد و این کندی عمومی می‌تواند خود را به شکل خطای 504 نشان دهد.

راهنمای مرحله برای رفع خطای 504

برای رفع این خطا، باید پردازش کندی که باعث این «انتظار طولانی» شده را شناسایی و بهینه کنید.

مرحله اول: بررسی‌های اولیه (آیا مشکل از سمت شماست؟)

گاهی اوقات مشکل موقتی است. صفحه را چند بار رفرش کنید (با فاصله چند دقیقه).

مرحله دوم: بررسی لاگ‌های سرور

برای پیدا کردن منبع خطا، لاگ‌های وب‌سرور خود را بررسی کنید. به دنبال پیام‌هایی بگردید که به «timeout» اشاره دارند.

• در Nginx: فایل /var/log/nginx/error.log را باز کرده و به دنبال پیامی مانند upstream timed out (110: Connection timed out) بگردید.
• در Apache: فایل /var/log/apache2/error.log را برای پیام‌های مشابه بررسی کنید.

این پیام‌ها معمولا نشان می‌دهند که کدام اسکریپت یا درخواست باعث بروز مشکل شده است.

مرحله سوم: شناسایی کوئری‌های کند دیتابیس (مهم‌ترین مرحله)

از آنجایی که دیتابیس هم یکی از رایج ترین خطاهای 504 است، باید کوئری‌های کند را شناسایی کنید. بهترین راه برای این کار، فعال کردن Slow Query Log در MySQL/MariaDB است. این ابزار تمام کوئری‌هایی که اجرای آن‌ها بیش از یک زمان مشخص (مثلا ۲ ثانیه) طول می‌کشد را در یک فایل جداگانه ثبت می‌کند.

پس از شناسایی کوئری‌های کند، باید آن‌ها را با کمک یک توسعه‌دهنده بهینه کنید یا از افزونه‌های کش دیتابیس در وردپرس استفاده کنید.

مرحله چهارم: غیرفعال کردن افزونه‌ها و بررسی قالب

یک افزونه بهینه نشده (مخصوصا افزونه‌های آمار، پشتیبان‌گیری یا امنیتی) می‌تواند کوئری‌های سنگینی را اجرا کند. تمام افزونه‌های خود را غیرفعال کنید و ببینید آیا مشکل برطرف می‌شود. اگر اینچنین بود، آن‌ها را یکی‌یکی فعال کنید تا افزونه مشکل‌ساز را پیدا کنید.

مرحله پنجم: افزایش مقادیر Timeout (به عنوان راه‌حل موقت)

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

• در فایل php.ini: مقدار max_execution_time را افزایش دهید (مثلا به 300 ثانیه).
• در تنظیمات PHP-FPM: مقدار request_terminate_timeout را افزایش دهید.
• در تنظیمات Nginx: مقدار proxy_read_timeout را افزایش دهید.

سوالات متداول درباره خطای 504