Cloudflare Turnstile是什么?从验证原理到网站接入排查
简答:Cloudflare Turnstile是一种嵌入网站表单的人机验证工具,通常不要求用户完成图片或拼图。它先在浏览器生成验证令牌,再由网站服务器调用 Siteverify 接口确认令牌有效,适合登录、注册、评论、联系表单等场景。
定义:Cloudflare Turnstile 是 Cloudflare 提供的 CAPTCHA 替代方案,用浏览器环境信号和非侵入式验证判断访问者是否像真人,并通过令牌让网站服务器决定是否放行表单操作。
先看结论:Turnstile、验证码和挑战页有什么区别?
如果你是在登录、注册或提交表单时看到一个小型验证框,通常它属于 Turnstile,而不是整页的“正在检查您的浏览器”挑战。Turnstile 嵌在具体页面或表单中,主要阻止某项操作;Challenge Page 则可能在访问页面前暂停请求。Cloudflare 文档将 Turnstile 定义为可嵌入任意网站的 CAPTCHA 替代方案,网站不必把全部流量接入 Cloudflare 网络。
本文为独立整理,具体界面、计划和实现细节应以 Cloudflare Turnstile 技术概览及相关文档当前内容为准。
| 项目 | Turnstile | 传统 CAPTCHA | Cloudflare Challenge Page |
|---|---|---|---|
| 出现位置 | 嵌入网页表单或指定组件 | 通常嵌入表单 | 可能在进入页面前显示整页挑战 |
| 用户操作 | 多数情况下无需操作,必要时可能出现简单勾选 | 可能要求输入字符、选择图片或完成拼图 | 由浏览器访问过程触发,可能阻止页面继续加载 |
| 主要保护对象 | 登录、注册、评论、联系表单、支付前操作等 | 网站表单和账号操作 | 站点或路径级访问请求 |
| 是否必须使用 Cloudflare CDN | 不必须,可独立部署 | 取决于服务商 | 通常属于 Cloudflare 站点防护链路 |
| 服务端校验 | 必须调用 Siteverify | 通常也需要服务端验证 | 由挑战平台和站点防护流程处理 |
从选择角度看:只想保护一个表单,优先研究 Turnstile;想控制整站访问,才需要进一步排查 WAF、DNS、SSL 或 Challenge Page 配置。
Cloudflare Turnstile是怎么工作的?
- 创建组件:网站管理员在 Cloudflare 控制台创建 Turnstile widget,并得到一对 sitekey 与 secret key。sitekey 放在网页前端,secret key 只应保存在服务器端。
- 嵌入网页:网站把 Turnstile 小组件放到登录、注册或其他表单中。组件会在访问者浏览器中运行验证逻辑,并根据配置生成令牌。
- 提交令牌:用户提交表单时,网站后端同时接收表单数据和 Turnstile 令牌。前端显示验证成功,不等于后端已经完成安全校验。
- 服务端验证:后端向 Siteverify 接口发送 secret 和 response,读取返回的 success 结果,再决定是否继续登录、注册或保存数据。Cloudflare 明确要求服务端验证,否则单靠前端组件不能保护表单。
令牌有时效并且设计为单次使用。根据 Cloudflare 令牌验证文档,令牌有效时间为生成后五分钟,重复提交可能返回超时或重复使用错误。因此,验证失败后应重新生成令牌,而不是反复提交旧令牌。
最容易被忽略的边界是:Turnstile 负责提供验证信号,最终是否放行仍由网站后端控制。假如接口只检查网页上是否出现了组件,却不调用 Siteverify,攻击者仍可能绕过前端直接请求表单接口。
网站接入 Turnstile 的可照做步骤
- 准备账号和站点:需要 Cloudflare 账号、要保护的网站或 Web 应用,以及可以修改网页和服务器代码的权限。
- 创建 widget:在 Cloudflare 控制台进入 Turnstile,创建组件并设置用途、允许的主机名和验证模式。开发、测试、生产环境建议分开管理,避免测试密钥误用于正式站点。
- 嵌入前端组件:按 Cloudflare 嵌入组件文档加载脚本,并将 sitekey 放入表单对应的组件容器。静态表单可以考虑隐式渲染;需要在特定操作时才触发验证的页面,可以评估显式渲染。
- 把令牌交给后端:表单提交时,将组件生成的令牌随表单数据发送到服务器。不要把 secret key 写进 HTML、JavaScript、移动端公开代码或浏览器可见配置。
- 调用 Siteverify:服务器向
https://challenges.cloudflare.com/turnstile/v0/siteverify发起 POST 请求,提交secret和response。返回成功后,再执行登录、注册、评论保存或其他敏感操作。 - 验证异常路径:为令牌过期、重复使用、主机名不匹配、组件加载失败和网络请求超时分别记录日志,但不要把 secret、完整令牌或用户敏感数据写入公开日志。
官方快速开始文档将流程概括为“创建组件、嵌入组件、服务端验证”三个环节,可参考 Cloudflare Turnstile 快速开始核对实现是否缺步骤。
如果页面设置了内容安全策略 CSP,还要检查是否允许组件依赖的 Cloudflare 验证域名连接。相关组件配置和域名要求可在 Turnstile widget 文档中核对。
Managed、Non-Interactive、Invisible怎么选?
| 模式 | 页面表现 | 适合场景 | 注意事项 |
|---|---|---|---|
| Managed | 根据访问者浏览器信号决定是否需要交互 | 登录、注册、公开表单等通用场景 | 适合先从较少打扰用户的默认方案开始测试 |
| Non-Interactive | 组件显示验证状态,但通常不要求用户点击 | 希望保留可见验证状态的表单 | 仍需后端调用 Siteverify,不能只看前端状态 |
| Invisible | 组件对用户不可见,验证在后台运行 | 已经有明确提交按钮、希望减少页面元素的表单 | 需要检查隐私政策和失败后的可恢复路径 |
Cloudflare 对组件模式的说明显示,三种模式背后的验证逻辑相同,主要差别在于交互呈现方式。初次接入时,不建议为了“看起来无感”而直接隐藏所有反馈;应先确认失败时用户能看到提示并重新验证。
对可访问性要求较高的站点,应测试键盘操作、屏幕阅读器、移动端 WebView 和脚本受限环境。官方产品页面将隐私和减少交互作为 Turnstile 的主要定位,但实际体验仍会受到浏览器、网络、内容安全策略和站点前端代码影响。
免费吗?是否必须使用Cloudflare网络?
Cloudflare 当前公开计划页面列有 Free 和 Enterprise 两类 Turnstile 计划:Free 计划标为免费,Enterprise 计划为联系销售;具体组件数量、主机名管理、分析回溯和企业能力应以 Cloudflare Turnstile plans当前内容为准。
Turnstile 不要求网站把全部流量代理到 Cloudflare。网站可以继续使用其他 CDN、云平台或自建服务器,但前端组件与服务器验证仍需要能够连接 Cloudflare 相关服务。如果用户反馈“验证框一直转圈”或“无法加载”,应优先检查浏览器扩展、DNS、代理、防火墙、CSP 和出站连接,而不是先修改表单业务逻辑。
隐私方面,Cloudflare 产品页面说明 Turnstile 不以广告重定向为目的收集数据;不过网站仍应根据自己的法律义务、隐私政策和实际集成方式进行评估,尤其是使用 Invisible 模式时,应查看对应的隐私条款和附录要求。
Turnstile验证失败的分阶段排查
- 只有某个浏览器失败:先用无痕窗口、另一浏览器或暂时停用脚本拦截扩展测试。若换浏览器正常,重点检查扩展、Cookie、JavaScript 和浏览器隐私设置。
- 所有用户都无法加载:检查页面是否能访问 Turnstile 脚本域名,确认 CSP、企业防火墙、DNS 和代理策略没有阻断组件依赖的请求。
- 前端显示成功但后端拒绝:确认表单确实把令牌传到服务器,服务器使用了正确的 secret,并以 POST 方式调用 Siteverify。不要用前端回调结果代替服务端验证。
- 频繁出现超时或重复令牌:检查是否在页面初始化时生成令牌,却延迟很久才提交;也要排查失败重试时是否重复发送旧令牌。重新渲染或重新获取令牌后再提交。
- 上线后才失败:核对生产域名是否加入组件允许的主机名,检查测试密钥是否被误部署到生产环境,并查看服务器时间、代理出口和错误日志。
如果你看到的是整页 403、520、521、522 或 524,而不是表单内的 Turnstile 组件,那么问题可能属于 DNS、源站、SSL、WAF 或网络链路,应转到对应的连接错误排查路径。
常见问题
Cloudflare Turnstile是验证码吗?
它属于 CAPTCHA 替代方案,但不等同于传统图片验证码。多数情况下,Turnstile在后台完成浏览器验证,必要时才要求用户进行简单交互。
使用Cloudflare Turnstile必须把网站接入Cloudflare CDN吗?
不必须。Turnstile可以独立用于未通过Cloudflare网络代理的网站,但网页组件和服务器端Siteverify请求仍需保持可连接,并正确配置域名、CSP和防火墙策略。
Turnstile只放一个前端组件就安全吗?
不安全。前端组件生成的令牌必须由服务器调用Siteverify验证,服务器确认success后才能继续登录、注册或提交数据。
Turnstile免费吗?
Cloudflare公开计划页面列有免费计划和Enterprise计划。免费计划的组件数量、主机名限制等以当前计划页为准,企业能力和定制价格需按页面说明核实。
为什么Turnstile一直转圈或显示验证失败?
先检查浏览器扩展、JavaScript、Cookie、DNS、代理、防火墙和CSP是否阻断组件请求;如果前端成功但后端失败,再检查令牌传递、secret、主机名和Siteverify请求格式。
Turnstile和Cloudflare“正在检查您的浏览器”是一回事吗?
不是。Turnstile通常嵌入具体表单并阻止某项操作;Challenge Page可能在页面访问前暂停请求,属于不同的访问控制呈现方式。