فحص جاهزية تطبيق Node.js في رصيف: لماذا لا يكفي فتح المنفذ؟

ابنِ مسار جاهزية HTTP مفيدًا، وجرّب الفرق بين فتح المنفذ وجاهزية التطبيق، واضبط فحوص رصيف وشخّص التحويلات وأخطاء 503 وحدود النشر.

فتح المنفذ لا يعني أن التطبيق جاهز

قد يبدأ تطبيق Node.js استقبال اتصالات HTTP قبل أن ينتهي من تحميل الإعدادات أو تهيئة الاتصال بقاعدة البيانات. في هذه الفترة ينجح اتصال TCP، لكن الطلب الفعلي يفشل. لذلك، السؤال الأهم عند نشر واجهة SaaS ليس «هل بدأت الحاوية؟»، بل «هل تستطيع النسخة الجديدة خدمة الطلبات التي ستصلها؟».

يدعم رصيف فحوص الجاهزية Process وTCP وHTTP. وتوضح وثائقه الحالية أن الخدمات المبنية من GitHub تفحص المنفذ افتراضيًا. يمنحك فحص HTTP معيارًا أدق قبل تحويل الزيارات، بشرط أن يقيس المسار جاهزية حقيقية.

يتضمن هذا الدليل تجربة Node.js نُفذت محليًا ويمكن إعادة تنفيذها. أما سلوك النشر في رصيف فمصدره الوثائق الحالية، وليس تجربة نشر إنتاجية جديدة. الغلاف رسم توضيحي مولّد، لا لقطة لوحة ولا دليل تشغيل.

حدّد معنى الجاهزية قبل اختيار الفحص

بحسب وثائق النشر في رصيف:

الفحصمتى ينجح؟ما الذي لا يثبته؟
Processعند بدء الحاويةأن معالج HTTP أو الاعتماديات جاهزة
TCPعندما يقبل المنفذ الاتصالأن التطبيق يقدم استجابة مفيدة
HTTPعندما يعيد GET لمسار الصحة حالة بين 200 و399أن التحويل أو الاستجابة السطحية يعكسان جاهزية فعلية

تذكر الوثائق أن الفحص يتكرر كل خمس ثوانٍ. وانتبه إلى أن نطاق النجاح يشمل التحويلات: استجابة 302 إلى صفحة تسجيل الدخول ليست دليلًا مناسبًا على الجاهزية. الأفضل تخصيص مسار مثل /healthz يعيد 200 بعد اكتمال التهيئة الضرورية، و503 قبل ذلك.

استثنِ هذا المسار من تحويلات تسجيل الدخول واللغة. اجعل استجابته قصيرة وعامة؛ لا تعرض فيه كلمات مرور أو روابط اتصال أو تفاصيل أخطاء الاعتماديات.

تجربة عملية: المنفذ مفتوح والتطبيق غير جاهز

احفظ المثال التالي باسم server.mjs. لا يحتاج إلى حزم npm. المؤقت يحاكي تأخر التهيئة فقط؛ ليس فحصًا لقاعدة بيانات ولا طريقة مقترحة لتحديد الجاهزية في الإنتاج.

import http from 'node:http';
const port = Number(process.env.PORT ?? 3000);
let ready = false;
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
  res.setHeader('Cache-Control', 'no-store');
  if (req.url === '/healthz') {
    res.statusCode = ready ? 200 : 503;
    return res.end(ready ? 'ready\n' : 'starting\n');
  }
  if (req.url === '/login') {
    res.statusCode = 302;
    res.setHeader('Location', '/sign-in');
    return res.end();
  }
  res.statusCode = ready ? 200 : 503;
  res.end(ready ? 'app ready\n' : 'starting\n');
});
server.listen(port, '0.0.0.0', () => {
  console.log('listening');
  // Demonstration only: replace with real initialization.
  setTimeout(() => { ready = true; }, 1500);
});
process.on('SIGTERM', () => server.close());

شغّله في نافذة طرفية:

PORT=3000 node server.mjs

وفي نافذة أخرى نفّذ الطلبين الأولين مباشرة بعد التشغيل، ثم أعد طلب الصحة بعد اكتمال التهيئة:

curl -i http://127.0.0.1:3000/healthz
curl -i http://127.0.0.1:3000/login
curl -i http://127.0.0.1:3000/healthz

لا تضف curl -L عند فحص التحويل؛ المطلوب رؤية الحالة الأصلية، لا استجابة الصفحة التالية. إذا استغرقت كتابة الأوامر وقتًا أطول من التأخير، أعد تشغيل التطبيق مع زيادة المؤقت، أو نفّذ الطلبات آليًا.

نفّذنا المثال محليًا في 16 نوفمبر 2026 باستخدام Node.js v26.8.2. انتظر برنامج الاختبار إعلان بدء الاستماع، ثم اتصل عبر TCP وطلب المسارين، وانتظر 1.8 ثانية قبل إعادة طلب الصحة.

الملاحظةالنتيجة الفعلية
اتصال TCP فور بدء الاستماعقُبل الاتصال
طلب /healthz المبكر503 مع starting
طلب /login دون اتباع التحويل302 مع Location: /sign-in
طلب /healthz اللاحق200 مع ready

مدة التهيئة الوهمية، 1.5 ثانية، وانتظار الاختبار، 1.8 ثانية، قيم اخترناها للتجربة وليستا قياسًا لزمن رصيف. النتيجة تثبت الفرق بين فتح المنفذ والجاهزية في المثال، ولا تقيس انقطاع المنصة أو سعتها أو آلية توجيه الزيارات فيها.

استبدل المؤقت بشرط تشغيل حقيقي

في التطبيق الفعلي، لا ترفع علامة الجاهزية إلا بعد نجاح التهيئة اللازمة لخدمة الطلبات. لواجهة تعتمد على قاعدة بيانات، قد يشمل ذلك إنشاء مجموعة الاتصالات وتنفيذ استعلام صغير بمهلة محددة. عند الفشل، أوقف بدء التشغيل أو أبقِ النسخة غير جاهزة، وسجّل السبب في السجلات الداخلية.

ليس من المفيد فحص كل تكامل اختياري مع كل طلب صحة. تعطل مزود البريد لا يستلزم دائمًا منع واجهة تستطيع وضع الرسائل في طابور ومواصلة الخدمة. بالمقابل، لا ينبغي لواجهة عاجزة عن تنفيذ أي طلب دون قاعدة البيانات الأساسية أن تعلن الجاهزية لمجرد أن خادم HTTP بدأ.

اجعل فحص الاعتماديات محدود المدة، ولا تنفّذ استعلامات مكلفة أو عمليات كتابة أو ترحيل مخطط داخل مسار الصحة. علامة الجاهزية المخزنة قليلة التكلفة، لكنها إذا ضُبطت مرة واحدة عند البدء فلن تكشف تعطل الاعتماديات لاحقًا. صمّم المراقبة المستمرة بصورة منفصلة؛ وثائق النشر تصف شرطًا لتمرير النسخة أثناء النشر، ولا ينبغي استنتاج كل سلوكيات المراقبة اللاحقة منه.

إعداد فحص HTTP في رصيف

  1. تأكد من أن التطبيق يستمع على 0.0.0.0 وعلى المنفذ المحدد للخدمة. يجب أن تتوافق قيمة PORT التي يستخدمها التطبيق مع إعداد المنفذ.
  2. من إعدادات الخدمة، اختر HTTP ضمن Readiness check، واضبط Health path على /healthz.
  3. احفظ الإعدادات ثم انشرها؛ الحفظ وحده لا يغير النسخة العاملة.
  4. تابع Deployments وLogs، وتحقق من اكتمال التهيئة دون كشف أسرار في السجلات.
  5. بعد النشر، اختبر مسار الصحة عبر عنوان HTTPS العام ومسارًا فعليًا يمثل استخدام التطبيق. نجاح الصحة وحده ليس اختبار قبول شاملًا.

بحسب الوثائق، يبدأ مسار الصحة بشرطة مائلة /، ويستخدم بعدها الحروف والأرقام والشرطة المائلة والشرطة السفلية والشرطة العادية، بحد أقصى 128 محرفًا بعد الشرطة المائلة الأولى. استخدم مسارًا بسيطًا دون معاملات استعلام.

إذا لم تنشئ الخدمة بعد، راجع دليل نشر تطبيق GitHub على رصيف. وإذا حفظت إعدادًا ولم يصل إلى التطبيق، فراجع الفرق بين الحفظ والنشر وإعادة التشغيل لمتغيرات البيئة.

شخّص المشكلة دون إضعاف الفحص

العَرَضالخطوة التالية
ينجح الفحص محليًا ولا ينجح النشرراجع عنوان الاستماع والمنفذ والمسار والنسخة العاملة
يعيد مسار الصحة 301 أو 302افحص تحويلات الدخول وHTTPS واللغة؛ أعد حالة جاهزية مباشرة
يبقى مسار الصحة عند 503افحص سجلات التهيئة والاعتماديات الإلزامية
تنجح الجاهزية وتفشل طلبات المستخدمقد يكون الفحص سطحيًا، أو لم يُختبر مسار العمل المتأثر
يعيد العنوان العام خطأميّز استجابة البوابة عن استجابة التطبيق

تفرّق وثائق HTTP العام بين 503 من البوابة عند تعذر الوصول للتطبيق، و502 عند رد غير صالح أو ترويسات استجابة كبيرة، و504 عند تأخر بدء الاستجابة. لكن 503 الذي يعيده تطبيق المثال ليس بالضرورة خطأ من البوابة. اقرأ محتوى الاستجابة مع سجلات التطبيق قبل تحديد السبب.

حدود النشر والتراجع التي لا يحلها فحص الصحة

في النشر التدريجي المعتاد، توضح وثائق رصيف أن نسخة جديدة تبدأ بجوار النسخة العاملة، ثم تنتقل الزيارات بعد نجاح الجاهزية. لكن ذلك ليس ضمانًا عامًا لانعدام الانقطاع: الخدمة المرتبطة بوحدة تخزين توقف نسختها القديمة قبل بدء الجديدة، ويُتوقع انقطاع قصير عند النشر.

كذلك، يعيد التراجع إعدادات وصورة نسخة سابقة، ولا يستعيد بيانات قاعدة البيانات أو وحدة التخزين. نجاح مسار الصحة لا يجعل ترحيلًا مدمرًا لمخطط البيانات قابلًا للعكس. خطّط لتغييرات قاعدة بيانات متوافقة مع النسختين القديمة والجديدة أثناء تداخلهما، وافصل خطة استعادة البيانات عن التراجع عن التطبيق.

العرض الحالي لرصيف تجربة خاصة. لتقييم هذا الأسلوب مع تطبيقك، اطلب الوصول.

المصادر وحدود الدليل

رُوجعت المصادر في 16 نوفمبر 2026. التجربة محلية بلا اعتماديات خارجية، ولم تشمل نظام عميل أو زيارات إنتاجية أو قياس أداء المنصة.