همه مقالات تخصصی

تنظیم PHP-FPM و رفع خطای 504 Gateway Timeout؛ راهنمای عملی Poolها

راهنمای عملی رفع خطای 504 در Nginx و PHP-FPM با بررسی صف درخواست، ظرفیت Pool، pm.max_children، Slowlog و هماهنگ‌سازی Timeoutها در سرورهای وب پرترافیک.

تنظیم PHP-FPM و رفع خطای 504 Gateway Timeout؛ راهنمای عملی Poolها

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

مسیر درخواست و مالک timeout را مشخص کنید

در معماری رایج، کاربر به Nginx می‌رسد و Nginx درخواست PHP را به یک Socket یا پورت FastCGI می‌فرستد. 504 با 502 فرق دارد: 502 معمولاً به اتصال نامعتبر یا Worker از دسترس خارج‌شده اشاره می‌کند؛ 504 یعنی اتصال برقرار بوده اما پاسخ به‌موقع نرسیده است. زمان خطا را با access log، error log و لاگ PHP-FPM تطبیق دهید.

sudo tail -f /var/log/nginx/error.log
sudo journalctl -u php8.3-fpm -f
sudo grep -R "upstream timed out" /var/log/nginx/

اشباع Pool را با عدد ثابت کنید

پیام server reached pm.max_children نشانه مستقیم کمبود Worker است؛ ولی زیادکردن بی‌حساب Workerها می‌تواند RAM را تمام کند و OOM Killer را فعال کند. میانگین حافظه هر Worker را در بار واقعی اندازه بگیرید و بخشی از RAM را برای سیستم‌عامل، Nginx، پایگاه‌داده و Cache کنار بگذارید.

ps --no-headers -o rss,cmd -C php-fpm8.3 | awk '{sum+=$1;n++} END {print sum/n/1024 " MB per worker"}'
systemctl status php8.3-fpm
ss -xl | grep php

pm.max_children را براساس RAM محاسبه کنید

فرمول شروع مناسب: بودجه حافظه Pool تقسیم بر مصرف واقعی هر Worker. اگر 2 گیگابایت برای PHP در نظر گرفته‌اید و Workerها میانگین 80 مگابایت مصرف می‌کنند، سقف نظری 25 است؛ برای نوسان مصرف حاشیه امن بگذارید. نمونه زیر برای سایت متوسط است و باید با اندازه‌گیری تطبیق داده شود.

[www]
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 4
pm.max_spare_servers = 8
pm.max_requests = 500
request_terminate_timeout = 120s

Slowlog را فعال کنید تا درخواست کند پیدا شود

اگر فقط timeout را افزایش دهید، endpoint کند ناشناس می‌ماند. Slowlog پس از چند ثانیه Stack PHP را ثبت می‌کند و معمولاً افزونه، Query یا فراخوانی HTTP خارجی مشکل‌دار را نشان می‌دهد.

request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log

sudo php-fpm8.3 -tt
sudo systemctl reload php8.3-fpm

Timeoutها را هماهنگ، نه افراطی تنظیم کنید

fastcgi_read_timeout در Nginx باید کمی بیشتر از سقف منطقی اجرای درخواست باشد. max_execution_time، request_terminate_timeout و timeoutهای Load Balancer را نیز بررسی کنید. عملیات طولانی مانند Export یا Import را به Queue و Worker پس‌زمینه منتقل کنید؛ درخواست وب نباید چند دقیقه باز بماند.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_connect_timeout 5s;
    fastcgi_send_timeout 60s;
    fastcgi_read_timeout 120s;
}

پس از تغییر، تحت بار کنترل‌شده اعتبارسنجی کنید

قبل و بعد از تغییر، نرخ 504، زمان پاسخ p95، تعداد Worker فعال، CPU، RAM و صف Socket را مقایسه کنید. اگر افزایش max_children فقط CPU را 100 درصد می‌کند، گلوگاه ظرفیت پردازنده یا کد است، نه تعداد Worker. تغییرات را مرحله‌ای و قابل بازگشت اعمال کنید.

چک‌لیست رفع 504

  • زمان خطا را بین Nginx و PHP-FPM تطبیق دهید.
  • وجود پیام pm.max_children و خطاهای OOM را بررسی کنید.
  • مصرف واقعی حافظه Workerها را اندازه بگیرید.
  • Slowlog را فعال و endpoint کند را اصلاح کنید.
  • Timeoutها را در همه لایه‌ها هماهنگ کنید.
  • پیکربندی را با php-fpm -tt و nginx -t اعتبارسنجی کنید.

سؤال‌های رایج

آیا افزایش fastcgi_read_timeout کافی است؟

خیر. این کار فقط زمان انتظار Nginx را بیشتر می‌کند. اگر Pool اشباع یا Query کند باشد، ظرفیت و علت اصلی باید اصلاح شود.

pm dynamic بهتر است یا ondemand؟

برای ترافیک پیوسته معمولاً dynamic تأخیر کمتری دارد. ondemand برای سایت کم‌ترافیک حافظه را ذخیره می‌کند، اما ساخت Worker در شروع درخواست هزینه دارد.

چرا بعد از افزایش max_children سرور کندتر شد؟

Workerهای بیشتر می‌توانند RAM و CPU را اشباع کنند، Swap بسازند و زمان پاسخ را افزایش دهند. سقف باید از روی بودجه منابع تعیین شود.

راهنماهای مرتبط