配置和管理 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 控制台添加和修改环境变量。依次前往查看后端 >> 设置 >> 环境，然后添加、修改或删除环境变量。

如需在 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：（可在 build 和运行时环境中获取）提供以下 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 脚本自动检查此 FIREBASE_WEBAPP_CONFIG 环境变量，从而让您无需任何实参即可初始化客户端 SDK。

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

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

变量层次结构

Firebase App Hosting 会根据变量的来源按优先级顺序应用变量。例如，在控制台中设置的值始终会替换或优先于在 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 管理的 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 服务的配置方式。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
  • 超过 16GiB 需要至少 6 个 CPU
  • 超过 24GiB 时，至少需要 8 个 CPU

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

替换构建和运行脚本

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

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

构建命令替换会优先于任何其他构建命令，并使您的应用选择不使用框架适配器，同时停用 App Hosting 提供的任何框架特定优化。当适配器无法很好地支持应用功能时，最好使用此属性。如果您想更改 build 命令，但仍想使用我们提供的适配器，请按照App Hosting 框架适配器中的说明，在 package.json 中设置 build 脚本。

如果您想使用特定命令（与 App Hosting 推断出的命令不同）来启动应用，请使用运行命令替换。

配置 build 输出

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

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

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

存储和访问 Secret 参数

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

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

  -   variable: API_KEY
      secret: myApiKeySecret

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

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

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

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

配置 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

管理后端

Firebase CLI和 Firebase 控制台中提供了用于对 App Hosting 后端进行基本管理的命令。本部分介绍了一些更常见的管理任务，包括创建和删除后端。

创建一个后端

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

Firebase 控制台：在构建菜单中，选择 App Hosting，然后选择创建后端（如果这是 Firebase 项目中的第一个后端，请选择开始）。

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 后端。 此命令会停用后端的所有网域，并删除关联的 Cloud Run 服务：

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. （可选）在 Artifact Registry 的 Google Cloud 控制台标签页中，删除“firebaseapphosting-images”中后端对应的映像。

  3. 在 Cloud Secret Manager 中，删除所有在 Secret 名称中包含“apphosting”的 Secret，并特别注意确保这些 Secret 不会被 Firebase 项目的其他后端或其他方面使用。