خطای 504 Gateway Timeout یعنی سروری که جلوی برنامه قرار دارد (Nginx، Apache به‌عنوان پراکسی، Cloudflare یا یک Load Balancer) درخواست را به سرور پشتی فرستاده، ولی در مهلت تعیین‌شده جوابی نگرفته است. تفاوتش با 502 این است که در 502 جواب نامعتبر یا قطع اتصال رسیده و در 504 اصلاً جوابی نیامده. رایج‌ترین علت‌ها اسکریپت کند یا گیرکرده PHP، کوئری سنگین دیتابیس، پر شدن Workerهای PHP-FPM و پایین بودن مقدار مهلت (timeout) است.
عیب‌یابی را از لاگ شروع کنید و قبل از بالا بردن مهلت‌ها، علت کندی را پیدا کنید. بالا بردن timeout فقط پیام خطا را دیرتر نشان می‌دهد. اگر با 502 هم روبه‌رو هستید، خطای 502 Bad Gateway را ببینید و برای 500 به خطای 500 Internal Server Error مراجعه کنید.
خطای 504 Gateway Timeout از کجا می‌آید؟
پیش از هر کار، مشخص کنید خطا را کدام لایه می‌دهد:
| ظاهر صفحه | لایه محتمل |
|---|---|
| صفحه سفید ساده با متن 504 Gateway Time-out و نام nginx | Nginx |
| صفحه Cloudflare با شماره خطا و ابر نارنجی | Cloudflare (خطای 504 یا 524) |
| صفحه ارائه‌دهنده یا Load Balancer | لایه جلوی سرور |
| سایت با آدرس IP مستقیم کار می‌کند ولی با دامنه 504 می‌دهد | CDN یا پراکسی بین کاربر و سرور |
اگر با آدرس مستقیم سرور (یا با تغییر فایل hosts) سایت درست باز می‌شود، مشکل در لایه جلویی است. اگر آنجا هم کند یا خطا می‌دهد، مشکل از خود سرور و برنامه است.
مرحله اول: خواندن لاگ خطای 504 Gateway Timeout
sudo tail -n 50 /var/log/nginx/error.log
sudo tail -n 50 /var/log/php8.3-fpm.logنام فایل لاگ PHP-FPM به نسخه PHP بستگی دارد. پیام‌های رایج در لاگ Nginx:
upstream timed out (110: Connection timed out) while reading response header from upstream: برنامه در مهلت جواب نداده است.connect() to unix:/run/php/php8.3-fpm.sock failed: PHP-FPM اجرا نیست یا مسیر سوکت اشتباه است.
در لاگ PHP-FPM دنبال این پیام باشید: server reached pm.max_children setting. یعنی همه Workerها مشغول‌اند و درخواست‌های تازه در صف می‌مانند تا مهلت تمام شود. روش‌های جست‌وجو در لاگ را در راهنمای grep و find بخوانید.
مرحله دوم: کندی اسکریپت یا دیتابیس
اگر کار سنگین مثل گزارش، درون‌ریزی، پشتیبان‌گیری یا اجرای کرون در حال انجام است، ممکن است از مهلت بگذرد. بررسی کنید در لحظه خطا چه چیزی اجرا می‌شود:
top -c
sudo mysqladmin processlistاگر پردازش‌های PHP تمام CPU را می‌گیرند یا کوئری‌های طولانی در processlist هستند، باید خود کار را بهینه کنید. در وردپرس، افزونه‌های سنگین، کوئری‌های بدون ایندکس و درخواست‌های admin-ajax.php پرتکرار از دلایل رایج‌اند. چند راه کاهش بار دیتابیس در بهینه سازی دیتابیس سرور آمده است.
مرحله سوم: پر شدن Workerهای PHP-FPM
مقدار pm.max_children باید با حافظه سرور هماهنگ باشد. اگر خیلی کم باشد، درخواست‌ها در صف می‌مانند. اگر خیلی زیاد باشد، حافظه تمام می‌شود و سرور شروع به swap می‌کند. میانگین حافظه هر Worker را اندازه بگیرید:
ps --no-headers -o rss -C php-fpm8.3 | awk '{ sum += $1; n++ } END { printf "%d workers, avg %.0f MB\n", n, sum/n/1024 }'مقدار max_children را از تقسیم حافظه قابل‌استفاده برای PHP بر میانگین مصرف هر Worker به‌دست آورید و کمی محافظه‌کارانه بگذارید. بعد از تغییر در /etc/php/8.3/fpm/pool.d/www.conf:
sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpmمسیرها نمونه‌اند و بسته به نسخه فرق می‌کنند.
مرحله چهارم: مهلت‌ها در Nginx
وقتی کار طولانی واقعاً لازم است (مثل خروجی گرفتن یا درون‌ریزی)، مهلت را برای همان مسیر بالا ببرید و برای کل سایت زیاد نکنید:
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
include fastcgi_params;
fastcgi_read_timeout 120s;
}در حالت پراکسی (Reverse Proxy) به برنامه دیگر:
proxy_connect_timeout 10s;
proxy_read_timeout 120s;مقدار پیش‌فرض خواندن در Nginx برای هر دو 60 ثانیه است. در PHP هم max_execution_time در php.ini حدی دارد که باید با fastcgi_read_timeout هماهنگ باشد. پس از تغییر، تنظیمات را تست و بارگذاری کنید:
sudo nginx -t
sudo systemctl reload nginxدرباره ساختار پراکسی در Reverse Proxy چیست و کانفیگ Nginx در نصب Nginx روی اوبونتو بیشتر بخوانید.
504 و 524 در Cloudflare
اگر سایت پشت Cloudflare است، دو خطا را باید از هم جدا کنید:
- 504: Cloudflare به سرور اصلی وصل شده ولی جواب مناسب نگرفته، یا خود سرور اصلی گیتوی دیگری دارد که timeout داده است.
- 524: اتصال برقرار شده ولی سرور اصلی در مهلت تعیین‌شده (در طرح‌های معمولی حدود 100 ثانیه) پاسخ کامل نداده.
برای هر دو، لاگ سرور اصلی را ببینید. اگر کار طولانی دارید، آن را به یک صف یا کرون ببرید و جواب را سریع به کاربر بدهید. ابزار بررسی DNS دامنه نشان می‌دهد دامنه به کدام IP می‌رسد و واقعاً پشت CDN است یا نه.
مرحله پنجم: منابع سرور و شبکه
- مصرف حافظه و swap را با
free -hوvmstat 1 5ببینید. swap سنگین یعنی سرور حافظه کم دارد. دستورات مانیتورینگ در دستورات مانیتورینگ سرور لینوکس آمده است. - پر بودن دیسک یا inode می‌تواند نوشتن لاگ و نشست را مختل کند:
df -hوdf -i. - اتصال سرور به سرویس بیرونی (API پرداخت، سرویس ایمیل) را بررسی کنید. اگر آن سرویس جواب نمی‌دهد، برنامه شما تا پایان مهلت منتظر می‌ماند.
جدول عیب‌یابی سریع
| نشانه | علت محتمل | راه حل |
|---|---|---|
لاگ: upstream timed out | اسکریپت یا کوئری کند | پیدا کردن کار کند و بهینه‌سازی |
لاگ PHP-FPM: max_children | Workerها پر شده‌اند | تنظیم pm.max_children متناسب با حافظه |
| 504 فقط روی مسیرهای سنگین | مهلت کم برای کار طولانی | افزایش مهلت همان مسیر |
| 504 فقط پشت Cloudflare | سرور اصلی کند یا مهلت CDN | بررسی لاگ سرور و تغییر کار طولانی به صف |
| همه صفحات کند، swap بالا | کمبود حافظه | کاهش مصرف یا افزایش حافظه |
| 504 فقط هنگام پشتیبان‌گیری | بار IO و CPU | جابه‌جایی زمان بکاپ به ساعات کم‌بار |
سوالات متداول
فرق 502 و 504 چیست؟
در 502 پاسخ نامعتبر یا قطع اتصال از سرور پشتی رسیده. در 504 تا پایان مهلت هیچ پاسخی نیامده است.
آیا بالا بردن timeout مشکل را حل می‌کند؟
فقط وقتی کار واقعاً طولانی است و برای همان مسیر انجام شود. اگر علت کندی یا گیر کردن است، با افزایش مهلت کاربر بیشتر منتظر می‌ماند و سرور درگیرتر می‌شود.
504 روی سئو اثر دارد؟
بله، اگر ربات گوگل مکرر خطای سرور بگیرد، ممکن است سرعت خزش کم شود. خطای مداوم را سریع رفع کنید.
چطور بفهمم مشکل از وردپرس است یا سرور؟
افزونه‌ها را موقتاً غیرفعال کنید و قالب پیش‌فرض بگذارید. اگر خطا رفت، مشکل از افزونه یا قالب است. اگر نرفت، منابع سرور و تنظیمات PHP-FPM را بررسی کنید.
