المدونة

ابق على اطلاع بأخبارنا الجديدة

كيفية إنشاء واستضافة تطبيق Node.js على لوحة تحكم cPanel

Osama Algabsi | 25/05/2026 | المنتجات, خدمات الاستضافة

لتتمكن من استضافة تطبيقات Node.js مباشرةً داخل حساب الاستضافة المشتركة في لوحة cPanel، يعتمد النظام على تقنيتين أساسيتين تعملان معاً بتناغم تام: CloudLinux Node.js Selector و Phusion Passenger.

تعتبر أداة Node.js Selector هي الواجهة الذكية داخل cPanel المسؤولة عن إنشاء بيئة افتراضية (Virtual Environment) آمنة ومعزولة لمشروعك الرقمي. تمنحك هذه الأداة السيطرة الكاملة لإدارة إصدارات Node.js المختلفة وتثبيت الحزم البرمجية (Dependencies) بضغطة زر، دون تداخل مع ملفات الاستضافة الأخرى.

بمجرد إعداد هذه البيئة، يأتي دور Phusion Passenger ليكون المحرّك الأساسي، حيث يتولى مهمة ربط التطبيق بخادم الويب (Web Server) وتعيين المنافذ (Ports) ديناميكياً، بالإضافة إلى إدارة العمليات بذكاء، فهو يقوم بتشغيل التطبيق فور وصول الزوار، ويدخله في حالة “سكون” (Sleep) عند عدم وجود نشاط، مما يضمن أقصى توفير لموارد الخادم.

في هذا الدليل، سنستخدم هذه الأدوات المدمجة لإنشاء تطبيق Express.js تجريبي من الصفر، ورفعه على نطاق فرعي (Subdomain)، ونتعلم كيفية استكشاف الأخطاء وإصلاحها (Debugging) باحترافية باستخدام الـ Terminal داخل cPanel.

المتطلبات (Prerequisites)

قبل البدء في كتابة الكود، دعونا نتأكد من توفر الآتي:

حساب استضافة مشتركة فعال مع العنكبوت الليبي.
نطاق فرعي (Subdomain) جاهز للاستخدام (مثل node-js.yourdomain.ly). يمكننا إنشاؤه من قسم “Domains” في لوحة cPanel.
تفعيل الوصول إلى Terminal/SSH. سنستخدم سطر الأوامر (Command Line) للقيام بخطوات فحص واكتشاف الأخطاء. إذا لم تقم بتفعيله بعد، يمكنك اتباع هذا الدليل السريع:
كيفية تفعيل/إلغاء تفعيل الوصول إلى (SSH) لحساب cPanel.

الخطوة 1: تخصيص بيئة Node.js

أولاً، نحتاج إلى توجيه الخادم لإنشاء بيئة افتراضية آمنة لتطبيقنا.

قم بتسجيل الدخول إلى لوحة تحكم cPanel.
انتقل للأسفل إلى قسم Software واضغط على Setup Node.js App.
اضغط على الزر الأزرق Create Application.
قم بتعبئة بيانات التطبيق:

Node.js version: اختر إصداراً حديثاً (مثل 18.x أو 20.x).
Application mode: اختر Development.
Application root: اكتب nodeapp. سينشئ هذا مجلداً لحفظ الكود الخاص بك بأمان خارج مسار الويب العام (public web access).
Application URL: اختر النطاق الفرعي الخاص بك (مثل node-js.yourdomain.ly).
Application startup file: اكتب app.js..
Passenger log file: اكتب /home/yourusername/nodeapp/passenger.log (مع استبدال “yourusername” باسم المستخدم الفعلي لحساب cPanel الخاص بك).
اضغط على Create.

الخطوة 2: فهم إعدادات وشكل المجلدات (Folder Structure)

بمجرد الإنشاء، ستقوم لوحة cPanel بتوليد عدة مجلدات في الـ File Manager. من المهم جداً معرفة وظيفة كل منها:

nodeapp: هذا هو المكان الذي نضع فيه الكود الخاص بنا. جميع ملفات الـ backend وملف package.json توضع هنا.
node-js.yourdomain.ly: هذا هو المسار العام للنطاق (Public Document Root). بما أن Phusion Passenger يقوم بتوجيه الزيارات مباشرة إلى الـ backend، فنحن لسنا بحاجة لوضع ملفات Node هنا. دعنا نتركه فارغاً.
nodevenv: هذه هي البيئة الافتراضية التي أنشأها CloudLinux. يجب علينا عدم رفع أي ملفات أو تعديل أي شيء هنا، وإلا قد يتعطل التطبيق.

لنتوجه الآن إلى الـ File Manager، و ننتقل إلى مجلد nodeapp ونقوم بحذف ملف app.js الافتراضي الذي أنشأته cPanel تلقائياً. سنقوم بكتابة الملف الخاص بنا.

الخطوة 3: كتابة الكود (تطبيق Express.js)

كما ذكرنا سابقاً، لشرح كيفية عمل هذه البيئة، سنقوم بإنشاء تطبيق تجريبي باستخدام إطار عمل Express.js.

داخل مجلد nodeapp، نضغط على زر + File في أعلى الـ File Manager لإنشاء ملفين جديدين.

1. Package.json

دعونا ننشئ هذا الملف، ثم نضغط عليه بزر الماوس الأيمن، ونختار Edit، ونلصق الكود التالي. هذا يخبر الخادم أن تطبيقنا التجريبي يحتاج إلى إطار عمل Express:

Shell ▼

{
  “name”: “my-sample-cpanel-app”,
  “version”: “1.0.0”,
  “main”: “app.js”,
  “scripts”: {
    “start”: “node app.js”
  },
  “dependencies”: {
    “express”: “^4.18.2”
  }
}

2. app.js

سنقوم بتكوين الملف آخر، ونقوم بتعديله، ولصق الكود التالي.

قاعدة هامة جداً (CRITICAL RULE): نظراً لأن cPanel تستخدم Phusion Passenger، يجب علينا عدم تعيين منفذ ثابت (Hardcode a port) مثل 8080 أو 3000 ليعمل الخادم عليه. يجب أن نستخدم process.env.PORT لكي يتمكن Passenger من تعيين منفذ ديناميكي (Dynamic Port) أو Socket في الوقت الفعلي. هذه القاعدة تنطبق على جميع تطبيقات Node.js المستضافة في هذه البيئة!

Shell ▼

const express = require(‘express‘);
const app = express();
// Passenger assigns the port dynamically. This is required for cPanel!
const port = process.env.PORT 
app.get(‘/‘, (req, res) => {
  res.send(‘<h1>Hello from my brand new Node.js app on Libyan Spider!</h1>‘);
});
app.listen(port, () => {
  console.log(`Application started on port ${port}`);
});

الخطوة 4: تثبيت الحزم (Install Dependencies)

أخيراً، الكود الخاص بنا جاهز، ولكن لا يزال يتعين علينا تثبيت حزمة Express المحددة في ملف package.json.

دعونا نعود إلى واجهة Setup Node.js App.
نضغط على أيقونة القلم (Edit) بجوار التطبيق.
ننزل لأسفل إلى قسم Detected configuration files ونضغط على زر Run NPM Install.

استخدام الـ Terminal كبديل

في بعض الأحيان، تستغرق cPanel بعض الوقت للتعرف على الملفات الجديدة، وقد يظهر زر Run NPM Install باللون الرمادي (غير مفعل). يمكننا تجاوز واجهة المستخدم (UI) بالكامل باستخدام الـ Terminal:

في أعلى صفحة إعداد Node.js، قم بنسخ الأمر الخاص بالدخول إلى البيئة الافتراضية (Command for entering to virtual environment) والذي يبدو كالتالي:
source /home/username/nodevenv/..
اذهب إلى لوحة تحكم cPanel الرئيسية، وافتح الـ Terminal، والصق الأمر، ثم اضغط Enter.
اكتب npm install واضغط Enter. سيقوم الـ Terminal بتحميل الحزم المطلوبة.
أخيراً، قم بالرجوع إلى واجهة Node JS و الضغط على Restart.

تطبيقنا الآن يعمل! قم بزيارة النطاق الفرعي في متصفحك لترى النتيجة.

الخطوة 5: اكتشاف الأخطاء (قدرات الـ Terminal)

عندما يكبر التطبييق قد نواجه خطأ “503 Service Unavailable” المزعج. بدلاً من التخمين لمعرفة الخلل، يمكننا استخدام الـ Terminal في cPanel لتشخيص المشكلة بشكل أفضل.

ادخل إلى البيئة الافتراضية باستخدام أمر source الموجود في واجهة Node.js داخل cPanel. بمجرد الدخول، سيصبح لدينا تحكم كامل.

1. لماذا لا تعمل أداة pm2 هنا؟

إذا كانت لديك خلفية في التعامل مع خوادم VPS، فقد يكون دافعك الأول هو كتابة pm2 start app.js. إذا قمت بذلك في cPanel، فستحصل على خطأ command not found .

لماذا؟ لأن Phusion Passenger هو مدير العمليات (Process Manager) الخاص بنا. وهو يغني تماماً عن الحاجة لاستخدام PM2. يتولى Passenger إدارة التطبيق في الخلفية من حيث التشغيل والإيقاظ ووضع السكون تلقائياً.

2. قراءة سجلات الأخطاء (Crash Logs)

هل توقف التطبيق عن العمل؟ يمكننا قراءة ملف السجلات الذي حددناه في الخطوة 1 لمعرفة السطر البرمجي الذي تسبب في الخطأ بالتحديد.

Shell

cat passenger.log

إذا نسيت تشغيل أمر npm install، سيُظهر هذا السجل بوضوح خطأ Cannot find module ‘express’

3. التحقق من إصدارات البيئة (Verify The Environment)

يمكننا استخدام الأوامر التالية للتأكد من أن CloudLinux يقوم بتشغيل إصدار Node.js الصحيح الذي اخترناه:

Shell

node -v npm -v

4. فحص متغيرات البيئة (Inspect Environment Variables)

إذا قمت بإضافة مفاتيح API أو كلمات مرور قواعد البيانات (Database passwords) داخل واجهة Node في cPanel، يمكننا التحقق من أن التطبيق يستطيع فعلياً “قراءتها”:

Shell

printenv

أو، لمعرفة كيف يقرأها Node.js بالتحديد:

Shell

node -e “console.log(process.env)“

سيقوم هذا بطباعة قائمة كبيرة من المتغيرات، بما في ذلك (NODE_ENV (development/production، مما يثبت أن الكود يعمل بأمان ومحمي داخل البيئة المعزولة CL_VIRTUAL_ENV.

استضافة تطبيقات Node.js على استضافة مشتركة لا تعني العمل بشكل مباشر دون أي توجيه. من خلال فهم هيكلة المجلدات، واستخدام process.env.PORT ، والاستفادة من الـ Terminal لتثبيت حزم NPM وقراءة السجلات، يمكننا تشغيل تطبيقات ويب قوية بكل ثقة مباشرةً على حساب استضافة مشتركة من شركة العنكبوت الليبي!