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

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

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

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

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

Firebase وحدة التحكّم

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

`apphosting.yaml`

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

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

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

وحدة تحكّم Firebase:
1. في وحدة تحكّم Firebase، انتقِل إلى الاستضافة وبدون خادم >استضافة التطبيقات.
2. انتقِل إلى عرض الخلفية > الإعدادات > البيئة.
3. إضافة متغيرات البيئة أو تعديلها أو حذفها
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 التي تحتوي على متغيرات البيئة مع 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'
}
```
يتم تطبيق هذا الإعداد تلقائيًا عند تهيئة حزمة تطوير البرامج (SDK) الخاصة بـ Firebase Admin بدون وسيطات.
‫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',
}
```
تتحقّق حزمة تطوير البرامج (SDK) من Firebase JS تلقائيًا من متغير البيئة FIREBASE_WEBAPP_CONFIG هذا في نص برمجي بعد التثبيت أثناء عملية الإنشاء، ما يتيح لك أيضًا تهيئة حزمة تطوير البرامج (SDK) الخاصة بالعميل بدون أي وسيطات.

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

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

التسلسل الهرمي للمتغيرات

تطبِّق ميزة "استضافة التطبيقات على 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 CLI firebase apphosting:secrets:set، وسيُطلب منك إضافة الأذونات اللازمة. يمنحك هذا المسار خيار إضافة مرجع المفتاح السري تلقائيًا إلى apphosting.yaml.

لاستخدام المجموعة الكاملة من وظائف Cloud Secret Manager، يمكنك بدلاً من ذلك استخدام وحدة تحكّم Cloud Secret Manager. في حال إجراء ذلك، عليك منح أذونات إلى الخلفية App Hosting باستخدام الأمر Firebase لواجهة سطر الأوامر 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 وواجهة سطر الأوامر Firebase. يوضّح هذا القسم بعض مهام الإدارة الأكثر شيوعًا، بما في ذلك إنشاء الخلفيات وحذفها.

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

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

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

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

firebase apphosting:backends:create --project PROJECT_ID

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

اضبط دليل الجذر لتطبيقك (يكون / تلقائيًا)

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

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

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

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

حذف نظام خلفي

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

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

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

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