設定及管理 App Hosting 後端

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

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

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

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

同樣地，cpu 的值會影響並行設定。如果設定的值小於 1 個 CPU，您必須將並行數設為 1，且系統只會在要求處理期間分配 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

有效的變數鍵由 A-Z 字元或底線組成。部分環境變數鍵保留供內部使用。請勿在設定檔中使用下列任何鍵：

  • 以 X_FIREBASE_ 開頭的任何變數
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

覆寫建構和執行指令碼

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

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

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

設定虛擬私有雲存取權

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

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

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

管理後端

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

建立後端

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

Firebase 控制台：在「Build」(建構) 選單中，選取「App Hosting」(應用程式託管)，然後選取「Get started」(開始使用)。

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

  • 設定即時分支

    這是 GitHub 存放區的分支版本，會部署至您的即時網址。通常是合併功能分支或開發分支的分支。

  • 接受或拒絕自動推出

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

  • 為後端指派名稱。

刪除後端

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

Firebase 主控台：從「設定」選單中選取「刪除後端」。

CLI： (13.15.4 以上版本)

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

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

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

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