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

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

ضبط إعدادات الخلفية

بالنسبة إلى الإعدادات المتقدّمة، مثل متغيّرات البيئة أو إعدادات وقت التشغيل، مثل حدود التزامن ووحدة المعالجة المركزية والذاكرة، عليك إنشاء ملف 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

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

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

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

  -   variable: API_KEY
      secret: myApiKeySecret

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

مزامنة حالة Firebase Auth

على التطبيقات التي تستخدم Firebase Auth التفكير في استخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase على الويب للمساعدة في الحفاظ على تزامن حالة مصادقة العميل والخادم. ويمكن تسهيل ذلك من خلال تنفيذ FirebaseServerApp باستخدام عامل خدمة. في ما يلي الخطوات الأساسية لسلسلة المهام:

  1. تنفيذ مشغّل خدمات يضيف الرؤوس الصحيحة لتطبيقك في طلبات الخادم
  2. احصل على الرؤوس من الطلب على الخادم، واحوِّلها إلى مستخدم مصادقة باستخدام FirebaseServerApp.

إدارة الخلفيات

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

إنشاء خلفية

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

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

  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.