配置和管理 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 管理的 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。

配置环境

有时，您需要对构建流程进行额外配置，例如第三方 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 应用，您还可以像在 dotenv 文件中一样使用 NEXT_PUBLIC_ 前缀，使变量可在浏览器中访问。

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 会根据检测到的框架推断应用的 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 类型的参数表示具有存储在 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

您可以使用 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 后端可以连接到 Virtual Private Cloud (VPC) 网络。如需了解详情和示例，请参阅将 Firebase App Hosting 连接到 VPC 网络。

使用 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 为构建和运行 Web 应用而创建的一组受管理的资源。

Firebase 控制台：在构建菜单中，选择 App Hosting，然后点击开始。

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 项目的其他后端或其他方面使用。