خطای 502 Bad Gateway؛ علت و رفع سریع

سایت بالا نمی‌آید و مرورگر فقط یک عدد نشان می‌دهد: 502 Bad Gateway. اگر Nginx جلوی درخواست ایستاده باشد، این پیام یعنی Nginx درخواست را به بک‌اند فرستاده و از آن جواب نگرفته. پس مشکل تقریباً همیشه در سمت بک‌اند است، نه در Nginx و نه در مرورگر کاربر. اولین کاری که باید بکنید این است که بفهمید کدام لایه جواب نداده.

خطای 502 از کجا می‌آید

یک درخواست HTTP از مرورگر تا PHP چند ایستگاه دارد. هر ایستگاه می‌تواند 502 تولید کند و هرکدام لاگ خودش را دارد:

• مرورگر → Cloudflare (یا هر CDN): اگر لبه نتواند به مبدأ وصل شود، 502 می‌دهد.
• Cloudflare → Nginx: اگر پورت 80/443 مبدأ بسته باشد، همان 502.
• Nginx → PHP-FPM: اگر سوکت یا پورت FPM جواب ندهد، Nginx خطای 502 برمی‌گرداند.
• PHP-FPM → MySQL یا Redis: اینجا معمولاً 500 می‌گیرید، ولی اگر ورکر FPM بمیرد، نتیجه‌اش 502 است.

ترتیب عیب‌یابی از بیرون به داخل است. اول ببینید خطا از Cloudflare می‌آید یا از خود سرور.

تشخیص سریع: خطا از CDN است یا از سرور

یک درخواست مستقیم به IP سرور بزنید و هدرها را ببینید:

curl -sSI -H "Host: example.com" http://185.x.x.x/ | head -n 5

اگر پاسخ مستقیم 200 بود ولی دامنه از پشت Cloudflare 502 می‌دهد، مشکل در لبه یا در تنظیمات مبدأ است. اگر هر دو 502 دادند، برو سراغ لاگ Nginx:

tail -f /var/log/nginx/error.log

خطی که دنبالش هستید چیزی شبیه این است:

connect() to unix:/run/php/php8.2-fpm.sock failed (11: Resource temporarily unavailable)

یا:

upstream prematurely closed connection while reading response header from upstream

اولی یعنی صف ورکرهای FPM پر شده. دومی یعنی PHP وسط اجرا مرده. این دو، دو درمان کاملاً متفاوت دارند.

تایم‌اوت PHP-FPM و صف پر ورکر

PHP-FPM تعداد محدودی ورکر دارد. وقتی همه ورکرها مشغول باشند، درخواست جدید در صف می‌ماند و اگر Nginx زودتر از FPM خسته شود، 502 می‌دهد. دو عدد را باید کنار هم ببینید: request_terminate_timeout در FPM و fastcgi_read_timeout در Nginx.

اگر fastcgi_read_timeout روی 60 ثانیه باشد و اسکریپتی 90 ثانیه طول بکشد، Nginx در ثانیه 60 اتصال را می‌بندد و کاربر 502 می‌بیند، در حالی که PHP هنوز دارد کار می‌کند و ورکر را اشغال نگه داشته. این‌جا اشتباه می‌کنند: مقدار fastcgi_read_timeout را بی‌نهایت می‌کنند تا خطا برود. خطا می‌رود، ولی صف پر می‌ماند و ده دقیقه بعد کل سایت 502 می‌شود. علامتش هم این است که سایت برای چند دقیقه سالم است و بعد یک‌دفعه همه درخواست‌ها می‌خوابند.

راه درست این است که اول بفهمید کدام اسکریپت طول می‌کشد. لاگ کندی FPM را روشن کنید:

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

بعد از چند دقیقه، فایل slow.log دقیقاً می‌گوید کدام تابع و کدام خط از کد وقت می‌خورد. در نُه مورد از ده مورد، یک کوئری بدون ایندکس یا یک درخواست HTTP به یک API بیرونی است.

تنظیم درست pm.max_children

تعداد ورکر را با حافظه حساب کنید، نه با حدس. اگر هر پروسه PHP حدود 80 مگابایت RSS بگیرد و سرور 4 گیگابایت رم داشته باشد، سقف منطقی چیزی حدود 30 تا 35 ورکر است، نه 100. فرمول ساده:

pm = dynamic
pm.max_children = 32
pm.start_servers = 8
pm.min_spare_servers = 8
pm.max_spare_servers = 16
pm.max_requests = 500

مقدار pm.max_requests را دست‌کم نگیرید. نشتی حافظه در افزونه‌های وردپرس واقعی است و ری‌استارت دوره‌ای ورکر جلوی خیلی از 502های تدریجی را می‌گیرد.

نقش Cloudflare در خطای 502

Cloudflare وقتی 502 می‌دهد که نتواند به مبدأ وصل شود یا مبدأ جواب معتبر ندهد. سه علت رایج:

1. IP مبدأ در رکورد DNS عوض شده و رکورد A قدیمی مانده. با ابزار بررسی DNS و شبکه چک کنید رکورد A و AAAA به IP درست اشاره می‌کنند.
2. فایروال سرور، IPهای Cloudflare را بلاک کرده. اگر iptables یا CSF دارید، رنج‌های Cloudflare باید مجاز باشند.
3. حالت SSL روی Full (strict) است ولی گواهی روی مبدأ منقضی شده. اینجا مرورگر 502 می‌بیند و لاگ مبدأ هیچ چیزی ندارد.

یک نکته که خیلی‌ها را گمراه می‌کند: Cloudflare خطای مبدأ را کش نمی‌کند، ولی صفحه خطای خودش را با کد 502 برمی‌گرداند. اگر در تب Network مرورگر cf-ray می‌بینید، یعنی خطا از لبه آمده و باید لاگ مبدأ را جدا بررسی کنید.

وقتی ورکر تمام شده ولی سرور سالم است

حالتی هست که CPU و RAM کاملاً آزادند، ولی سایت 502 می‌دهد. این تقریباً همیشه یعنی ورکرهای FPM در انتظار یک منبع بیرونی گیر کرده‌اند: یک اتصال MySQL که قفل شده، یک Redis که جواب نمی‌دهد، یا یک درخواست curl بدون timeout به یک سرویس خارجی.

برای دیدن وضعیت لحظه‌ای صف:

systemctl status php8.2-fpm
ss -x -p | grep php

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

در وردپرس، wp-cron.php روی سایت‌های پربازدید یکی از متهم‌های همیشگی است. هر بازدید یک درخواست cron جدا می‌سازد و روی ترافیک بالا صف ورکرها را پر می‌کند. راه‌حل استاندارد، غیرفعال کردن cron داخلی و اجرای آن با crontab سیستم است:

define('DISABLE_WP_CRON', true);

*/5 * * * * wget -q -O - https://example.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1

چه زمانی مشکل از منابع سرور است

اگر بعد از تنظیم درست FPM و پیدا کردن اسکریپت کند، هنوز در ساعات اوج 502 می‌گیرید، دیگر مسئله تنظیمات نیست؛ سرور به سقف رسیده. اینجا دو راه دارید و انتخاب بین‌شان به الگوی بار بستگی دارد.

اگر کد و تنظیمات را خودتان کنترل می‌کنید و می‌خواهید پارامترهای FPM و کش را آزادانه تنظیم کنید، هاست لینوکس با دسترسی کامل SSH انتخاب درست‌تری است تا بمانید و هر هفته با 502 بجنگید. اگر بار سایت شما مداوم و سنگین است و به ایزوله کردن دیتابیس از وب‌سرور نیاز دارید، سرور اختصاصی منطقی‌تر است.

چک‌لیست پنج‌دقیقه‌ای

1. لاگ /var/log/nginx/error.log را ببینید و پیام دقیق upstream را بردارید.
2. با systemctl status php8.2-fpm سلامت سرویس را چک کنید.
3. مقدار pm.max_children را با حافظه واقعی سرور مقایسه کنید.
4. لاگ کندی FPM را روشن کنید و اسکریپت مقصر را پیدا کنید.
5. اگر پشت Cloudflare هستید، رکورد DNS و حالت SSL را بررسی کنید.

اگر بعد از این پنج مرحله هنوز خطا دارید، وقت آن است که معماری را ببینید، نه تنظیمات را. راهنمای عیب‌یابی سایت کند نقطه شروع خوبی است، چون 502 و کندی معمولاً یک ریشه دارند. برای مواردی که به تنظیمات سطح وب‌سرور مربوط می‌شود، مستندات و پایگاه دانش سرورنت نمونه‌های آماده دارد.

پرسش‌های پرتکرار

تفاوت خطای 502 و 504 چیست؟

502 یعنی بک‌اند جواب نامعتبر داد یا اتصال قطع شد؛ 504 یعنی بک‌اند در بازه تعیین‌شده هیچ جوابی نداد. در عمل، 504 معمولاً با افزایش تایم‌اوت حل می‌شود ولی 502 نشانه خرابی یا اشباع ورکر است. اگر هر دو را می‌بینید، اول صف ورکرهای PHP-FPM را بررسی کنید.

آیا ری‌استارت PHP-FPM خطای 502 را حل می‌کند؟

موقتاً بله، ولی علت را برطرف نمی‌کند. اگر بعد از systemctl restart php8.2-fpm سایت چند ساعت سالم است و بعد دوباره 502 می‌دهد، یعنی یک اسکریپت یا نشتی حافظه ورکرها را از پا درمی‌آورد. لاگ کندی FPM را روشن کنید تا مقصر را ببینید.

چرا فقط بعضی کاربران خطای 502 می‌گیرند؟

چون خطا به ورکر خاصی وابسته است. اگر یکی از چند سرور بک‌اند خراب باشد، یا یک نود در لودبالانسر از مدار خارج شده باشد، فقط بخشی از درخواست‌ها به آن می‌رسند. همچنین اگر کش لبه بخشی از صفحات را سرو کند، کاربران دیگر اصلاً به مبدأ نمی‌رسند و خطا را نمی‌بینند.

آیا خطای 502 روی سئو اثر دارد؟

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