設定及管理 App Hosting 後端

App Hosting 的設計宗旨是方便使用及維護，預設設定也經過最佳化，適用於大多數用途。同時，App Hosting 也提供工具，讓您管理及設定後端，滿足特定需求。本指南將說明這些工具和程序。

設定及更新環境變數

有時您可能需要為建構程序進行額外設定。App Hosting 提供環境設定，可透過 Firebase 控制台，以及 apphosting.yaml 儲存及擷取專案的這類資料。

在 Firebase 控制台中設定環境變數，是開始使用的最快方式。如需儲存及存取私密參數、設定僅在建構或執行階段可用的變數，或在多個環境之間共用環境變數，請使用 apphosting.yaml。透過控制台和 apphosting.<env>.yaml，您可以為不同環境設定不同值。

Firebase控制台

Firebase 控制台對話方塊的螢幕截圖，顯示新增環境變數的畫面

apphosting.yaml 

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

更新變數

您可以在 Firebase 控制台中新增、編輯或刪除環境變數，也可以使用 apphosting.yaml 執行這項操作：

  • Firebase 控制台：

    1. 在 Firebase 控制台中，依序前往「Hosting & Serverless」(主機代管和無伺服器) >「App Hosting」(應用程式主機代管)。

    2. 依序前往「查看後端」 >「設定」 >「環境」。

    3. 新增、編輯或刪除環境變數。

  • apphosting.yaml：

    瞭解如何手動建立及編輯檔案。

變更只會在下次推出時生效，不會影響目前的版本。您可以儲存並建立新的推出作業，也可以儲存變數，稍後再部署。

設定變數可用性

在 Firebase 控制台中建立的環境變數，在建構時間和執行階段都適用。這也是在 apphosting.yaml 中定義變數的預設條件，除非您使用 availability 屬性縮小範圍。在 apphosting.yaml 中 (而非在控制台中)，您可以限制環境變數只能用於建構環境，或只能用於執行階段環境。

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

如果是 Next.js 應用程式，您也可以在 dotenv 檔案中使用 NEXT_PUBLIC_ 前置字元，讓變數可在瀏覽器中存取。

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

Next.js 的 dotenv 檔案

對於 Next.js 應用程式，含有環境變數的 dotenv 檔案可搭配 App Hosting 使用。

建立或更新後端時，您可以將 dotenv 檔案中的環境變數複製並貼到 Firebase 控制台中，方法是將 dotenv 檔案的完整內容複製到「環境變數設定」的「新增」表單中第一個「金鑰」欄位。

以這種方式複製的所有環境變數都會整齊地格式化為表單，您不必個別輸入每個變數，前提是輸入內容的格式如下：

KEY1=value1
KEY2=value2
KEY3=value3

如要使用任何架構進行複雜或精細的環境變數控制，建議使用 apphosting.yaml。

自動填入的環境變數

App Hosting 會自動填入環境變數。包括由 Google Cloud 填入的變數，以及在設定期間於後端設定 appId 時的 Firebase 專屬環境變數：

  • 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。

如要進一步瞭解如何使用這些環境變數初始化 SDK，請參閱「自動初始化 Firebase Admin 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 的值，以及設定 SSR 應用程式主機名稱和通訊埠的環境變數 (由 bundle.yaml 中的 App Hosting 介面卡設定)

保留名稱和限制

系統會預留Cloud Run 容器執行階段合約中定義的環境變數，您無法設定這些變數。

在日後的執行階段版本中，環境提供的環境變數可能會變更 (自動設定的變數除外)。建議的最佳做法是，不要依賴或修改您未明確設定的任何環境變數，並對所有環境變數加上不重複的鍵做為前置字元，避免發生衝突。

部分環境變數鍵保留供內部使用，請勿在設定檔中使用下列任何鍵：

  • 空字串 ("")
  • 包含「=」的金鑰
  • 開頭為 X_FIREBASE_、X_GOOGLE_ 或 CLOUD_RUN_ 的鍵
  • 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 服務的佈建方式。runConfig 物件提供 Cloud Run 服務的可用設定：

  • cpu：每個服務執行個體使用的 CPU 數量 (預設為 0)。
  • memoryMiB：以 MiB 為單位，為每個服務執行個體分配的記憶體量 (預設為 512)
  • maxInstances - 一次執行的容器數量上限 (預設為 100，由配額管理)
  • minInstances - 隨時保持運作的容器數量 (預設為 0)。
  • concurrency - 每個服務執行個體可接收的要求數量上限 (預設為 80)。

請注意 cpu 和 memoryMiB 之間的重要關係；記憶體可設為 128 到 32768 之間的任何整數值，但提高記憶體上限可能需要提高 CPU 上限：

  • 超過 4GiB 至少需要 2 個 CPU
  • 超過 8 GiB 至少需要 4 個 CPU
  • 超過 16 GiB 至少需要 6 個 CPU
  • 超過 24 GiB 至少需要 8 個 CPU

同樣地，cpu 的值會影響並行設定。如果設定的值小於 1 個 CPU，您必須將並行設為 1，且 CPU 只會在要求處理期間分配。

覆寫建構和執行指令碼

App Hosting 會根據偵測到的架構，推斷應用程式的建構和啟動指令。如要使用自訂建構或啟動指令，可以在 apphosting.yaml 中覆寫 App Hosting 的預設值。

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 設為 [.]，系統就會部署所有檔案。

儲存及存取密鑰參數

API 金鑰等機密資訊應儲存為密鑰。您可以在 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

您可以使用 Firebase CLI 指令 firebase apphosting:secrets:set 建立密鑰，系統會提示您新增必要權限。這個流程可讓您選擇自動將密鑰參照新增至 apphosting.yaml。

如要使用 Cloud Secret Manager 的完整功能套件，請改用 Cloud Secret Manager 控制台。如果這麼做，您需要使用 Firebase CLI 指令 firebase apphosting:secrets:grantaccess，將權限授予 App Hosting 後端。

設定虛擬私有雲存取權

App Hosting 後端可以連線至虛擬私有雲 (VPC) 網路。如需更多資訊和範例，請參閱「將 Firebase App Hosting 連線至虛擬私有雲網路」。

在 apphosting.yaml 檔案中使用 vpcAccess 對應設定存取權。請使用完整網路/連接器名稱或 ID。使用 ID 可在測試和正式環境之間轉移，且這兩個環境的連接器/網路不同。

直連虛擬私有雲輸出設定 (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

管理後端

Firebase 控制台和 Firebase CLI 提供基本後端管理指令。本節說明一些常見的管理工作，包括建立及刪除後端。App Hosting

建立後端

App Hosting 後端是 App Hosting 建立的一系列受管理資源，用於建構及執行您的網頁應用程式。

Firebase 控制台：依序前往「Hosting & Serverless」 >「App Hosting」，然後點選「Create backend」 (如果這是專案中的第一個後端，請點選「Get started」Firebase)。

Firebase CLI： (13.15.4 以上版本) 如要建立後端，請從本機專案目錄的根目錄執行下列指令，並以引數形式提供專案 ID：

firebase apphosting:backends:create --project PROJECT_ID

無論是使用控制台或 CLI，請按照提示選擇區域、設定 GitHub 連線，並設定下列基本部署設定：

  • 設定應用程式的根目錄 (預設為 /)

    這通常是 package.json 檔案的所在位置。

  • 設定即時分支

    這是你 GitHub 存放區的分支版本，會部署到你的線上網址。通常是合併功能分支或開發分支的分支。

  • 接受或拒絕自動推出

    自動推出功能預設為啟用。後端建立完成後，您可以選擇立即將應用程式部署至 App Hosting。

  • 為後端指派名稱。

  • 選取執行階段環境。系統預設會為您預先選取最新建議的 Node.js 版本。

    • 設定自動更新基本映像檔 (ABIU)。 ABIU 預設為啟用，並會自動將安全性修補程式套用至基礎環境。如要停用 ABIU，請為執行階段選取「未指定」。

刪除後端

如要完全移除後端，請先使用 Firebase 控制台或 Firebase CLI 刪除後端，然後手動移除相關資產，並特別注意不要刪除其他後端或 Firebase 專案其他方面可能使用的任何資源。

Firebase 控制台：在「設定」選單中，選取「刪除後端」。

Firebase CLI： (13.15.4 以上版本)

  1. 執行下列指令，刪除 App Hosting 後端。這會停用後端的所有網域，並刪除相關聯的 Cloud Run 服務：

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (選用) 在 Artifact Registry 的 Google Cloud 控制台分頁中，刪除「firebaseapphosting-images」中後端的映像檔。

  3. 在 Cloud Secret Manager 中，刪除密鑰名稱含有「apphosting」的所有密鑰，並特別留意這些密鑰是否用於其他後端或 Firebase 專案的其他方面。