تفتح موقعك وتطلع لك صفحة فيها 502 Bad Gateway أو 504 Gateway Timeout. أحيانًا عليها شعار Cloudflare، وأحيانًا صفحة بيضاء فيها سطر واحد وتحته nginx. الرقمين قريبين من بعض، لكن معناهم مختلف، والتفريق بينهم نص الحل.
إيش يعني «Gateway» أصلًا
بين زائرك وتطبيقك غالبًا فيه وسيط: Cloudflare، أو nginx على السيرفر، أو موزّع الطلبات في منصة الاستضافة مثل Render و Railway و Replit. الوسيط يستقبل الطلب ويمرّره لتطبيقك، وينتظر الرد ويرجّعه للزائر.
- 502 Bad Gateway: الوسيط حاول يكلّم تطبيقك وما لقى أحد يرد، أو جاه رد خربان. التطبيق غالبًا واقف، أو تعطّل، أو يسمع على منفذ (port) غير اللي ينتظره الوسيط.
- 504 Gateway Timeout: الوسيط حاول يوصل لتطبيقك أو مرّر له الطلب، لكن ما جاه رد في الوقت المسموح. غالبًا التطبيق شغّال، لكنه بطيء أو عالق.
- في Cloudflare فيه رقم ثالث ممكن تشوفه:
Error 524: A timeout occurred، ومعناه إن Cloudflare وصل لسيرفرك لكن الرد تأخر أكثر من مهلته، وهي 125 ثانية في كل الخطط، وخطة Enterprise فقط تقدر ترفعها.
ليش يصير كثير في المنتجات المبنية بالذكاء الاصطناعي
- التطبيق يتعطّل عند أول خطأ: خطأ واحد ما انمسك (unhandled error) يوقف السيرفر كامل، وحتى يرجع يشتغل كل الزوار يشوفون 502.
- الذاكرة تخلص: خطة صغيرة فيها ذاكرة محدودة، والكود يحمّل بيانات كثيرة أو ملفات كبيرة مرة وحدة. النظام يقتل التطبيق، فيرجع يشتغل، ثم يتعطّل مرة ثانية.
- منفذ غلط: الكود يسمع على
3000ثابت، والمنصة تنتظره على المنفذ اللي تعطيه فيPORT. أو يسمع علىlocalhostفقط بدل0.0.0.0، فالوسيط ما يقدر يوصل له. شوف درس EADDRINUSE. - طلبات طويلة: توليد نص بالذكاء الاصطناعي أو تقرير داخل الطلب نفسه، فيطلع 504. نفس فكرة FUNCTION_INVOCATION_TIMEOUT في Vercel.
كيف تعرف المسؤول بنفسك
- شوف مين رسم الصفحة. صفحة خطأ Cloudflare فيها رسمة توضح وين المشكلة: المتصفح، أو Cloudflare، أو السيرفر (Host). إذا العلامة الحمراء عند Host، المشكلة عند سيرفرك مو عند Cloudflare. وإذا الصفحة بيضاء وتحتها
nginx، الوسيط هو nginx على سيرفرك. - كل الصفحات ولا صفحة وحدة؟ كل الصفحات تطلع 502: التطبيق واقف. صفحة وحدة تطلع 504: هالصفحة تسوي شيء ثقيل.
- افتح سجلات التطبيق في لوحة منصة الاستضافة، وروح للوقت اللي صار فيه الخطأ. دوّر على آخر سطر قبل ما يسكت التطبيق، أو على كلمات مثل
out of memoryأوkilledأوrestarting. - شوف استهلاك الذاكرة في لوحة المنصة. خط يطلع حتى السقف ثم ينزل فجأة يعني إن التطبيق ينقتل ويرجع.
الحل الصح
- 502 لأن التطبيق يتعطّل: السجل يقول ليش. الخطأ اللي يوقف السيرفر لازم ينمسك ويتسجّل، والطلب يرجع رسالة خطأ واضحة بدل ما يوقف كل شيء. وإذا السبب الذاكرة، الحل غالبًا في الكود، مثل تحميل البيانات على دفعات بدل كلها مرة وحدة، قبل ما يكون في ترقية الخطة.
- 502 لأن المنفذ غلط: التطبيق يقرأ المنفذ من
process.env.PORT. على منصة مثل Replit أو Render يسمع على0.0.0.0، أما على VPS خلف nginx فيسمع على127.0.0.1وعلى نفس المنفذ اللي في إعداد nginx، عشان ما ينفتح للعالم من غير nginx. - 504: الشغل الطويل يطلع من الطلب ويشتغل في الخلفية، والصفحة تتابع النتيجة. والطلبات للخدمات الخارجية لها حد زمني.
- مراقبة: أداة بسيطة تفتح موقعك كل دقيقة وتنبّهك إذا وقف، عشان تعرف قبل ما يعلّمك عميل.
الحل اللي لا تسويه
أشهر اقتراحين: ترفع كل المهل الزمنية في nginx و Cloudflare لأرقام كبيرة، أو تضيف إعادة تشغيل للسيرفر كل كم ساعة. الأول يخلّي الزائر ينتظر أطول قبل ما يشوف نفس الخطأ. والثاني يخبّي التعطّل بدل ما يصلّحه، ويقطع على المستخدمين اللي في نص عملية، مثل دفع أو رفع ملف.
قبل يوم الإطلاق
أغلب 502 و 504 تبان أول مرة يوم الزحمة: إعلان، أو إطلاق، أو رسالة انتشرت. اختبرها قبلها على نسخة تجريبية بأداة تحاكي زوار كثير، وشوف السجلات والذاكرة وقت الاختبار، مو بعده. الطريقة في درس منتجك يبطّأ أو يتعطّل لما يكثر الناس؟.
إذا ما عرفت السبب
احجز مكالمة استشارية: نقرأ السجلات معك ونوصل لسبب التعطّل، ويوصلك التسجيل وخطوات مكتوبة. وإذا المشكلة ترجع كل كم يوم، الإصلاح المباشر يصلّح السبب ويضيف المراقبة. لو منتجك على Replit، شوف بعد مشاكل Replit الأشهر.