Cloudflare Turnstile 启用指南

这页解决什么问题

这页专门讲：

1. 怎么在 Cloudflare Dashboard 创建 Turnstile widget
2. site_key 和 secret_key 去哪里拿
3. 回到 fknock 后应该填到哪里
4. 登录页验证失败时该怎么排查

先明确：这里说的是登录页的人机验证

这里配置的是：

• 访问 fknock 登录页时的人机验证控件

它不是：

• Cloudflare WAF 的挑战页
• Cloudflare Access 的身份认证
• Cloudflare Tunnel 本身的开关

fknock 后端已经会在服务端调用 Cloudflare 的 siteverify 接口校验 token，所以你不需要自己再写额外回调代码，关键是把 widget 和两把密钥配置正确。

开始前先准备 3 件事

1. 一个可登录的 Cloudflare 账号
2. 一个稳定的登录域名，例如 home.example.com
3. 确认你准备让管理员实际通过这个域名访问 fknock 登录页

如果你现在主要还是通过：

• 裸 IP
• localhost
• 临时内网地址

来访问登录页，那么建议先继续使用：

• 验证码设置 里的 PoW 验证码

因为 Cloudflare 官方默认要求 widget 至少绑定一个明确的 hostname。

第 1 步：在 Cloudflare Dashboard 创建 widget

Cloudflare 官方当前的 Dashboard 路线是：

1. 登录 Cloudflare Dashboard
2. 进入 Turnstile
3. 点击 Add widget

创建时重点看 3 个字段：

Widget name

建议写成一眼能认出的名字，例如：

• fknock-login
• home-example-login

Hostname management

这里填的是允许使用这个 widget 的域名。

推荐填写你真实会用来打开登录页的完整域名，例如：

• home.example.com
• nas.example.com

Cloudflare 官方文档当前强调：

• 默认至少要配置一个 hostname
• 需要使用完整域名
• 默认不支持通配符

如果你有多个入口域名，就把它们逐个加进去。

Widget mode

Cloudflare 官方推荐优先选择：

• Managed

这是最稳妥的选择。

对 fknock 来说，也更建议这样做，因为当前登录页使用的是可见控件区域。你也可以评估：

• Non-Interactive

但通常不建议把第一次接入直接做成：

• Invisible

因为当前产品更适合使用可见的人机验证流程，排错也更容易。

创建完成后，Cloudflare 会给你：

• sitekey
• secret key

请立刻复制并保存。

第 2 步：把两把密钥填回 fknock

路径：系统设置 → 验证码

操作顺序：

1. 把验证码类型切到 Cloudflare Turnstile
2. 在 站点密钥 中粘贴 site_key
3. 在 密钥 中粘贴 secret_key
4. 保存

字段对应关系如下：

fknock 字段	Cloudflare 字段	用途
站点密钥	sitekey	前端渲染 Turnstile 控件
密钥	secret key	后端向 Cloudflare 校验 token

第 3 步：从真实登录页验证

建议不要只在后台页里看有没有保存成功，而是直接从真实登录页验证。

推荐顺序：

1. 用管理员平时会访问的正式域名打开登录页
2. 确认先出现 Turnstile 控件
3. 完成人机验证
4. 再继续 TOTP 或 Passkey
5. 完成一次完整登录

如果这一步没问题，就说明：

• widget 的 hostname 配对正确
• site_key 和 secret_key 也基本正确

hostname 应该怎么填才不容易出错

最稳妥的原则是：

填“管理员实际访问登录页时会看到的域名”，不要靠猜。

例如：

• 登录页地址是 https://home.example.com/，就填 home.example.com
• 登录页地址是 https://nas.example.com/，就填 nas.example.com

如果你通过多个不同域名访问同一个 fknock 登录页，就把这些域名都加进去。

常见问题

Turnstile 控件根本不显示

优先检查：

1. site_key 是否为空
2. 当前访问域名是否在 widget 的 hostname 列表里
3. 浏览器、广告拦截器或网络策略是否拦掉了 challenges.cloudflare.com

控件能显示，也能勾选，但后台提示验证失败

优先检查：

1. secret_key 是否填错
2. 当前保存的是不是另外一个 widget 的密钥
3. 服务器当前网络是否能连通 Cloudflare 的 siteverify

为什么我不建议一上来就选 Invisible

主要不是说它一定不能用，而是：

• 当前产品更适合可见登录验证流程
• 可见模式更容易判断“是脚本没加载、hostname 不对，还是服务端校验失败”

对第一次部署的用户来说，Managed 更省心。

我只打算用 IP 地址访问，能不能开 Turnstile

这类场景通常不推荐。

如果你暂时没有稳定域名，更稳妥的做法一般是：

• 先用 验证码设置 里的 PoW

官方参考

• Cloudflare Turnstile Get started
• Create and manage widgets using the Cloudflare dashboard
• Turnstile widgets and widget modes
• Hostname management

相关阅读

• 验证码设置
• 认证体系总览
• Passkey