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

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

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

تتيح لك منصة App Hosting استخدام متغيّرات البيئة لقيم الإعدادات غير الحسّاسة والبيانات السرية للمَعلمات الحسّاسة، مثل مفاتيح واجهة برمجة التطبيقات وبيانات اعتماد قاعدة البيانات ورموز الخدمة المميّزة.

  • متغيّرات البيئة العادية: تُستخدَم للإعدادات غير الحسّاسة التي تتضمّن نصوصًا عادية (مثل عناوين URL العامة لواجهات برمجة التطبيقات أو علامات الميزات أو أهداف الإصدارات). تكون القيم مرئية لجميع أعضاء المشروع.
  • البيانات السرية: تُستخدَم للمَعلمات الحسّاسة (مثل أسرار عملاء OAuth أو رموز واجهة برمجة التطبيقات المميّزة أو كلمات مرور قواعد البيانات). يتم الاحتفاظ بنسخة احتياطية من البيانات السرية من خلال Cloud Secret Manager. تكون قيم المفاتيح السرية محمية ولا يتم عرضها مطلقًا كنص عادي في وحدة تحكّم Firebase، بل توفّر وحدة التحكّم روابط لصفحات معيّنة لعرض قيم المفاتيح السرية وإدارتها مباشرةً في Cloud Secret Manager.

يمكنك تحديد مَعلمات البيئة وإدارتها باستخدام طريقتَين متكاملتَين:

  • وحدة تحكّم Firebase: يمكنك إضافة وتعديل وإرفاق الرموز السرية أو المتغيّرات بسرعة وبشكل ديناميكي أثناء إنشاء الخلفية الأوّلية أو بعد النشر في إعدادات الخلفية.

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

وحدة تحكّم Firebase

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

apphosting.yaml 

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

إدارة المتغيّرات والبيانات السرية في وحدة تحكّم Firebase

يمكنك ضبط متغيرات البيئة والرموز السرية في وحدة تحكّم Firebase عند إنشاء خلفية أو في أي وقت من إعدادات الخلفية. التغييرات التي يتم حفظها بدون نشرها تسري في عملية الطرح التالية ولا تؤثر في عملية الطرح الحالية.

إعداد المتغيّرات والرموز السرية أثناء إنشاء الخلفية

عند إنشاء خلفية جديدة في App Hosting في وحدة تحكّم Firebase، يمكنك ضبط متغيرات البيئة العادية والرموز السرية أثناء خطوة ضبط الخلفية في معالج الإعداد:

  1. في وحدة تحكّم Firebase، انتقِل إلى الاستضافة والحوسبة بدون خادم > استضافة التطبيقات وانقر على إنشاء خلفية.
  2. أكمِل خطوات المعالج الأولية لاختيار منطقتك الأساسية ومستودع الرموز البرمجية.
  3. في قسم ضبط الخلفية، ابحث عن البطاقات القابلة للتصغير متغيّرات البيئة والرموز السرية، حيث يمكنك إضافة متغيّرات عادية وإرفاق رموز سرية.
  4. أكمِل معالج إنشاء الخلفية وانقر على إنهاء ونشر.

إدارة المتغيّرات والرموز السرية في إعدادات الخلفية

يمكنك عرض متغيّرات البيئة والرموز السرية للخلفيات النشطة أو إضافتها أو تعديلها أو حذفها من لوحة بيانات إعدادات الخلفية:

  1. في وحدة تحكّم Firebase، اختَر الخلفية App Hosting وافتح الإعدادات > البيئة.
  2. راجِع الإعدادات الحالية في جدول متغيّرات البيئة:
    • المتغيّرات العادية: يتم عرض القيم كنص عادي في مجموعات رموز برمجية قابلة للنسخ.
    • البيانات السرية: تظهر كرابط قابل للنقر يعرض اسم البيانات السرية (الذي يفتح Cloud Secret Manager في وحدة تحكّم Google Cloud) إلى جانب الإصدار المستهدَف (مثل latest أو رقم إصدار محدّد مثل 2).
  3. لإضافة متغيّر أو مفتاح سرّي:
    1. انقر على إضافة جديد.
    2. في الخطوة 1: اختيار النوع، اختَر متغيّر بيئة عادي (للبيانات غير الحسّاسة التي تظهر لجميع أعضاء المشروع) أو سرّي (لمفاتيح واجهة برمجة التطبيقات وبيانات الاعتماد الحسّاسة التي تفرض قيودًا على الوصول)، ثم انقر على التالي.
    3. في الخطوة 2: ضبط الإعدادات، أدخِل اسم المفتاح والقيمة النصية العادية (للمتغيّرات العادية) أو اختَر رقم تعريف الرمز السرّي والإصدار (للرموز السرّية).
    4. احفظ التغييرات باستخدام أحد الخيارات التالية:
      • حفظ ونشر: يؤدي هذا الخيار إلى تعديل إعدادات الخلفية على الفور وبدء عملية إنشاء وطرح جديدة.
      • حفظ فقط (من سهم القائمة المنسدلة بجانب حفظ ونشر): يتم حفظ التغييرات في الإعدادات بدون بدء عملية طرح فورية. تسري الإعدادات المعدَّلة في عملية النشر التالية.
  4. لتعديل إدخال حالي أو حذفه، انقر على قائمة إجراءات إضافية (...) في نهاية الصف:
    • انقر على تعديل لتعديل المفتاح أو القيمة أو ربط الرمز السرّي أو الإصدار، ثمّ انقر على حفظ ونشر أو حفظ فقط.
    • انقر على حذف وأكِّد الإزالة في مربّع الحوار.

نقل المتغيّرات من ملفات dotenv

بالنسبة إلى تطبيقات Next.js، تعمل ملفات dotenv التي تحتوي على متغيرات البيئة مع App Hosting.

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

يتم تلقائيًا تنسيق جميع متغيّرات البيئة التي يتم نسخها بهذه الطريقة في النموذج بدون الحاجة إلى إدخال كل منها على حدة، طالما أنّ الإدخال يستخدم تنسيق KEY=value العادي:

KEY1=value1
KEY2=value2
KEY3=value3

للتحكّم في متغيّرات البيئة المعقّدة أو الدقيقة باستخدام أي إطار عمل، ننصحك باستخدام apphosting.yaml.

إدارة المتغيّرات والبيانات السرية في apphosting.yaml

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

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

يتيح كل إدخال في env: استخدام الحقول التالية:

  • variable: اسم متغيّر البيئة الذي تم عرضه لعملية التطبيق.
  • ‫value: قيمة السلسلة النصية العادية (لمتغيّرات البيئة العادية)
  • secret: مرجع بيانات Cloud Secret Manager السرية (للبيانات السرية). يمكنك استخدام اسم الرمز السري القصير (مثل myGeminiApiKeySecret أو myGeminiApiKeySecret@1 المثبَّت) أو مسار المورد الكامل (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). يُرجى الاطّلاع على تخزين المَعلمات السرية والوصول إليها لمزيد من التفاصيل.
  • availability: يتحكّم في إمكانية الوصول إلى المتغيّر أو الرمز السرّي أثناء مرحلة BUILD أو في RUNTIME أو كليهما.

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

تتوفّر متغيّرات البيئة والرموز السرية التي تم ضبطها في وحدة تحكّم Firebase في وقتَي الإنشاء والتشغيل. هذا هو أيضًا الإعداد التلقائي للإدخالات المحدّدة في apphosting.yaml ما لم تضيّق النطاق باستخدام السمة availability. في apphosting.yaml (وليس في وحدة التحكّم)، يمكنك تقييد متغيّر أو رمز سري على بيئة الإصدار فقط (BUILD) أو على بيئة التشغيل فقط (RUNTIME).

الوصول إلى المتغيّرات والبيانات السرية في الرمز البرمجي للتطبيق

سواء تم ضبطها في وحدة تحكّم Firebase أو apphosting.yaml، يتم عرض متغيّرات البيئة والرموز السرية لوقت تشغيل التطبيق كمتغيّرات بيئة عادية (على سبيل المثال، process.env في Node.js).

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}
  • الوصول من جهة الخادم: يمكن الوصول إلى جميع متغيّرات البيئة والرموز السرية بأمان في سياقات التنفيذ من جهة الخادم (مثل مكوّنات خادم Next.js أو مسارات واجهة برمجة التطبيقات أو معالِجات الخلفية في Node.js).

  • عرض المتغيّرات من جهة العميل: لعرض متغيّرات البيئة العادية في المتصفّح في أُطر عمل مثل Next.js، تأكَّد من أنّ مفتاح المتغيّر يتّبع اصطلاحات إطار العمل (على سبيل المثال، مسبوق بـ NEXT_PUBLIC_).

    env:
  - variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

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

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

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

  1. وحدة تحكّم Firebase ← المتغيّرات والرموز السرية التي تم ضبطها في وحدة التحكّم
  2. ‫apphosting.<env>.yaml: المتغيّرات والرموز السرية المحدّدة في ملف YAML خاص بالبيئة، مثل apphosting.staging.yaml (يُرجى الاطّلاع على نشر بيئات متعددة)
  3. apphosting.yaml ← المتغيّرات والرموز السرية المحدّدة في ملف apphosting.yaml
  4. نظام Firebase ← المتغيّرات التي تم ضبطها من خلال Firebase والتي تحتوي على قيم FIREBASE_CONFIG أو FIREBASE_WEBAPP_CONFIG، بالإضافة إلى متغيّرات البيئة التي تضبط أسماء المضيفين والمنافذ لتطبيقات العرض من جهة الخادم (يتم ضبطها من خلال محوّلات App Hosting في bundle.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"
}</span>

    تتحقّق حزمة تطوير البرامج (SDK) لبرنامج Firebase JS تلقائيًا من متغيّر البيئة هذا FIREBASE_WEBAPP_CONFIG في نص برمجي postinstall أثناء عملية الإنشاء، ما يتيح لك أيضًا إعداد حزمة تطوير البرامج (SDK) للعميل بدون أي وسيطات.

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

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

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

تطبّق Firebase App Hosting المتغيّرات بترتيب أولوية استنادًا إلى مصدرها. على سبيل المثال، القيم المحدّدة في وحدة تحكّم 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، بالإضافة إلى متغيّرات البيئة التي تضبط أسماء المضيفين والمنافذ لتطبيقات العرض من جهة الخادم (يتم ضبطها من خلال محوّلات 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 وmemoryMiB وconcurrency لها حدود مترابطة (على سبيل المثال، تتطلّب إعدادات الذاكرة الأعلى حدودًا أعلى لوحدة المعالجة المركزية، وتتطلّب وحدات المعالجة المركزية الجزئية تزامنًا يبلغ 1). يُرجى الاطّلاع على مستندات Cloud Run حول حدود وحدة المعالجة المركزية وحدود الذاكرة لمعرفة النطاقات الصالحة والمجموعات المطلوبة.

تجاوز نصوص الإنشاء والتشغيل البرمجية

يستنتج 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 على [.] وسيتم نشر جميع الملفات.

تخزين المَعلمات السرية والوصول إليها

يجب تخزين المعلومات الحساسة، مثل مفاتيح واجهة برمجة التطبيقات، كبيانات سرية. يمكنك إرفاق الرموز السرية بالخلفية في وحدة تحكّم Firebase أو الإشارة إليها في apphosting.yaml لتجنُّب التحقّق من المعلومات الحساسة في نظام التحكّم بالمصادر.

تمثّل المَعلمات من النوع secret مَعلمات سلاسل لها قيمة مخزَّنة في Cloud Secret Manager. بدلاً من استخلاص القيمة مباشرةً، تتحقّق المَعلمات السرية من وجودها في Cloud Secret Manager وتحمّل القيم أثناء الطرح.

env:
  - variable: API_KEY
    secret: myApiKeySecret

يمكن أن تتضمّن البيانات السرية في Cloud Secret Manager نُسخًا متعدّدة. By default, the value of a secret parameter available to your live backend is pinned to the latest available version of the secret at the time the backend was built. إذا كانت لديك متطلبات لإدارة الإصدارات ومراحل النشاط للمَعلمات، يمكنك تثبيت إصدارات معيّنة في وحدة تحكّم "Firebase" أو في "apphosting.yaml". على سبيل المثال، لتثبيت الإصدار 5 في apphosting.yaml:

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

يمكنك إنشاء بيانات اعتماد سرية باستخدام الأمر Firebase في واجهة سطر الأوامر firebase apphosting:secrets:set، وسيُطلب منك إضافة الأذونات اللازمة. يتيح لك هذا الإجراء إضافة مرجع الرمز السرّي تلقائيًا إلى apphosting.yaml.

منح إذن الوصول إلى Cloud Secret Manager

لكي يتمكّن "App Hosting" من جلب القيم السرية أثناء عمليات طرح الإصدارات ووقت التشغيل، يجب أن يمتلك حساب خدمة الخلفية "App Hosting" إذنًا للوصول إلى Cloud Secret Manager.

في حال إنشاء بيانات سرية باستخدام وحدة تحكّم Cloud Secret Manager أو واجهة سطر أوامر gcloud بدلاً من firebase apphosting:secrets:set، يمكنك منح إذن الوصول إلى الخلفية باستخدام واجهة سطر أوامر Firebase:

firebase apphosting:secrets:grantaccess SECRET_NAME

بدلاً من ذلك، يمكنك منح دور Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) لوكيل خدمة App Hosting (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) أو حساب خدمة وقت التشغيل في الخلفية باستخدام واجهة سطر الأوامر gcloud:

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

الوصول إلى وحدة التحكّم والأذونات المستندة إلى الأدوار

تقيّد وحدة تحكّم Firebase بشكل ديناميكي ميزات إدارة البيئة والبيانات السرية استنادًا إلى أذونات "إدارة الهوية وإمكانية الوصول" (IAM) الخاصة بالمستخدم:

  • دور المشاهد: يمكن للمستخدمين الذين لديهم أذونات المشروع للقراءة فقط الاطّلاع على إعدادات الضبط الحالية ولكن لا يمكنهم إجراء تغييرات.
    • أثناء إنشاء الخلفية، يتم إيقاف الزر إنشاء خلفية.
    • في الواجهة الخلفية، ضمن الإعدادات > البيئة، يتم إيقاف الزر إضافة جديد وإخفاء قوائم الصفوف مزيد من الإجراءات (...).
  • عدم توفّر أذونات Secret Manager: تظهر رسالة تحذير في وحدة التحكّم للمستخدمين الذين ليس لديهم أذونات "إدارة الهوية وإمكانية الوصول" للتفاعل مع Cloud Secret Manager (يُرجى طلب الإذن من مالك المشروع لإضافة بيانات سرية):
    • أثناء إنشاء الخلفية، يتم إيقاف بطاقة الرموز السرية.
    • في الخلفية، ضمن الإعدادات > البيئة، يتم إيقاف خيار السر عند النقر على إضافة جديد، ويتم إخفاء بعض الخيارات في قائمة الصف مزيد من الإجراءات (...) في إدخالات السر الحالية.

ضبط إعدادات الوصول إلى شبكة VPC

يمكن لخدمة الخلفية في App Hosting الاتصال بشبكة سحابة إلكترونية خاصة افتراضية (VPC). لمزيد من المعلومات والاطّلاع على مثال، يُرجى الاطّلاع على ربط Firebase App Hosting بشبكة VPC.

استخدِم عملية الربط vpcAccess في ملف apphosting.yaml لضبط إمكانية الوصول. استخدِم اسم شبكة/موصل مؤهَّل بالكامل أو رقم تعريف. يتيح استخدام المعرّفات إمكانية النقل بين بيئات التشغيل التجريبي والتشغيل الفعلي باستخدام موصّلات أو شبكات مختلفة.

إعدادات Direct VPC Egress‏ (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: انتقِل إلى الاستضافة والحوسبة بدون خادم > App Hosting، ثم انقر على إنشاء خلفية (إذا كانت هذه هي الخلفية الأولى في مشروعك على Firebase، انقر على البدء).

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

firebase apphosting:backends:create --project PROJECT_ID

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

  • اضبط الدليل الجذري لتطبيقك (يتم ضبطه تلقائيًا على /)

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

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

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

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

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

  • أدخِل اسمًا للخلفية.

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

حذف خلفية

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

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

Firebase CLI: (الإصدار 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.