كل المقالات التقنية

ضبط PHP-FPM وحل خطأ 504 Gateway Timeout: دليل عملي للـPool

دليل عملي لتشخيص 504 بين Nginx وPHP-FPM عبر قياس تشبع الـPool، وضبط pm.max_children، وتفعيل slowlog، وموازنة مهلات الانتظار.

ضبط PHP-FPM وحل خطأ 504 Gateway Timeout: دليل عملي للـPool

يعني خطأ 504 أن الخادم الوسيط انتظر استجابة PHP-FPM ولم يحصل عليها قبل انتهاء المهلة. زيادة timeout قد تخفي العرض مؤقتاً، لكنها لا تعالج Pool ممتلئاً أو استعلاماً بطيئاً أو طلباً خارجياً عالقاً. التشخيص الصحيح يبدأ بتحديد أين قضى الطلب وقته.

حدد الطبقة التي أنهت المهلة

في البنية الشائعة يمرر Nginx طلب PHP إلى FastCGI عبر Socket أو منفذ. خطأ 502 يشير غالباً إلى اتصال مكسور أو Upstream غير متاح، بينما 504 يعني أن الاتصال لم يعط استجابة في الوقت المحدد. طابق الطابع الزمني بين سجلات Nginx و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 يستهلك ذاكرة، وقد يؤدي Pool كبير إلى Swap أو OOM Killer. قس RSS الفعلي أثناء حمل حقيقي.

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

احسب pm.max_children من ميزانية الذاكرة

اقسم الذاكرة المخصصة لـPHP على متوسط استهلاك Worker، ثم اترك هامشاً للنظام وNginx وقاعدة البيانات والذاكرة المخبأة. إذا كانت الميزانية 2GB والمتوسط 80MB فـ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 لكشف التنفيذ البطيء

يسجل Slowlog مسار تنفيذ PHP بعد تجاوز حد زمني، وغالباً يكشف إضافة أو Query أو عملية ملفات أو API خارجية بطيئة. عالج السبب بدلاً من إعطائه مهلة أكبر فقط.

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

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

وازن المهلات في جميع الطبقات

اجعل fastcgi_read_timeout أعلى قليلاً من المدة المشروعة القصوى. راجع max_execution_time وrequest_terminate_timeout ومهلة Load Balancer معاً. انقل التصدير والاستيراد والمعالجة الثقيلة إلى Queue.

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 وعدد العمال النشطين وصف الـSocket واستهلاك CPU والذاكرة قبل كل تغيير وبعده. إذا رفع عدد العمال CPU إلى 100% فالمشكلة في القدرة أو الكود، لا في عدد العمال.

قائمة فحص 504

  • طابق وقت الخطأ في سجلات Nginx وPHP-FPM.
  • ابحث عن pm.max_children وأحداث OOM.
  • قس ذاكرة العمال تحت حمل واقعي.
  • فعّل Slowlog وأصلح Endpoint البطيء.
  • وحّد المهلات بين Nginx وFPM وPHP وLoad Balancer.
  • اختبر الإعدادات عبر php-fpm -tt وnginx -t.

أسئلة شائعة

هل تكفي زيادة fastcgi_read_timeout؟

لا؛ هي تجعل Nginx ينتظر أكثر فقط. يجب معالجة تشبع الـPool أو SQL البطيء أو الاعتماد الخارجي.

هل dynamic أفضل من ondemand؟

dynamic مناسب عادةً للحمل المستمر، بينما ondemand يوفر الذاكرة في المواقع الهادئة مع تكلفة بدء Worker.

لماذا أصبح الخادم أبطأ بعد زيادة max_children؟

لأن العمال الزائدين قد يستهلكون RAM وCPU ويؤدون إلى Swap وتنافس أكبر.

أدلة مرتبطة