使用 Firebase App Check 防止 Gemini API 滥用

如果您直接从移动应用或 Web 应用调用 API，则该 API 很容易受到未经授权的客户端滥用。如果您想直接从移动应用或 Web 应用调用 Gemini API，则需要使用 Firebase AI Logic 并强制执行 Firebase App Check 来帮助保护它免遭滥用。强制执行 App Check 后，系统将仅允许经过验证的、来自您的实际应用和/或未经篡改的设备的传入请求。

跳转到设置说明

Firebase AI Logic 提供了一个代理网关，可让您与 Firebase App Check 集成，并在移动应用和 Web 应用直接调用 Gemini API 时保护 Gemini API。当对 Firebase AI Logic 强制执行 App Check 时，有助于保护 Gemini Developer API 和 Agent Platform Gemini API (formerly Vertex AI)。

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


App Check 的运作方式简要总结

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

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

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

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

您可以在 的文档中找到有关 App Check的详细信息，包括对证明提供方的说明以及任何适用的配额和限制。

设置 App Check

以下说明经过优化，可用于为 Firebase AI Logic 设置 Firebase App Check 强制执行。

第 1 步：强制执行 App Check

自 2026 年 7 月初起，在 Firebase 控制台的引导式设置工作流程中，Firebase 会自动为 Firebase AI Logic 强制执行 Firebase App Check，以帮助保护 Gemini API。

不过，如果您在 2026 年 7 月初之前已在 Firebase 项目中设置 Firebase AI Logic（或由于其他原因而未强制执行 App Check），则可以按照以下说明自行强制执行 App Check。

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

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

    2. 找到 Firebase AI Logic 所在的行。如果显示 Unenforced，请继续按照这些说明的其余部分操作。

  2. 点击 Firebase AI Logic 对应的行，您会看到指标图表。 点击这些图表下方的设置。

  3. 在对话框的第一个界面（基准保护）中，选择强制执行，然后点击继续。

  4. 在下一个界面（重放保护）中，选择已停用，然后点击继续。

  5. 在最后一个界面中，查看有关强制执行 App Check 的注意事项，确保您已准备好强制执行 App Check。准备就绪后，点击继续。

    如果您只想强制执行 App Check，并且仅在预生产应用中使用 Firebase AI Logic 调试提供程序，则不需要注册应用。不过，当您准备向最终用户发布应用时，需要注册应用，以便设置生产环境中的证明提供方（例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise）。

第 2 步：为本地开发设置调试提供程序

对于本地开发，您可以设置 App Check 调试提供程序，同时仍保持 App Check 对 Firebase AI Logic 的强制执行。

Swift

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供方，请执行以下操作：

  1. 在 Xcode 项目中，导入 FirebaseAppCheck 并使用调试提供方工厂 在配置 Firebase 之前初始化 App Check。

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. 获取调试令牌：

    1. 在模拟器中或在测试设备上启动应用。

    2. 打开 Xcode 控制台，然后查找 App Check 调试令牌。 例如：

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 复制令牌（例如 123a4567-b89c-12d3-e456-789012345678）。

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

Kotlin

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

  1. 在调试 build 中，将 App Check 配置为使用调试提供方工厂：

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

  2. 获取调试令牌：

    1. 在模拟器中或在测试设备上运行应用。

    2. 在日志中查找 App Check 调试令牌。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 复制令牌（例如 123a4567-b89c-12d3-e456-789012345678）。

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

Java

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

  1. 在调试 build 中，将 App Check 配置为使用调试提供方工厂：

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. 获取调试令牌：

    1. 在模拟器中或在测试设备上运行应用。

    2. 在日志中查找 App Check 调试令牌。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 复制令牌（例如 123a4567-b89c-12d3-e456-789012345678）。

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

Web

如需在从 localhost 以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

  1. 在调试 build 中，请在初始化 App Check 之前将 self.FIREBASE_APPCHECK_DEBUG_TOKEN 设置为 true 以启用调试模式。例如：

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(app, { /* App Check options */ });

  2. 在本地访问 Web 应用，然后打开浏览器的开发者工具。在调试控制台中，您将看到一个调试令牌：

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

Dart

iOS+

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供方，请执行以下操作：

  1. 在初始化 Firebase 应用后立即使用调试提供方激活 App Check：

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set appleProvider to `AppleProvider.debug`
    appleProvider: AppleProvider.debug,
  );
  runApp(App());
}

  2. 在 Xcode 项目中启用调试日志记录：

    1. 打开 Product（产品）> Scheme（方案）> Edit scheme（修改方案）。
    2. 从左侧菜单中选择 Run（运行），然后选择 Arguments（参数）标签页。
    3. 在 Arguments Passed on Launch（启动参数）部分，添加 -FIRDebugEnabled。

  3. 获取调试令牌：

    1. 使用 Xcode 打开 ios/Runner.xcworkspace，然后在模拟器或测试设备上运行您的应用。

    2. 打开 Xcode 控制台，然后查找 App Check 调试令牌。 例如：

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 复制令牌（例如 123a4567-b89c-12d3-e456-789012345678）。

  4. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

Android

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

  1. 在初始化 Firebase 应用后立即使用调试提供方激活 App Check：

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set androidProvider to `AndroidProvider.debug`
    androidProvider: AndroidProvider.debug,
  );
  runApp(App());
}

  2. 获取调试令牌：

    1. 在模拟器中或在测试设备上运行应用。

    2. 在日志中查找 App Check 调试令牌。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 复制令牌（例如 123a4567-b89c-12d3-e456-789012345678）。

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

Web

如需在从 localhost 以交互方式运行应用时（例如在本地开发期间）使用调试提供方，请执行以下操作：

  1. 在 web/index.html 文件中，将 self.FIREBASE_APPCHECK_DEBUG_TOKEN 设置为 true，以启用调试模式：

    <body>
  <script>
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  </script>

  ...

</body>

  2. 在本地运行您的 Web 应用，然后打开浏览器的开发者工具。在调试控制台中，您将看到一个调试令牌：

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

    此令牌存储在您的浏览器本地，每当您在同一计算机上的同一浏览器中使用您的应用时，系统都会使用该令牌。如果要在其他浏览器或其他机器上使用该令牌，请将 self.FIREBASE_APPCHECK_DEBUG_TOKEN 明确设置为该令牌对应的字符串，而不是 true。

  3. 向 App Check 注册调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

Unity

如需在模拟器中以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

  1. 在 Firebase 控制台中，创建调试令牌：

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

    2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

    3. 按照屏幕上的说明创建新的调试令牌。

  2. 在应用的初始化代码中，添加以下内容：

    using Firebase.AppCheck;

void InitializeFirebase() {
  // Configure the Debug Provider factory with your debug token.
  DebugAppCheckProviderFactory.Instance.SetDebugToken("YOUR_DEBUG_TOKEN");

  // Set App Check to use the debug provider factory
  FirebaseAppCheck.SetAppCheckProviderFactory(
    DebugAppCheckProviderFactory.Instance);

  // Proceed to initialize Firebase as normal
}

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

第 3 步：为最终用户和正式版设置 App Check

当您准备好向最终用户发布应用时，需要注册应用并设置正式版证明提供方（例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise）。

  1. 选择一个生产环境证明提供方，然后按照以下链接中的实现说明操作：

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

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

通过添加重放保护来增强保护功能

我们建议您使用最新版本的 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 提供商，以查看此页面上特定于提供商的内容和代码。

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

  1. 如果您尚未设置，请按照本页上文中的说明设置 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
);

// ...

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

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

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

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

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

    5. 对于重放保护，请选择不强制执行（仅监控）或强制执行。

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

      • 如果您的相当一部分用户可能在使用未启用受限用途令牌的旧版应用，建议您监控请求。如果您立即强制执行重放保护，系统会屏蔽这些用户的请求。

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

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

了解 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 之前进行。

常见问题解答和问题排查

查找与 Firebase AI Logic 相关的其他常见问题解答和问题排查或错误代码。