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

تم تصميم 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.

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

تطبِّق ميزة "استضافة التطبيقات على 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)

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

يجب أن تبدأ مفاتيح المتغيرات الصالحة بحرف كبير وأن تحتوي على أحرف كبيرة وأرقام وشرطات سفلية فقط. بعض مفاتيح متغيرات البيئة محجوزة للاستخدام الداخلي. لا تستخدِم أيًا من المفاتيح التالية في ملفات الإعداد:

السلاسل الفارغة ("")
المتغيرات التي تحتوي على "="
أي متغيّر يبدأ بـ X_FIREBASE_
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الأمر المستنتج.

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

تعمل 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.