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

تم تصميم 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، انتقِل إلى الاستضافة وبدون خادم > استضافة التطبيقات.

  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 التي تحتوي على متغيرات البيئة مع خدمة "استضافة التطبيقات".

عند إنشاء خلفية تطبيق أو تعديلها، يمكنك نقل متغيّرات البيئة من ملف 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، أو لها الأولوية عليها.

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

1. Firebase وحدة التحكّم → المتغيرات التي تم ضبطها في وحدة التحكّم
2. apphosting.<env>.yaml → المتغيرات المحدّدة في ملف yaml خاص ببيئة معيّنة، مثل apphosting.staging.yaml (راجِع نشر بيئات متعددة)
3. ‫apphosting.yaml → المتغيّرات المحدّدة في ملف apphosting.yaml
4. نظام 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المستنتج.

ضبط ناتج الإصدار

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

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

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

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

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

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

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

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

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

• امنح الخلفية اسمًا.

• اختَر بيئة وقت التشغيل. يتم تلقائيًا اختيار أحدث إصدار مقترَح من Node.js.

  • اضبط التحديثات التلقائية لصورة النظام الأساسية (ABIU). تكون ميزة ABIU مفعَّلة تلقائيًا وتطبِّق تصحيحات الأمان تلقائيًا على البيئة الأساسية. يمكنك إيقاف ABIU من خلال اختيار "لم يتم التحديد" لوقت التشغيل.

حذف خادم خلفي

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

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

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

1. نفِّذ الأمر التالي لحذف الخلفية App Hosting. يؤدي هذا الإجراء إلى إيقاف جميع النطاقات في الخلفية وحذف خدمة Cloud Run المرتبطة بها:

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

2. (اختياري) في علامة التبويب Google Cloudوحدة التحكّم الخاصة بـ Artifact Registry، احذف الصورة الخاصة بالخادم الخلفي في "firebaseapphosting-images".

3. في Cloud Secret Manager، احذف أي أسرار يتضمّن اسمها "apphosting"، مع الحرص بشكل خاص على التأكّد من أنّ هذه الأسرار لا تستخدمها أي أنظمة خلفية أخرى أو أي جوانب أخرى من مشروع Firebase.