Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mengonfigurasi dan mengelola backend App Hosting

App Hosting telah didesain agar mudah digunakan dan memerlukan sedikit pemeliharaan, dengan setelan default yang dioptimalkan untuk sebagian besar kasus penggunaan. Pada saat yang sama, App Hosting menyediakan alat untuk mengelola dan mengonfigurasi backend sesuai kebutuhan spesifik Anda. Panduan ini menjelaskan alat dan proses tersebut.

Menetapkan dan memperbarui variabel lingkungan

Terkadang, Anda mungkin memerlukan konfigurasi tambahan untuk proses build. App Hosting menawarkan konfigurasi lingkungan untuk menyimpan dan mengambil jenis data ini untuk project Anda melalui Firebase console dan secara alternatif di apphosting.yaml.

Menetapkan variabel lingkungan di Firebase console adalah cara tercepat untuk memulai. Gunakan apphosting.yaml jika Anda perlu menyimpan dan mengakses parameter secret, menetapkan variabel yang hanya tersedia pada waktu build atau runtime, atau berbagi variabel lingkungan di beberapa lingkungan. Dengan konsol dan apphosting.<env>.yaml, Anda dapat menetapkan nilai yang berbeda untuk lingkungan yang berbeda.

Firebase console

Screenshot dialog Firebase console untuk menambahkan variabel lingkungan

`apphosting.yaml`

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

Memperbarui variabel

Anda dapat menambahkan, mengedit, atau menghapus variabel lingkungan di Firebase konsol atau menggunakan apphosting.yaml:

Firebase console:
1. Di Firebase console, buka Hosting & Serverless > App Hosting.
2. Buka View Backend > Settings > Environment.
3. Tambahkan, edit, atau hapus variabel lingkungan.
apphosting.yaml:

Pelajari cara membuat dan mengedit file secara manual.

Perubahan Anda hanya akan berlaku pada peluncuran berikutnya, dan tidak akan memengaruhi peluncuran saat ini. Simpan dan buat peluncuran baru atau simpan variabel Anda dan deploy nanti.

Menetapkan ketersediaan variabel

Variabel lingkungan yang dibuat di Firebase konsol tersedia pada waktu build dan runtime. Ini juga merupakan kondisi default untuk variabel yang ditentukan di apphosting.yaml kecuali jika Anda telah mempersempit cakupan tersebut menggunakan properti availability. Di apphosting.yaml (tetapi tidak di konsol), Anda dapat membatasi variabel lingkungan agar hanya tersedia untuk lingkungan build atau hanya tersedia untuk lingkungan runtime.

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

Untuk aplikasi Next.js, Anda juga dapat menggunakan awalan NEXT_PUBLIC_ dengan cara yang sama seperti yang Anda lakukan di file dotenv untuk membuat variabel dapat diakses di browser.

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

File `dotenv` untuk Next.js

Untuk aplikasi Next.js, dotenv file yang berisi variabel lingkungan berfungsi dengan App Hosting.

Saat membuat atau memperbarui backend, Anda dapat mentransfer variabel lingkungan dari file dotenv ke Firebase console dengan menyalin dan menempelkan seluruh konten file dotenv ke kolom "Key" pertama di formulir "Add new" di Environment Variables Settings.

Semua variabel lingkungan yang disalin dengan cara ini harus diformat dengan rapi ke dalam formulir tanpa perlu memasukkan setiap variabel satu per satu, selama input memiliki format seperti berikut:

KEY1=value1
KEY2=value2
KEY3=value3

Untuk kontrol variabel lingkungan yang kompleks atau terperinci dengan framework apa pun, sebaiknya gunakan apphosting.yaml.

Variabel lingkungan yang diisi secara otomatis

Ada variabel lingkungan yang diisi secara otomatis oleh App Hosting. Variabel lingkungan tersebut meliputi variabel lingkungan yang diisi oleh Google Cloud, serta variabel lingkungan khusus Firebase saat appId ditetapkan di backend selama penyiapan:

FIREBASE_CONFIG: (tersedia di lingkungan build &runtime) Menyediakan info konfigurasi project Firebase berikut:
```
{
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
  "projectId": 'PROJECT_ID'
}
```
Konfigurasi ini diterapkan secara otomatis saat Anda menginisialisasi Firebase Admin SDK tanpa argumen.
FIREBASE_WEBAPP_CONFIG: (hanya tersedia di lingkungan build) Menyediakan info konfigurasi project Firebase berikut:
```
{
  "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 secara otomatis memeriksa variabel lingkungan FIREBASE_WEBAPP_CONFIG ini dalam skrip postinstall selama build, sehingga Anda juga dapat menginisialisasi SDK klien tanpa argumen apa pun.

Lihat Menginisialisasi Firebase Admin SDK dan SDK web secara otomatis untuk mengetahui detail selengkapnya tentang cara menggunakan variabel lingkungan ini untuk menginisialisasi SDK.

Perhatikan bahwa nilai dalam konfigurasi Firebase Anda yang sebenarnya akan sesuai dengan resource tertentu yang telah Anda sediakan di project Anda.

Hierarki variabel

Firebase App Hosting menerapkan variabel Anda dalam urutan prioritas berdasarkan sumbernya. Misalnya, nilai yang ditetapkan di Firebase konsol selalu mengganti, atau lebih diutamakan daripada, nilai yang ditetapkan di apphosting.yaml dan dotenv file.

Berikut urutan prioritas lengkapnya:

Firebase konsol → variabel yang ditetapkan di konsol
apphosting.<env>.yaml → variabel yang ditentukan dalam file yaml khusus lingkungan seperti apphosting.staging.yaml (lihat Men-deploy beberapa lingkungan)
apphosting.yaml → variabel yang ditentukan dalam file apphosting.yaml
Sistem Firebase → variabel yang ditetapkan oleh Firebase yang berisi nilai untuk firebase_config json atau firebase_webapp_config, serta variabel lingkungan yang menetapkan nama host dan port untuk aplikasi SSR (ditetapkan oleh adapter App Hosting di bundle.yaml)

Nama dan batasan yang dicadangkan

Variabel lingkungan yang didefinisikan di dalam Cloud Run container runtime contract terkategorikan sebagai "dilindungi" dan tidak boleh diubah.

Variabel lingkungan yang disediakan oleh lingkungan, selain yang ditetapkan secara otomatis, dapat berubah pada versi runtime mendatang. Sebagai praktik terbaik, sebaiknya Anda tidak bergantung pada atau mengubah variabel lingkungan yang belum ditetapkan secara eksplisit, dan pertimbangkan untuk memberi awalan pada variabel lingkungan apa pun dengan kunci unik untuk menghindari konflik.

Beberapa kunci variabel lingkungan dicadangkan untuk penggunaan internal. Jangan gunakan kunci berikut dalam file konfigurasi Anda:

String kosong ("")
Kunci yang berisi "="
Kunci yang diawali dengan X_FIREBASE_, X_GOOGLE_, atau CLOUD_RUN_
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION
Kunci Duplikat

Membuat dan mengedit `apphosting.yaml`

Untuk konfigurasi lanjutan seperti secret atau setelan runtime seperti batas serentak, CPU, dan memori, Anda harus membuat dan mengedit file apphosting.yaml di direktori root aplikasi Anda. File ini mendukung referensi ke secret yang dikelola dengan Cloud Secret Manager, sehingga aman untuk diperiksa ke dalam kontrol sumber.

Untuk membuat apphosting.yaml, jalankan perintah berikut:

firebase init apphosting

Tindakan ini akan membuat file apphosting.yaml starter dasar dengan konfigurasi contoh (berkomentar). Setelah diedit, file apphosting.yaml yang umum mungkin terlihat seperti berikut, dengan setelan untuk layanan Cloud Run backend, beberapa variabel lingkungan, dan beberapa referensi ke secret yang dikelola oleh 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

Bagian selanjutnya dari panduan ini memberikan informasi dan konteks selengkapnya untuk setelan contoh ini.

Mengonfigurasi setelan layanan Cloud Run

Dengan setelan apphosting.yaml, Anda dapat mengonfigurasi cara layanan Cloud Run Anda disediakan. Setelan yang tersedia untuk layanan Cloud Run disediakan dalam objek runConfig:

cpu – Jumlah CPU yang digunakan untuk setiap instance inferensi (default 0).
memoryMiB – Jumlah memori yang dialokasikan untuk setiap instance inferensi dalam MiB (default 512)
maxInstances – Jumlah maksimum container yang akan dijalankan sekaligus (default 100 dan dikelola berdasarkan kuota)
minInstances – Jumlah container yang akan selalu aktif (default 0).
concurrency – Jumlah maksimum permintaan yang dapat diterima setiap instance inferensi (default 80).

Perhatikan hubungan penting antara cpu dan memoryMiB; memori dapat ditetapkan ke nilai bilangan bulat apa pun antara 128 hingga 32768, tetapi meningkatkan batas memori mungkin memerlukan peningkatan batas CPU:

Di atas 4 GiB memerlukan setidaknya 2 CPU
Di atas 8 GiB memerlukan setidaknya 4 CPU
Di atas 16 GiB memerlukan setidaknya 6 CPU
Di atas 24 GiB memerlukan setidaknya 8 CPU

Demikian pula, nilai cpu memengaruhi setelan serentak. Jika Anda menetapkan nilai kurang dari 1 CPU, Anda harus menetapkan serentak ke 1, dan CPU hanya akan dialokasikan selama pemrosesan permintaan.

Mengganti skrip build dan run

App Hosting menyimpulkan perintah build dan mulai aplikasi Anda berdasarkan framework yang terdeteksi. Jika ingin menggunakan perintah build atau mulai kustom, Anda dapat mengganti App Hosting's default di apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

Penggantian perintah build lebih diutamakan daripada perintah build lainnya dan membuat aplikasi Anda tidak menggunakan adapter framework serta menonaktifkan pengoptimalan khusus framework yang disediakan App Hosting. Penggantian ini paling baik digunakan jika fitur aplikasi Anda tidak didukung dengan baik oleh adapter. Jika Anda ingin mengubah perintah build tetapi tetap menggunakan adapter yang kami sediakan, tetapkan skrip build Anda di package.json sebagai gantinya seperti yang dijelaskan di App Hosting adapter framework.

Gunakan penggantian perintah run jika ada perintah tertentu yang ingin Anda gunakan untuk memulai aplikasi yang berbeda dari App Hosting-perintah yang disimpulkan.

Mengonfigurasi output build

App Hosting mengoptimalkan deployment aplikasi Anda secara default dengan menghapus file output yang tidak digunakan seperti yang ditunjukkan oleh framework. Jika ingin lebih mengoptimalkan ukuran deployment aplikasi atau mengabaikan pengoptimalan default, Anda dapat menggantinya di apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

Parameter include mengambil daftar direktori dan file relatif terhadap direktori root aplikasi yang diperlukan untuk men-deploy aplikasi Anda. Jika ingin memastikan semua file disimpan, tetapkan include ke [.] dan semua file akan di-deploy.

Menyimpan dan mengakses parameter secret

Informasi sensitif seperti kunci API harus disimpan sebagai secret. Anda dapat mereferensikan secret di apphosting.yaml untuk menghindari pemeriksaan informasi sensitif ke dalam kontrol sumber.

Parameter jenis secret mewakili parameter string yang memiliki nilai yang disimpan di Cloud Secret Manager. Alih-alih mendapatkan nilai secara langsung, parameter secret memeriksa keberadaan nilai di Cloud Secret Manager, dan memuat nilai selama peluncuran.

  -   variable: API_KEY
      secret: myApiKeySecret

Secret di Cloud Secret Manager dapat memiliki beberapa versi. Secara default, nilai parameter secret yang tersedia untuk backend aktif Anda disematkan ke versi secret terbaru yang tersedia pada saat backend dibuat. Jika Anda memiliki persyaratan untuk pembuatan versi dan pengelolaan siklus proses parameter, Anda dapat menyematkan ke versi tertentu dengan Cloud Secret Manager. Misalnya, untuk menyematkan ke versi 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Anda dapat membuat secret dengan perintah CLI Firebase firebase apphosting:secrets:set, dan Anda akan diminta untuk menambahkan izin yang diperlukan. Alur ini memberi Anda opsi untuk menambahkan referensi secret secara otomatis ke apphosting.yaml.

Untuk menggunakan rangkaian lengkap fungsi Cloud Secret Manager, Anda dapat menggunakan Cloud Secret Manager console. Jika melakukannya, Anda harus memberikan izin ke backend App Hosting Anda dengan perintah CLI Firebase firebase apphosting:secrets:grantaccess.

Mengonfigurasi akses VPC

Backend App Hosting Anda dapat terhubung ke jaringan Virtual Private Cloud (VPC). Untuk mengetahui informasi selengkapnya dan contohnya, lihat Menghubungkan Firebase App Hosting ke jaringan VPC.

Gunakan pemetaan vpcAccess di file apphosting.yaml untuk mengonfigurasi akses. Gunakan nama/konektor jaringan yang sepenuhnya memenuhi syarat atau ID. Penggunaan ID memungkinkan portabilitas antara lingkungan staging dan produksi dengan konektor/jaringan yang berbeda.

Konfigurasi Traffic Keluar VPC Langsung (`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

Konfigurasi Konektor Serverless (`apphosting.yaml`):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Mengelola backend

Perintah untuk pengelolaan dasar backend App Hosting disediakan di Firebase console dan the Firebase CLI. Bagian ini menjelaskan beberapa tugas pengelolaan yang lebih umum, termasuk membuat dan menghapus backend.

Membuat backend

Backend App Hosting adalah kumpulan resource terkelola yang dibuat App Hosting untuk membangun dan menjalankan aplikasi web Anda.

Firebase console: Buka Hosting & Serverless > App Hosting, lalu klik Create backend (jika ini adalah backend pertama di project Firebase Anda, klik Get started).

Firebase CLI: (v13.15.4 atau yang lebih baru) Untuk membuat backend, jalankan perintah berikut dari root direktori project lokal Anda, dengan memberikan project ID Anda sebagai argumen:

firebase apphosting:backends:create --project PROJECT_ID

Untuk konsol atau CLI, ikuti perintah untuk memilih region, menyiapkan koneksi GitHub, dan mengonfigurasi setelan deployment dasar ini:

Tetapkan direktori root aplikasi Anda (default ke /)

Biasanya, file package.json Anda berada di sini.

Tetapkan cabang aktif

Ini adalah cabang repositori GitHub Anda yang di-deploy ke URL aktif Anda. Sering kali, cabang ini adalah cabang tempat cabang fitur atau cabang pengembangan digabungkan.
Setujui atau tolak peluncuran otomatis

Peluncuran otomatis diaktifkan secara default. Setelah pembuatan backend selesai, Anda dapat memilih agar aplikasi Anda segera di-deploy ke App Hosting
Tetapkan nama ke backend Anda.

Menghapus backend

Untuk menghapus backend sepenuhnya, pertama-tama gunakan Firebase console atau Firebase CLI untuk menghapusnya, lalu hapus aset terkait secara manual, dengan berhati-hati agar tidak menghapus resource yang mungkin digunakan oleh backend lain atau aspek lain dari project Firebase Anda.

Firebase konsol: Dari menu Setting, pilih Delete backend.

Firebase CLI: (v13.15.4 atau yang lebih baru)

Jalankan perintah berikut untuk menghapus backend App Hosting. Tindakan ini akan menonaktifkan semua domain untuk backend Anda dan menghapus layanan terkait Cloud Run:
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
(Opsional) Di tab Google Cloud console untuk Artifact Registry, hapus image untuk backend Anda di "firebaseapphosting-images".
Di Cloud Secret Manager, hapus secret apa pun dengan "apphosting" di nama secret, dengan sangat berhati-hati untuk memastikan secret ini tidak digunakan oleh backend lain atau aspek lain dari project Firebase Anda.