Cloudflare Turnstile 是什么?模式、Token 与校验

Cloudflare Turnstile 是什么?它是 Cloudflare 推出的验证码替代方案。它用在后台运行的检测来核实访问者,而不是图片谜题;访问者通过后,页面会收到一个 token,站点的服务器再向 Cloudflare 校验这个 token。本指南讲解三种小组件模式、token 及其限制、校验的工作方式,以及如何区分小组件和整页挑战。
访问者看到什么:三种小组件模式
Cloudflare 在其 小组件文档中说明了三种模式。站点所有者在创建小组件时选择其中一种。
| 模式 | 访问者看到什么 |
|---|---|
| Managed 模式 | 由 Cloudflare 在非交互式检查和复选框之间选择,所以只有在需要进一步检查时才会出现复选框 |
| Non-interactive 模式 | 检查运行期间显示一个加载动画的小组件,访问者从不会被要求做任何事 |
| Invisible 模式 | 什么都没有:没有小组件,也没有加载动画,检查在后台运行 |
这三种都不会要求访问者辨认扭曲的文字或挑选图片。根据 Cloudflare 的概述,站点不必把流量经过 Cloudflare 就能使用这个小组件,但站点所有者需要有一个 Cloudflare 账户才能创建它。
Cloudflare Turnstile 给页面什么?一个 token
对开发者来说,它归结为三件事:一个名为 cf-turnstile-response 的表单字段,服务器上的一次校验调用,以及当你自动化一个使用它的站点时,需要由你自己提供的 token。当小组件位于表单内时,Cloudflare 说它会添加一个名为 cf-turnstile-response 的隐藏 input,随其他字段一起发送到服务器。小组件可以隐式渲染,即它会扫描标记中带有 cf-turnstile 类的元素,也可以由页面脚本通过调用 turnstile.render() 显式渲染。显式渲染的页面还可以传入一个回调函数,CapSkip API 文档说,如果页面定义了回调,就用返回的 token 去运行它。
token 的有效期很短。服务端校验指南说,每个 token 的有效期是 300 秒,并且只供单次使用,而且 Cloudflare 在其网络中追踪兑换情况时会有延迟。所以,你在一个很长的脚本开头请求的 token,等表单发出时可能已经被用掉或已经过期。
服务器如何校验 token
仅仅收到这个字段并不能证明什么。Cloudflare 称服务端校验是必须的:站点把 token 和它的密钥发送到 siteverify 端点,也就是向 https://challenges.cloudflare.com/turnstile/v0/siteverify 发送一个 POST 请求,然后读取 JSON 答复。文档记载的值如下。
| 方向 | 值 | 含义 |
|---|---|---|
| 发送 | secret(必填) | 小组件的密钥 |
| 发送 | response(必填) | 表单字段中的 token |
| 发送 | remoteip(可选) | 访问者的 IP 地址 |
| 发送 | idempotency_key(可选) | 你生成的一个 UUID,使同一次检查的重试是安全的 |
| 返回 | success | 校验是否通过 |
| 返回 | challenge_ts, hostname | 挑战何时被识别,以及在哪里提供 |
| 返回 | error-codes | 一个列表,例如 missing-input-response 或 timeout-or-duplicate |
| 返回 | action, cdata | 页面在小组件上设置的自定义值 |
Cloudflare 列出了七个错误代码,这里有两个重要。代码 missing-input-response 表示没有 token 到达 Cloudflare,timeout-or-duplicate 表示 token 已过期或已被校验过。文档记载的答复不带分数:结果只有通过或失败,外加页面设置的 action 和 cdata 值,以便服务器检查它们。这是对文档所列字段的解读,不是 Cloudflare 关于它从不返回什么的声明。
小组件还是挑战页面:这是哪种 Turnstile?
小组件是一回事,整页挑战是另一回事。小组件是已经加载好的页面中的一个元素。挑战页面则是 Cloudflare 在任何内容到达之前,用来代替站点显示的页面。Cloudflare 的放行文档说,识别这样的挑战会设置一个 cf_clearance cookie,它绑定到访问者和设备。文档还说,启用了 pre-clearance 的小组件可以签发这个 cookie,而默认情况下,小组件签发的是一次性 token。请用下表判断你面对的是哪一种。
| 你所看到的 | 它是什么 | CapSkip 需要你提供什么 |
|---|---|---|
| 表单内的一个框或加载动画,以及 HTML 中的一个 cf-turnstile-response input | 小组件,处于 managed 或 non-interactive 模式 | sitekey 和完整的页面地址。token 会填进该字段 |
| 没有 token 就会失败的表单,但屏幕上没有任何框 | 处于 invisible 模式的小组件,或者没有渲染出来的小组件 | 同样的两个值。在标记或 render 调用中找到 sitekey |
| 站点加载之前显示 "Just a moment" 的整页 | 整页挑战 | CapSkip 有两条路径。一是 Turnstile token 请求,当页面把 action、data 和 pagedata 传给 turnstile.render 时一并带上;二是下文介绍的 cf_clearance cookie 请求 |
从 CapSkip 获取 Turnstile token
CapSkip 运行在你自己的 Windows PC 上,在 127.0.0.1:8080 上以 2captcha 请求格式应答,已授权的副本没有按次费用。 Cloudflare Turnstile 识别工具 页面介绍了这款产品, API 文档 列出了这里用到的参数。如果你的脚本运行在另一台机器上,请把 CapSkip 切换到 Server mode,并把那台 PC 的地址作为主机,具体见设置指南中的 连接设置 一节。CapSkip 在 Server mode 启动时会向所有地址开放它的端口,所以如果想只允许你预期的机器访问,请为其他地址添加一条 Windows Firewall 阻止规则。
下面是手动发出的小组件请求。方法是 turnstile,API 文档把 sitekey 和 pageurl 列为必需的值。每个调用是一行 curl.exe,PowerShell 会照原样运行。在 cmd 中,请去掉以井号开头的行。
# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}
# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}通过 Python SDK 完成同样的任务只需一次调用。它会提交、轮询,并返回一个字典,其中的 code 值就是要填进 cf-turnstile-response 字段的 token。
# python -m pip install capskip
from capskip import CapSkip
# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)
result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")
print(result["code"]) # the token for the cf-turnstile-response field
print(result.get("userAgent")) # the User-Agent to send with itAPI 文档说,CapSkip 使用特定的浏览器 User-Agent 来识别 Turnstile,并且你在提交 token 时必须发送同一个 User-Agent。使用 JSON 回复时,答案里以 userAgent 携带它,在纯文本模式下,它位于 X-Turnstile-User-Agent 响应头中。SDK 请求的是 JSON 回复,所以请从结果中读取该值,并把它放进携带 token 的请求里。
挑战页面请求
对于挑战页面,API 文档要求你再传三个值,它们要从页面传给 turnstile.render() 的参数中读取。请发送页面定义了的那些,不要发送空值。文档里附有一段简短的脚本,它会覆盖该函数并打印出这些参数。
| 请求值 | 页面中存放的位置 |
|---|---|
| action | data-action 属性,或 render 调用中的 action |
| data | render 调用中的 cData 值,或 data-cdata 属性 |
| pagedata | render 调用中的 chlPageData 值 |
# python -m pip install capskip
from capskip import CapSkip
solver = CapSkip(host="127.0.0.1", port=8080)
# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
"YOUR_SITEKEY",
"https://example.com/protected",
action="managed",
data="YOUR_CDATA",
pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))action 的 managed 值是从 API 文档的示例请求中照搬的,所以请使用你的页面定义的 action。
cookie 路径是另一种请求。API 文档把它列在 Cloudflare Challenge (cf_clearance) 之下,用于显示 "Just a moment" 的整页。它只能通过 JSON createTask API 使用,默认是关闭的,需要在 Cloudflare 设置下打开 Return cf_clearance cookies,并且每个请求都必须指明你之后要使用的代理。Python SDK 没有对应的调用,所以下面是按 API 文档写法给出的请求,用 PowerShell 发送。代理的值是文档里的占位符。
# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body
# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
Start-Sleep -Seconds 5
$result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")
$result.solution.cookies.cf_clearance
$result.solution.userAgent如果你想在挑战之后用普通的 HTTP 请求获取该站点,请使用 cookie 请求。API 文档描述的是没有自带浏览器的脚本或工具的这种情况,并说要通过同一个代理、使用同一个 User-Agent 发送该 cookie。token 请求则适合调用 turnstile.render() 并带有回调或接收 token 的字段的页面。token 请求的这种搭配是根据文档的两个部分推断出来的,不是文档里的说法。
关于在 Python 中复用该 cookie,请参阅 如何复用 cf_clearance cookie。在代码中请求 token,请参阅 Node.js 指南。PHP 版本见 用 PHP 识别 Turnstile,C# 版本见 C# 挑战页面指南.
我运行了什么,以及它没有证明什么
我针对一个扮演 CapSkip 的模拟服务器运行了全部四个代码块,Python 版本为 3.11.7、3.13.7 和 3.14.0,capskip 为 1.7.0,两个 PowerShell 代码块在 Windows PowerShell 5.1 中运行。我没有向真正的应用发送任何任务,所以这里的一切都不能说明真实的 Turnstile 页面会如何响应,也不能说明真实应用会为小组件返回什么。
| 对照模拟服务器的检查 | 结果 |
|---|---|
| Python 小组件调用 | 一个任务,方法为 turnstile,带 sitekey 和页面地址,token 和 User-Agent 都出现在结果里 |
| Python 挑战页面调用 | 同一个任务还带有 action、data 和 pagedata,与传入时完全一致 |
| 两个 Python 代码块粘贴到同一个文件中 | 两个任务都已发送并读回 |
| PowerShell 中的 cookie 路径 | 模拟服务器收到了类型 AntiCloudflareTask、页面地址和代理。它先回答一次 processing,然后返回 cookie 和 User-Agent,代码块把它们打印了出来 |
| curl.exe 提交,然后轮询 | 第一次轮询说任务尚未就绪,第二次返回了 token |
常见问题
Turnstile token 的有效期有多长?
Cloudflare 说是 300 秒,并且 token 只供单次使用。请在表单发出之前才向 CapSkip 请求 token。
Turnstile 和站点加载之前的 Cloudflare 检查是同一回事吗?
不是。小组件位于页面内部,产出的是 token。整页挑战会取代页面,最终得到的是 cf_clearance cookie。上面的判断表展示了如何区分它们。
不写任何代码,能先看到 Turnstile 小组件吗?
可以。打开 Turnstile 演示页面 即可看到一个实时的小组件和它所填充的字段。
我能从另一台 PC 调用识别工具吗?
可以,通过 Server mode。把运行 CapSkip 的那台 PC 的地址作为主机,并为不应访问它的地址添加 Windows Firewall 阻止规则。识别工具仍然运行在你自己的 Windows 硬件上。
简短版结论
简而言之,Cloudflare Turnstile 是什么?它是 cf-turnstile-response 中的一个 token,由站点向 Cloudflare 校验,旁边还有一个独立的整页挑战,最终得到一个 cookie。如果想在自己的代码里提供 token 或 cookie,像 CapSkip 这样的本地 验证码绕过 工具可以在你自己的 PC 上完成,采用统一授权,没有按次费用。
