JavaScript on Azure Container Apps overview

يمكن لتطبيقات حاويات Azure تشغيل أي تطبيق JavaScript محوى في الحاويات في السحابة مع توفير خيارات مرنة لكيفية نشر تطبيقاتك.

التكوين

تمكنك تطبيقات حاويات Azure من تبسيط نشر تطبيقات جافاسكريبت الخاصة بك من خلال الحاويات الفعالة، بما في ذلك إعداد متغيرات البيئة، وتصميم ملفات Docker الفعالة، وتنظيم عملية بناء تطبيقك.

متغيرات البيئة

المتغيرات البيئية ضرورية لتكوين تطبيقك. استخدم ملفا .env لإدارة هذه المتغيرات محليا وتأكد من إدارتها بأمان في الإنتاج باستخدام خدمة مثل Azure Key Vault.

المثال التالي يوضح لك كيفية إنشاء متغيرات لتطبيقك.

# .env
NODE_ENV=production
PORT=3000
AZURE_COSMOS_DB_ENDPOINT=https://<YOUR_COSMOSDB_RESOURCE_NAME>.documents.azure.com:443/

الحاويات

ملف Docker المكون جيدا ضروري لتعبئة تطبيقك:

• استخدم ملف Docker الأساسي: إذا كان هناك عدة مشاريع تشترك في إعداد مشترك، يمكنك إنشاء ملف Dockerfile أساسي يتضمن هذه الخطوات المشتركة. يمكن لملف Dockerfile لكل مشروع أن يبدأ بهذه FROM الصورة الأساسية ويضيف تكوينات خاصة بالمشروع.

• تمثيل مبادلات البناء: يمكنك استخدام حجج البناء (ARG) في ملف Docker الخاص بك لجعله أكثر مرونة. بهذه الطريقة، يمكنك تمرير قيم مختلفة لهذه الحجج عند البناء للتطوير أو الإعداد أو الإنتاج.

• صورة Node.js الأساسية المحسنة: تأكد من أنك تستخدم صورةNode.js الأساسية المناسبة. فكر في استخدام صور أصغر ومحسنة مثل نسخ ألبين لتقليل التكاليف التشغيلية.

• الملفات البسيطة – الأساسيات للنسخ فقط: ركز على نسخ الملفات الضرورية فقط إلى الحاوية. أنشئ ملفا .dockerignore للتأكد من عدم نسخ ملفات التطوير مثل .env و node_modules. يساعد هذا الملف في تسريع عمليات البناء في الحالات التي قام فيها المطورون بنسخ ملفات غير ضرورية.

• فصل بين البناء ووقت التشغيل مع بناءات متعددة المراحل: استخدم البناءات متعددة المراحل لإنشاء صورة نهائية رشيقة عن طريق فصل بيئة البناء عن بيئة وقت التشغيل.

• التشويذات المبدعة مسبقا عن طريق الترجمة والتجميع: بناء مسبق لتشويذات التطبيق (مثل تجميع TypeScript أو تجميع JavaScript) قبل نسخها إلى مرحلة التشغيل يمكن أن يقلل من حجم الصورة، ويسرع نشر الحاويات، ويحسن أداء التشغيل البارد. الترتيب الدقيق للتعليمات في ملف Dockerfile الخاص بك يحسن أيضا أوقات التخزين المؤقت وإعادة البناء.

• تركيب دوكر لبيئات التطوير: يتيح لك تركيب دوكر تعريف وتشغيل تطبيقات دوكر متعددة الحاويات. هذا النهج متعدد الحاويات مفيد لإعداد بيئات التطوير. يمكنك تضمين سياق البناء وملف Dockerfile في ملف التركيب. هذا المستوى من التغليف يسمح لك باستخدام ملفات Docker مختلفة لخدمات مختلفة عند الحاجة.

Base Dockerfile

يعمل هذا الملف كنقطة انطلاق مشتركة لصورك Node.js. يمكنك استخدامه مع FROM توجيه في Dockerfiles يشير إلى هذه الصورة الأساسية. استخدم إما رقم الإصدار أو الالتزام لدعم النسخة الحديثة والآمنة من الصورة.

# Dockerfile.base

FROM node:22-alpine

# Set the working directory
WORKDIR /usr/src/app

# Define build arguments with default values
ARG PORT_DEFAULT=3000
ARG ENABLE_DEBUG_DEFAULT=false

# Set environment variables using the build arguments
ENV PORT=${PORT_DEFAULT}
ENV ENABLE_DEBUG=${ENABLE_DEBUG_DEFAULT}

# Copy package manifests and install dependencies
COPY package*.json ./
RUN npm install

# Expose the application and debugging ports
EXPOSE $PORT
EXPOSE 9229

# This image focuses on common steps; project-specific Dockerfiles can extend this.

عندما تمرر القيم باستخدام العلم --build-arg أثناء عملية البناء، فإن القيم المرسلة تتجاوز القيم الافتراضية المبرمجة في ملف Docker الخاص بك.

على سبيل المثال:

docker build \
  --build-arg PORT_DEFAULT=4000 \
  --build-arg ENABLE_DEBUG_DEFAULT=true \
  --tag <IMAGE>:<TAG> \
  --file Dockerfile.base .

في هذا المثال، يتم تعيين متغيرات PORT البيئة و ENABLE_DEBUG على قيم صريحة، بدلا من قيمها الافتراضية.

اتفاقيات وسم صور الحاوية مثل استخدام هي latest اتفاقية. تعرف أكثر على التوصيات الخاصة بوضع العلامات وإصدار صور الحاويات.

إعداد بيئة تطوير باستخدام Docker Compose

يستخدم المثال التالي ملف Dockerfile مخصص للتطوير (Dockerfile.dev) مع تركيبات حجم لإعادة التحميل المباشر ومزامنة المصدر المحلي.

version: "3.8"
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.base
      args:
        PORT_DEFAULT: ${PORT:-3000}
        ENABLE_DEBUG_DEFAULT: ${ENABLE_DEBUG:-false}
    ports:
      - "${PORT:-3000}:3000"
      - "9229:9229"  # Expose debug port if needed
    volumes:
      - .:/usr/src/app
      - /usr/src/app/node_modules
    environment:
      - NODE_ENV=development
      - PORT=${PORT:-3000}
      - ENABLE_DEBUG=${ENABLE_DEBUG:-false}

لبدء Docker Compose بقيم مخصصة، يمكنك تصدير متغيرات البيئة في سطر الأوامر. على سبيل المثال:

PORT=4000 ENABLE_DEBUG=true docker compose up

ملف Dockerfile الإنتاج

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

# Stage 1: Builder
FROM node:22 AS build

WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .

# Build your project (e.g., compile TypeScript or bundle JavaScript)
RUN npm run build

# Stage 2: Runtime
FROM my-base-image:latest AS runtime

WORKDIR /usr/src/app

# Copy only the compiled output and essential files from the build stage
COPY --from=build /usr/src/app/dist ./dist
COPY --from=build /usr/src/app/package*.json ./

# Install only production dependencies
RUN npm ci --omit=dev

# Copy the entrypoint script for remote debugging
COPY entrypoint.sh /usr/src/app/entrypoint.sh
RUN chmod +x /usr/src/app/entrypoint.sh

# Expose the application port (using the PORT environment variable) and the debug port (9229)
EXPOSE $PORT
EXPOSE 9229

# Use the entrypoint script to conditionally enable debugging
ENTRYPOINT ["sh", "/usr/src/app/entrypoint.sh"]

يتيح لك سكريبت نقطة الدخول الاتصال بتطبيق الحاوية الخاص بك للتصحيح عن بعد.

لتشغيل حاوية من الصورة الإنتاجية المبنية مع متغيرات البيئة المخصصة، قم بتشغيل:

docker run \
  --env PORT=4000 \
  --env ENABLE_DEBUG=true \
  --publish 4000:4000 \
  --publish 9229:9229 \
  <IMAGE>:<TAG>

بالنسبة لبناءات الإنتاج، تأكد من استخدام وسم النسخة الصحيح، والذي قد لا يكون latest. اتفاقيات وسم صور الحاوية مثل استخدام هي latest اتفاقية. تعرف أكثر على التوصيات الخاصة بوضع العلامات وإصدار صور الحاويات.

نشر

لدعم التكامل المستمر/النشر المستمر (CI/CD)، قم بإعداد خط أنابيب CI/CD باستخدام GitHub Actions، Azure DevOps، أو أداة CI/CD أخرى لأتمتة عملية النشر.

# .github/workflows/deploy.yml
name: Deploy to Azure

on:
push:
    branches:
    - main

jobs:
build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
          node-version: '22'

    - name: Install dependencies
      run: npm ci

    - name: Build the app
      run: npm run build

    - name: Log in to Azure
      uses: azure/login@v2
      with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

    - name: Deploy to Azure Container Apps
      run: |
          az containerapp up \
          --name my-container-app \
          --resource-group my-resource-group \
          --image my-image:my_tag \
          --environment my-environment \
          --cpu 1 --memory 2Gi \
          --env-vars NODE_ENV=production PORT=3000

عند استخدام سجل Docker، قم بتسجيل الدخول إلى سجل السجل الخاص بك ثم ادفع صور Docker إلى سجل حاويات مثل Azure Container Registry (ACR) أو Docker Hub.

# Tag the image
docker tag \
  <IMAGE>:<TAG> \
  <AZURE_REGISTRY>.azurecr.io/<IMAGE>:<TAG>

# Push the image
docker push <AZURE_REGISTRY>.azurecr.io/<IMAGE>:<TAG>

البداية الباردة

قم بتحسين بناء الإنتاج الخاص بك من خلال تضمين الكود الأساسي والتبعيات فقط. لضمان أن الحمولة رشيقة قدر الإمكان، استخدم أحد الطرق التالية:

• بناءات أو تجميع Docker متعددة المراحل: استخدم أدوات البناء والتجميع مثل Webpack أو Rollup لمساعدتك في إنشاء أصغر حمولة ممكنة لحاويتك. عندما تجمع وتجمع فقط ما هو مطلوب للإنتاج، فإنك تساعد في تقليل حجم الحاوية والمساعدة في تحسين أوقات التشغيل الباردة.

• إدارة التبعيات بعناية: حافظ على تنسيق مجلدك node_modules بتضمين الحزم المطلوبة فقط لتشغيل كود الإنتاج. لا تذكر تبعيات التطوير أو الاختبار في قسم من package.json.dependencies قم بإزالة أي تبعيات غير مستخدمة وتأكد من بقاء ملف القفل وملفك package.json متسقا.

الأمان

تشمل اعتبارات الأمان لمطوري JavaScript الذين يستخدمون Azure Container Apps تأمين متغيرات البيئة (مثل استخدام Azure Key Vault)، وضمان HTTPS مع إدارة الشهادات بشكل صحيح، والحفاظ على الاعتماديات up-to-date مع تدقيقات منتظمة، وتنفيذ تسجيل ومراقبة قوية لاكتشاف التهديدات بسرعة والاستجابة لها.

متغيرات البيئة الآمنة

تأكد من تخزين المعلومات الحساسة مثل سلاسل اتصال قاعدة البيانات ومفاتيح واجهة برمجة التطبيقات بشكل آمن. استخدم Azure Key Vault لإدارة الأسرار ومتغيرات البيئة بأمان.

قبل تشغيل هذا الأمر، تأكد من استبدال القيم المؤقتة المحاطة بقيمك <> .

az keyvault secret set \
  --vault-name <KEY_VAULT_APP> \
  --name "<SECRET_NAME>" \
  --value "<CONNECTION_STRING>"

HTTPS والشهادات

تأكد من أن طلبك يتم تسليمه عبر HTTPS. Azure Container Apps يمكنها إدارة الشهادات نيابة عنك. قم بتكوين النطاق والشهادة المخصصة في بوابة Azure.

إدارة الاعتماد

قم بتحديث تبعياتك بانتظام لتجنب الثغرات الأمنية. استخدم أدوات مثل npm audit التحقق من الثغرات.

npm audit

معالجة الأخطاء

نفذ معالجة أخطاء قوية في تطبيقك Node.js. استخدم الوسيط في Express أو Fastify للتعامل مع الأخطاء برشاقة.

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

export function errorHandler(err: any, req: Request, res: Response, next: NextFunction) {
  console.error(err.stack);
  res.status(500).send('Something broke!');
}

إغلاقات رشيقة

إغلاق طلبك بشكل صحيح أمر بالغ الأهمية لضمان اكتمال الطلبات أثناء الرحلة وإصدار الموارد بشكل صحيح. يساعد ذلك في منع فقدان البيانات ويحافظ على تجربة مستخدم سلسة أثناء عمليات النشر أو التوسع في الفعاليات. يوضح المثال التالي أحد الأساليب باستخدام Node.js وExpress للتعامل مع إشارات الإيقاف بشكل سلس.

import express from 'express';
import healthRouter from './health.js';

const app = express();

app.use(healthRouter);

const server = app.listen(process.env.PORT || 3000);

// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });

  // Force close after 30s
  setTimeout(() => {
    console.error('Could not close connections in time, forcing shutdown');
    process.exit(1);
  }, 30000);
});

تسجيل الدخول

في Azure Container Apps، يتم التقاط وتسجيل المكالمات console.logconsole.error تلقائيا. تلتقط Azure Container Apps تدفقات الإخراج القياسية (stdout) وأخطاء (stderr) القياسية من تطبيقك وتجعلها متاحة في Azure Monitor وLog Analytics.

إعداد تسجيل الدخول في Azure Container Apps

لضمان أن سجلاتك ملتقطة بشكل صحيح ومتاحة للوصول، تحتاج إلى إعداد إعدادات التشخيص لتطبيق Azure Container الخاص بك. الإعداد هو عملية من خطوتين.

1. تفعيل إعدادات التشخيص: استخدم واجهة برمجة Azure لتفعيل إعدادات التشخيص لتطبيق Azure Container الخاص بك.

   قبل تشغيل هذا الأمر، تأكد من استبدال القيم المؤقتة المحاطة بقيمك <> .

   az monitor diagnostic-settings create \
   --resource /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Web/containerApps/<CONTAINER_APP_NAME> \
   --name "containerapp-logs" \
   --workspace <LOG_ANALYTICS_WORKSPACE_ID> \
   --logs '[{"category": "ContainerAppConsoleLogs","enabled": true}]'
   

2. يمكنك الوصول إلى السجلات في البوابة من خلال الذهاب إلى مساحة عمل تحليلات السجلات واستعلام السجلات.

استخدام مكتبات التسجيل

بينما console.log يتم التقاطها تلقائيا console.error ، فإن استخدام مكتبة تسجيل مثل Winston يوفر مرونة وتحكم أكبر في تسجيلك. تتيح لك هذه المرونة تنسيق السجلات، وضبط مستويات السجل، وإخراج السجلات إلى وجهات متعددة مثل الملفات أو خدمات السجلات الخارجية.

يوضح المثال التالي كيفية تكوين Winston لتخزين سجلات عالية الدقة.

// src/logger.ts
import { createLogger, transports, format } from 'winston';

const logger = createLogger({
  level: 'info',
  format: format.combine(
    format.timestamp(),
    format.json()
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'app.log' })
  ]
});

export default logger;

لاستخدام اللوجر، استخدم الصياغة التالية في تطبيقك:

import logger from './logger';

logger.info('This is an info message');
logger.error('This is an error message');

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

لتمكين التصحيح عن بعد، يمكنك استخدام المفتش المدمج في Node. بدلا من ترميز إعدادات التصحيح الثابت في ملفات CMDDocker الخاصة بك، يمكنك تفعيل التصحيح عن بعد ديناميكيا باستخدام سكريبت shell كنقطة دخول للحاوية.

يتحقق السكربت التالي من متغير البيئة (على سبيل المثال، ENABLE_DEBUG) عند بدء الحاوية. إذا كان المتغير مضبوطا على true، يبدأ السكربت Node.js في وضع التصحيح (باستخدام --inspect أو --inspect-brk). وإلا، تبدأ الحاوية التطبيق بشكل طبيعي.

يمكنك تنفيذ التصحيح عن بعد من خلال الخطوات التالية:

1. أنشئ سكريبت نقطة دخول في ملف يحمل اسم entrypoint.sh في جذر مشروعك يحتوي على المحتوى التالي:

   #!/bin/sh
   # If ENABLE_DEBUG is set to "true", start Node with debugging enabled
   if [ "$ENABLE_DEBUG" = "true" ]; then
     echo "Debug mode enabled: starting Node with inspector"
     exec node --inspect=0.0.0.0:9229 dist/index.js
   else
     echo "Starting Node without debug mode"
     exec node dist/index.js
   fi
   

2. عدل ملف Docker الخاص بك لنسخ السكربت entrypoint.sh إلى الحاوية وضبطه كنقطة دخول. أيضا، كشف منفذ التصحيح إذا لزم الأمر:

   # Copy the entrypoint script to the container
   COPY entrypoint.sh /usr/src/app/entrypoint.sh
   
   # Ensure the script is executable
   RUN chmod +x /usr/src/app/entrypoint.sh
   
   # Expose the debugging port (if using debug mode)
   EXPOSE 9229
   
   # Set the shell script as the container’s entrypoint
   ENTRYPOINT ["sh", "/usr/src/app/entrypoint.sh"]
   

3. تفعيل وضع التصحيح عن طريق تعيين متغير ENABLE_DEBUG البيئة على true. على سبيل المثال، باستخدام واجهة الأزرق (Azure CLI):

   az containerapp update \
     --name <CONTAINER_APP> \
     --env-vars ENABLE_DEBUG=true
   

قبل تشغيل هذا الأمر، تأكد من استبدال القيم المؤقتة المحاطة بقيمك <> .

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

اعتبارات الصيانة والأداء

للحفاظ على أداء تطبيقك وتحسينه مع مرور الوقت، تأكد من إدارة تغييرات متغيرات البيئة بكفاءة، ومراقبة مواردك، والحفاظ على تبعياتك up-toالتاريخ، وضبط التوسع بشكل صحيح، وإعداد تنبيهات المراقبة.

تغيرات متغيرات البيئة

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

تخصيص الموارد

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

تحديثات التبعية

قم بتحديث اعتماداتك بانتظام للاستفادة من تحسينات الأداء وتصحيحات الأمان. استخدم أدوات مثل npm-check-updates هذه العملية لأتمتة.

npm install -g npm-check-updates
ncu -u
npm install

تغير الحجم

قم بتكوين التدرج التلقائي بناء على حمل التطبيق. يدعم Azure Container Apps التحجيم الأفقي، الذي يضبط تلقائيا عدد نسخ الحاويات بناء على استخدام وحدة المعالجة المركزية أو الذاكرة.

يوضح المثال التالي كيفية تعيين قاعدة مقياس تعتمد على وحدة المعالجة المركزية. قبل تشغيل هذا الأمر، تأكد من استبدال القيم المؤقتة المحاطة بقيمك <> .

az containerapp revision set-scale \
  --name <CONTAINER_APP> \
  --resource-group <RESOURCE_GROUP> \
  --min-replicas 1 \
  --max-replicas 10 \
  --cpu 80

تنبيهات المراقبة

قم بإعداد المراقبة والتنبيهات لتتبع أداء وصحة تطبيقك. استخدم Azure Monitor لإنشاء تنبيهات لمقاييس محددة مثل استخدام المعالج، واستخدام الذاكرة، وأوقات الاستجابة.

قبل تشغيل هذا الأمر، تأكد من استبدال القيم المؤقتة المحاطة بقيمك <> .

az monitor metrics alert create \
  --name "HighCPUUsage" \
  --resource-group <RESOURCE_GROUP> \
  --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerInstance/containerGroups/<CONTAINER_GROUP> \
  --condition "avg Percentage CPU > 80" \
  --description "Alert when CPU usage is above 80%"

إدارة الموارد

استخدم إضافة Azure Container Apps ل Visual Studio Code لإنشاء وتحرير ونشر التطبيقات المحوطة بالحاويات بسرعة من Visual Studio Code.

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

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

تسجيل الدخول

تمكين وتكوين تسجيل السجلات لالتقاط سجلات التطبيقات. استخدم Azure Monitor وLog Analytics لجمع وتحليل السجلات. قبل تشغيل هذه الأوامر، تأكد من استبدال القيم المؤقتة المحيطة بقيمك <> .

1. أنشئ مساحة عمل جديدة.

   az monitor log-analytics workspace create \
       --resource-group <RESOURCE_GROUP> \
       --workspace-name <WORKSPACE_NAME>
   

2. ثم أنشئ إعداد مساحة عمل جديد.

   az monitor diagnostic-settings create \
       --resource <CONTAINER_APP> \
       --workspace <WORKSPACE_NAME> \
       --logs '[{"category": "ContainerAppConsoleLogs","enabled": true}]'
   

التصحيح

تستخدم أدوات تصحيح الأخطاء عن بعد للاتصال بالحاوية الجارية. تأكد من أن ملف Docker الخاص بك يكشف المنافذ اللازمة للتصحيح.

# Expose the debugging port
EXPOSE 9229

فحوصات صحية

قم بضبط الفحوصات الصحية لمراقبة صحة تطبيقك. تضمن هذه الميزة أن تطبيقات حاوية Azure يمكنها إعادة تشغيل الحاوية إذا أصبحت غير مستجيبة.

# Azure Container Apps YAML configuration
properties:
configuration:
    livenessProbe:
    httpGet:
        path: /health
        port: 3000
    initialDelaySeconds: 30
    periodSeconds: 10

المحتوى ذو الصلة

• تجهيزات الحاويات المسبق للتطوير
• الحاويات قيد التطوير والإنتاج