Loading...

خطاهای HTTP

504 Gateway Timeout: چه کسی منتظر ماند، چقدر، و چگونه رفعش کنیم

خطای 504 یک مشکل انتظار است، نه اتصال خراب. پروکسی‌ای که جلوی سایت شما قرار دارد صفحه‌ای را از سرور شما خواست، تا آنجا که اجازه داشت منتظر ماند و تسلیم شد. این راهنما نشان می‌دهد چطور بفهمید چه کسی منتظر چه کسی بوده، کدام timeout زودتر تمام شده و چطور بخش کند را درست کنید، نه اینکه آن را پنهان کنید.

9 دقیقه مطالعه متوسط به‌روزرسانی

504 Gateway Timeout: چه کسی منتظر ماند، چقدر، و چگونه رفعش کنیم

خطای 504 دقیقاً چه می‌گوید

gateway هر چیزی است که درخواستی را می‌گیرد و به جلو می‌فرستد: edge یک CDN، یک load balancer، یا nginx جلوی PHP-FPM یا Node. 504 Gateway Timeout یعنی gateway می‌گوید: به سروری که پشت من است رسیدم، پرسیدم و پاسخ پیش از رسیدن به محدودیت من نیامد.

همین، 504 را از همسایه‌هایش جدا می‌کند. 502 Bad Gateway یعنی پاسخ قابل استفاده نبود یا اتصال برقرار نشد. 503 Service Unavailable یعنی چیزی عمداً درخواست را برگرداند. 504 یعنی هیچ‌کس چیزی را رد نکرده است: درخواست پذیرفته شده و حتی ممکن است پس از نمایش خطا به بازدیدکننده، هنوز روی سرور شما در حال اجرا باشد.

این نکتهٔ آخر در عمل مهم است. 504 کار را لغو نمی‌کند: گزارشی که در پروکسی timeout شده می‌تواند یک دقیقه بعد روی مبدأ تمام شود، و بازدیدکننده‌ای که دوباره دکمه را بزند نسخهٔ دومی را شروع می‌کند.

چه کسی منتظر چه کسی است

یک درخواست معمولی از چند نقطهٔ انتظار می‌گذرد: بازدیدکننده ← edge CDN ← وب‌سرور شما (nginx یا Apache) ← برنامهٔ شما (PHP-FPM، Node، یک کانتینر) ← پایگاه داده یا یک API بیرونی. هر فلش یک gateway با timeout مخصوص خودش است و این مقدارها جداگانه و اغلب توسط افراد مختلف تنظیم شده‌اند.

قاعده‌ای که بیشترین وقت را نجات می‌دهد: کوتاه‌ترین timeout در زنجیره همان است که فعال می‌شود. اگر edge 60 ثانیه صبر کند، nginx شما 60 ثانیه منتظر PHP-FPM بماند و PHP اجرای اسکریپت را بعد از 30 ثانیه قطع کند، درخواست هرگز به محدودیت edge نمی‌رسد؛ PHP در 30 ثانیه آن را تمام می‌کند و حلقهٔ بالاتر شکست را گزارش می‌دهد.

پس اولین پرسش این نیست که «چرا CDN timeout می‌شود»، بلکه این است که پیش از ظاهر شدن خطا چقدر طول کشید؟ یک 504 در حدود دقیقاً 60 ثانیه به محدودیت 60 ثانیه‌ای اشاره می‌کند؛ یکی در 30 ثانیه، به محدودیت 30 ثانیه‌ای. این عدد را با محدودیت‌هایی که می‌شناسید مقایسه کنید؛ معمولاً حلقه‌ای که تسلیم شده خودش را نشان می‌دهد.

علت‌های پشت تقریباً هر 504

یک query کند. یک query بدون index مناسب که جدولی را پیمایش می‌کند که از ده هزار ردیف به ده میلیون رسیده است. در زمان راه‌اندازی سریع بود و امروز کند است، بی‌آنکه چیزی در کد تغییر کرده باشد.

کار ذاتاً طولانی. export به CSV و Excel، گزارش‌های PDF، import حجیم، پردازش تصویر یا ویدیو، یک backup که از صفحهٔ مدیریت شروع شده است. این‌ها باگ نیستند؛ کارهایی هستند که نباید داخل یک درخواست وب اجرا شوند.

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

مبدأ بیش‌ازحد بارگرفته. وقتی همهٔ workerها یا threadهای PHP-FPM مشغول‌اند، درخواست‌های جدید حتی پیش از شروع در صف می‌مانند. شاید هر درخواست سریع باشد؛ این انتظار در صف است که زمان را تمام می‌کند. این 504ها در اوج ترافیک خوشه می‌شوند.

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

عیب‌یابی: ببینید زمان کجا می‌رود

درخواست را یک بار از طریق CDN و یک بار مستقیم به مبدأ زمان‌گیری کنید. curl می‌تواند زمان را به فازها تقسیم کند، مانند دستورهای زیر.

اگر connect بزرگ است یا هرگز تمام نمی‌شود، مشکل در رسیدن به مبدأ است: فایروال، مسیریابی، سروری که از کار افتاده. اگر connect سریع است و ttfb (زمان تا اولین بایت) طولانی، مبدأ درخواست را پذیرفته و هنوز مشغول کار است؛ همان 504 کلاسیک، و پاسخ در برنامهٔ شماست.

دستور دوم با --resolve از CDN عبور می‌کند و همچنان نام میزبان شما را می‌فرستد. اگر مبدأ به‌تنهایی هم 70 ثانیه طول بکشد، edge حقیقت را گزارش می‌کند. اگر مستقیم در دو ثانیه پاسخ می‌دهد اما از طریق CDN timeout می‌شود، به تفاوت‌ها نگاه کنید: یک قاعدهٔ فایروال، backend دیگری برای آن نام میزبان، یا سرآیندهایی که برنامهٔ شما متفاوت رفتار می‌کند.

سپس لاگ‌های خود مبدأ را برای همان لحظه بخوانید. در nginx، $request_time و $upstream_response_time را به log format اضافه کنید؛ در Apache، %D را. slow query log پایگاه داده را فعال کنید و برای PHP، slowlog در PHP-FPM را که برای هر درخواستِ بیش‌ازحد طولانی یک stack trace می‌نویسد؛ معمولاً سریع‌ترین راه تا خط دقیق است.

زمان‌گیری یک درخواست از طریق CDN و مستقیم به مبدأ

# through the CDN
curl -o /dev/null -s -w 'connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  https://www.example.com/reports/export

# straight to the origin, same hostname
curl -o /dev/null -s -w 'connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
  --resolve www.example.com:443:ORIGIN_IP https://www.example.com/reports/export

ابتدا بخش کند را درست کنید

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

index و cache. query کند را در slow log پیدا کنید و index لازمش را اضافه کنید. نتایجی را که بسیاری از بازدیدکنندگان مشترکاً استفاده می‌کنند cache کنید، در برنامه یا در edge با سرآیندهای Cache-Control.

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

برای هر فراخوانی بیرونی timeout جداگانه بگذارید. چند ثانیه، با یک fallback معقول، تا قطعی شرکتی دیگر قطعی شما نشود.

مبدأ را برای اوج اندازه کنید. اگر 504ها در ساعت‌های شلوغ خوشه می‌شوند، workerها را اضافه کنید (pm.max_children در PHP-FPM، پردازه‌های Node، replicaهای کانتینر) و بگذارید cache در edge درخواست‌های تکراری را جذب کند تا اصلاً کمتر به مبدأ برسند.

timeout را فقط جایی بالا ببرید که به آن تعلق دارد

بعضی درخواست‌ها ذاتاً طولانی‌اند: یک آپلود بزرگ که در حال پردازش است، گزارشی که قابل تقسیم نیست، API‌ای که نتایج را stream می‌کند. برای آن‌ها محدودیت را بالا ببرید، فقط برای همان مسیر و در هر حلقه.

در cdn.com.tr این یک تنظیم قانون تحویل است: مهلت پاسخ سرور مبدأ (ثانیه)، از 1 تا 3,600 ثانیه برای هر قانون، با پیش‌فرض 60 ثانیه. برای مسیری که به آن نیاز دارد یک قانون جداگانه بسازید، مثلاً /admin/export/، و فقط به همان قانون timeout بلندتری بدهید. بقیهٔ سایت پیش‌فرض کوتاه را نگه می‌دارد و وقتی واقعاً چیزی خراب است همچنان سریع شکست می‌خورد. در دامنهٔ یک برنامهٔ Managed Container، پیش‌فرض 300 ثانیه است مگر اینکه قانون مقدار دیگری تعیین کند.

این timeout زمان بین دو تکه داده از مبدأ شما را می‌شمارد، نه طول کل درخواست را. تا وقتی داده جریان دارد، edge درخواست را باز نگه می‌دارد. به همین دلیل یک پاسخ stream‌شده، مثل CSV که ردیف‌به‌ردیف نوشته می‌شود یا یک feed پیشرفت، می‌تواند چند دقیقه ادامه یابد، اما اسکریپتی که پنج دقیقه محاسبه می‌کند و بعد همه‌چیز را یک‌جا چاپ می‌کند نمی‌تواند.

سپس حلقه‌های پشت edge را هماهنگ کنید: proxy_read_timeout یا fastcgi_read_timeout در nginx، max_execution_time در PHP، و محدودیت خود application server شما. یک مسیر طولانی فقط به اندازهٔ کوتاه‌ترین محدودیتش طولانی است.

وقتی یک CDN جلوی سرور است

CDN هزینهٔ یک 504 را برای شما تغییر می‌دهد.

صفحه‌های cache‌شده همچنان سرو می‌شوند. در قانونی که cache می‌کند، اگر مبدأ شما timeout شود در حالی که edge هنوز یک نسخه از صفحه را دارد، حتی منقضی‌شده، edge همان نسخه را به‌جای خطا سرو می‌کند. یک دقیقهٔ کند روی مبدأ به‌جای صفحهٔ خراب، یک صفحهٔ کمی قدیمی می‌شود. این دلیل خوبی است که هر چه را می‌شود cache کنید، با TTLهایی که با دفعات واقعی تغییر محتوا هماهنگ باشند.

مسیرهای کند دیده می‌شوند. وقتی 504ها فقط روی /search یا /checkout ظاهر می‌شوند، یعنی مسیرهای پویا و بدون cache، دقیقاً می‌دانید کجا را بگردید.

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

نحوه راه‌اندازی

راهنماهای گام‌به‌گام در مرکز راهنما:

پرسش‌های پرتکرار دربارهٔ 504 Gateway Timeout

خطای 504 تقصیر سرور من است یا CDN؟

در بیشتر موارد زمان روی مبدأ شما صرف می‌شود و edge همان است که منتظر مانده. یک درخواست از طریق CDN را با یک درخواست مستقیم به مبدأ مقایسه کنید. اگر مبدأ به‌تنهایی هم همین‌قدر کند است، راه‌حل روی مبدأ است؛ اگر مستقیم سریع است و فقط از طریق CDN کند، دنبال تفاوتی در فایروال یا مسیریابی بگردید که روی اتصال edge اثر می‌گذارد.

timeout پیش‌فرض مبدأ در cdn.com.tr چقدر است؟

60 ثانیه بدون دریافت داده از مبدأ شما. می‌توانید آن را برای هر قانون تحویل از 1 تا 3,600 ثانیه در مهلت پاسخ سرور مبدأ (ثانیه) تنظیم کنید. در دامنهٔ یک برنامهٔ Managed Container پیش‌فرض 300 ثانیه است.

آیا timeout را همه‌جا روی 3,600 ثانیه بگذارم؟

خیر. timeout بلند روی همهٔ مسیرها یعنی وقتی واقعاً چیزی خراب می‌شود، بازدیدکنندگان به‌جای دریافت پاسخ در یک دقیقه، یک ساعت به یک spinner خیره می‌مانند و درخواست‌های گیرکرده روی مبدأ شما انباشته می‌شوند. پیش‌فرض را برای سایت نگه دارید و فقط روی قانون مسیری که ذاتاً کند است بالا ببرید.

چرا export من برای فایل‌های کوچک کار می‌کند و برای بزرگ‌ها شکست می‌خورد؟

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

آیا با وجود سریع بودن برنامه هم می‌توانم 504 بگیرم؟

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

آیا refresh کردن صفحه کمک می‌کند؟

گاهی، اما هر refresh همان کار کند را دوباره روی مبدأ شما شروع می‌کند. در صفحه‌های سنگین، refreshهای مکرر دقیقاً وقتی بار اضافه می‌کنند که سرور از قبل در تنگناست.