فحص جاهزية تطبيق 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 في رصيف
- تأكد من أن التطبيق يستمع على
0.0.0.0وعلى المنفذ المحدد للخدمة. يجب أن تتوافق قيمةPORTالتي يستخدمها التطبيق مع إعداد المنفذ. - من إعدادات الخدمة، اختر HTTP ضمن Readiness check، واضبط Health path على
/healthz. - احفظ الإعدادات ثم انشرها؛ الحفظ وحده لا يغير النسخة العاملة.
- تابع Deployments وLogs، وتحقق من اكتمال التهيئة دون كشف أسرار في السجلات.
- بعد النشر، اختبر مسار الصحة عبر عنوان HTTPS العام ومسارًا فعليًا يمثل استخدام التطبيق. نجاح الصحة وحده ليس اختبار قبول شاملًا.
بحسب الوثائق، يبدأ مسار الصحة بشرطة مائلة /، ويستخدم بعدها الحروف والأرقام والشرطة المائلة والشرطة السفلية والشرطة العادية، بحد أقصى 128 محرفًا بعد الشرطة المائلة الأولى. استخدم مسارًا بسيطًا دون معاملات استعلام.
إذا لم تنشئ الخدمة بعد، راجع دليل نشر تطبيق GitHub على رصيف. وإذا حفظت إعدادًا ولم يصل إلى التطبيق، فراجع الفرق بين الحفظ والنشر وإعادة التشغيل لمتغيرات البيئة.
شخّص المشكلة دون إضعاف الفحص
| العَرَض | الخطوة التالية |
|---|---|
| ينجح الفحص محليًا ولا ينجح النشر | راجع عنوان الاستماع والمنفذ والمسار والنسخة العاملة |
| يعيد مسار الصحة 301 أو 302 | افحص تحويلات الدخول وHTTPS واللغة؛ أعد حالة جاهزية مباشرة |
| يبقى مسار الصحة عند 503 | افحص سجلات التهيئة والاعتماديات الإلزامية |
| تنجح الجاهزية وتفشل طلبات المستخدم | قد يكون الفحص سطحيًا، أو لم يُختبر مسار العمل المتأثر |
| يعيد العنوان العام خطأ | ميّز استجابة البوابة عن استجابة التطبيق |
تفرّق وثائق HTTP العام بين 503 من البوابة عند تعذر الوصول للتطبيق، و502 عند رد غير صالح أو ترويسات استجابة كبيرة، و504 عند تأخر بدء الاستجابة. لكن 503 الذي يعيده تطبيق المثال ليس بالضرورة خطأ من البوابة. اقرأ محتوى الاستجابة مع سجلات التطبيق قبل تحديد السبب.
حدود النشر والتراجع التي لا يحلها فحص الصحة
في النشر التدريجي المعتاد، توضح وثائق رصيف أن نسخة جديدة تبدأ بجوار النسخة العاملة، ثم تنتقل الزيارات بعد نجاح الجاهزية. لكن ذلك ليس ضمانًا عامًا لانعدام الانقطاع: الخدمة المرتبطة بوحدة تخزين توقف نسختها القديمة قبل بدء الجديدة، ويُتوقع انقطاع قصير عند النشر.
كذلك، يعيد التراجع إعدادات وصورة نسخة سابقة، ولا يستعيد بيانات قاعدة البيانات أو وحدة التخزين. نجاح مسار الصحة لا يجعل ترحيلًا مدمرًا لمخطط البيانات قابلًا للعكس. خطّط لتغييرات قاعدة بيانات متوافقة مع النسختين القديمة والجديدة أثناء تداخلهما، وافصل خطة استعادة البيانات عن التراجع عن التطبيق.
العرض الحالي لرصيف تجربة خاصة. لتقييم هذا الأسلوب مع تطبيقك، اطلب الوصول.
المصادر وحدود الدليل
- رصيف: النشر: فحوص الجاهزية واستثناءات النشر والتراجع.
- رصيف: HTTP العام: المنفذ وأخطاء البوابة.
- واجهة HTTP في Node.js: الخادم واستجابات HTTP.
رُوجعت المصادر في 16 نوفمبر 2026. التجربة محلية بلا اعتماديات خارجية، ولم تشمل نظام عميل أو زيارات إنتاجية أو قياس أداء المنصة.