إعداد وإدارة الخلفيات الخاصة باستضافة التطبيقات

تم تصميم App Hosting لتسهيل الاستخدام وتقليل الصيانة، مع تحسين الإعدادات التلقائية لمعظم حالات الاستخدام. في الوقت نفسه، توفّر لك App Hosting أدوات لإدارة الخلفيات وضبطها بما يتناسب مع احتياجاتك المحدّدة. يوضّح هذا الدليل هذه الأدوات والعمليات.

إنشاء apphosting.yaml وتعديله

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

لإنشاء apphosting.yaml، شغِّل الأمر التالي:

firebase init apphosting

يؤدي ذلك إلى إنشاء ملف apphosting.yaml أساسي يتضمّن مثالاً على الإعدادات (مع تعليقات). بعد التعديل، قد يبدو ملف apphosting.yaml النموذجي على النحو التالي، مع إعدادات لخدمة Cloud Run الخلفية وبعض متغيرات البيئة وبعض المراجع إلى الأسرار التي تديرها خدمة Cloud Secret Manager:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

يقدّم الجزء المتبقّي من هذا الدليل المزيد من المعلومات والسياق حول إعدادات المثال هذه.

ضبط إعدادات خدمة Cloud Run

باستخدام إعدادات apphosting.yaml، يمكنك ضبط طريقة توفير خدمة Cloud Run. يتم توفير الإعدادات المتاحة لخدمة Cloud Run في عنصر runConfig:

• استبدِل cpu بعدد وحدات المعالجة المركزية المستخدَمة لكل مثيل عرض (القيمة التلقائية هي 0).
• ‫memoryMiB – مقدار الذاكرة المخصّصة لكل مثيل عرض في وحدة MiB (القيمة التلقائية هي 512)
• maxInstances: الحد الأقصى لعدد الحاويات التي يمكن تشغيلها في المرة الواحدة (القيمة التلقائية هي 100 ويتم إدارتها حسب الحصة)
• minInstances: عدد الحاويات التي يجب إبقاؤها نشطة دائمًا (القيمة التلقائية هي 0).
• ‫concurrency: الحدّ الأقصى لعدد الطلبات التي يمكن أن يتلقّاها كل مثيل عرض (القيمة التلقائية هي 80).

يُرجى ملاحظة العلاقة المهمة بين cpu وmemoryMiB، إذ يمكن ضبط الذاكرة على أي قيمة عددية صحيحة بين 128 و32768، ولكن قد تتطلّب زيادة حد الذاكرة زيادة حدود وحدة المعالجة المركزية:

• يتطلّب استخدام أكثر من 4 غيغابايت وحدتَي معالجة مركزية على الأقل
• يتطلّب استخدام أكثر من 8 غيغابايت من الذاكرة 4 وحدات معالجة مركزية على الأقل
• يتطلّب أكثر من 16 غيغابايت من الذاكرة 6 وحدات معالجة مركزية على الأقل
• يتطلّب أكثر من 24 غيغابايت من الذاكرة 8 وحدات معالجة مركزية على الأقل

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

ضبط البيئة

في بعض الأحيان، ستحتاج إلى إعدادات إضافية لعملية الإنشاء، مثل مفاتيح واجهة برمجة التطبيقات التابعة لجهات خارجية أو إعدادات قابلة للضبط. توفّر App Hosting إعدادات البيئة في apphosting.yaml لتخزين هذا النوع من البيانات واسترجاعه لمشروعك.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

بالنسبة إلى تطبيقات Next.js، ستعمل أيضًا ملفات dotenv التي تحتوي على متغيرات البيئة مع App Hosting. ننصحك باستخدام apphosting.yaml للتحكّم الدقيق في متغيرات البيئة مع أي إطار عمل.

في apphosting.yaml، يمكنك تحديد العمليات التي يمكنها الوصول إلى متغيّر البيئة باستخدام السمة availability. يمكنك حصر توفّر متغيّر بيئة على بيئة الإنشاء فقط أو على بيئة وقت التشغيل فقط. ويكون متاحًا تلقائيًا لكليهما.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

بالنسبة إلى تطبيقات Next.js، يمكنك أيضًا استخدام البادئة NEXT_PUBLIC_ بالطريقة نفسها التي تستخدمها في ملف dotenv لجعل المتغير متاحًا في المتصفّح.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

تتألف مفاتيح المتغيرات الصالحة من أحرف من الألف إلى الياء أو شرطات سفلية. بعض مفاتيح متغيرات البيئة محجوزة للاستخدام الداخلي. لا تستخدِم أيًا من المفاتيح التالية في ملفات الإعداد:

• أي متغير يبدأ بـ X_FIREBASE_
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION

تجاوز نصوص الإنشاء والتشغيل البرمجية

يستنتج App Hosting أمرَي إنشاء تطبيقك وتشغيله استنادًا إلى إطار العمل الذي تم رصده. إذا أردت استخدام أمر إنشاء أو بدء مخصّص، يمكنك تجاهل الإعدادات التلقائية في App Hosting من خلال apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

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

استخدِم خيار تجاهل أمر التشغيل عندما يكون هناك أمر محدّد تريد استخدامه لبدء تطبيقك يختلف عن الأمر App Hosting-inferred.

ضبط ناتج الإصدار

تعمل أداة App Hosting على تحسين عمليات نشر تطبيقك تلقائيًا من خلال حذف ملفات الإخراج غير المستخدَمة كما هو موضّح في إطار العمل. إذا كنت تريد إجراء المزيد من التحسينات على حجم نشر تطبيقك أو تجاهل التحسينات التلقائية، يمكنك إلغاء هذا الإعداد في apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

يستقبل المَعلمة include قائمة بالأدلة والملفات ذات الصلة بدليل جذر التطبيق واللازمة لنشر تطبيقك. إذا أردت التأكّد من الاحتفاظ بجميع الملفات، اضبط قيمة include على [.] وسيتم نشر جميع الملفات.

تخزين المَعلمات السرية والوصول إليها

يجب تخزين المعلومات الحساسة، مثل مفاتيح واجهة برمجة التطبيقات، كأسرار. يمكنك الرجوع إلى الأسرار في apphosting.yaml لتجنُّب إدخال المعلومات الحسّاسة في نظام التحكّم بالمصادر.

تمثّل المَعلمات من النوع secret مَعلمات السلسلة التي تتضمّن قيمة مخزّنة في Cloud Secret Manager. بدلاً من استخلاص القيمة مباشرةً، تتحقّق المَعلمات السرية من توفّرها في Cloud Secret Manager، ويتم تحميل القيم أثناء الطرح.

  -   variable: API_KEY
      secret: myApiKeySecret

يمكن أن تتضمّن الأسرار في Cloud Secret Manager إصدارات متعددة. بشكلٍ تلقائي، يتم تثبيت قيمة مَعلمة سرية متاحة للخادم الخلفي المباشر على أحدث إصدار متاح من السر في وقت إنشاء الخادم الخلفي. إذا كانت لديك متطلبات بشأن تحديد إصدارات المَعلمات وإدارة دورة حياتها، يمكنك تثبيت إصدارات معيّنة باستخدام Cloud Secret Manager. على سبيل المثال، لتثبيت الإصدار 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

يمكنك إنشاء أسرار باستخدام أمر واجهة سطر الأوامر firebase apphosting:secrets:set، وسيُطلب منك إضافة الأذونات اللازمة. يمنحك هذا المسار خيار إضافة مرجع سرّي إلى apphosting.yaml تلقائيًا.

لاستخدام المجموعة الكاملة من وظائف Cloud Secret Manager، يمكنك بدلاً من ذلك استخدام وحدة تحكّم Cloud Secret Manager. في حال إجراء ذلك، عليك منح أذونات إلى الخلفية App Hosting باستخدام أمر واجهة سطر الأوامر firebase apphosting:secrets:grantaccess.

ضبط إعدادات الوصول إلى شبكة VPC

يمكن أن يتصل الخلفية App Hosting بشبكة سحابة إلكترونية خاصة افتراضية (VPC). لمزيد من المعلومات ومثال، راجِع ربط Firebase App Hosting بشبكة VPC.

استخدِم عملية الربط vpcAccess في ملف apphosting.yaml لإعداد أذونات الوصول. استخدِم اسم شبكة مؤهَّل بالكامل أو رقم تعريف. يتيح استخدام المعرّفات إمكانية نقل البيانات بين بيئات العرض التجريبي والإنتاج التي تتضمّن موصّلات/شبكات مختلفة.

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

إدارة الأنظمة الخلفية

تتوفّر الأوامر الخاصة بالإدارة الأساسية لخلفيات App Hosting في واجهة سطر الأوامر (CLI) الخاصة بـ Firebase ووحدة تحكّم Firebase. يوضّح هذا القسم بعض مهام الإدارة الأكثر شيوعًا، بما في ذلك إنشاء الخلفيات وحذفها.

إنشاء خادم خلفي

App Hosting الخلفية هي مجموعة من الموارد المُدارة التي App Hosting يتم إنشاؤها لإنشاء تطبيق الويب وتشغيله.

وحدة تحكّم Firebase: من قائمة إنشاء، اختَر استضافة التطبيقات، ثم انقر على البدء.

واجهة سطر الأوامر: (الإصدار 13.15.4 أو إصدار أحدث) لإنشاء خلفية، شغِّل الأمر التالي من جذر دليل المشروع المحلي، مع توفير projectID كمعلَمة:

firebase apphosting:backends:create --project PROJECT_ID

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

• اضبط دليل الجذر لتطبيقك (يكون / هو الإعداد التلقائي).

  عادةً ما يكون هذا هو المكان الذي يتم فيه تخزين ملف package.json.

• ضبط الفرع المباشر

  هذا هو فرع مستودع GitHub الذي يتم نشره على عنوان URL المباشر. وغالبًا ما يكون هذا الفرع هو الذي يتم دمج فروع الميزات أو فروع التطوير فيه.

• قبول عمليات الطرح التلقائي أو رفضها

  تكون عمليات الطرح التلقائي مفعّلة تلقائيًا. بعد اكتمال عملية إنشاء الخلفية، يمكنك اختيار نشر تطبيقك على App Hosting على الفور.

• امنح الخلفية اسمًا.

حذف نظام خلفي

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

وحدة تحكّم Firebase: من قائمة الإعدادات، اختَر حذف الخلفية.

واجهة سطر الأوامر: (الإصدار 13.15.4 أو الإصدارات الأحدث)

1. نفِّذ الأمر التالي لحذف App Hosting Backend. يؤدي هذا الإجراء إلى إيقاف جميع النطاقات في الخلفية وحذف خدمة Cloud Run المرتبطة بها:

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

2. (اختياري) في علامة التبويب Google Cloud Console الخاصة بـ Artifact Registry، احذف صورة الخلفية في "firebaseapphosting-images".

3. في Cloud Secret Manager، احذف أي أسرار يتضمّن اسمها "apphosting"، مع الحرص بشكل خاص على التأكّد من أنّ هذه الأسرار لا تستخدمها أي أنظمة خلفية أخرى أو أي جوانب أخرى من مشروعك على Firebase.