Formbricks 项目中集成 reCAPTCHA v3 的技术实现方案

在 Web 应用开发中，防止自动化机器人提交垃圾数据是一个常见需求。本文将详细介绍如何在 Formbricks 项目中实现 reCAPTCHA v3 的集成方案，为在线调查系统提供有效的防机器人保护。

技术背景

reCAPTCHA v3 是 Google 提供的无感验证服务，它通过分析用户行为给出 0-1 之间的风险评分，无需用户进行任何交互操作。相比传统验证码，v3 版本提供了更流畅的用户体验，同时能有效识别自动化脚本。

系统架构设计

数据库层改造

在 Prisma 数据模型中，我们需要为 Survey 表添加两个新字段：

enableRecaptcha Boolean @default(false)  // 是否启用 reCAPTCHA
recaptchaThreshold Decimal?  // 验证阈值(0-1)

阈值设置建议：

• 0.9+：非常严格，仅允许极可信用户
• 0.7-0.9：中等严格，适合大多数场景
• 0.5-0.7：宽松模式，允许部分可疑流量

服务端验证流程

1. 请求处理：客户端提交调查响应时附带 reCAPTCHA token
2. 验证调用：服务端向 Google API 发送验证请求
3. 评分比对：将返回的评分与预设阈值比较
4. 结果处理：低于阈值则拒绝提交

关键验证代码示例：

async function validateRecaptcha(token: string, threshold: number) {
  const response = await fetch('https://www.google.com/recaptcha/api/siteverify', {
    method: 'POST',
    body: `secret=${RECAPTCHA_SECRET_KEY}&response=${token}`
  });
  
  const { success, score } = await response.json();
  return success && score >= threshold;
}

客户端集成方案

前端需要完成以下工作：

1. 加载 reCAPTCHA v3 脚本
2. 在执行提交操作时获取 token
3. 将 token 随请求一起发送

典型实现：

grecaptcha.ready(() => {
  grecaptcha.execute(SITE_KEY, { action: 'survey_submit' })
    .then(token => {
      // 将token加入提交数据
    });
});

错误处理机制

当验证失败时，系统应返回清晰的错误信息：

{
  "error": {
    "code": 422,
    "message": "提交被拒绝，检测到疑似自动化行为",
    "details": {
      "recaptchaScore": 0.3,
      "requiredScore": 0.5
    }
  }
}

前端应据此显示友好的提示信息，建议用户重新尝试或联系支持。

配置管理

项目需要添加两个环境变量：

1. RECAPTCHA_SITE_KEY：用于前端集成的公钥
2. RECAPTCHA_SECRET_KEY：用于服务端验证的私钥

这些密钥应通过安全渠道获取并妥善保管。

性能考量

reCAPTCHA v3 验证会增加约 100-300ms 的请求延迟，建议：

1. 对关键业务才启用验证
2. 设置合理的超时时间
3. 考虑异步验证方式减轻主流程负担

测试策略

完整的测试应覆盖以下场景：

1. 有效高评分 token 的接受
2. 低评分 token 的拒绝
3. 无效/过期 token 的处理
4. 网络异常时的降级处理
5. 不同阈值配置下的行为验证

最佳实践建议

1. 渐进式启用：初期可设置较低阈值，观察日志调整
2. 监控分析：记录验证分数分布，优化阈值设置
3. 备用方案：考虑为验证失败提供替代提交渠道
4. 地域考量：部分地区可能需要特殊处理

通过以上方案，Formbricks 项目可以无缝集成 reCAPTCHA v3 保护，在保障系统安全的同时最大限度保持用户体验的流畅性。