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

what is cloudflare turnstile - What Is Cloudflare Turnstile? Modes, Token and Verification

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 it

API 文档说,CapSkip 使用特定的浏览器 User-Agent 来识别 Turnstile,并且你在提交 token 时必须发送同一个 User-Agent。使用 JSON 回复时,答案里以 userAgent 携带它,在纯文本模式下,它位于 X-Turnstile-User-Agent 响应头中。SDK 请求的是 JSON 回复,所以请从结果中读取该值,并把它放进携带 token 的请求里。

挑战页面请求

对于挑战页面,API 文档要求你再传三个值,它们要从页面传给 turnstile.render() 的参数中读取。请发送页面定义了的那些,不要发送空值。文档里附有一段简短的脚本,它会覆盖该函数并打印出这些参数。

请求值页面中存放的位置
actiondata-action 属性,或 render 调用中的 action
datarender 调用中的 cData 值,或 data-cdata 属性
pagedatarender 调用中的 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 上完成,采用统一授权,没有按次费用。