تكوين تطبيق Node.js لـ Azure App Service

مقالة
06/01/2023

يجب نشر تطبيقات Node.js مع كافة تبعيات NPM المطلوبة. يشغل محرك نشر App Service npm install --production لك تلقائيًا عندما تنشر مستودع Git، أو حزمة zip من خلال تمكين أتمتة الإنشاء. ومع ذلك، في حال قمت بنشر ملفاتك باستخدام FTP/S، ستحتاج إلى تحميل الحزم المطلوبة يدويًا.

يوفر هذا الدليل المفاهيم الإرشادات الرئيسية لمطوري Node.js الذين ينشرون إلى App Service. في حال لم يسبق لك استخدام Azure App Service، فاتبع التشغيل السريع Node.js والبرنامج التعليمي Node.js مع MongoDB أولاً.

عرض إصدار Node.js

لعرض إصدار Node.js الحالي، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

لعرض كافة إصدارات Node.js المدعومة، انتقل إلى https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime أو قم بتشغيل الأمر التالي في Cloud Shell:

az webapp list-runtimes --os windows | grep NODE

لعرض إصدار Node.js الحالي، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

لعرض كافة إصدارات Node.js المدعومة، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp list-runtimes --os linux | grep NODE

تعيين إصدار Node.js

لتعيين تطبيقك إلى إصدار Node.js مدعوم، شغل الأمر التالي في Cloud Shell لتعيين WEBSITE_NODE_DEFAULT_VERSION إلى إصدار مدعوم:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~16"

إشعار

يستخدم هذا المثال «tilde syntax» الموصى به لاستهداف أحدث إصدار متوفر من وقت تشغيل Node.js 16 على App Service.

نظرًا إلى أن وقت التشغيل يصحح ويحدث بانتظام بواسطة النظام الأساسي، فلا يوصى باستهداف إصدار/تصحيح ثانوي محدد لأن هذه ليست مضمونة لتكون متاحة بسبب المخاطر الأمنية المحتملة.

إشعار

عليك تعيين الإصدار Node.js في package.json لدى مشروعك. يشغل محرك النشر في عملية منفصلة تحتوي على جميع إصدارات Node.js المدعومة.

لتعيين التطبيق الخاص بك إلى إصدار Node.js مدعوم، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|14-lts"

يحدد هذا الإعداد إصدار Node.js لاستخدامه، سواء في وقت التشغيل أو في أثناء استعادة الحزمة التلقائية في Kudu.

إشعار

عليك تعيين الإصدار Node.js في package.json لدى مشروعك. يشغل محرك النشر في حاوية منفصلة، والتي تحتوي على جميع إصدارات Node.js المدعومة.

الحصول على رقم منفذ

يحتاج تطبيق Node.js الخاص بك إلى الاستماع إلى المنفذ الصحيح لتلقي الطلبات الواردة.

في App Service على Windows، تتم استضافة تطبيقات Node.js باستخدام IISNode، ويجب أن يستمع تطبيق Node.js إلى المنفذ المحدد في المتغير process.env.PORT. يبين المثال التالي كيفية القيام بذلك في تطبيق Express بسيط:

يعين App Service متغير البيئة PORT في حاوية Node.js، ويعيد توجيه الطلبات الواردة إلى الحاوية الخاصة بك في رقم المنفذ هذا. لتلقي الطلبات، يجب أن يستمع تطبيقك إلى ذلك المنفذ باستخدام process.env.PORT. يبين المثال التالي كيفية القيام بذلك في تطبيق Express بسيط:

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

تخصيص أتمتة البناء

في حال نشرت تطبيقك باستخدام Git، أو حزم zip مع تمكين أتمتة الإنشاء، فإن App Service ينشئ خطوات أتمتة من خلال التسلسل التالي:

قم بتشغيل برنامج نصي مخصص إذا تم تحديده بواسطة PRE_BUILD_SCRIPT_PATH.
شغل npm install بدون أي علامات، والذي يتضمن البرامج النصية npm preinstall وpostinstall وأيضًا يثبت devDependencies.
شغل npm run build في حال تم تحديد برنامج نصي للإنشاء في package.json.
شغل npm run build:azure في حال تم تحديد البرنامج النصي build:azure في package.json.
قم بتشغيل برنامج نصي مخصص إذا تم تحديده بواسطة POST_BUILD_SCRIPT_PATH.

إشعار

وكما هو موضح في مستندات npm، يتم تشغيل البرامج النصية المسماة prebuild وpostbuildقبل وبعد build، على التوالي، إذا تم تحديدها. يتم تشغيل preinstall وpostinstall قبل وبعد install، على التوالي.

PRE_BUILD_COMMAND وPOST_BUILD_COMMAND هما من متغيرات البيئة التي تكون فارغة بشكل افتراضي. لتشغيل أوامر ما قبل الإنشاء، قم بتحديد PRE_BUILD_COMMAND. لتشغيل أوامر ما بعد الإنشاء، قم بتحديد POST_BUILD_COMMAND.

يحدد المثال التالي المتغيرين لسلسلة من الأوامر، مفصول بينها بفاصلات.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

وللحصول على متغيرات البيئة الإضافية لتخصيص أتمتة الإنشاء، راجع تكوين Oryx.

للمزيد من المعلومات حول كيفية تشغيل App Service وإنشائه لتطبيقات Node.js في Linux، راجع مستندات Oryx: كيفية اكتشاف تطبيقات Node.js وإنشائها.

تكوين خادم Node.js

تأتي حاويات Node.js مع PM2، مدير عمليات إنتاج. بإمكانك تكوين تطبيقك للبدء بـ «PM2» أو باستخدام «NPM» أو بأمر مخصص.

الأداة	الغرض
تشغيل باستخدام PM2	مستحسن - إنتاج أو استخدام مرحلي. يوفر «PM2» نظامًا أساسيًا لإدارة تطبيقات الخدمة الكاملة.
تشغيل بدء npm	استخدام التطوير فقط.
تشغيل الأمر المخصص	إما تطوير أو تقسيم مرحلي.

تشغيل باستخدام PM2

تبدأ الحاوية تشغيل تطبيقك تلقائيًا باستخدام PM2 عند العثور على أحد ملفات Node.js الشائعة في مشروعك:

bin/www
server.js
app.js
index.js
hostingstart.js
واحد من ملفات PM2 التالية: process.json وecosystem.config.js

بإمكانك أيضًا تكوين ملف بدء مخصص بالملحقات التالية:

ملف .js
ملف PM2 مع الملحق .json أو .config.jsأو .yaml أو .yml

إشعار

اعتبارًا من Node 14 LTS، لا تبدأ الحاوية تشغيل تطبيقك تلقائيًا باستخدام PM2. لبدء تشغيل تطبيقك باستخدام PM2، عين أمر بدء التشغيل إلى pm2 start <.js-file-or-PM2-file> --no-daemon. احرص على التأكد من استخدام الوسيطة --no-daemon لأن PM2 يحتاج إلى التشغيل في المقدمة حتى تعمل الحاوية بشكل صحيح.

لإضافة ملف بدء مخصص، شغل الأمر التالي في Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

تشغيل الأمر المخصص

بإمكان App Service بدء تشغيل تطبيقك باستخدام أمر مخصص، مثل قابل للتنفيذ مثل run.sh. على سبيل المثال، لتشغيل npm run start:prod، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

تشغيل بدء npm

لبدء تشغيل التطبيق الخاص بك باستخدام npm start، ما عليك سوى التأكد من وجود برنامج نصي start في ملف package.json. على سبيل المثال:

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

لكي تستخدم package.json مخصصًا في مشروعك، قم بتشغيل الأمر التالي في Cloud Shell:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

تصحيح الأخطاء عن بُعد

إشعار

تصحيح الأخطاء عن بُعد متوفر في الإصدار الأولي حاليًا.

بإمكانك تصحيح أخطاء تطبيق Node.js عن بُعد في Visual Studio Code إذا قمت بتكوينه للتشغيل باستخدام PM2، إلا عند تشغيله باستخدام .config.js أو.yml أو .yaml.

في معظم الحالات، لا يتطلب تكوين إضافي لتطبيقك. في حال تم تشغيل تطبيقك بملف process.json (افتراضي أو مخصص)، يجب أن تكون له خاصية script في جذر JSON. على سبيل المثال:

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

لإعداد Visual Studio Code لتصحيح الأخطاء عن بُعد، ثبت ملحق App Service. اتبع الإرشادات الموجودة في صفحة الملحق وسجل دخول إلى Azure في Visual Studio Code.

في مستعرض Azure، ابحث عن التطبيق الذي تود تصحيحه، وانقر بزر الماوس الأيمن فوقه وحدد Start Remote Debugging. انقر فوق Yes لتمكينه لتطبيقك. يبدأ App Service وكيل نفق لك ويرفق مصحح الأخطاء. بإمكانك بعد ذلك تقديم طلبات إلى التطبيق ورؤية مصحح الأخطاء يتعطل عند نقاط التوقف.

بمجرد الانتهاء من تصحيح الأخطاء، أوقف مصحح الأخطاء عن طريق تحديد Disconnect. عند المطالبة، عليك النقر فوق Yes لتعطيل تصحيح الأخطاء عن بُعد. لتعطيله لاحقًا، انقر بزر الماوس الأيمن فوق تطبيقك مرة أخرى في مستكشف Azure وحدد Disable Remote Debugging.

الوصول إلى متغيرات البيئة

في App Service، يمكنك تعيين إعدادات التطبيق خارج التعليمات البرمجية للتطبيق. بعد ذلك يمكنك الوصول إليها باستخدام نمط Node.js القياسي. على سبيل المثال، للوصول إلى إعداد تطبيق يسمى NODE_ENV، استخدم التعليمات البرمجية التالية:

process.env.NODE_ENV

تشغيل Grunt/Bower/Gulp

بشكل افتراضي، تشغل أتمتة إنشاء App Service npm install --production عندما تتعرف على تطبيق Node.js يتم نشره من خلال Git، أو من خلال نشر Zip مع تمكين أتمتة الإنشاء. في حال كان تطبيقك يتطلب أيًا من أدوات الأتمتة الشائعة، مثل Grunt أو Bower أو Gulp، ستحتاج إلى توفير برنامج نصي مخصص للنشر لتشغيله.

لتمكين المستودع الخاص بك من تشغيل هذه الأدوات، تحتاج إلى إضافتها إلى التبعيات في package.json. على سبيل المثال:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

من نافذة المحطة الطرفية المحلية، غير الدليل إلى جذر المستودع الخاص بك وشغل الأوامر التالية:

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

لدى جذر المستودع الآن ملفين إضافيين: .deployment وdeploy.sh.

قم بفتح deploy.sh وابحث عن Deployment القسم الذي يبدو كما يلي:

##################################################################################################################################
# Deployment
# ----------

هذا القسم ينتهي بتشغيل npm install --production. أضف قسم التعليمات البرمجية الذي تحتاجه لتشغيل الأداة المطلوبة في نهايةالقسم Deployment:

Bower
Gulp
Grunt

راجع مثالاً في نموذج MEAN.js، حيث يقوم البرنامج النصي للنشر أيضًا بتشغيل أمر npm install مخصص.

Bower

تشغل هذه القصاصة البرمجية bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

تشغل هذه القصاصة البرمجية gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

تشغل هذه القصاصة البرمجية grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

الكشف عن جلسة عمل HTTPS

في خدمة التطبيقات، يحدث إنهاء TLS/SSL في موازنات تحميل الشبكة، لذلك تصل جميع طلبات HTTPS إلى تطبيقك كطلبات HTTP غير مشفرة. إذا كان منطق التطبيق الخاص بك يحتاج إلى التحقق مما إذا كانت طلبات المستخدم مشفرة أم لا، فافحص ترويسة X-Forwarded-Proto.

وتتيح لك أطر عمل الويب الشائعة الوصول إلى معلومات X-Forwarded-* في نمط التطبيق القياسي. في Express، بإمكانك استخدام وكلاء الثقة. على سبيل المثال:

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

الوصول إلى سجلات التشخيص

للوصول إلى سجلات وحدة التحكم التي تم إنشاؤها من داخل التعليمة البرمجية للتطبيق في خدمة التطبيقات، قم بتشغيل تسجيل التشخيص عن طريق تشغيل الأمر التالي في Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

القيم المحتملة لـ --level هي: Error وWarning وInfo وVerbose. يتضمن كل مستوى لاحق المستوى السابق. على سبيل المثال: Error يتضمن رسائل الخطأ فقط بينما Verbose يتضمن جميع الرسائل.

بمجرد تشغيل التسجيل التشخيصي، قم بتشغيل الأمر التالي لمشاهدة تدفق السجل:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

وفي حال عدم رؤية سجلات وحدة التحكم على الفور، فتحقق مجددًا في غضون 30 ثانية.

إشعار

يمكنك أيضا فحص ملفات السجل من المستعرض في https://<app-name>.scm.azurewebsites.net/api/logs/docker.

لإيقاف تسجيل التدفق في أي وقت، اكتب Ctrl+C.

يمكنك الوصول إلى سجلات وحدة التحكم المنشأة من داخل الحاوية.

أولًا، قم بتشغيل تسجيل الحاويات عن طريق تشغيل الأمر التالي:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

استبدل <app-name> و<resource-group-name> بالأسماء المناسبة لتطبيق الويب الخاص بك.

بمجرد تشغيل تسجيل الحاويات، قم بتشغيل الأمر التالي لمشاهدة تدفق السجل:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

وفي حال عدم رؤية سجلات وحدة التحكم على الفور، فتحقق مجددًا في غضون 30 ثانية.

لإيقاف دفق السجل في أي وقت، اكتب Ctrl+C.

يمكنك أيضًا فحص ملفات السجل من المتصفح الموجود في https://<app-name>.scm.azurewebsites.net/api/logs/docker.

المراقبة باستخدام Application Insights

يسمح لك Application Insights بمراقبة أداء التطبيق واستثناءاته واستخدامه دون إجراء أي تغييرات في التعليمات البرمجية. لإرفاق عامل App Insights، انتقل إلى تطبيق الويب الخاص بك في المدخل وحدد Application Insights ضمن Settings، بعد ذلك حدد Turn on Application Insights. ثم حدد مورد App Insights موجودًا أو أنشئ موردًا جديدًا. وأخيرًا، حدد Apply في الأسفل. لتضع علامة على تطبيق الويب الخاص بك باستخدام PowerShell، يرجى الاطلاع على هذه الإرشادات

سيراقب هذا العامل تطبيق Node.js من جانب الخادم الخاص بك. لمراقبة JavaScript من جانب العميل الخاص بك، أضف عدة تطوير البرامج JavaScript إلى مشروعك.

للمزيد من المعلومات، راجع ملاحظات حول إصدار ملحق Application Insights.

استكشاف الأخطاء وإصلاحها

عندما يتصرف تطبيق Node.js يعمل على نحو مختلف في App Service أو يحتوي على أخطاء، جرب ما يلي:

الوصول إلى دفق السجل.
قم باختبار التطبيق محلياً في وضع الإنتاج. يقوم App Service بتشغيل تطبيقات Node.js الخاصة بك في وضع الإنتاج، لذلك تحتاج إلى التأكد من أن مشروعك يعمل كما هو متوقع في وضع الإنتاج محليًا. على سبيل المثال:
- اعتمادًا على package.json، قد تثبت حزم مختلفة لوضع الإنتاج (dependencies مقابل devDependencies).
- قد توزع أطر عمل ويب معينة ملفات ثابتة على نحو مختلف في وضع الإنتاج.
- ربما تستخدم أطر عمل ويب معينة برامج نصية مخصصة لبدء التشغيل عند التشغيل في وضع الإنتاج.
شغل تطبيقك في App Service في وضع التطوير. على سبيل المثال، في MEAN.js، بإمكانك تعيين تطبيقك إلى وضع التطوير في وقت التشغيل عن طريق تعيين إعداد التطبيق NODE_ENV.

لا تمتلك إذنًا لعرض هذا الدليل أو الصفحة

بعد نشر التعليمات البرمجية Node.js إلى تطبيق Windows أصلي في App Service، قد ترى الرسالة You do not have permission to view this directory or page. في المستعرض عند الانتقال إلى عنوان URL للتطبيق. هذا على الأرجح لأنك لا تمتلك ملف web.config (راجع القالب ومثال).

في حال قمت بنشر ملفاتك باستخدام Git، أو باستخدام نشر ZIP مع تمكين أتمتة الإنشاء، يقوم محرك النشر بإنشاء web.config في جذر الويب لتطبيقك (%HOME%\site\wwwroot) تلقائيًا إذا كان أحد الشروط التالية صحيحًا:

يحتوي جذر مشروعك على package.json الذي يعرف البرنامج النصي start الذي يحتوي على مسار ملف JavaScript.
يحتوي جذر مشروعك إما على server.js أو app.js.

صمم web.config الذي تم إنشاؤه وفقًا للبرنامج النصي للبدء المكتشف. فيما يتعلق بأساليب النشر الأخرى، أضف web.config يدويًا. تأكد من تنسيق الملف على نحو صحيح.

في حال كنت تستخدم نشر ZIP (من خلال Visual Studio Code، على سبيل المثال)، فتأكد من تمكين أتمتة الإنشاء لأنها غير ممكنة بشكل افتراضي. az webapp up يستخدم نشر ZIP مع تمكين أتمتة الإنشاء.

robots933456 في السجلات

قد تشاهد الرسالة التالية في سجلات الحاوية:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

يمكنك تجاهل هذه الرسالة بأمان. /robots933456.txt هو مسار عنوان URL وهمي يستخدم "خدمة التطبيقات" للتحقق من إمكانية تقديم الحاوية "طلبات". يُشير رد 404 ببساطة إلى أن المسار غير موجود، ولكنه يتيح لـ"خدمة التطبيقات" معرفة أن الحاوية سليمة وجاهزة للاستجابة للطلبات.

الخطوات التالية

البرنامج التعليمي: تطبيق Node.js مع MongoDB

الأسئلة الشائعة حول App Service بنظام Linux

أو راجع موارد إضافية:

متغيرات البيئة ومرجع إعدادات التطبيق

Share via

تكوين تطبيق Node.js لـ Azure App Service

عرض إصدار Node.js

تعيين إصدار Node.js

الحصول على رقم منفذ

تخصيص أتمتة البناء

تكوين خادم Node.js

تشغيل باستخدام PM2

تشغيل الأمر المخصص

تشغيل بدء npm

تصحيح الأخطاء عن بُعد

الوصول إلى متغيرات البيئة

تشغيل Grunt/Bower/Gulp

Bower

Gulp

Grunt

الكشف عن جلسة عمل HTTPS

الوصول إلى سجلات التشخيص

المراقبة باستخدام Application Insights

استكشاف الأخطاء وإصلاحها

لا تمتلك إذنًا لعرض هذا الدليل أو الصفحة

robots933456 في السجلات

الخطوات التالية

الموارد الإضافية