App Hosting برای سهولت استفاده و نیاز به نگهداری کم طراحی شده است و تنظیمات پیشفرض آن برای اکثر موارد استفاده بهینه شده است. در عین حال، App Hosting ابزارهایی را برای مدیریت و پیکربندی backendها برای نیازهای خاص شما فراهم میکند. این راهنما این ابزارها و فرآیندها را شرح میدهد.
تنظیم و بهروزرسانی متغیرهای محیطی
گاهی اوقات ممکن است برای فرآیند ساخت خود به پیکربندی اضافی نیاز داشته باشید. App Hosting پیکربندی محیطی را برای ذخیره و بازیابی این نوع دادهها برای پروژه شما از طریق کنسول Firebase و به طور جایگزین در apphosting.yaml ارائه میدهد.
تنظیم متغیرهای محیطی در کنسول سریعترین راه برای شروع است. اگر نیاز به ذخیره و دسترسی به پارامترهای مخفی ، تنظیم متغیرهایی که فقط در زمان ساخت یا اجرا در دسترس هستند، یا اشتراکگذاری متغیرهای محیطی در چندین محیط دارید، از apphosting.yaml استفاده کنید. با هر دو console و apphosting.<env>.yaml ، میتوانید مقادیر مختلفی را برای محیطهای مختلف تنظیم کنید .
کنسول فایربیس
apphosting.yaml
env:
- variable: STORAGE_BUCKET
value: mybucket.firebasestorage.app
متغیرها را بهروزرسانی کنید
شما میتوانید متغیرهای محیطی را در کنسول Firebase در تب تنظیمات برای backend اضافه و ویرایش کنید. به View Backend >> Settings >> Environment بروید و سپس متغیرهای محیطی را اضافه، ویرایش یا حذف کنید.
برای افزودن و ویرایش متغیرهای محیطی در 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 کار میکنند.
هنگام ایجاد یا بهروزرسانی یک backend، میتوانید متغیرهای محیطی را از فایل dotenv خود به کنسول Firebase منتقل کنید، برای این کار کل محتویات فایل dotenv را در اولین فیلد "Key" در فرم "Add new" در تنظیمات متغیرهای محیطی کپی و جایگذاری کنید.
تمام متغیرهای محیطی که به این روش کپی میشوند، باید به طور مرتب در فرم قالببندی شوند و نیازی به وارد کردن تک تک آنها نباشد، البته تا زمانی که ورودی فرمتی مانند زیر داشته باشد:
KEY1=value1
KEY2=value2
KEY3=value3
برای کنترل متغیرهای محیطی پیچیده یا جزئی با هر چارچوبی، توصیه میکنیم از apphosting.yaml استفاده کنید.
سلسله مراتب متغیر
میزبانی برنامه Firebase متغیرهای شما را به ترتیب اولویت و بر اساس منبع آنها اعمال میکند. برای مثال، مقادیر تعیین شده در کنسول همیشه بر مقادیر تعیین شده در فایلهای apphosting.yaml و dotenv اولویت دارند یا آنها را نادیده میگیرند.
در اینجا ترتیب کامل اولویت آمده است:
- کنسول فایربیس → متغیرهای تنظیمشده در کنسول
-
apphosting.<env>.yaml→ متغیرهای مشخص شده در یک فایل yaml مخصوص محیط مانندapphosting.staging.yaml( به استقرار چندین محیط مراجعه کنید) -
apphosting.yaml→ متغیرهای مشخص شده در فایلapphosting.yaml - سیستم Firebase → متغیرهایی که توسط Firebase تنظیم شدهاند و شامل مقادیری برای
firebase_config jsonیاfirebase_webapp_configهستند، و همچنین متغیرهای محیطی که نامهای میزبان و پورتها را برای برنامههای SSR تنظیم میکنند (توسط App Hosting adapters درbundle.yamlتنظیم شدهاند)
نامها و محدودیتهای رزرو شده
کلیدهای معتبر متغیر باید با حرف بزرگ شروع شوند و فقط شامل حروف بزرگ، اعداد و زیرخط باشند. برخی از کلیدهای متغیرهای محیطی برای استفاده داخلی رزرو شدهاند. از هیچ یک از این کلیدها در فایلهای پیکربندی خود استفاده نکنید:
- رشتههای خالی ("")
- متغیرهایی که شامل "=" هستند
- هر متغیری که با
X_FIREBASE_شروع شود -
PORT -
K_SERVICE -
K_REVISION -
K_CONFIGURATION - کلیدهای تکراری
ایجاد و ویرایش apphosting.yaml
برای پیکربندی پیشرفته مانند تنظیمات مخفی یا تنظیمات زمان اجرا مانند همزمانی، CPU و محدودیتهای حافظه، باید فایل 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- مقدار حافظه اختصاص داده شده برای هر نمونه ارائه شده به مگابایت (پیش فرض ۵۱۲) -
maxInstances- حداکثر تعداد کانتینرهایی که میتوانند همزمان اجرا شوند (پیشفرض ۱۰۰ و با سهمیه مدیریت میشود) -
minInstances– تعداد کانتینرهایی که همیشه باید فعال نگه داشته شوند (پیشفرض ۰). -
concurrency- حداکثر تعداد درخواستهایی که هر نمونهی سرویسدهنده میتواند دریافت کند (پیشفرض ۸۰).
به رابطه مهم بین cpu و memoryMiB توجه کنید؛ حافظه را میتوان روی هر مقدار صحیحی بین ۱۲۸ تا ۳۲۷۶۸ تنظیم کرد، اما افزایش محدودیت حافظه ممکن است نیاز به افزایش محدودیتهای CPU داشته باشد:
- بیش از ۴ گیگابایت حداقل به ۲ پردازنده نیاز دارد
- بیش از ۸ گیگابایت به حداقل ۴ پردازنده نیاز دارد
- بیش از ۱۶ گیگابایت به حداقل ۶ پردازنده نیاز دارد
- بیش از ۲۴ گیگابایت به حداقل ۸ پردازنده نیاز دارد
به طور مشابه، مقدار cpu بر تنظیمات همزمانی تأثیر میگذارد. اگر مقداری کمتر از ۱ برای CPU تعیین کنید، باید همزمانی را روی ۱ تنظیم کنید و CPU فقط در طول پردازش درخواست اختصاص داده میشود.
اسکریپتهای ساخت و اجرا را نادیده بگیرید
App Hosting بر اساس چارچوب شناساییشده، دستور ساخت و شروع برنامه شما را استنباط میکند. اگر میخواهید از یک دستور ساخت یا شروع سفارشی استفاده کنید، میتوانید پیشفرضهای App Hosting را در apphosting.yaml نادیده بگیرید.
scripts:
buildCommand: next build --no-lint
runCommand: node dist/index.js
لغو دستور build بر هر دستور build دیگری اولویت دارد و برنامه شما را از آداپتورهای چارچوب خارج میکند و هرگونه بهینهسازی خاص چارچوب را که App Hosting ارائه میدهد غیرفعال میکند. بهتر است زمانی استفاده شود که ویژگیهای برنامه شما به خوبی توسط آداپتورها پشتیبانی نمیشوند. اگر میخواهید دستور build خود را تغییر دهید اما همچنان از آداپتورهای ارائه شده ما استفاده کنید، اسکریپت build خود را به جای آن، همانطور که در آداپتورهای چارچوب App Hosting توضیح داده شده است، در package.json تنظیم کنید.
وقتی میخواهید از دستور خاصی برای شروع برنامهتان استفاده کنید که با دستور App Hosting -inferred متفاوت است، از override دستور run استفاده کنید.
پیکربندی خروجی ساخت
App Hosting به طور پیشفرض با حذف فایلهای خروجی بلااستفاده، همانطور که توسط چارچوب مشخص شده است، استقرار برنامه شما را بهینه میکند. اگر میخواهید اندازه استقرار برنامه خود را بیشتر بهینه کنید یا بهینهسازیهای پیشفرض را نادیده بگیرید، میتوانید این مورد را در apphosting.yaml بازنویسی کنید.
outputFiles:
serverApp:
include: [dist, server.js]
پارامتر include لیستی از دایرکتوریها و فایلهای مربوط به دایرکتوری ریشه برنامه را که برای استقرار برنامه شما ضروری هستند، دریافت میکند. اگر میخواهید مطمئن شوید که همه فایلها حفظ میشوند، include را روی [.] تنظیم کنید تا همه فایلها مستقر شوند.
پارامترهای مخفی را ذخیره و دسترسی کنید
اطلاعات حساس مانند کلیدهای API باید به عنوان اطلاعات محرمانه ذخیره شوند. میتوانید برای جلوگیری از بررسی اطلاعات حساس در کنترل منبع، به اطلاعات محرمانه در apphosting.yaml ارجاع دهید.
پارامترهای از نوع secret پارامترهای رشتهای هستند که مقداری در Cloud Secret Manager ذخیره کردهاند. به جای استخراج مستقیم مقدار، پارامترهای secret وجودشان در Cloud Secret Manager بررسی میشود و مقادیر در طول فرآیند نصب بارگذاری میشوند.
- variable: API_KEY
secret: myApiKeySecret
اسرار در Cloud Secret Manager میتوانند چندین نسخه داشته باشند. به طور پیشفرض، مقدار یک پارامتر مخفی موجود در backend زنده شما به آخرین نسخه موجود از راز در زمان ساخت backend پین شده است. اگر الزاماتی برای نسخهبندی و مدیریت چرخه عمر پارامترها دارید، میتوانید با Cloud Secret Manager به نسخههای خاصی پین کنید. به عنوان مثال، برای پین کردن به نسخه ۵:
- variable: PINNED_API_KEY
secret: myApiKeySecret@5
شما میتوانید با دستور firebase apphosting:secrets:set CLI، فایلهای محرمانه ایجاد کنید و از شما خواسته میشود مجوزهای لازم را اضافه کنید. این روند به شما این امکان را میدهد که به طور خودکار مرجع محرمانه را به apphosting.yaml اضافه کنید.
برای استفاده از مجموعه کامل قابلیتهای Cloud Secret Manager، میتوانید از کنسول Cloud Secret Manager استفاده کنید. اگر این کار را انجام دهید، باید با دستور firebase apphosting:secrets:grantaccess در CLI، به App Hosting backend خود مجوز بدهید.
پیکربندی دسترسی 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 CLI و کنسول Firebase ارائه شدهاند. این بخش برخی از وظایف مدیریتی رایجتر، از جمله ایجاد و حذف بکاندها را شرح میدهد.
ایجاد یک بکاند
بکاند App Hosting ، مجموعهای از منابع مدیریتشده است که App Hosting برای ساخت و اجرای اپلیکیشن وب شما ایجاد میکند.
کنسول فایربیس : از منوی Build ، گزینه App Hosting و سپس Create backend را انتخاب کنید (اگر این اولین backend در پروژه فایربیس شماست، گزینه Get started را انتخاب کنید).
رابط خط فرمان (CLI): (نسخه ۱۳.۱۵.۴ یا بالاتر) برای ایجاد یک backend، دستور زیر را از ریشه دایرکتوری پروژه محلی خود اجرا کنید و projectID خود را به عنوان آرگومان وارد کنید:
firebase apphosting:backends:create --project PROJECT_ID
برای هر دو کنسول یا CLI، دستورالعملها را دنبال کنید تا یک منطقه را انتخاب کنید، یک اتصال GitHub برقرار کنید و این تنظیمات اولیه استقرار را پیکربندی کنید:
دایرکتوری ریشه برنامه خود را تنظیم کنید (پیشفرض روی
/)این معمولاً جایی است که فایل
package.jsonشما قرار دارد.
شاخه زنده را تنظیم کنید
این شاخهای از مخزن گیتهاب شماست که به آدرس اینترنتی (URL) زنده شما منتقل میشود. اغلب، این شاخهای است که شاخههای ویژگی یا شاخههای توسعه در آن ادغام میشوند.
پذیرش یا رد انتشار خودکار
انتشار خودکار به صورت پیشفرض فعال است. پس از اتمام ساخت بکاند، میتوانید انتخاب کنید که برنامه شما بلافاصله در App Hosting مستقر شود.
یک نام به backend خود اختصاص دهید.
حذف یک بکاند
برای حذف کامل یک backend، ابتدا از Firebase CLI یا کنسول Firebase برای حذف آن استفاده کنید و سپس به صورت دستی داراییهای مرتبط را حذف کنید، و توجه ویژه داشته باشید که منابعی را که ممکن است توسط سایر backendها یا سایر جنبههای پروژه Firebase شما استفاده شوند، حذف نکنید.
کنسول فایربیس : از منوی تنظیمات ، گزینه حذف backend را انتخاب کنید.
رابط خط فرمان (CLI): (نسخه ۱۳.۱۵.۴ یا بالاتر)
دستور زیر را برای حذف App Hosting Backend اجرا کنید. این دستور تمام دامنههای backend شما را غیرفعال کرده و سرویس Cloud Run مرتبط را حذف میکند:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID(اختیاری) در تب Google Cloud Console برای Artifact Registry ، تصویر مربوط به backend خود را در "firebaseapphosting-images" حذف کنید.
در Cloud Secret Manager ، هر گونه راز (secret) که در نام راز آن عبارت "apphosting" وجود دارد را حذف کنید، و به طور ویژه مراقب باشید که این رازها توسط سایر backendها یا سایر جنبههای پروژه Firebase شما استفاده نشوند .