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

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

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

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

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

Firebase وحدة تحكّم

apphosting.yaml

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

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

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

يمكنك إضافة متغيرات البيئة أو تعديلها أو حذفها في 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) للعميل بدون أي وسيطات.

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

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

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

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

**ملاحظة:** في وحدة التحكّم Firebase، يمكنك اختيار عملية طرح محدّدة لعرض تفاصيلها. انتقِل إلى متغيرات البيئة في هذا الإصدار في أسفل لوحة تفاصيل عملية الطرح لمراجعة قائمة متغيرات البيئة المستخدَمة أثناء عملية الطرح ومصادرها.

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

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 – مقدار الذاكرة المخصّصة لكلّ مثيل عرض بالميغابايت (الإعداد التلقائي هو 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 تنشئها لإنشاء تطبيق الويب وتشغيله.

على مالك المشروع إنشاء أول App Hosting خلفية. بعد هذا الإعداد الأولي، App Hosting يمكن للمشرفين أيضًا إنشاء خلفيات إضافية وإدارتها. للاطّلاع على جميع مستودعات مؤسستك، تأكَّد من أنّ لديك دور مشرف المؤسسة في GitHub. لا يعرض دور العضو العادي سوى المستودعات التي أنشأتها شخصيًا. للحصول على التفاصيل، اطّلِع على Firebase 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 على الفور.

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

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

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

حذف خلفية

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

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

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.