名词解释

核心概念

captcha_id

验证公钥 - 32 位字符串，验证码的唯一标识。

对公众可见，用以区分不同页面的验证模块
在 Geelab 后台创建获得
建议在每个验证场景部署不同的验证 ID

示例：a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

captcha_key

验证私钥 - 32 位字符串，与验证码公钥唯一对应。

在验证服务中用于数据加密，保障验证安全
在 Geelab 后台创建 ID 后会生成相应的 KEY
必须妥善保管，不要暴露在客户端代码中

重要： captcha_key 是敏感信息，只能在服务端使用，切勿在前端代码中暴露。

lot_number

验证事件流水号 - 针对单次验证事件的唯一标识。

用于保证单次验证事件的唯一性，防止重放攻击
通过部署的 SDK 从 Geelab 服务器上动态注册获得
每条流水号的有效时间约为 10 分钟

示例：4dc3cfc2cdff448cad8d13107198d473

sign_token

用户签名 - 用于二次校验的签名参数。

使用 HMAC-SHA256 算法生成
由 lot_number 和 captcha_key 计算得出
二次校验接口确认签名正确后才会进行校验流程

生成方法：

sign_token = hmac.new(
    captcha_key.encode(),
    lot_number.encode(),
    hashlib.sha256
).hexdigest()

完整的签名生成文档和多语言示例请参考 Server API - 签名生成。

验证流程

二次验证

当用户在前端界面通过验证码后的服务端校验流程。

流程说明：

用户在前端完成验证，生成验证参数
前端将验证参数提交到您的后端
后端将这些参数上传到 Geelab 二次校验接口
Geelab 服务器确认该用户本次验证的有效性
您的后端根据校验结果决定是否允许用户操作

必须执行二次验证 - 仅依赖前端验证结果是不安全的，必须在服务端进行二次验证。

离线模式（容灾模式）

当验证服务出现异常时的降级处理机制。

前端表现：

当服务出现异常时，前端会加载一键通过的本地验证形式
保证前端不会阻塞页面正常交互流程

后端处理：

需要对服务异常情况进行处理（请求超时、请求被拒绝、状态码非 200）
建议在异常时放行请求，保证二次验证不会阻塞业务流程

离线模式确保了验证服务异常时业务的连续性。

验证参数

pass_token

验证通过标识 - 用户完成验证后生成的令牌。

由 Geelab 服务器生成
用于标识用户已通过验证
需要在二次验证时提交

captcha_output

验证输出信息 - 验证过程中生成的加密数据。

包含验证过程的详细信息
用于服务端验证用户行为的真实性
需要在二次验证时提交

gen_time

验证通过时间戳 - 用户完成验证的时间。

纯数字字符串格式
用于防止验证结果被重放
需要在二次验证时提交

gen_time 必须是纯数字字符串，不能包含其他字符。

验证类型

滑动拼图

经典的拼图验证方式，用户需要拖动滑块完成拼图。

安全性： 中
用户体验： 好
适用场景： 一般场景

图标点选

用户需要按顺序点击指定的图标。

安全性： 高
用户体验： 较低
适用场景： 高风险场景

一键通过

无感验证，系统自动判断风险等级。

安全性： 低
用户体验： 最佳
适用场景： 低风险场景

九宫格验证

多点触控验证方式。

安全性： 高
用户体验： 较低
适用场景： 高风险场景

消消乐

趣味性验证体验。

安全性： 中
用户体验： 好
适用场景： 一般场景

五子棋

创新互动验证方式。

安全性： 中
用户体验： 好
适用场景： 一般场景

验证模式

智能模式

系统自动选择验证类型。

根据风险等级智能分配验证形式
可在控制台配置允许的验证类型组合
在安全性和用户体验之间取得最佳平衡

风控融合模式

您的服务器决定显示哪种验证类型。

通过 API 参数指定验证类型
可根据业务规则动态调整
适合有自定义风控系统的场景

无感模式

不显示验证界面，仅进行行为分析。

不显示验证界面
仅进行行为分析并返回风险评分
适合对用户体验要求极高的场景

下一步

查看快速开始了解如何使用这些概念
阅读部署指南了解集成流程
查看 API 参考了解详细参数