App Hosting برای سهولت استفاده و نیاز به نگهداری کم طراحی شده است و تنظیمات پیش‌فرض آن برای اکثر موارد استفاده بهینه شده است. در عین حال، App Hosting ابزارهایی را برای مدیریت و پیکربندی backendها برای نیازهای خاص شما فراهم می‌کند. این راهنما این ابزارها و فرآیندها را شرح می‌دهد.
ایجاد و ویرایش 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 فقط در طول پردازش درخواست اختصاص داده می‌شود.
پیکربندی محیط
گاهی اوقات برای فرآیند ساخت خود به پیکربندی اضافی، مانند کلیدهای API شخص ثالث یا تنظیمات قابل تنظیم، نیاز خواهید داشت. App Hosting پیکربندی محیط را در apphosting.yaml برای ذخیره و بازیابی این نوع داده‌ها برای پروژه شما ارائه می‌دهد.
env:
- variable: STORAGE_BUCKET
value: mybucket.firebasestorage.app
برای برنامه‌های Next.js، فایل‌های dotenv حاوی متغیرهای محیطی با App Hosting نیز کار خواهند کرد. توصیه می‌کنیم برای کنترل دقیق متغیرهای محیطی با هر فریم‌ورکی apphosting.yaml استفاده کنید.
در apphosting.yaml ، می‌توانید با استفاده از ویژگی availability مشخص کنید که کدام فرآیندها به متغیر محیطی شما دسترسی دارند. می‌توانید یک متغیر محیطی را محدود کنید که فقط در محیط ساخت یا فقط در محیط زمان اجرا در دسترس باشد. به طور پیش‌فرض، برای هر دو در دسترس است.
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
کلیدهای معتبر متغیرها از کاراکترهای AZ یا زیرخط تشکیل شده‌اند. برخی از کلیدهای متغیرهای محیطی برای استفاده داخلی رزرو شده‌اند. از هیچ یک از این کلیدها در فایل‌های پیکربندی خود استفاده نکنید:
- هر متغیری که با
X_FIREBASE_شروع شود -
PORT -
K_SERVICE -
K_REVISION -
K_CONFIGURATION
اسکریپت‌های ساخت و اجرا را نادیده بگیرید
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 برای ساخت و اجرای اپلیکیشن وب شما ایجاد می‌کند.
کنسول فایربیس : از منوی ساخت ، گزینه میزبانی برنامه و سپس شروع به کار را انتخاب کنید.
رابط خط فرمان (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 شما استفاده نشوند .