يعني 502 من Nginx أن البوابة لم تحصل على استجابة صالحة من الخدمة الخلفية. في مواقع PHP يكون Nginx قادراً على استقبال الطلب، لكن الاتصال بـPHP-FPM يفشل. إعادة تشغيل كل شيء قد تعيد الخدمة مؤقتاً لكنها لا تفسر السبب.
ابدأ بسجل خطأ Nginx
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --since "10 minutes ago"
No such file or directory: مسار Socket غير موجود.Connection refused: PHP-FPM متوقف أو لا يستمع على المنفذ.Permission denied: Nginx لا يملك صلاحية Socket.upstream prematurely closed connection: Worker خرج أو قُتل أو انهار.upstream timed out: التطبيق لم يرد ضمن المهلة؛ لا ترفعها قبل تشخيص التطبيق.
تحقق من خدمة PHP-FPM
systemctl status php-fpm
systemctl status php8.2-fpm
journalctl -u php8.2-fpm --since "30 minutes ago"
php-fpm8.2 -t
ابحث عن إعداد Pool غير صالح أو Extension منهار أو OOM. اجمع الأدلة قبل إعادة التشغيل.
طابق Endpoint بين Nginx وPHP-FPM
sudo nginx -T | grep -n "fastcgi_pass"
grep -R "^listen" /etc/php/*/fpm/pool.d/
ss -ltnp
ss -lxnp
يجب أن يطابق fastcgi_pass unix:/run/php/php8.2-fpm.sock أو TCP الجهة التي يستمع عليها Pool. بعد ترقية PHP قد يبقى Nginx على Socket إصدار قديم.
افحص ملكية Socket وصلاحياته
namei -l /run/php/php8.2-fpm.sock
ps -o user,group,cmd -C nginx
ls -l /run/php/
راجع كل Parent Directory. اضبط owner/group/mode بأقل صلاحية، ولا تجعل Socket قابلاً للكتابة للجميع.
ابحث عن امتلاء Pool والذاكرة
ps --no-headers -o rss -C php-fpm8.2 | awk '{sum+=$1; n++} END {print n, sum/1024 " MB"}'
free -m
vmstat 1 5
journalctl -k | grep -i -E "out of memory|killed process"
رسالة الوصول إلى pm.max_children دليل على التشبع. لا ترفع العدد عشوائياً؛ احسب ذاكرة كل Worker واترك مساحة للنظام وقاعدة البيانات وCache.
إذا أظهر سجل Kernel رسائل Out of memory أو Killed process، فاتبع دليل تشخيص ضغط الذاكرة وOOM Killer في Linux قبل زيادة pm.max_children أو عدد Workers.
فرّق بين البطء وعدم توفر Upstream
راجع fastcgi_connect_timeout وfastcgi_read_timeout وPHP max_execution_time وFPM request_terminate_timeout. رفع المهلة مناسب فقط لعمل متوقع وطاقة كافية. انقل الأعمال الطويلة إلى Queue.
وفّر دليلاً للحادث التالي
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/site-slow.log
استخدم Slow Log وحد حجم السجل. يمكن لـFPM Status المقيد محلياً عرض العمال النشطين والطابور والحد الأقصى.
تسلسل استعادة آمن
- سجّل الوقت والمضيف والرابط وخطأ Nginx.
- افحص FPM وjournal.
- طابق Socket أو Port.
- افحص الصلاحيات.
- راجع الذاكرة والعمال وOOM.
- اختبر إعداد Nginx وFPM.
- أعد تشغيل المكوّن الفاشل فقط.
- اختبر ملفاً ثابتاً ورابط PHP وراقب السجلات.
إذا أظهرت Access Logs أن الطلبات المتكررة إلى Login أو API تستنزف عمال PHP-FPM، فاتبع دليل إعداد Rate Limiting في Nginx لحماية Login وAPI قبل زيادة حدود Workers.
