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

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

ضبط متغيرات البيئة وتعديلها

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

إنّ ضبط متغيرات البيئة في Firebase هو أسرع طريقة للبدء. استخدِم apphosting.yaml إذا كنت بحاجة إلى تخزين معلّمات سرية والوصول إليها، ضبط متغيرات لا تتوفّر إلا في وقت الإنشاء أو وقت التشغيل، أو مشاركة متغيرات البيئة بين بيئات متعددة. باستخدام كلّ من "وحدة التحكّم" و apphosting.<env>.yaml، يمكنك ضبط قيم مختلفة لبيئات مختلفة.

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

تعديل المتغيرات

يمكنك إضافة متغيرات البيئة أو تعديلها أو حذفها في Firebase أو باستخدام apphosting.yaml:

• Firebase وحدة تحكّم:

  1. في وحدة التحكّم Firebase، انتقِل إلى الاستضافة والخدمات بدون خادم > App Hosting.

  2. انتقِل إلى عرض الخدمة الخلفية > الإعدادات > البيئة.

  3. أضِف متغيرات البيئة أو عدِّلها أو احذفها.

• apphosting.yaml:

  تعرَّف على كيفية إنشاء الملف وتعديله يدويًا.

لن تسري التغييرات إلا عند طرح الإصدار التالي، ولن تؤثر في الإصدار الحالي. يمكنك حفظ الإصدار الحالي وإنشاء إصدار جديد، أو حفظ المتغيرات ونشرها لاحقًا.

ضبط مدى توفّر المتغيرات

تتوفّر متغيرات البيئة التي تم إنشاؤها في Firebase console في كلٍّ من مدّة التصميم ووقت التشغيل. هذا هو أيضًا الشرط التلقائي للمتغيرات المحدّدة في apphosting.yaml ما لم تضيّق هذا النطاق باستخدام السمة availability. في apphosting.yaml (ولكن ليس في "وحدة التحكّم")، يمكنك حصر متغير البيئة ليكون متاحًا فقط لبيئة الإنشاء أو لبيئة وقت التشغيل فقط.

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

ملفات dotenv لتطبيقات Next.js

بالنسبة إلى تطبيقات Next.js، تعمل ملفات dotenv التي تحتوي على متغيرات البيئة مع App Hosting.

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

يجب تنسيق جميع متغيرات البيئة التي تم نسخها بهذه الطريقة بشكلٍ أنيق في النموذج بدون الحاجة إلى إدخال كلّ منها على حدة، طالما أنّ الإدخال يتّخذ تنسيقًا مثل ما يلي:

KEY1=value1
KEY2=value2
KEY3=value3

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

متغيرات البيئة التي تتم تعبئتها تلقائيًا

هناك متغيرات بيئة تتم تعبئتها تلقائيًا من خلال App Hosting. ويشمل ذلك المتغيرات التي تتم تعبئتها من خلال Google Cloud، بالإضافة إلى متغيرات البيئة الخاصة بـ Firebase عندما يتم ضبط appId على الخدمة الخلفية أثناء الإعداد:

• FIREBASE_CONFIG: (متاحة في بيئتَي الإنشاء ووقت التشغيل) توفّر معلومات إعداد مشروع Firebase التالية:

  {
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
    "projectId": 'PROJECT_ID'
  }
  

  يتم تطبيق هذا الإعداد تلقائيًا عند تهيئة حزمة Firebase Admin SDK بدون أي وسيطات.

• FIREBASE_WEBAPP_CONFIG: (متاحة في بيئة الإنشاء فقط) توفّر معلومات إعداد مشروع Firebase التالية:

  {
    "apiKey": 'API_KEY',
    "appId": 'APP_ID',
    "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "messagingSenderId": 'PROJECT_NUMBER',
    "projectId": 'PROJECT_ID',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
  }
  

  تتحقّق حزمة Firebase JS SDK تلقائيًا من متغير البيئة FIREBASE_WEBAPP_CONFIG في نص برمجي بعد التثبيت أثناء الإنشاء، ما يسمح لك أيضًا بتهيئة حزمة تطوير البرامج (SDK) للعميل بدون أي وسيطات.

اطّلِع على مقالة تهيئة مدير SDK في Firebase وحِزم SDK للويب تلقائيًا لمزيد من التفاصيل حول كيفية استخدام متغيرات البيئة هذه لتهيئة حِزم SDK.

يُرجى العِلم أنّ القيم في إعدادات Firebase الفعلية ستتطابق مع الموارد المحدّدة التي أعددتها في مشروعك.

التدرّج الهرمي للمتغيرات

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

في ما يلي ترتيب الأولوية الكامل:

1. Firebase وحدة تحكّم ← المتغيرات التي تم ضبطها في "وحدة التحكّم"
2. apphosting.<env>.yaml ← المتغيرات المحدّدة في ملف yaml خاص بالبيئة، مثل apphosting.staging.yaml (اطّلِع على مقالة نشر بيئات متعددة)
3. apphosting.yaml ← المتغيرات المحدّدة في ملف apphosting.yaml
4. نظام Firebase ← المتغيرات التي يضبطها Firebase والتي تحتوي على قيم لـ firebase_config json أو firebase_webapp_config، بالإضافة إلى متغيرات البيئة التي تضبط أسماء المضيفين والمنافذ لتطبيقات العرض من جهة الخادم (التي تضبطها محوّلات App Hosting في bundle.yaml)

الأسماء المحجوزة والقيود

متغيرات البيئة المحدّدة في الـ Cloud Run عقد وقت تشغيل الحاوية محجوزة ولا يمكن ضبطها.

قد تتغيّر متغيرات البيئة التي توفّرها البيئة، بخلاف المتغيرات التي يتم ضبطها تلقائيًا، في إصدارات وقت التشغيل المستقبلية. كأفضل ممارسة، ننصحك بعدم الاعتماد على أي متغيرات بيئة لم تضبطها بشكلٍ صريح أو تعديلها، وننصحك أيضًا بإضافة بادئة لأي متغيرات بيئة باستخدام مفتاح فريد لتجنُّب التعارضات.

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

• السلاسل الفارغة ("")
• المفاتيح التي تحتوي على "="
• المفاتيح التي تبدأ بـ X_FIREBASE_ أو X_GOOGLE_ أو CLOUD_RUN_
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• المفاتيح المكرّرة

إنشاء ملف 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 يستنتج أمرَي الإنشاء والبدء لتطبيقك استنادًا إلى إطار العمل الذي تم رصده. إذا كنت تريد استخدام أمر إنشاء أو بدء مخصّص، يمكنك إلغاء الإعدادات التلقائية في App Hosting's في apphosting.yaml.

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

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

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

ضبط ناتج الإنشاء

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

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

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

ضبط إمكانية الوصول إلى سحابة VPC

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

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

إعدادات الخروج المباشر من سحابة VPC‏ (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

إعدادات الموصّل بدون خادم (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

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

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

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

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

Firebase console: انتقِل إلى الاستضافة والخدمات بدون خادم > App Hosting، ثم انقر على إنشاء خدمة خلفية (إذا كانت هذه هي الخدمة الخلفية الأولى في مشروعك على Firebase ، انقر على البدء).

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

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

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

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

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

• عيِّن اسمًا لخدمتك الخلفية.

حذف خدمة خلفية

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

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

Firebase CLI: (الإصدار 13.15.4 أو أحدث)

1. نفِّذ الأمر التالي لحذف خدمة App Hosting الخلفية. يؤدي هذا إلى إيقاف جميع النطاقات لخدمتك الخلفية وحذف الخدمة المرتبطة بها 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.