مشخصات پیشنهادی انتشار
عنوان سئو
رفع خطای 502 Bad Gateway در Nginx | نگهبان وب
توضیح متا
علت خطای 502 در Nginx را با بررسی لاگ، وضعیت برنامه و ارتباط upstream پیدا کنید؛ راهنمای مرحله‌ای تشخیص و جلوگیری از تکرار خطا را بخوانید.
مسیر پیشنهادی
/blog/nginx-502-bad-gateway
عبارت اصلی
رفع خطای 502 در Nginx
تصویر
nginx-502-bad-gateway.webp
یادداشت انتشار
تصویر را در CMS بارگذاری و تاریخ واقعی انتشار و URL تصویر را ثبت کنید.

خطای 502 Bad Gateway معمولاً یعنی یک واسط مانند Nginx نتوانسته پاسخ معتبر از سرویس پشت خود دریافت کند. علت می‌تواند خاموش بودن برنامه، اشتباه بودن مقصد اتصال، مشکل شبکه داخلی یا بسته شدن غیرمنتظره ارتباط باشد. خود عدد ۵۰۲ علت نهایی را نشان نمی‌دهد؛ برای پیدا کردن علت باید مسیر درخواست و لاگ همان لحظه را بررسی کنید.

راه درست از ثبت شواهد شروع می‌شود. ری‌استارت هم‌زمان همه سرویس‌ها ممکن است موقتاً خطا را پنهان کند و تشخیص مشکل تکرارشونده را سخت‌تر کند. مراحل زیر برای زیرساختی است که مجوز مدیریت آن را دارید؛ نام سرویس و آدرس‌ها باید با محیط واقعی تطبیق داده شوند.

قدم اول: مشخص کنید خطا از کدام لایه می‌آید

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

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

قدم دوم: لاگ Nginx را با زمان خطا تطبیق دهید

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

sudo nginx -t
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --since '15 minutes ago' --no-pager

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

پیام‌های رایج چه معنایی دارند؟

نمونه پیام در لاگ مسیر بررسی پیشنهادی
connection refused هنگام اتصال به upstream اجرا بودن برنامه و درست بودن پورت مقصد
no live upstreams در دسترس بودن مقصدهای تعریف‌شده و تنظیم upstream
upstream prematurely closed connection کرش برنامه، پایان اجباری worker یا قطع ارتباط
upstream sent too big header اندازه header و cookie و سپس تنظیم buffer مناسب
upstream timed out مدت پردازش، دیتابیس و timeoutهای مسیر؛ اغلب همراه خطای ۵۰۴

این پیام‌ها سرنخ‌اند، نه تشخیص قطعی. مثلاً connection refused الزاماً به معنی خراب بودن Nginx نیست؛ ممکن است برنامه اصلاً روی پورت موردنظر گوش ندهد. همچنین افزایش buffer باید پس از فهمیدن دلیل بزرگ شدن header انجام شود.

قدم سوم: مقصد واقعی برنامه را آزمایش کنید

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

ss -lnt
curl -sS --max-time 5 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health

آدرس بالا صرفاً نمونه است؛ فقط endpoint سلامت بدون اثر جانبی را انتخاب کنید. اگر Nginx داخل کانتینر باشد، localhost به همان کانتینر اشاره دارد، نه الزاماً به میزبان یا کانتینر برنامه. در شبکه مشترک Compose، نام سرویس و پورت داخلی معمولاً مبنای ارتباط هستند.

قدم چهارم: برنامه و وابستگی‌ها را ببینید

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

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

چه زمانی timeout را تغییر دهیم؟

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

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

پس از رفع خطا، از تکرار جلوگیری کنید

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

پرسش‌های رایج

آیا خطای ۵۰۲ همیشه با ری‌استارت حل می‌شود؟

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

تفاوت ۵۰۲ و ۵۰۴ چیست؟

۵۰۲ به پاسخ نامعتبر از سرویس بالادست اشاره دارد؛ ۵۰۴ معمولاً پایان زمان انتظار واسط برای دریافت پاسخ است. لایه تولیدکننده خطا را هم بررسی کنید.

برای بررسی حرفه‌ای، درخواست رفع مشکل موردی را با زمان رخداد، مسیر خطادار و آخرین تغییر ثبت کنید.

منابع و مطالعه بیشتر