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

تم تصميم 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: مقدار الذاكرة المخصّصة لكل مثيل عرض بوحدة ميغابايت (الإعداد التلقائي هو 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

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

  • أي متغيّر يبدأ بـ 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 محوِّلات إطار العمل.

استخدِم الأمر run override عندما يكون هناك ملف برمجي معيّن تريد استخدامه لبدء تطبيقك يختلف عن الملف البرمجي 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

يمكن أن تتضمّن الأسرار في أداة إدارة الأسرار في السحابة الإلكترونية نُسخًا متعددة. بشكلٍ تلقائي، يتم تثبيت قيمة مَعلمة سرية متاحة للخلفية المنشورة على أحدث إصدار متاح من السر في وقت إنشاء الخلفية. إذا كانت لديك متطلبات متعلّقة بإدارة الإصدارات وإدارة دورة حياة المَعلمات، يمكنك تثبيتها على إصدارات معيّنة باستخدام أداة "إدارة الأسرار في السحابة الإلكترونية". على سبيل المثال، لتثبيت الإصدار 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 في Firebase CLI ووحدة تحكّم Firebase. يصف هذا القسم بعض مهام الإدارة الأكثر شيوعًا، بما في ذلك إنشاء الخلفيات وحذفها.

إنشاء خلفية

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

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

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

firebase apphosting:backends:create --project PROJECT_ID --location us-central1

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

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

    هذا هو عادةً مكان توفُّر ملف package.json.

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

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

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

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

  • حدِّد اسمًا لنظامك الأساسي.

حذف خلفية

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

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

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

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

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1

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

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