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

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

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

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

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

وحدة تحكُّم Firebase

لقطة شاشة لمربّع حوار وحدة تحكّم Firebase لإضافة متغيرات البيئة

`apphosting.yaml`

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

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

يمكنك إضافة متغيرات البيئة وتعديلها في وحدة تحكّم Firebase ضمن علامة التبويب الإعدادات للخادم الخلفي. انتقِل إلى عرض الخلفية >> الإعدادات >> البيئة، ثم أضِف متغيرات البيئة أو عدِّلها أو احذفها.

لإضافة متغيّرات البيئة وتعديلها في apphosting.yaml,، عليك إنشاء الملف وتعديله يدويًا.

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

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

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

عند إنشاء خلفية تطبيق أو تعديلها، يمكنك نقل متغيّرات البيئة من ملف 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'
}
```
يتم تطبيق هذا الإعداد تلقائيًا عند تهيئة حزمة تطوير البرامج (SDK) الخاصة بمسؤول Firebase بدون وسيطات.
‫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" المتغيّرات بترتيب الأولوية استنادًا إلى مصدرها. على سبيل المثال، تحلّ القيم التي يتم ضبطها في وحدة التحكّم دائمًا محلّ القيم التي يتم ضبطها في ملفات apphosting.yaml وdotenv، أو تكون لها الأولوية عليها.

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

وحدة تحكّم Firebase → المتغيّرات التي تم ضبطها في وحدة التحكّم
‫apphosting.<env>.yaml → المتغيرات المحدّدة في ملف yaml خاص ببيئة معيّنة مثل apphosting.staging.yaml (راجِع نشر بيئات متعددة)
‫apphosting.yaml → المتغيّرات المحدّدة في ملف apphosting.yaml
نظام Firebase: متغيرات يضبطها Firebase وتحتوي على قيم firebase_config json أو firebase_webapp_config، بالإضافة إلى متغيرات البيئة التي تضبط أسماء المضيفين والمنافذ لتطبيقات SSR (يتم ضبطها بواسطة محوّلات 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 من خلال 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 لإعداد أذونات الوصول. استخدِم إما اسم شبكة/موصل مؤهَّل بالكامل أو رقم تعريف. يتيح استخدام المعرّفات إمكانية نقل البيانات بين بيئات الاختبار والإنتاج التي تتضمّن موصّلات/شبكات مختلفة.

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

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

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

وحدة تحكّم Firebase: من قائمة إنشاء، اختَر 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 أو الإصدارات الأحدث)

نفِّذ الأمر التالي لحذف App Hosting Backend. يؤدي هذا الإجراء إلى إيقاف جميع النطاقات في الخلفية وحذف خدمة Cloud Run المرتبطة بها:
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
(اختياري) في علامة التبويب Google Cloud Console الخاصة بـ Artifact Registry، احذف صورة الخلفية في "firebaseapphosting-images".
في Cloud Secret Manager، احذف أي أسرار يتضمّن اسمها "apphosting"، مع الحرص بشكل خاص على التأكّد من أنّ هذه الأسرار لا تستخدمها أي أنظمة خلفية أخرى أو أي جوانب أخرى من مشروع Firebase.