設定及管理 App Hosting 後端

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

設定及更新環境變數

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

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

Firebase 控制台

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

`apphosting.yaml`

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

更新變數

您可以在後端的「設定」分頁中，透過 Firebase 控制台新增及編輯環境變數。依序前往「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

Next.js 的 dotenv 檔案

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

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

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

KEY1=value1
KEY2=value2
KEY3=value3

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

變數階層

Firebase App Hosting 會根據變數來源的優先順序套用變數。舉例來說，在控制台中設定的值一律會覆寫 apphosting.yaml 和 dotenv 檔案中設定的值，或優先於這些值。

以下是完整的優先順序：

Firebase 控制台 → 在控制台中設定的變數
apphosting.<env>.yaml → 環境專屬 YAML 檔案 (例如 apphosting.staging.yaml) 中指定的變數 (請參閱「部署多個環境」)
apphosting.yaml → apphosting.yaml 檔案中指定的變數
Firebase 系統 → Firebase 設定的變數，包含 firebase_config json 或 firebase_webapp_config 的值，以及設定 SSR 應用程式主機名稱和連接埠的環境變數 (由應用程式託管介面卡在 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 服務的佈建方式。runConfig 物件會提供 Cloud Run 服務的可用設定：

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。

覆寫建構和執行指令碼

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 可在不同連接器/網路的測試和正式環境之間移植。

直接虛擬私有雲輸出設定 (`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 CLI 和 Firebase 控制台提供基本 App Hosting 後端管理指令。本節將說明一些常見的管理工作，包括建立及刪除後端。

建立後端

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

Firebase 控制台：從「Build」(建構) 選單中選取 App Hosting，然後選取「Create backend」(建立後端) (如果這是 Firebase 專案中的第一個後端，請選取「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 以上版本)

執行下列指令，刪除 App Hosting Backend。這會停用後端的所有網域，並刪除相關聯的 Cloud Run 服務：
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
(選用) 在 Artifact Registry 的 Google Cloud 控制台分頁中，刪除「firebaseapphosting-images」中的後端映像檔。
在 Cloud Secret Manager 中，刪除密鑰名稱含有「apphosting」的所有密鑰，並特別留意這些密鑰是否用於其他後端或 Firebase 專案的其他方面。