- خطای 502 Bad Gateway یعنی سرور واسط، مثل Nginx یا CDN، از برنامه یا سرور پشت خود جواب نامعتبر گرفته یا اتصالش قطع شده است.
- رایج‌ترین علت‌های خطای 502 خاموش بودن PHP-FPM، توقف پردازش به دلیل کمبود حافظه، مسیر سوکت اشتباه، هدر بزرگ و قطع ارتباط CDN با سرور اصلی هستند.
- گزارش خطای Nginx با پیام‌هایی مثل Connection refused یا upstream prematurely closed connection سریع‌ترین راه پیدا کردن علت خطای 502 است.
یک صفحه سفید، وسطش با حروف درشت نوشته 502 Bad Gateway و زیر یک خط افقی فقط یک کلمه: nginx. همین صفحه ساده یعنی بازدیدکننده به سایت رسیده، اما سایت جوابی برای نشان دادن نداشته است.
خطای 502 یعنی سروری که درخواست را گرفته، از سرور یا برنامه پشت خودش جواب درست دریافت نکرده است. در بیشتر سایت‌ها این یعنی وب‌سرور (مثل Nginx) سالم است و مشکل در PHP، برنامه سایت یا اتصال بین CDN و سرور اصلی است. در این مقاله علت‌های رایج خطای 502، روش پیدا کردن علت و راه‌حل هر کدام را مرور می‌کنیم.
#خطای 502 Bad Gateway یعنی چه؟
خطای 502 Bad Gateway یعنی سرور واسط از سرور بالادستی جواب نامعتبر گرفته است. این تعریف در استاندارد RFC 9110 آمده است. برای فهمیدنش باید بدانید یک صفحه سایت معمولاً از چند لایه عبور می‌کند:
- مرورگر کاربر درخواست را به CDN یا مستقیم به وب‌سرور می‌فرستد.
- وب‌سرور (Nginx، آپاچی یا لایت‌اسپید) درخواست را به برنامه سایت میدهد، مثلاً PHP-FPM برای وردپرس یا Node.js برای یک برنامه جاوااسکریپتی.
- برنامه صفحه را می‌سازد و از همان مسیر برمی‌گرداند.
هر جا که یک لایه نتواند از لایه بعدی جواب درست بگیرد، کاربر خطای 502 می‌بیند. مستندات MDN یک نکته مهم دیگر هم دارد: اگر سرور بالادستی اصلاً در زمان مقرر جواب ندهد، خطای درست 504 است. پس خطای 502 معمولاً یعنی اتصال برقرار نشده، قطع شده یا جواب خراب برگشته است.
خطای 502 بسته به وب‌سرور و CDN با این متن‌ها دیده می‌شود: 502 Bad Gateway، HTTP Error 502، 502 Proxy Error یا صفحه اختصاصی CDN که می‌گوید سرور اصلی پاسخ نمی‌دهد.
#فرق خطای 502 با 503 و 504
| کد خطا | چه اتفاقی افتاده است | کجا را بررسی کنیم |
|---|---|---|
| 502 Bad Gateway | سرور واسط از برنامه یا سرور پشتی جواب نامعتبر گرفته یا اتصال قطع شده است | PHP-FPM یا برنامه سایت، اتصال CDN به سرور اصلی |
| 503 Service Unavailable | سرور سالم است اما موقتاً ظرفیت یا آمادگی جواب دادن ندارد | ترافیک، منابع هاست، حالت تعمیر |
| 504 Gateway Timeout | سرور پشتی در زمان مقرر جواب نداده است | پردازش‌های طولانی، کندی پایگاه داده |
اگر سایت شما خطای 503 میدهد، علت‌ها و راه‌حلش را در مقاله خطای 503 چیست و چطور رفع می‌شود توضیح داده‌ایم.
#علت‌های رایج خطای 502
#۱. PHP-FPM یا برنامه سایت از کار افتاده است
رایج‌ترین علت خطای 502 در سایت‌های وردپرسی این است که سرویس PHP-FPM خاموش شده یا در حال راه‌اندازی دوباره است. Nginx درخواست را به PHP می‌فرستد و کسی پشت در نیست. در گزارش خطای Nginx پیامی شبیه connect() failed (111: Connection refused) while connecting to upstream دیده می‌شود.
در برنامه‌های Node.js، پایتون یا هر برنامه دیگری که پشت Nginx اجرا می‌شود هم همین اتفاق می‌افتد: پردازش برنامه از کار افتاده، کانتینر داکر در حال راه‌اندازی دوباره است یا برنامه روی پورت دیگری اجرا شده است.
#۲. پردازش PHP وسط کار متوقف شده است
گاهی PHP درخواست را می‌گیرد، اما قبل از تمام کردن کار متوقف می‌شود. دلیلش معمولاً تمام شدن حافظه سرور است که سیستم‌عامل را مجبور می‌کند پردازش را ببندد، یا تنظیم request_terminate_timeout در PHP-FPM که پردازش‌های طولانی را قطع می‌کند. نشانه‌اش در گزارش Nginx پیام upstream prematurely closed connection است و این خطا معمولاً فقط روی صفحه‌های سنگین مثل گزارش‌گیری، درون‌ریزی محصول یا تسویه‌حساب دیده می‌شود.
#۳. آدرس سوکت یا پورت اشتباه است
بعد از ارتقای نسخه PHP، مسیر سوکت PHP-FPM عوض می‌شود. مثلاً از php8.1-fpm.sock به php8.3-fpm.sock. اگر تنظیمات Nginx هنوز به مسیر قدیمی اشاره کند، همه صفحه‌ها خطای 502 می‌دهند و در گزارش خطا پیام No such file or directory کنار نام سوکت دیده می‌شود. این مشکل معمولاً درست بعد از به‌روزرسانی سرور یا تغییر نسخه PHP در کنترل‌پنل شروع می‌شود.
#۴. هدر پاسخ از بافر Nginx بزرگ‌تر است
اگر برنامه سایت هدرهای بزرگی برگرداند، مثلاً کوکی‌های زیاد یا طولانی، و این هدرها در بافر Nginx جا نشوند، Nginx جواب را نامعتبر می‌داند و خطای 502 برمی‌گرداند. پیام upstream sent too big header در گزارش خطا نشانه همین مشکل است. راه‌حلش بزرگ‌تر کردن fastcgi_buffer_size یا proxy_buffer_size است که در مستندات Nginx توضیح داده شده است. این خطا معمولاً فقط برای کاربرانی دیده می‌شود که وارد حساب شده‌اند یا سبد خرید پری دارند.
#۵. CDN به سرور اصلی دسترسی ندارد
وقتی سایت پشت CDN است، CDN نقش همان سرور واسط را دارد. اگر سرور اصلی خاموش باشد، آیپی آن عوض شده و در پنل CDN به‌روز نشده باشد، فایروال سرور آیپیهای CDN را مسدود کرده باشد یا تنظیمات HTTPS بین CDN و سرور اصلی با هم جور نباشد، کاربر خطای 502 را از طرف CDN می‌بیند. در این حالت صفحه خطا معمولاً ظاهر و نام خود CDN را دارد.
#۶. مشکل از شبکه کاربر است
این حالت کم‌تکرار است، اما وجود دارد. طبق مستندات MDN، اگر سایت برای بقیه باز می‌شود و فقط برای یک کاربر خطای 502 میدهد، ممکن است پروکسی، فیلترشکن یا تنظیمات شبکه همان کاربر مقصر باشد. بستن ابزار تغییر مسیر و امتحان دوباره، این حالت را مشخص می‌کند.
#جدول عیب‌یابی خطای 502
| علت | نشانه در گزارش یا رفتار سایت | راه‌حل |
|---|---|---|
| PHP-FPM یا برنامه خاموش | Connection refused، همه صفحه‌ها خطا می‌دهند | راه‌اندازی دوباره سرویس و پیدا کردن علت توقف |
| توقف پردازش وسط کار | upstream prematurely closed connection، فقط صفحه‌های سنگین | افزایش حافظه یا memory_limit، بهینه‌سازی صفحه سنگین |
| مسیر سوکت اشتباه | No such file or directory، بعد از تغییر نسخه PHP | اصلاح مسیر سوکت در تنظیمات Nginx |
| هدر بزرگ | upstream sent too big header، فقط کاربران واردشده | بزرگ‌تر کردن fastcgi_buffer_size یا proxy_buffer_size |
| قطع ارتباط CDN و سرور اصلی | صفحه خطا با ظاهر CDN | بررسی آیپی سرور در CDN، فایروال و تنظیمات HTTPS |
| شبکه کاربر | فقط برای یک نفر، با فیلترشکن یا پروکسی | امتحان بدون پروکسی و فیلترشکن |
#رفع خطای 502 قدم‌به‌قدم
اگر بازدیدکننده هستید، چند دقیقه صبر کنید، صفحه را دوباره بارگذاری کنید و اگر از فیلترشکن یا پروکسی استفاده می‌کنید، یک بار بدون آن امتحان کنید. اگر صاحب سایت هستید، این مراحل را به ترتیب جلو ببرید:
- زمان شروع را مشخص کنید. ببینید خطای 502 از چه زمانی شروع شده و آن موقع چه تغییری روی سایت یا سرور انجام شده است: به‌روزرسانی PHP، نصب افزونه، تغییر DNS یا تنظیمات CDN.
- CDN را موقتاً کنار بگذارید. سایت را مستقیم با آیپی سرور اصلی امتحان کنید یا حالت پروکسی CDN را برای چند دقیقه خاموش کنید. اگر خطا رفت، مشکل در ارتباط CDN و سرور است.
- گزارش خطای وب‌سرور را بخوانید. در سرورهای Nginx معمولاً فایل
/var/log/nginx/error.logاست. پیام‌های جدول بالا علت را مستقیم نشان می‌دهند. - وضعیت PHP-FPM یا برنامه را بررسی کنید. اگر سرویس خاموش است، دوباره راه‌اندازی‌اش کنید. بعد گزارش خود PHP را ببینید تا مشخص شود چرا متوقف شده بود، وگرنه خطا برمی‌گردد.
- مصرف حافظه سرور را ببینید. اگر حافظه پر می‌شود، تعداد پردازش‌های PHP را با حافظه سرور هماهنگ کنید یا منابع سرور را ارتقا دهید.
- در هاست اشتراکی سراغ پشتیبانی بروید. در هاست اشتراکی به گزارش‌های Nginx و PHP-FPM دسترسی ندارید. زمان شروع خطا و آدرس صفحه‌هایی را که خطا می‌دهند برای پشتیبانی بفرستید.
راه‌اندازی دوباره PHP خطای 502 را برای چند دقیقه برطرف می‌کند، اما اگر علت تمام شدن حافظه باشد، خطا با اولین ترافیک سنگین برمی‌گردد. همیشه بعد از رفع موقت، علت اصلی را در گزارش‌ها پیدا کنید.
#چطور جلوی تکرار خطای 502 را بگیریم؟
- بعد از هر ارتقای PHP یا تغییر تنظیمات سرور، چند صفحه اصلی سایت را باز کنید و مسیر خرید را امتحان کنید.
- سرویس PHP-FPM یا برنامه سایت را طوری تنظیم کنید که بعد از توقف خودکار دوباره راه بیفتد.
- تعداد پردازش‌های PHP را با حافظه سرور هماهنگ کنید تا سرور در ساعت شلوغ حافظه کم نیاورد.
- کارهای سنگین مثل درون‌ریزی محصول و گزارش‌گیری را در ساعت‌های کم‌بازدید یا در پس‌زمینه انجام دهید.
- اگر آیپی سرور را عوض می‌کنید، همزمان آن را در پنل CDN و فایروال به‌روز کنید.
#آیا خطای 502 به سئو آسیب می‌زند؟
خطای 502 چند دقیقه‌ای به سئو آسیب جدی نمی‌زند، چون موتورهای جستجو خطاهای 5xx را موقتی در نظر می‌گیرند. طبق مستندات Google Search Central، گوگل در برخورد با خطاهای سرور سرعت خزش را کم می‌کند و صفحه‌هایی را که مدت طولانی خطا می‌دهند ممکن است از نتایج حذف کند. پس خطای 502 که چند ساعت یا چند روز ادامه پیدا کند، هم فروش را از بین می‌برد و هم جایگاه سایت را در جستجو.
#خبر خطای 502 را از بینا بگیرید
خطای 502 معمولاً بی‌صدا شروع می‌شود. سرور روشن است، کنترل‌پنل هاست چیزی نشان نمی‌دهد و صاحب سایت تا وقتی خودش صفحه را باز نکند یا مشتری پیام ندهد، از مشکل خبر ندارد.
بینا، سرویس مانیتورینگ سایت، در دسترس بودن سایت را مرتب بررسی می‌کند و هر پاسخ 5xx، از جمله خطای 502، را قطعی حساب می‌کند. همان لحظه با تلگرام، پیامک یا ایمیل هشدار میدهد و بعد از رفع مشکل هم خبر میدهد. در نمای کلی داشبورد هم پایداری سایت، تعداد مشکل‌ها و مدت باز ماندن هر مشکل را می‌بینید. زمان دقیق شروع قطعی در بینا ثبت می‌شود و همین زمان، اولین سرنخ برای پیدا کردن علت در گزارش‌های سرور است.
#جمع‌بندی
خطای 502 Bad Gateway یعنی سرور واسط از برنامه یا سرور پشت خود جواب درست نگرفته است. در بیشتر سایت‌ها علت یکی از این‌هاست: PHP-FPM یا برنامه سایت خاموش است، پردازش وسط کار متوقف شده، مسیر سوکت اشتباه است، هدر پاسخ بزرگ است یا CDN به سرور اصلی دسترسی ندارد.
گزارش خطای وب‌سرور سریع‌ترین راه پیدا کردن علت است. بعد از رفع خطای 502، علت اصلی را هم برطرف کنید و سایت را زیر نظر بگیرید تا اگر خطا برگشت، قبل از مشتری‌ها باخبر شوید.
پرسش‌های متداول
خطای 502 Bad Gateway چیست؟
خطای 502 Bad Gateway کد وضعیتی است که سرور واسط، مثل Nginx یا CDN، وقتی از برنامه یا سرور پشت خود جواب نامعتبر بگیرد یا اتصالش قطع شود، برمی‌گرداند.
خطای 502 از سمت کاربر است یا سرور؟
خطای 502 تقریباً همیشه از سمت سرور است. فقط در موارد کمی، وقتی سایت برای بقیه باز است، پروکسی یا فیلترشکن کاربر باعث آن می‌شود.
فرق خطای 502 و 504 چیست؟
خطای 502 یعنی سرور واسط جواب نامعتبر گرفته یا اتصال قطع شده است. خطای 504 یعنی سرور پشتی اصلاً در زمان مقرر جواب نداده است.
چرا وردپرس خطای 502 میدهد؟
وردپرس معمولاً وقتی خطای 502 میدهد که PHP-FPM خاموش شده، پردازش PHP به دلیل کمبود حافظه متوقف شده یا بعد از ارتقای نسخه PHP مسیر سوکت در تنظیمات Nginx اشتباه مانده است.
پیام upstream prematurely closed connection یعنی چه؟
پیام upstream prematurely closed connection یعنی برنامه سایت، مثلاً PHP، قبل از تمام کردن جواب اتصال را بسته است. علت رایجش تمام شدن حافظه یا قطع پردازش‌های طولانی است.
خطای 502 در CDN را چطور رفع کنم؟
برای رفع خطای 502 در CDN بررسی کنید سرور اصلی روشن است، آیپی آن در پنل CDN درست ثبت شده، فایروال سرور آیپیهای CDN را مسدود نکرده و تنظیمات HTTPS بین CDN و سرور اصلی هماهنگ است.
چطور زودتر از خطای 502 سایت باخبر شوم؟
با یک سرویس مانیتورینگ سایت مثل بینا، در دسترس بودن سایت مرتب بررسی می‌شود و به محض دیدن خطای 502 یا هر خطای 5xx دیگر، با تلگرام، پیامک یا ایمیل هشدار می‌گیرید.
نظرها