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

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

إعداد واجهة خلفية

لإجراء عملية ضبط متقدّمة، مثل متغيّرات البيئة أو إعدادات وقت التشغيل، مثل التزامن ووحدة المعالجة المركزية (CPU) وحدود الذاكرة، عليك إنشاء ملف 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.appspot.com
    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، ولكن قد تتطلّب زيادة حد الذاكرة زيادة حدود وحدة المعالجة المركزية:

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

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

ضبط بيئة الإصدار

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

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com

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

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

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

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

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.appspot.com
    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 باستخدام أمر CLI firebase apphosting:secrets:grantaccess.

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

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

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

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

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

إنشاء خلفية

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

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

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

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

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

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

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

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

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

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

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

حذف خلفية

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