配置和管理 App Hosting 后端

App Hosting 旨在提供易用性和低维护性，其默认设置针对大多数使用情形进行了优化。同时， App Hosting 还提供了一些工具，供您根据具体需求管理和配置后端。本指南介绍了这些工具和流程。

设置和更新环境变量

有时，您可能需要为构建流程进行其他配置。 App Hosting 提供环境配置，用于通过 Firebase 控制台或在 apphosting.yaml 中为您的项目存储和检索此类数据。

在 Firebase 控制台中设置环境变量是快速入门的最简单方法。如果您需要apphosting.yaml，请使用存储和访问 Secret、设置仅在构建或运行时可用的变量，或者在多个环境之间共享环境变量。借助控制台和 apphosting.<env>.yaml，您可以为不同的环境设置不同的值。

Firebase 控制台

用于添加环境变量的 Firebase 控制台对话框的屏幕截图

`apphosting.yaml`

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

更新变量

您可以在 Firebase 控制台中或使用 apphosting.yaml 添加、修改或删除环境变量：

Firebase 控制台：
1. 在 Firebase 控制台中，依次前往 Hosting 和无服务器 > 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 搭配使用。

创建或更新后端时，您可以将环境变量从 Firebase文件转移到 Firebase 控制台，方法是将 dotenv 文件的全部内容复制并粘贴到 **环境变量设置** 中“添加新”表单的第一个“键”字段中。dotenv

以这种方式复制的所有环境变量都应整齐地格式化到表单中，无需单独输入每个变量，前提是输入内容的格式如下所示：

KEY1=value1
KEY2=value2
KEY3=value3

对于使用任何框架进行复杂或精细的环境变量控制，我们建议使用 apphosting.yaml。

自动填充的环境变量

有一些环境变量由 App Hosting 自动填充。其中包括 Google Cloud 填充的环境变量Google Cloud，以及在设置期间在后端设置 `appId`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 会在构建期间的 postinstall script 中自动检查此 FIREBASE_WEBAPP_CONFIG 环境变量，从而让您也可以在不带任何参数的情况下初始化客户端 SDK。

如需详细了解如何使用这些环境变量初始化 SDK，请参阅自动初始化 Firebase Admin SDK 和 Web SDK 。

请注意，实际 Firebase 配置中的值将与您在项目中预配的特定资源相对应。

变量层次结构

Firebase App Hosting 会根据变量的来源按优先级顺序应用变量。例如，在 Firebase 控制台中设置的值始终会替换或优先于在 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 中的 App Hosting 适配器设置）

预留名称和限制

容器运行时合同中定义的环境变量会预留给系统，不得设置。Cloud Run

环境提供的环境变量（自动设置的环境变量除外）可能会在未来运行时版本中发生变化。我们建议的最佳实践是，不要依赖或修改任何未明确设置的环境变量，并考虑为所有环境变量添加一个唯一键作为前缀，以避免冲突。

某些环境变量键已预留给内部使用。请勿在配置文件中使用以下任何键：

空字符串 ("")
包含“=”的键
以 X_FIREBASE_、X_GOOGLE_ 或 CLOUD_RUN_ 开头的键
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION
重复键

创建和修改 `apphosting.yaml`

对于高级配置（例如 Secret）或运行时设置（例如并发、CPU 和内存限制），您需要在应用的根目录中创建和修改 apphosting.yaml 文件。此文件支持引用使用 Cloud Secret Manager 管理的 Secret，因此可以安全地签入源代码控制系统。

如需创建 apphosting.yaml，请运行以下命令：

firebase init apphosting

此命令会创建一个基本的启动器 apphosting.yaml 文件，其中包含示例（注释）配置。修改后，典型的 apphosting.yaml 文件可能如下所示，其中包含后端 Cloud Run 服务的设置、一些环境变量以及对 Cloud Secret Manager 管理的一些 Secret 的引用：

# 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 service 的可用设置：

cpu：每个服务实例使用的 CPU 数量（默认值为 0）。
memoryMiB ：为每个服务实例分配的内存量（以 MiB 为单位，默认值为 512）
maxInstances ：一次运行的容器数量上限（默认值为 100，由配额管理）
minInstances：始终保持活跃的容器数量（默认值为 0）。
concurrency ：每个服务实例可以接收的请求数量上限（默认值为 80）。

请注意 cpu 和 memoryMiB 之间的重要关系；内存可以设置为 128 到 32768 之间的任何整数值，但增加内存限制可能需要增加 CPU 限制：

超过 4GiB 至少需要 2 个 CPU
超过 8GiB 至少需要 4 个 CPU
超过 16GiB 至少需要 6 个 CPU
超过 24GiB 至少需要 8 个 CPU

同样，cpu 的值会影响并发设置。如果您设置的值小于 1 个 CPU，则必须将并发设置为 1，并且 CPU 仅在请求处理期间分配。

替换构建和运行脚本

App Hosting 会根据检测到的框架推断应用的构建和启动命令。如果您想使用自定义构建或启动命令，可以替换 App Hosting的默认值，在apphosting.yaml中。

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

构建命令替换优先于任何其他构建命令，并且会使您的应用退出框架适配器，并停用任何框架特定优化，这些优化由 App Hosting 提供。当适配器无法很好地支持应用功能时，最好使用此功能。如果您想更改构建命令但仍使用我们提供的适配器，请改为在 package.json 中设置构建脚本，如 App Hosting 框架适配器中所述。

当您想使用与 App Hosting-推断的命令不同的特定命令来启动应用时，请使用运行命令替换。

配置构建输出

App Hosting 默认情况下，App Hosting 会通过删除框架指示的未使用输出文件来优化应用部署。如果您想进一步优化应用部署大小或忽略默认优化，可以在 apphosting.yaml 中替换此设置。

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

include 参数接受相对于应用根目录的目录和文件列表，这些目录和文件是部署应用所必需的。如果您想确保保留所有文件，请将 include 设置为 [.]，这样所有文件都将部署。

存储和访问 Secret 参数

API 密钥等敏感信息应存储为 Secret。您可以在 apphosting.yaml 中引用 Secret，以避免将敏感信息签入源代码控制系统。

secret 类型的参数表示具有存储在 Cloud Secret Manager 中的值的字符串参数。Secret 参数不会直接派生值，而是检查 Cloud Secret Manager 中是否存在所需值，并在发布期间加载这些值。

  -   variable: API_KEY
      secret: myApiKeySecret

Cloud Secret Manager 中的 Secret 可以有多个版本。默认情况下，在构建后端时，可供实际后端使用的 Secret 参数的值会固定为 Secret 的最新可用版本。如果您对参数的版本控制和生命周期管理有要求，可以使用 Cloud Secret Manager 固定到特定版本。例如，如需固定到版本 5：

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

您可以使用 Firebase CLI 命令 firebase apphosting:secrets:set 创建 Secret，系统会提示您添加必要的权限。此流程可让您选择自动将 Secret 引用添加到 apphosting.yaml。

如需使用 Cloud Secret Manager 的全套功能，您可以改用 Cloud Secret Manager 控制台。如果您这样做，则需要向您的 App Hosting 后端授予权限，并使用 Firebase CLI 命令 firebase apphosting:secrets:grantaccess。

配置 VPC 访问权限

您的 App Hosting 后端可以连接到虚拟私有云 (VPC) 网络。如需了解详情和示例，请参阅将 Firebase App Hosting 连接到 VPC 网络。

使用 apphosting.yaml 文件中的 vpcAccess 映射来配置访问权限。使用完全限定的网络/连接器名称或 ID。使用 ID 可以在具有不同连接器/网络的预演环境和生产环境之间实现可移植性。

直接 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 控制台和 Firebase CLI 中提供。本部分介绍了一些更常见的管理任务，包括创建和删除后端。

创建一个后端

App Hosting 后端是 App Hosting 创建的一组受管理资源，用于构建和运行 Web 应用。

Firebase 控制台：依次前往 Hosting 和无服务器 > App Hosting，然后点击创建后端 （如果这是 Firebase 项目中的第一个后端，请点击开始使用）。

Firebase CLI: （v13.15.4 或更高版本）如需创建后端，请在本地项目目录的根目录中运行以下命令，并提供项目 ID 作为实参：

firebase apphosting:backends:create --project PROJECT_ID

对于控制台或 CLI，请按照提示选择区域、设置 GitHub 连接并配置以下基本部署设置：

设置应用的根目录 （默认为/）

这通常是 package.json 文件所在的位置。

设置实际分支

这是 GitHub 代码库的分支，它会部署到您的实际网址。通常，它是功能分支或开发分支合并到的分支。
接受或拒绝自动发布

自动发布功能默认处于启用状态。后端创建完成后，您可以选择立即将应用部署到 App Hosting。
为后端分配名称。

删除一个后端

如需完全移除后端，请先使用 Firebase 控制台或 Firebase CLI 将其删除，然后手动移除相关资产，并特别注意不要删除可能被 Firebase 项目的其他后端或其他方面使用的任何资源。

Firebase 控制台：从设置菜单中，选择 删除后端。

Firebase CLI：（v13.15.4 或更高版本）

运行以下命令以删除 App Hosting 后端。这会停用后端的所有网域，并删除关联的 Cloud Run 服务：
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
```
（可选）在 Google Cloud控制台标签页中，对于Artifact Registry，删除“firebaseapphosting-images”中后端的映像。
在 Cloud Secret Manager 中，删除 Secret 名称中包含“apphosting”的所有 Secret，并特别注意确保这些 Secret 不会被其他后端或 Firebase 项目的其他方面使用。