使用 Firebase App Check 防止 Gemini API 滥用

如果您直接从移动应用或 Web 应用调用 API（例如，允许访问生成式 AI 模型的 API），则该 API 很容易被未经授权的客户端滥用。为帮助保护这些 API 免遭滥用，您可以使用 Firebase App Check来验证所有传入的 API 调用 是否来自您的实际应用和未经篡改的设备。

Firebase AI Logic 提供了一个代理网关，让您可以与 Firebase App Check 集成，并保护您的 移动应用和 Web 应用调用的生成式 AI 模型 API。将 App Check 与 Firebase AI Logic SDK 搭配使用支持我们的所有配置：

• 保护“Gemini API”提供程序：Gemini Developer API 和 Vertex AI Gemini API。

• 保护所有受支持的模型，包括 Gemini 模型和 Imagen 模型。

务必尽早强制执行 App Check ，尤其是在您将应用提交到公开提供的源代码控制系统、共享应用或公开提供应用之前。

从 2026 年 7 月初开始，Firebase 会在 Firebase控制台的引导式设置工作流中自动为AI Logic强制执行 App Check。

如果您在 2026 年 7 月初之前在 Firebase 项目中设置了 AI Logic， 则必须自行强制执行 App Check。您甚至可以选择在没有证明提供程序的情况下 强制执行 App Check，以便更轻松地开始使用。

App Check 还支持 重放攻击防范，这意味着 App Check 令牌只能使用一次。

App Check 的工作原理简述

使用 App Check 时，运行您的应用的设备会使用应用或设备证明 提供程序，用于验证以下两项或其中一项：

• 请求来自您的正版应用
• 请求来自真实的、未经篡改的设备

此证明会附加到您的应用使用 Firebase AI Logic SDK 发出的每个请求。启用 App Check 强制执行后，来自没有有效证明的客户端的请求将被拒绝，来自未经您授权的应用或平台的请求也将被拒绝。

设置 App Check 时，请考虑添加 重放攻击防范，这会使 App Check 令牌成为 一次性令牌。此选项除了提供基准保护之外，还提供增强的保护，让您可以为应用和用例设置适当的保护级别。

您可以在 的文档中找到有关 App Check 的详细信息，包括其 配额和限制。

设置 App Check

App Check 文档详细介绍了证明 提供程序，并提供了详细的实现说明。

**注意**： 为了更轻松地开始使用，您可以强制执行 App Check ，但可以稍后设置生产证明提供程序，而只需使用 App Check 调试提供程序进行本地开发。

1. 选择一个证明提供程序，然后按照以下链接中的实现说明操作：

   • Apple 平台： DeviceCheck 或 App Attest
   • Android： Play Integrity
   • Web： reCAPTCHA Enterprise
   • Flutter：支持 上述所有默认提供程序
     如果您使用的是旧版插件，请参阅下文关于 特殊实例化的注意事项。 适用于 Flutter 和 App Check。
   • Unity：支持 上述所有默认提供程序

   请注意，如果这些证明提供程序都不能完全满足您的 需求，您可以 实现自己的提供程序，从而使用第三方证明提供程序或您自己的证明 方法。

2. （必需） 在您将应用提交到公开提供的源代码控制 系统、共享应用或公开提供应用之前， 启用强制执行。App Check

3. （推荐） 通过添加重放攻击防范， 来增强保护，这意味着 App Check 令牌只能使用一次。

4. 对于在强制执行 App Check 时进行的本地开发，请配置 App Check 调试提供程序，以绕过证明，同时仍保持 App Check 的强制执行。请参阅适用于您平台的设置说明： iOS+ | Android | Web | Flutter | Unity。

如果使用旧版插件，则需要进行特殊实例化

点击您的 Gemini API 提供程序，以查看此页面上特定于提供程序的内容 和代码。 Gemini Developer API Vertex AI Gemini API

只有当您的应用使用 Flutter 插件 firebase_ai v3.11.0 或更低版本（BoM v4.12.0 或更低版本）时，才需要进行此特殊实例化。如果您的应用使用的是较新版本的插件，则不需要进行此特殊实例化。

注意 ：Firebase 建议使用 最新版本的 SDK、插件和工具 ，以便您可以使用最新功能、bug 修复等。

如果您启用 App Check 强制执行，那么在使用旧版 插件的 Flutter 应用中，您需要在实例化期间显式传入 App Check，如下所示：

// ...

// During instantiation, enable usage of limited-use tokens
final ai = await FirebaseAI.googleAI(
  // For Flutter plugin v3.11.0 or lower (BoM v4.12.0 or lower), pass in App Check explicitly.
  appCheck: FirebaseAppCheck.instance,
  useLimitedUseAppCheckTokens: true,
);

// ...

通过添加重放攻击防范来增强保护

我们建议使用最新版本的 SDK，但 请确保您至少使用以下版本之一来使用 重放攻击防范： Apple 平台 v12.2.0+ | Android BoM v34.14.0+ (App Check v19.1.0+) | Web v12.14.0+ | Flutter v4.15.0+ (App Check v4.10.0+) | Unity v13.12.0+

默认情况下，App Check 使用 会话令牌，其 存留时间 (TTL) 可配置，介于 30 分钟到 7 天之间。 这些会话令牌由 App Check SDK 缓存，随 应用发出的请求一起发送，并且可以重复使用，直到其 TTL 过期。使用会话令牌被视为基准保护 。

不过，您可以通过强制执行 重放攻击防范来增强保护，使其超出此基准保护，而重放攻击防范使用有限次使用令牌。强制执行重放攻击防范时，会发生以下情况：

• App Check 将阻止使用 会话令牌向 Firebase AI Logic 发出的请求。相反，App Check 仅在请求使用 新生成的有限次使用令牌时，才允许向 Firebase AI Logic发出请求。

• 验证有限次使用令牌后，该令牌将被消耗掉，因此只能使用一次，从而防止重放攻击。

• App Check SDK 会为 每个 请求生成一个新的有限次使用令牌。 请注意，此过程可能会增加一些延迟，有时还会产生费用（具体取决于您的证明提供程序），从而影响您的请求。

设置并强制执行重放攻击防范

点击您的 Gemini API 提供程序，以查看此页面上特定于提供程序的内容 和代码。 Gemini Developer API Vertex AI Gemini API

以下是设置并强制执行重放攻击防范的方法：

1. 如果尚未实现 ，请先实现 App Check，然后 启用 App Check 强制执行 为您的应用。

2. 启用有限次使用令牌的使用。

   在实例化期间，在应用中将 useLimitedUseAppCheckTokens 参数设置为 true：

   Swift

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   let ai = FirebaseAI.firebaseAI(
     backend: .googleAI(),
     useLimitedUseAppCheckTokens: true
   )
   
   // ...
   
   

   Kotlin

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   val ai = Firebase.ai(
     backend = GenerativeBackend.googleAI(),
     useLimitedUseAppCheckTokens = true
   )
   
   // ...
   
   

   Java

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   FirebaseAI ai = FirebaseAI.getInstance(
     /* backend: */ GenerativeBackend.googleAI(),
     /* useLimitedUseAppCheckTokens: */ true
   );
   
   // ...
   
   

   Web

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   const ai = getAI(firebaseApp, {
     backend: new GoogleAIBackend(),
     useLimitedUseAppCheckTokens: true
   });
   
   // ...
   
   

   Dart

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   final ai = await FirebaseAI.googleAI(
     useLimitedUseAppCheckTokens: true,
   );
   
   // ...
   
   

   Unity

   // ...
   
   // During instantiation, enable usage of limited-use tokens
   var ai = FirebaseAI.GetInstance(
     useLimitedUseAppCheckTokens: true
   );
   
   // ...
   

   注意： 请考虑将有限次使用令牌设置为 Firebase Remote Config参数，以便您可以远程控制其设置 ，而不是将其硬编码到应用中。详细了解如何 使用Remote Config。

3. 强制执行重放攻击防范。

   1. 在应用的代码库中，确保您已启用有限次使用令牌的使用（请参阅上一步）。

   2. 在 Firebase 控制台中，依次前往 安全性 > App Check。

   3. 展开 Firebase AI Logic 的指标视图。

   4. 确保 基准保护 处于**已强制执行** 状态，然后点击 继续。

   5. 对于重放攻击防范，请选择未强制执行（仅监控） 或已强制执行 。

      请考虑以下因素，以确定何时强制执行重放攻击防范：

      • 如果大量用户可能使用的是未启用有限次使用令牌的旧版应用，建议您监控请求。如果您立即强制执行重放攻击防范，来自这些用户的请求将被阻止。

      • 您可以专门监控未验证：重复使用的令牌 指标，该指标是指具有已在之前的请求中使用过的令牌的请求数。在 Firebase控制台中监控此指标（依次前往安全性 > App Check > API标签页）。

        如果近期请求中有很大一部分属于此类别，您可以避免干扰用户，并考虑等待更多用户更新到使用有限次使用令牌的应用版本后，再强制执行重放攻击防范。

注意：如果您 仅 启用有限次使用令牌的使用，并且未 强制执行重放攻击防范，请注意以下事项：

• 有限次使用令牌的 TTL 仅为 5 分钟，并且 TTL 不可调整（与会话令牌不同）。如果未强制执行重放攻击防范，有限次使用令牌与会话令牌类似，可以重复使用，直到其 TTL 过期。
• 即使有限次使用令牌的有效期为 5 分钟， SDK 仍会为 每个 请求生成一个新令牌。此外， SDK 不会缓存有限次使用令牌__。
• 如果未强制执行重放攻击防范，App Check将 不会阻止使用 有效会话令牌向Firebase AI Logic发出的请求。

了解 Firebase AI Logic 如何与 App Check 集成

如需使用 Firebase AI Logic SDK，必须在 Firebase 项目中启用 Firebase AI Logic API (firebasevertexai.googleapis.com) 。这是因为 Firebase AI Logic SDK 发出的请求首先会发送到 Firebase AI Logic 服务器，该服务器充当代理网关，Firebase App Check 验证 会在请求获准继续发送到您选择的 “Gemini API”提供程序的后端以及用于访问 Gemini 和 Imagen 模型的 API 之前进行。

（可选） 在没有生产证明提供程序的情况下强制执行 App Check（仅限调试提供程序）

您可以为 AI Logic 强制执行 App Check，而无需向 生产证明提供程序注册应用。通过此设置，您可以使用 App Check 调试提供程序 更轻松地开始使用 AI Logic，同时仍 保护 Gemini API。

注意 此设置仅适用于预生产应用。在向最终用户发布应用之前，您需要按照本页前面的说明设置并使用生产证明提供程序（例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise）。

1. 检查是否已为 AI Logic 强制执行 App Check。

   1. 在 Firebase 控制台中，依次前往 安全性 > App Check > API 标签页。

   2. 找到 Firebase AI Logic 对应的行。如果显示 Unenforced，请继续执行这些说明的其余部分。

2. 使用 App Check REST API 为 Firebase AI Logic强制执行 App Check。

   提示： 您可以使用嵌入式文档的API Explorer更轻松地直接从 API 的参考文档页面发出此请求。在任何方法的文档页面的右侧边栏中找到 Explorer（如果未显示 Explorer，请点击试用！ ）。

   向 projects.services.patch 端点发出请求。

   • 指定以下请求参数：

     • PROJECT_NUMBER：您的 Firebase 项目编号。
       在 Firebase 控制台的 设置 > 常规 标签页中找到此项目标识符。

     • SERVICE_ID：firebasevertexai.googleapis.com
       此 ID 是 Firebase AI Logic API 的官方服务名称， 无论您访问的是 Vertex AI Gemini API还是Gemini Developer API，此 ID 都是有效的。

     • updateMask：enforcementMode

   • 在请求正文中指定以下内容：

     • "enforcementMode": "ENFORCED"

3. 现在已强制执行 App Check，对于本地开发，您需要 配置 App Check 调试提供程序，以绕过证明，同时 仍保持 App Check 的强制执行。

   如需详细了解如何配置调试提供程序，请参阅适用于 您平台的说明： iOS+ | Android | Web | Flutter | Unity。

注意：您可以使用相同的 projects.services.patch 端点 来取消强制执行 App Check，以用于 Firebase AI Logic。按照上述说明操作，但在请求正文中指定 "enforcementMode": "UNENFORCED"。

如果您选择取消强制执行 App Check，那么在您将应用提交到公开提供的源代码控制系统、共享应用或公开提供应用之前，务必再次强制执行。