配置和管理 App Hosting 后端

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

设置和更新环境变量和 Secret

App Hosting 允许您将环境变量用于非敏感配置值，将 Secret 用于敏感参数（例如 API 密钥、数据库凭据和服务令牌）。

• 标准环境变量：用于非敏感的纯文本配置（例如公共 API 网址、功能标志或构建目标）。所有项目成员都可以看到这些值。
• Secret：用于敏感参数（例如 OAuth 客户端密钥、API 令牌或数据库密码）。Secret 由 Cloud Secret Manager 提供支持。密文值会受到保护，绝不会在 Firebase 控制台中以纯文本形式显示；相反，控制台会提供深层链接，以便直接在 Cloud Secret Manager 中查看和管理密文值。

您可以使用两种互补的方法来定义和管理环境参数：

• Firebase 控制台：在初始后端创建期间或部署后，在后端设置中快速动态添加、修改和附加 Secret 或变量。

• 代码优先 (apphosting.yaml)：在代码库的配置文件中声明环境变量和 Secret 引用，以便进行版本控制的部署，或使用 apphosting.<env>.yaml 为不同环境设置不同的值。

env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
  - variable: API_KEY
    secret: myApiKeySecret

在 Firebase 控制台中管理变量和 Secret

您可以在创建后端时或随时通过后端设置在 Firebase 控制台中配置环境变量和 Secret。保存但未部署的更改会在下次发布时生效，不会影响当前发布。

在创建后端期间设置变量和 Secret

在 Firebase 控制台中创建新的 App Hosting 后端时，您可以在设置向导的配置后端步骤中配置标准环境变量和 Secret：

1. 在 Firebase 控制台中，前往托管和无服务器 > App Hosting，然后点击创建后端。
2. 完成初始向导步骤，选择主要区域和代码库。
3. 在配置后端部分中，找到环境变量和密钥的可收起卡片，您可以在其中添加标准变量并附加密钥。
4. 完成后端创建向导，然后点击完成并部署。

在后端设置中管理变量和 Secret

您可以通过后端设置信息中心查看、添加、修改或删除活跃后端的环境变量和密钥：

1. 在 Firebase 控制台中，选择您的 App Hosting 后端，然后依次打开设置 > 环境。
2. 在环境变量表中查看现有配置：
   • 标准变量：值在可复制的代码块中显示为纯文本。
   • Secret：显示为可点击的链接，其中包含 Secret 名称（点击后会在 Google Cloud 控制台中打开 Cloud Secret Manager）及其目标版本（例如 latest 或特定版本号，如 2）。
3. 如需添加变量或 Secret，请执行以下操作：
   1. 点击新增。
   2. 在第 1 步：选择类型中，选择标准环境变量（适用于所有项目成员可见的非敏感数据）或Secret（适用于 API 密钥和访问受限的敏感凭据），然后点击下一步。
   3. 在第 2 步：配置设置中，输入键名称和纯文本值（对于标准变量），或选择Secret ID 和版本（对于密钥）。
   4. 使用以下任一方式保存更改：
      • 保存并部署：立即更新后端配置，并触发新的构建和发布。
      • 仅保存（从保存并部署旁边的下拉箭头中选择）：保存配置更改，而不立即触发发布。更新后的设置会在您下次部署时生效。
4. 如需修改或删除现有条目，请点击行末尾的更多操作 (...) 菜单：
   • 选择修改以修改键、值、密钥映射或版本，然后点击保存并部署或仅保存。
   • 选择删除，然后在对话框中确认移除。

从 dotenv 文件中转移变量

对于 Next.js 应用，包含环境变量的 dotenv 文件可与 App Hosting 搭配使用。

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

只要输入内容使用标准 KEY=value 格式，以这种方式复制的所有环境变量都会自动设置格式并填入表单，而无需单独输入每个变量：

KEY1=value1
KEY2=value2
KEY3=value3

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

在 apphosting.yaml 中管理变量和 Secret

对于代码优先工作流，请在项目代码库的 apphosting.yaml 配置文件中的 env: 键下声明标准环境变量和 Secret 引用（请参阅创建和修改 apphosting.yaml）。

env:
  # Standard environment variables
  - variable: PUBLIC_API_URL
    value: https://api.example.com
    availability:
      - BUILD
      - RUNTIME
  - variable: FEATURE_FLAG_NEW_UI
    value: "true"

  # Secret references backed by Cloud Secret Manager
  - variable: DATABASE_URL
    secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
  - variable: GEMINI_API_KEY
    secret: myGeminiApiKeySecret@1

env: 中的每个条目都支持以下字段：

• variable：向应用进程公开的环境变量名称。
• value：纯文本字符串值（适用于标准环境 变量）。
• secret：Cloud Secret Manager 密钥引用（对于密钥）。您可以使用 Secret 短名称（例如 myGeminiApiKeySecret 或固定的 myGeminiApiKeySecret@1）或完整资源路径 (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION)。如需了解详情，请参阅存储和访问 Secret 参数。
• availability：控制变量或 Secret 在 BUILD 阶段、RUNTIME 阶段或这两个阶段是否可访问。

设置变量可用性

在 Firebase 控制台中配置的环境变量和 Secret 在构建时和运行时均可用。这也是 apphosting.yaml 中定义的条目的默认行为，除非您使用 availability 属性缩小范围。在 apphosting.yaml（但不在控制台中）中，您可以将变量或 Secret 限制为仅限构建环境 (BUILD) 或仅限运行时环境 (RUNTIME)。

在应用代码中访问变量和 Secret

无论是在 Firebase 控制台还是 apphosting.yaml 中配置，环境变量和 Secret 都会作为标准环境变量（例如 Node.js 中的 process.env）向应用运行时公开。

// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;

// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;

export async function fetchData() {
  const response = await fetch(`${apiUrl}/data`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  return response.json();
}

• 服务器端访问：所有环境变量和 Secret 都可以在服务器端执行上下文（例如 Next.js 服务器组件、API 路由或 Node.js 后端处理程序）中安全访问。

• 客户端公开：如需在 Next.js 等框架中向浏览器公开标准环境变量，请确保变量键遵循框架惯例（例如，以 NEXT_PUBLIC_ 为前缀）。

  env:
    - variable: NEXT_PUBLIC_STORAGE_BUCKET
      value: mybucket.firebasestorage.app
      availability:
        - BUILD
        - RUNTIME
  

变量层次结构

Firebase App Hosting 会根据环境变量和 Secret 的来源，按优先级顺序应用它们。在 Firebase 控制台中设置的配置始终会覆盖 apphosting.yaml 和 dotenv 文件中声明的参数。如果 apphosting.yaml 和 Firebase 控制台中存在同名的环境变量或密钥，则在构建和运行时执行期间，控制台值优先。

以下是完整的优先级顺序：

1. Firebase 控制台 → 在控制台中设置的变量和 Secret
2. apphosting.<env>.yaml - 在特定于环境的 YAML 文件（例如 apphosting.staging.yaml）中指定的变量和 Secret（请参阅部署多个环境）
3. apphosting.yaml → apphosting.yaml 文件中指定的变量和 Secret
4. Firebase 系统 → 由 Firebase 设置的变量，其中包含 FIREBASE_CONFIG 或 FIREBASE_WEBAPP_CONFIG 的值，以及为 SSR 应用设置主机名和端口的环境变量（由 bundle.yaml 中的 App Hosting 适配器设置）

自动填充的环境变量

有一些环境变量会自动由 App Hosting 填充。其中包括 Google Cloud 填充的环境变量，以及在设置期间在后端设置 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"
  }</span>
  

  Firebase JS SDK 会在构建期间自动在 postinstall 脚本中检查此 FIREBASE_WEBAPP_CONFIG 环境变量，这样您也可以在不带任何参数的情况下初始化客户端 SDK。

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

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

变量层次结构

Firebase App Hosting 会根据变量的来源按优先级顺序应用变量。例如，在 Firebase 控制台中设置的值始终会替换或优先于在 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 应用的主机名和端口的环境变量（由 App Hosting 适配器在 bundle.yaml 中设置）

预留名称和限制

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 服务的预配方式。Cloud Run 服务的可用设置在 runConfig 对象中提供：

• cpu - 每个服务实例使用的 CPU 数量（默认值为 1）。
• memoryMiB - 为每个服务实例分配的内存量（以 MiB 为单位，默认值为 512）。
• maxInstances - 一次可运行的容器数量上限（默认值为 100，由配额管理）。
• minInstances - 始终保持活跃状态的容器数量（默认值为 0）。
• concurrency - 每个服务实例可以接收的请求数上限（默认值为 80）。
• cpuAlwaysAllocated - 即使没有正在处理的请求，是否始终分配 CPU（默认值为 false）。

请注意，cpu、memoryMiB 和 concurrency 具有相互依赖的限制（例如，较高的内存配置需要较高的 CPU 限制下限，而小数 CPU 需要 1 的并发）。如需了解有效范围和所需组合，请参阅有关 CPU 限制和内存限制的 Cloud Run 文档。

替换构建和运行脚本

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 推断的命令不同，请使用运行命令替换。

配置 build 输出

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

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

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

存储和访问 Secret 参数

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

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

env:
  - variable: API_KEY
    secret: myApiKeySecret

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

env:
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

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

授予对 Cloud Secret Manager 的访问权限

为了让 App Hosting 在构建和运行时发布期间提取 Secret 值，App Hosting 后端服务账号必须有权访问 Cloud Secret Manager。

如果您使用 Cloud Secret Manager 控制台或 gcloud CLI（而非 firebase apphosting:secrets:set）创建 Secret，请使用 Firebase CLI 授予对后端的访问权限：

firebase apphosting:secrets:grantaccess SECRET_NAME

或者，您也可以使用 gcloud CLI 向 App Hosting 服务代理 (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) 或后端的运行时服务账号授予 Secret Manager Secret Accessor 角色 (roles/secretmanager.secretAccessor)：

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

控制台访问权限和基于角色的权限

Firebase 控制台会根据用户 IAM 权限动态限制环境和 Secret Manager 管理功能：

• Viewer 角色：具有只读项目权限的用户可以查看现有配置设置，但无法进行更改。
  • 在创建后端期间，创建后端按钮处于停用状态。
  • 在后端设置 > 环境中，新增按钮处于停用状态，更多操作 (...) 行菜单处于隐藏状态。
• 缺少 Secret Manager 权限：没有与 Cloud Secret Manager 交互的 IAM 权限的用户会在控制台中看到警告消息（请向项目所有者请求添加 Secret 的权限）：
  • 在后端创建期间，Secret 卡片处于停用状态。
  • 在后端设置 > 环境中，点击添加新项时，密钥选项处于停用状态，并且更多操作 (...) 行菜单中的某些选项在现有密钥条目中处于隐藏状态。

配置 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 控制台和 Firebase CLI 中提供了用于对 App Hosting 后端进行基本管理的命令。本部分介绍了一些较为常见的管理任务，包括创建和删除后端。

创建一个后端

App Hosting 后端是 App Hosting 为构建和运行 Web 应用而创建的代管式资源的集合。

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

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

• 设置实时分支

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

• 接受或拒绝自动发布

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

• 为后端分配一个名称。

• 选择运行时环境。默认情况下，系统会为您预先选择最新推荐的 Node.js 版本。

  • 配置基础映像自动更新 (ABIU)。ABIU 默认处于启用状态，会自动将安全补丁应用于底层环境。您可以通过为运行时选择“未指定”来停用 ABIU。

删除一个后端

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

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

Firebase CLI（v13.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 中，删除名称中包含“apphosting”的所有 Secret，请特别注意确保这些 Secret 未被其他后端或 Firebase 项目的其他方面使用。