مهلات Keep-Alive في Node.js خلف موازن الأحمال: كيف نوقف أخطاء 502 العشوائية في NestJS
جدول المحتويات
عن الكاتب

Ahmed Mahmoud
كاتب ومطوّر
مهندس برمجيات شغوف بتطوير الويب وتصميم تجربة المستخدم.
مؤسّس ديفيا · eng-ahmed.com ↗الخلاصة: أخطاء 502 العشوائية الصادرة عن AWS Application Load Balancer أو Nginx أمام خادم Node.js سليم تعود غالبًا إلى قيمة افتراضية واحدة: http.Server.keepAliveTimeout تساوي 5 ثوانٍ، وهي أقصر من مهلة الخمول في الوسيط البالغة 60 ثانية. في Devya نضبط مهلة keep-alive في Node.js على قيمة أعلى من مهلة خمول الوسيط، ونطبّق القاعدة نفسها بالعكس على طلبات fetch الصادرة.
بلاغ الخطأ يتكرر بالصيغة نفسها: نسبة صغيرة من الطلبات تفشل برمز 502، بلا نمط واضح حسب المسار، وسجلات التطبيق لا تُظهر شيئًا. السجلات فارغة لأن الطلب لم يصل إلى الكود أصلًا. تشرح هذه الملاحظات سبب ذلك، والسطر الواحد الذي يعالجه في NestJS، والمشكلة المعكوسة في الطلبات الصادرة.
أهم النقاط
- Node.js يغلق الاتصالات الخاملة بعد 5 ثوانٍ: القيمة الافتراضية لـ server.keepAliveTimeout هي 5000 مللي ثانية في http.Server.
- الوسطاء ينتظرون أطول بكثير: AWS Application Load Balancer يُبقي الاتصالات الخاملة 60 ثانية افتراضيًا، وكذلك مجمع اتصالات upstream في Nginx.
- القاعدة لكل قفزة: الطرف الذي يرسل الطلبات يجب أن يتخلى عن الاتصال الخامل قبل الطرف الذي يستقبلها.
- الحل في NestJS سطر واحد: app.getHttpServer().keepAliveTimeout = 65_000 مع محوّل Express، أما Fastify فقيمته الافتراضية 72 ثانية.
- الطلبات الصادرة تعاني السباق نفسه: fetch في Node.js يحتفظ بمجمع اتصالات، وإعادة استخدام مقبس أغلقه الخادم البعيد تفشل بخطأ ECONNRESET.
لماذا يُرجع موازن الأحمال أخطاء 502 عشوائية أمام خادم Node.js سليم؟
يُرجع موازن الأحمال خطأ 502 عشوائيًا عندما يعيد استخدام اتصال keep-alive خامل في اللحظة نفسها التي يغلقه فيها Node.js. خاصية HTTP keep-alive، أي إعادة استخدام اتصال TCP واحد لعدة طلبات في HTTP/1.1، تسمح لموازن الأحمال بالاحتفاظ بمجمع اتصالات مفتوحة مع كل خادم خلفي. Node.js يغلق أي اتصال بقي خاملًا لمدة keepAliveTimeout، وهي 5 ثوانٍ افتراضيًا، بينما يعتبر موازن الأحمال الاتصال نفسه صالحًا حتى 60 ثانية.
السباق يحتاج إلى بضع مللي ثوانٍ فقط. يكتب موازن الأحمال طلبًا على الاتصال بينما إغلاق Node.js ما زال في الطريق. يرد Node.js بإعادة ضبط TCP، فلا يجد موازن الأحمال استجابة يمررها، ويحصل العميل على 502 Bad Gateway. المعالج لم يعمل أصلًا، ولذلك تبقى سجلات NestJS نظيفة. الخدمات قليلة الحركة تتعرض لهذا أكثر من المزدحمة، لأن اتصالاتها تبقى خاملة مدة كافية لبلوغ حد الخمس ثوانٍ.
ما القيم الافتراضية لمهلات keep-alive في Node.js و AWS ALB و Nginx؟
القيم الافتراضية غير متوافقة، والطرف المستقبِل هو الأقصر في أغلب الأحيان. تحققنا من قيم Node.js على إصدار حديث عبر http.createServer(): keepAliveTimeout تساوي 5000، و headersTimeout تساوي 60000، و requestTimeout تساوي 300000.
- من AWS ALB إلى Node.js: مهلة خمول ALB تساوي 60 ثانية و keepAliveTimeout في Node.js تساوي 5 ثوانٍ. نضبط Node.js على 65 ثانية.
- من مجمع upstream في Nginx إلى Node.js: قيمة keepalive_timeout في upstream تساوي 60 ثانية و keepAliveTimeout في Node.js تساوي 5 ثوانٍ. نضبط Node.js على 65 ثانية.
- من Google Cloud Application Load Balancer إلى الخادم الخلفي: مهلة keep-alive للخادم الخلفي ثابتة عند 600 ثانية. نضبط Node.js على 620 ثانية.
- من fetch في Node.js إلى واجهة برمجية أخرى: undici يُبقي الاتصالات الخاملة 4 ثوانٍ افتراضيًا. قيمة العميل يجب أن تبقى أقل من قيمة الخادم البعيد.
Node.js يعلن مهلته أيضًا. كل استجابة keep-alive تحمل الترويسة Keep-Alive: timeout=5، لكن AWS ALB و Nginx لا يعدّلان مجمع اتصالاتهما بناءً عليها. الإصدارات الأحدث من Node.js تضيف server.keepAliveTimeoutBuffer بقيمة افتراضية 1000 مللي ثانية، وهي تُبقي المقبس مفتوحًا مدة أطول قليلًا من القيمة المعلنة. هامش الثانية الواحدة يفيد العملاء الذين يحترمون الترويسة، لكنه لا يسد فجوة مقدارها 55 ثانية.
كيف نضبط keepAliveTimeout في NestJS؟
في NestJS مع محوّل Express الافتراضي نضبط keepAliveTimeout على كائن http.Server الذي تعيده app.getHttpServer(). القيمة يجب أن تكون أكبر من مهلة خمول موازن الأحمال، ولذلك نستخدم 65 ثانية مع ALB المتروك على قيمته الافتراضية 60 ثانية.
في ملف main.ts، بعد NestFactory.create(AppModule)، نستدعي const server = app.getHttpServer() ثم نسند server.keepAliveTimeout = 65_000 قبل app.listen().
محوّل Fastify في NestJS لا يحتاج إلى تغيير مع وسيط مهلته 60 ثانية، لأن Fastify يضبط keepAliveTimeout على 72 ثانية افتراضيًا. ومع مهلة وسيط أطول نمرر الخيار إلى المحوّل: new FastifyAdapter({ keepAliveTimeout: 620_000 }).
نحفظ الرقم في متغير بيئة واحد بجوار إعدادات موازن الأحمال، لأن القيمتين صحيحتان فقط نسبةً إلى بعضهما. رفع مهلة خمول ALB إلى 120 ثانية دون تعديل Node.js يعيد أخطاء 502.
هل يحتاج Nginx إلى الحل نفسه؟
يحتاج Nginx إلى الحل نفسه فقط عند تفعيل keep-alive مع upstream. بدون التعليمة keepalive داخل كتلة upstream يفتح Nginx اتصالًا جديدًا مع Node.js لكل طلب، فلا يوجد اتصال خامل يحدث عليه السباق. ومع تفعيل المجمع، وهو يتطلب أيضًا proxy_http_version 1.1 وترويسة Connection فارغة، يُبقي Nginx اتصالات upstream الخاملة 60 ثانية افتراضيًا.
عندما يسبق Node.js وسيط Nginx في السباق يظهر في سجل أخطاء Nginx النص: upstream prematurely closed connection while reading response header from upstream. الحل إما رفع keepAliveTimeout في Node.js فوق 60 ثانية أو خفض keepalive_timeout في upstream تحت قيمة Node.js. كلاهما يحقق القاعدة، ونفضّل رفع قيمة Node.js ليبقى المجمع جاهزًا.
لماذا تفشل طلبات fetch الصادرة من Node.js بخطأ ECONNRESET؟
تفشل طلبات fetch الصادرة بخطأ ECONNRESET عندما تعيد عملية Node.js استخدام اتصال من المجمع أغلقه الخادم البعيد مسبقًا. في الطلبات الصادرة خدمتنا هي المرسِل، فتنعكس الأدوار: مهلة الخمول عند العميل يجب أن تكون أقصر من مهلة الخادم البعيد. fetch في Node.js يعمل فوق undici، وهو عميل HTTP المضمّن في Node.js، و undici يُبقي الاتصالات الخاملة 4 ثوانٍ افتراضيًا. أما http.globalAgent القديم فيعمل بخيار keepAlive: true منذ Node.js 19 مع مهلة خمول 5 ثوانٍ.
undici يقرأ ترويسة الاستجابة Keep-Alive: timeout=N ويحتفظ بالاتصال مدة قريبة منها، بحد أقصى هو keepAliveMaxTimeout. الخادم الذي يعلن مهلة طويلة وهو يقف خلف وسيط مهلته أقصر ينتج مقابس منتهية. مع fetch يظهر الفشل على شكل TypeError: fetch failed وسببه خطأ مقبس في الخاصية cause.
نضع حدًا لهذه القيمة عبر Agent من undici: setGlobalDispatcher(new Agent({ keepAliveTimeout: 4_000, keepAliveMaxTimeout: 30_000 })). ونعيد المحاولة عند إعادة ضبط الاتصال، لكن للطلبات المتكررة الأثر فقط مثل GET و PUT. طلب POST الذي انقطع على مقبس معاد ضبطه ربما وصل إلى المعالج البعيد وربما لم يصل، ولذلك نعيد محاولة POST فقط عندما يحمل الطلب مفتاح idempotency.
كيف نتأكد أن مهلات keep-alive هي السبب؟
نتأكد من السبب بمطابقة ثلاث إشارات قبل أي تغيير. أولًا: أخطاء 502 لا يقابلها أي سطر في سجلات التطبيق. ثانيًا: سجلات الوصول في ALB تُظهر elb_status_code بقيمة 502 مع target_status_code بقيمة -، أي أن الخادم الهدف لم ينتج استجابة. ثالثًا: تنفيذ curl -v مباشرة على منفذ Node.js يُظهر Keep-Alive: timeout=5، وهذا يثبت أن القيمة الافتراضية ما زالت قائمة.
بعد الإصلاح نقرأ server.keepAliveTimeout مرة واحدة عند الإقلاع ونسجلها بجوار مهلة الوسيط المضبوطة. لا نذكر هنا نسبة أخطاء قبل الإصلاح وبعده، لأن النسبة تعتمد كليًا على شكل الحركة. الإشارة التي نراقبها هي اختفاء أخطاء 502 غير المفسرة ذات حالة الهدف الفارغة.
الأسئلة الشائعة
س: ما القيمة المناسبة لـ keepAliveTimeout خلف AWS ALB؟
ج: قيمة أعلى من مهلة خمول ALB. مع المهلة الافتراضية 60 ثانية تكفي server.keepAliveTimeout = 65_000.
س: هل ما زلنا بحاجة إلى ضبط headersTimeout أعلى من keepAliveTimeout؟
ج: تلك النصيحة كانت التفافًا على خلل في إصدارات Node.js الأقدم. في الإصدارات الحالية القيمة الافتراضية لـ headersTimeout هي 60000 مللي ثانية وتحدد المدة المسموحة للعميل لإرسال ترويسات الطلب، ولذلك نتركها كما هي.
س: هل تعطيل keep-alive يحل أخطاء 502؟
ج: تعطيل keep-alive يزيل السباق، لكن كل طلب يدفع عندها كلفة اتصال TCP جديد، ومصافحة TLS جديدة عند استخدام TLS. رفع keepAliveTimeout يحل أخطاء 502 ويحافظ على إعادة استخدام الاتصالات.
س: هل تهم keepAliveTimeout على Vercel أو المنصات عديمة الخوادم؟
ج: جهة الطلبات الواردة لا تهم، لأن المنصة تملك خادم HTTP والوسيط الذي أمامه. الإعداد مهم عندما يشغّل الفريق عملية Node.js بنفسه في Docker أو على خادم افتراضي أو على Kubernetes. أما جهة fetch الصادرة فتنطبق في كل مكان.
قراءات إضافية
هندسة الخوادم
لماذا يصبح الترقيم بـ OFFSET أبطأ مع كل صفحة: مؤشرات keyset ومفاتيح الترتيب المستقرة والفهرس الذي يجعلها تعمل
استبدلنا الترقيم بـ OFFSET في واجهة إنتاجية بعدما بدأت الصفحات العميقة تتجاوز مهلة الاستجابة. هذه ملاحظاتنا الهندسية حول سبب كون تكلفة OFFSET متناسبة مع عمق الصفحة، وكيف تحوّل مؤشرات keyset الترقيم إلى بحث مباشر داخل الفهرس، وأي فهرس مركّب يحتاجه الاستعلام، وخطأ دقة الطوابع الزمنية الذي جعل مؤشراتنا تتخطى صفوفًا.
هندسة الخوادم
ترحيل مخطط Postgres دون توقف: نمط التوسيع والتقليص و lock_timeout وطابور الأقفال
نادرًا ما يُسقط ترحيل قاعدة بيانات Postgres التطبيق بسبب بطء أمر DDL نفسه، بل لأن أمر ALTER TABLE ينتظر قفلًا فينتظر خلفه كل استعلام وارد. هذه ملاحظات فريقنا الميدانية عن طوابير الأقفال ونمط التوسيع والتقليص وأوامر DDL التي تعيد كتابة الجدول والتعبئة على دفعات.