رفع خطای Nginx 504 Gateway Timeout

پاسخ سریع

خطای 504 یعنی Upstream تا مهلت تعیین‌شده پاسخ کامل نداده؛ علت را در برنامه، دیتابیس، سرویس خارجی یا ظرفیت پیدا کنید.

Timeout یک بودجه انتهابه‌انتهاست. افزایش proxy_read_timeout ممکن است برای Job طولانی لازم باشد، اما برای Request معمولی اغلب گلوگاه را پنهان می‌کند.

اول نشانه را دقیق تعریف کنید

عبارت‌هایی مانند «کند است»، «وصل نمی‌شود» یا «RAM پر است» برای شروع کافی‌اند اما برای حل مشکل نه. زمان شروع، کاربران درگیر، Endpoint یا Process، پیام خطای دقیق و آخرین تغییر موفق را ثبت کنید. یک Timeline کوتاه معمولاً نصف مسیر تشخیص را روشن می‌کند.

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

علت‌های محتمل را لایه‌بندی کنید

از بیرون به داخل حرکت کنید: DNS و Route، Firewall و Port، Process و Service، منابع سیستم، Dependencyها و در نهایت منطق برنامه. این ترتیب از دست‌کاری برنامه برای مشکلی که در شبکه است جلوگیری می‌کند.

در هر لایه یک آزمون کم‌خطر انتخاب کنید که فرضیه را رد یا تأیید کند. نتیجه «کار نکرد» کافی نیست؛ فرمان، زمان و خروجی را ثبت کنید تا بتوانید مسیر را بازسازی و با همکار دیگری بررسی کنید.

• Request کند و Trace آن را مشخص کنید.
• Slow query، lock و pool exhaustion را بررسی کنید.
• زمان Nginx و Application را مقایسه کنید.

جمع‌آوری شواهد

Endpoint را مستقیم زمان‌گیری، Logهای upstream timing را تحلیل و dependencyهای آن را بررسی کنید. کار طولانی را به Queue منتقل کنید.

قبل از Restart یا Kill، وضعیت Processها، مصرف منابع، Connectionها و Log همان بازه را ذخیره کنید. ساعت Client و Server را تطبیق دهید؛ اختلاف زمان می‌تواند رویدادهای مرتبط را در چند Log از هم جدا نشان دهد.

1curl -sS -o /dev/null -w "%{time_connect} %{time_starttransfer} %{time_total}\n" https://example.com/path2sudo tail -f /var/log/nginx/error.log3sudo nginx -T | grep -n timeout

خروجی ابزارها را چطور بخوانیم؟

به یک عدد منفرد تکیه نکنید. CPU بالا همراه latency بالا معنای متفاوتی از CPU بالا با پاسخ سریع دارد؛ دیسک پر با inode آزاد با دیسکی که inode آن تمام شده یکسان نیست؛ و Connection refused با timeout مسیر عیب‌یابی متفاوتی دارد.

شاخص‌ها را در یک بازه و کنار Traffic، Deploy و Jobهای زمان‌بندی‌شده ببینید. به‌جای میانگین، p95، پیک و روند را بررسی کنید. همبستگی علت را ثابت نمی‌کند، اما فرضیه‌های شما را اولویت‌بندی می‌کند.

اصلاح کم‌خطر و مرحله‌ای

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

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

چرا راه‌حل‌های فوری گاهی بدتر می‌کنند؟

افزایش سراسری Timeout می‌تواند Workerها را مدت بیشتری اشغال و خرابی زنجیره‌ای را شدیدتر کند.

Restart، پاک‌کردن Cache، افزایش Timeout یا افزودن منابع ممکن است موقتاً نشانه را پنهان کند. اگر مجبور به اقدام اضطراری هستید، پیش از آن شواهد حداقلی بگیرید و پس از پایدارشدن سرویس تحلیل ریشه‌ای را در یک Incident review کامل کنید.

بعد از رفع مشکل

سلامت را فقط با ناپدیدشدن خطا تأیید نکنید؛ درخواست واقعی، latency، نرخ خطا و backlog را تا یک بازه کافی پایش کنید. سپس Alertی بسازید که قبل از رسیدن به همان وضعیت هشدار دهد.

علت، اثر، شواهد، اقدام اصلاحی و پیشگیری را کوتاه و بدون سرزنش ثبت کنید. اگر خطا با یک Runbook قابل تشخیص بود، آن را به Monitoring یا Automation تبدیل کنید تا دفعه بعد زمان بازیابی کمتر شود.

پرسش‌های مهمی که قبل از اقدام باید جواب دهید

برای اینکه پاسخ «رفع خطای Nginx 504 Gateway Timeout» فقط در حد اطلاعات عمومی نماند، ابتدا وضعیت فعلی خود را با عدد توصیف کنید: نسخه سیستم‌عامل یا نرم‌افزار، تعداد کاربر هم‌زمان، مصرف معمول و اوج منابع، حجم و رشد داده، محدودیت شبکه و بیشترین قطعی قابل قبول. بدون این اطلاعات ممکن است توصیه‌ای که از نظر فنی درست است، برای محیط شما انتخاب مناسبی نباشد.

دو سؤال بعدی مستقیماً از نکات این موضوع می‌آیند: «Request کند و Trace آن را مشخص کنید.» در زیرساخت شما چگونه اندازه‌گیری یا تأیید می‌شود؟ و «Slow query، lock و pool exhaustion را بررسی کنید.» چه اثری روی کاربر، هزینه یا مسیر بازیابی دارد؟ پاسخ را در قالب شواهدی مانند خروجی فرمان، نمودار متریک، نتیجه آزمون یا مستند ارائه‌دهنده ثبت کنید؛ اتکا به حافظه و حدس برای تصمیم عملیاتی کافی نیست.

یک برنامه عملی کم‌ریسک

کار را با ثبت وضعیت فعلی و یک معیار موفقیت آغاز کنید. سپس پیشنهاد اصلی این راهنما را در کوچک‌ترین محیط نماینده اجرا کنید: Endpoint را مستقیم زمان‌گیری، Logهای upstream timing را تحلیل و dependencyهای آن را بررسی کنید. کار طولانی را به Queue منتقل کنید. نتیجه را در حالت عادی و در یک سناریوی خطا یا فشار کنترل‌شده بسنجید. اگر معیار بهتر نشد، به‌جای افزودن تغییرات بیشتر، فرض اولیه را بازبینی کنید.

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

• Request کند و Trace آن را مشخص کنید.
• Slow query، lock و pool exhaustion را بررسی کنید.
• زمان Nginx و Application را مقایسه کنید.

چک‌لیست عیب‌یابی

برای حل «رفع خطای Nginx 504 Gateway Timeout» این ترتیب را حفظ کنید: تعریف نشانه، ثبت Timeline، بررسی لایه‌ها، جمع‌آوری شواهد، یک تغییر قابل بازگشت، اندازه‌گیری دوباره و اقدام پیشگیرانه. این روش شاید از یک Restart تصادفی کندتر به نظر برسد، اما نتیجه قابل اعتماد و تکرارپذیر می‌دهد.

• Request کند و Trace آن را مشخص کنید.
• Slow query، lock و pool exhaustion را بررسی کنید.
• زمان Nginx و Application را مقایسه کنید.