چرا Nginx خطای ۵۰۲ می‌دهد؟ راهنمای رفع Bad Gateway

پیام 502 Bad Gateway زمانی روی وب‌سایت یا اپلیکیشن نمایش داده می‌شود که Nginx نتواند پاسخ معتبری از سرور اصلی (Upstream) مانند PHP-FPM، Node.js یا Gunicorn دریافت کند. این خطا به مشکلاتی مانند از کار افتادن سرویس، تنظیمات نادرست Reverse Proxy، Timeout، اختلال در Socket یا محدودیت‌های دسترسی مربوط می‌شود.

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

$C:\Users\ErfanBiabi\AppData\Local\Microsoft\Windows\INetCache\Content.Word\ChatGPT Image Jun 17, 2026, 04_41_53 PM (1).png$

خطای ۵۰۲ Bad Gateway در Nginx چیست؟

Nginx یک وب‌سرور و Reverse Proxy است که بین کاربر و اپلیکیشن یا سرور اصلی قرار می‌گیرد. یعنی ابتدا درخواست‌های کاربران را دریافت می‌کند و سپس آن‌ها را به سرویس اصلی مانند PHP-FPM، Node.js، Gunicorn یا سایر برنامه‌های سمت سرور ارسال می‌کند. هدف Nginx این است که درخواست‌ها را به‌درستی مدیریت کند، بار پردازشی را توزیع کند و پاسخ نهایی را با سرعت بیشتری به کاربران تحویل دهد.

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

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

تفاوت ۵۰۲، ۵۰۳ و ۵۰۴

در کنار خطای 502 Bad Gateway، کاربران ممکن است با خطاهای دیگری مانند 503 Service Unavailable و 504 Gateway Timeout نیز هنگام باز کردن وب‌سایت یا اپلیکیشن مواجه شوند. هر یک از این خطاها علت متفاوتی دارند و دانستن تفاوت آن‌ها به شما کمک می‌کند مسیر عیب‌یابی را سریع‌تر و دقیق‌تر انتخاب کنید. در جدول زیر، تفاوت این سه کد وضعیت HTTP را مشاهده می‌کنید.

کد خطا	معنی	علت رایج
502 Bad Gateway	پاسخ نامعتبر از سرور اصلی	خرابی یا قطع ارتباط Upstream
503 Service Unavailable	سرویس در دسترس نیست	فشار زیاد، Maintenance یا کمبود منابع
504 Gateway Timeout	پاسخ بیش از حد طول کشیده است	Timeout بین Nginx و اپلیکیشن

لینک داخلی: اگر می‌خواهید تفاوت خطاهای سمت سرور را بهتر بشناسید، مقاله «علت داون شدن سایت در ترافیک بالا چیست؟» را نیز مطالعه کنید.

رایج‌ترین علت‌های خطای ۵۰۲ در Nginx

خطای ۵۰۲ Bad Gateway در Nginx علل مختلفی دارد و همیشه به معنای خرابی خود Nginx نیست. در اغلب موارد، این خطا به دلیل اختلال در ارتباط بین Nginx و سرویس اصلی (Upstream) ایجاد می‌شود. در ادامه، ۶ مورد از رایج‌ترین علت‌های بروز این خطا را به همراه روش تشخیص و رفع آن‌ها بررسی می‌کنیم.

۱. سرویس Upstream از کار افتاده است

زمانی که خطای 502 Bad Gateway را مشاهده می‌کنید، اولین احتمالی که باید بررسی شود از کار افتادن سرویس Upstream مانند PHP-FPM، Node.js یا Gunicorn است. در این وضعیت، Nginx درخواست کاربران را دریافت می‌کند اما هیچ پاسخی از سرویس اصلی دریافت نمی‌کند؛ در نتیجه خطای ۵۰۲ را به کاربر نمایش می‌دهد.

برای بررسی وضعیت سرویس، می‌توانید دستور زیر را اجرا کنید. اگر نتیجه‌ای مانند inactive، failed یا dead مشاهده کردید، به احتمال زیاد علت اصلی خطا متوقف شدن سرویس است و باید آن را مجدداً راه‌اندازی یا علت Crash شدن آن را بررسی کنید.

۲. اشتباه بودن Socket یا شماره پورت

گاهی اپلیکیشن روی پورت 9000 اجرا می‌شود اما Nginx به پورت دیگری متصل است یا مسیر فایل Socket به اشتباه در فایل پیکربندی وارد شده است. یکسان بودن آدرس Socket یا شماره پورت در تنظیمات Nginx و سرویس اصلی، برای برقراری ارتباط صحیح بین آن‌ها ضروری است. کوچک‌ترین مغایرت در این تنظیمات می‌تواند باعث نمایش خطای 502 Bad Gateway شود.

برای اینکه متوجه شوید این موضوع باعث بروز خطا شده است یا خیر، مراحل زیر را انجام دهید:

فایل تنظیمات Nginx را بررسی کنید و مقدار fastcgi_pass یا proxy_pass را مشاهده کنید.
مطمئن شوید اپلیکیشن روی همان پورت یا Socket مشخص‌شده در حال اجرا است.
دستور nginx -t را اجرا کنید تا از صحت فایل پیکربندی مطمئن شوید.
با استفاده از netstat یا ss بررسی کنید که سرویس واقعاً روی همان پورت در حال Listen کردن باشد.
پس از اصلاح تنظیمات، سرویس Nginx را Reload یا Restart کنید.

۳. Timeout بین Nginx و برنامه

اگر اپلیکیشن دیرتر از زمان تعیین‌شده پاسخ دهد، Nginx قبل از دریافت پاسخ، ارتباط را قطع می‌کند. این موضوع سومین علت رایج بروز خطای ۵۰۲ در Nginx است و معمولاً در زمان اجرای Queryهای سنگین، پردازش فایل‌های بزرگ یا افزایش ناگهانی ترافیک رخ می‌دهد.

در چنین شرایطی می‌توانید مقادیر proxy_read_timeout و proxy_connect_timeout را بررسی و در صورت نیاز افزایش دهید.

proxy_read_timeout 120;
proxy_connect_timeout 60;

البته افزایش Timeout فقط زمانی مفید است که علت اصلی کندی مشخص شده باشد. اگر کندی به دلیل مشکلاتی مانند کوئری‌های غیربهینه، کمبود منابع سرور یا اشکال در کدنویسی باشد، بیشتر کردن زمان انتظار تنها باعث افزایش مصرف منابع، اشغال شدن Connectionها و کاهش عملکرد کلی سرور خواهد شد.

۴. کمبود منابع PHP-FPM

اگر تعداد Worker Processها به سقف تعیین‌شده برسد یا حافظه سرور پر شود، درخواست‌های جدید دیگر پردازش نمی‌شوند و Nginx در دریافت پاسخ از PHP-FPM با مشکل مواجه خواهد شد.

این چهارمین علت رایج خطای 502 Bad Gateway است که ریشه آن معمولاً به کمبود منابع سخت‌افزاری یا تنظیمات نامناسب PHP-FPM برمی‌گردد.

برای تشخیص این مشکل بهتر است:

مقدار pm.max_children را بررسی کنید.
مصرف RAM و CPU سرور را کنترل کنید.
لاگ‌های PHP-FPM را مطالعه کنید.
در صورت مشاهده پیام‌هایی مانند server reached pm.max_children، تعداد Workerها را متناسب با منابع سرور افزایش دهید.
اگر مصرف حافظه بسیار زیاد است، اپلیکیشن را از نظر Memory Leak یا پردازش‌های سنگین بررسی کنید.

۵. مشکلات Permission روی Socket

در برخی سرورها، Nginx اجازه دسترسی به فایل Socket را ندارد و همین عدم دسترسی باعث می‌شود ارتباط با سرویس اصلی برقرار نشود و سایت خطای 502 Bad Gateway را نمایش دهد.

اگر به این موضوع مشکوک هستید، مراحل زیر را دنبال کنید:

مسیر فایل Socket را بررسی کنید.
مالک (Owner) و گروه (Group) فایل را مشاهده کنید.
سطح دسترسی (Permission) فایل را بررسی کنید.
مطمئن شوید کاربر Nginx (معمولاً www-data یا nginx) اجازه دسترسی به Socket را دارد.
در صورت نیاز، مقادیر chmod و chown را اصلاح کرده و سرویس‌ها را مجدداً راه‌اندازی کنید.

۶. محدودیت Firewall یا SELinux

آخرین علتی که می‌خواهیم در این مطلب بررسی کنیم، محدودیت‌های Firewall یا SELinux است. در برخی موقعیت‌ها، ارتباط بین Nginx و برنامه توسط تنظیمات امنیتی سیستم مسدود می‌شود و در نتیجه Nginx نمی‌تواند به سرویس Upstream متصل شود.

برای بررسی این مورد، ابتدا وضعیت Firewall و قوانین فعال آن را مشاهده کنید. اگر از SELinux استفاده می‌کنید، گزارش‌های امنیتی را نیز بررسی کنید تا مطمئن شوید ارتباط میان Nginx و اپلیکیشن توسط سیاست‌های امنیتی مسدود نشده است. در صورتی که مشکل از این بخش باشد، با اصلاح قوانین Firewall یا تنظیم Policy مناسب در SELinux، ارتباط دوباره برقرار شده و خطای ۵۰۲ برطرف خواهد شد.

چطور لاگ‌های Nginx را بررسی کنیم؟

برای پیدا کردن علت خطای 502 Bad Gateway، ابتدا باید لاگ خطاهای Nginx را بررسی کنید. با دستور زیر می‌توانید لاگ خطا را به‌صورت لحظه‌ای (Real-time) مشاهده کرده و هم‌زمان با وقوع خطا، پیام‌های ثبت‌شده را ببینید.

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

اگر هنگام بررسی لاگ با یکی از پیام‌های زیر مواجه شدید، توضیحات مربوط به آن را مطالعه کنید تا علت احتمالی خطا را سریع‌تر تشخیص دهید.

connect() failed (111: Connection refused)

این پیام نشان می‌دهد سرویس مقصد (مانند PHP-FPM یا Node.js) در حال اجرا نیست یا روی پورت موردنظر در دسترس قرار ندارد.

Upstream timed out

این خطا زمانی رخ می‌دهد که اپلیکیشن در زمان تعیین‌شده پاسخی به Nginx ارسال نکند و ارتباط به دلیل Timeout قطع شود.

Permission denied while connecting to upstream

این پیام نشان می‌دهد Nginx مجوز دسترسی به فایل Socket یا سرویس Upstream را ندارد.

Upstream prematurely closed connection

این خطا یعنی سرویس اصلی قبل از ارسال پاسخ کامل، ارتباط را به‌طور ناگهانی قطع کرده است.

Upstream sent too big header

این پیام نشان می‌دهد هدر ارسالی از سمت اپلیکیشن از اندازه مجاز Nginx بزرگ‌تر است و باید تنظیمات Buffer یا Header بررسی شوند.

چک‌لیست ۵ مرحله‌ای رفع خطای ۵۰۲

اگر نمی‌دانید عیب‌یابی را از کجا شروع کنید، مراحل زیر را به‌ترتیب انجام دهید؛ در بیشتر موارد، با همین چک‌لیست می‌توانید علت اصلی خطای 502 Bad Gateway را شناسایی کنید.

✅ وضعیت سرویس اصلی را بررسی کنید.

اولین قدم، اطمینان از فعال بودن سرویس اصلی مانند PHP-FPM، Node.js یا Gunicorn است. اگر این سرویس متوقف شده باشد، Nginx قادر به دریافت پاسخ نخواهد بود و خطای 502 را نمایش می‌دهد.

systemctl status php8.1-fpm

✅ تنظیمات Nginx را تست کنید.

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

nginx -t

✅ ارتباط مستقیم با Upstream را آزمایش کنید.

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

curl -v http://127.0.0.1:9000

✅ مقدار Timeoutها و Bufferها را بررسی کنید.

اگر اپلیکیشن برای پردازش درخواست‌ها به زمان بیشتری نیاز دارد، مقادیر Timeout و Buffer را بررسی کنید. البته قبل از افزایش این مقادیر، مطمئن شوید که کندی برنامه ناشی از مشکلات عملکردی یا کمبود منابع نیست.

proxy_read_timeout 120;
proxy_connect_timeout 60;
fastcgi_buffer_size 64k;

✅ سطح دسترسی فایل Socket و تنظیمات Firewall را کنترل کنید.

در آخر، مطمئن شوید Nginx به فایل Socket دسترسی دارد و هیچ قانون امنیتی در Firewall یا SELinux ارتباط بین Nginx و سرویس اصلی را مسدود نکرده است.

ls -la /var/run/php/
iptables -L
sestatus

اگر در این بخش‌ها مشکلی مشاهده کردید، با اصلاح سطح دسترسی فایل Socket یا تنظیم قوانین امنیتی، ارتباط میان Nginx و سرویس Upstream دوباره برقرار خواهد شد.

چرا راه‌حل‌های دستی همیشه کافی نیستند؟

بسیاری از مدیران سرور پس از مشاهده خطای 502 فقط یکی از اقدامات زیر را انجام می‌دهند:

ری‌استارت PHP-FPM
افزایش Timeout
افزایش pm.max_children
افزایش RAM

این اقدامات ممکن است مشکل را موقتاً برطرف کنند، اما معمولاً علت اصلی را از بین نمی‌برند.

اگر تیم فنی شما مرتباً با خطاهای 502، 503 یا کندی سرویس مواجه می‌شود، بهتر است هزینه پنهان مدیریت دستی سرور و همچنین مقاله «نشانه‌های ضعف زیرساخت؛ وقتی تیم فنی بیشتر با سرور می‌جنگد تا کد می‌نویسد» را نیز بررسی کنید.

راهکار ریشه‌ای برای کاهش خطاهای ۵۰۲

در زیرساخت‌های مدرن مبتنی بر PaaS، بسیاری از وظایفی که باعث بروز خطاهای 502 می‌شوند به‌صورت خودکار مدیریت می‌شوند، از جمله:

استقرار خودکار با Git
مدیریت Reverse Proxy
ری‌استارت خودکار برنامه پس از Crash
مانیتورینگ سلامت سرویس
مدیریت SSL
مقیاس‌پذیری ساده‌تر

اگر می‌خواهید بیشتر با این معماری آشنا شوید، مطالعه مقاله «PaaS چیست؟» می‌تواند دید بهتری نسبت به این رویکرد به شما بدهد.

ما در چابکان تمام ابزارهای موردنیاز را در اختیار تیم‌های توسعه قرار داده‌ایم تا به‌جای صرف زمان برای مدیریت و عیب‌یابی زیرساخت، روی توسعه محصول تمرکز کنند. چابکان یک پلتفرم ابری (PaaS) ایرانی است که با استقرار خودکار از طریق Git و مدیریت خودکار زیرساخت و مقیاس‌پذیری سرویس‌ها، بسیاری از چالش‌های رایج مدیریت سرور را برطرف می‌کند.

اگر می‌خواهید این قابلیت‌ها را از نزدیک تجربه کنید، می‌توانید همین امروز با اعتبار رایگان در چابکان ثبت‌نام کنید و بدون نیاز به پیکربندی پیچیده سرور، اپلیکیشن خود را مستقر کنید.

بهترین روش‌های پیشگیری از خطای ۵۰۲

برای کاهش احتمال بروز این خطا، رعایت این موارد توصیه می‌شود:

استفاده از Process Manager مناسب
مانیتورینگ مداوم سرویس‌ها
Health Check خودکار
تنظیم صحیح Timeoutها
Load Testing قبل از انتشار نسخه جدید
بررسی منظم لاگ‌های Nginx و اپلیکیشن
به‌روزرسانی نسخه‌های Nginx و Runtime

جدول خلاصه علت‌ها و راه‌حل‌ها

علت	راه‌حل سریع	سختی رفع
توقف Upstream	Restart سرویس	آسان
Socket یا Port اشتباه	اصلاح تنظیمات Nginx	آسان
Timeout	بررسی عملکرد برنامه و تنظیم Timeout	متوسط
اشباع PHP-FPM	افزایش Workerها و بهینه‌سازی منابع	متوسط
Permission	اصلاح مالکیت و سطح دسترسی Socket	متوسط
Firewall یا SELinux	اصلاح قوانین امنیتی	پیشرفته

جمع‌بندی

اگر در ابتدای مقاله این سؤال برایتان مطرح بود که چرا Nginx خطای 502 می‌دهد؟ اکنون پاسخ روشن است: خود Nginx در بیشتر مواقع مشکلی ندارد و این اختلال در ارتباط با سرویس Upstream، تنظیمات نادرست، کمبود منابع یا محدودیت‌های دسترسی است که باعث نمایش خطای 502 Bad Gateway می‌شود. بنابراین، برای رفع این خطا باید ابتدا علت اصلی را شناسایی کنید، نه اینکه صرفاً سرویس‌ها را ری‌استارت یا تنظیمات را تغییر دهید.

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

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

سوالات متداول (FAQ)

۱. رایج‌ترین علت خطای 502 Bad Gateway در Nginx چیست؟

رایج‌ترین علت، از کار افتادن سرویس Upstream مانند PHP-FPM، Node.js یا Gunicorn و ناتوانی Nginx در دریافت پاسخ از آن است.

۲. چگونه علت خطای 502 در Nginx را پیدا کنیم؟

بهترین راه، بررسی فایل لاگ Nginx (error.log) و وضعیت سرویس Upstream برای شناسایی دقیق منشأ خطا است.

۳. آیا با ری‌استارت کردن Nginx خطای 502 برطرف می‌شود؟

خیر، ری‌استارت Nginx معمولاً راه‌حل دائمی نیست و تا زمانی که علت اصلی مانند Timeout، تنظیمات نادرست یا اختلال در سرویس Upstream برطرف نشود، خطا ممکن است دوباره تکرار شود.

چرا Nginx خطای ۵۰۲ می‌دهد؟ راهنمای رفع Bad Gateway