文档/Turnstile 配置
垃圾信息防护

配置 Cloudflare Turnstile。

Turnstile 是 Cloudflare 提供的免费验证码替代方案。一个小部件在你的表单中运行,过滤机器人,并签发一次性令牌;FormPostbox 在接受提交之前会校验这个令牌。防护按网站可选——未开启防护的网站提交会直接保存、不经过验证;你只需要一个免费的 Cloudflare 账户,你的网站也不必在其他方面使用 Cloudflare。

这些密钥由你自己创建

FormPostbox 永远不会替你创建 Cloudflare 站点密钥。你在自己的 Cloudflare 账户中创建 widget,再把它的两个密钥粘贴到 FormPostbox,如下所述。Turnstile 是一项独立服务,无论网站是否接入 Cloudflare 网络都可以使用——参见 Cloudflare 的介绍。

Turnstile 为你的表单做了什么

  • 它区分真人和机器人,让自动化与垃圾提交更难进入你的收件箱。
  • 大多数访客不会察觉。在 Managed 模式下,Cloudflare 会静默判断是否需要交互;只有需要进一步检查时才要求勾选框,所以不要期望每次提交都会出现勾选框。
  • 检查在访客填写表单的同一页面上完成——没有人会被带到其他网站,也不需要解图片拼图。

1. 在 Cloudflare 创建 widget

打开你的 Cloudflare 控制台 → Turnstile(如果没有账户,先注册一个免费账户),然后点击 Add widget。有三个字段需要关注:

  • Widget name — 任意一个你日后能认出的名称,例如 FormPostbox contact form。
  • Hostname management — 将展示该表单的网站,例如 www.example.com。只填主机名:不要 https://、不要端口,也不要像 /contact 这样的路径。添加主机名会同时授权它的子域名,但不包括它周围的父域名;不支持通配符。免费账户每个 widget 最多可以添加 10 个主机名。
  • Widget mode — 选择 Managed(推荐):Cloudflare 会根据访客的风险自动在静默检查与勾选框之间选择。也存在 Non-interactive 和 invisible 模式;这里使用 Managed 是合适的默认值。

点击 创建。Cloudflare 随后会显示该 widget 的 Site Key 和 Secret Key——把两个都复制下来,并把 Secret Key 保存在安全的地方。之后想再次找到它们,打开该 widget 进入 Settings 即可。

Cloudflare 官方指南:创建和管理 widget(控制台) 以及 Widget 模式。你可以跳过 Pre-clearance——它面向单页应用,本文的示例不需要。

2. 弄清哪个密钥填在哪里

  • Site Key — 公开的一半。它放进你网站上的表单代码里;访客能看到它,这没有关系。
  • Secret Key — 私密的一半。FormPostbox 在服务端用它向 Cloudflare 确认每个令牌。永远不要把它写进网站代码,也不要粘贴到预览工具、截图或聊天里。
  • 两个密钥必须来自同一个 widget。来自两个不同 widget 的 Site Key 和 Secret Key 无法配合工作。

3. 在 FormPostbox 中保存两个密钥

在你的工作区中,打开 网站 → 你的网站 → 设置 → 垃圾信息防护:

  • Turnstile 站点密钥 — 粘贴 Site Key。这里会显示你当前的密钥,因此你随时可以确认正在使用哪套配置。
  • Turnstile 私密密钥 — 粘贴 Secret Key。它会被加密保存。如果已经保存过私密密钥,把这个字段留空即可保留原有的;只有想替换时才填写。

点击 保存防护设置。你应该看到 防护设置已保存。,网站切换为 防护已开启。如果它仍显示 防护未开启,说明保存没有成功——请重复这一步。

正式上线的网站请使用 widget 的真实密钥。下面描述的测试密钥只用于本地开发。

4. 用 AI 接入你的表单

打开 表单 → 你的表单。在 连接你的网站 下选择 使用 AI 接入,把生成的提示词交给你的 AI 编程工具。提示词会使用真实端点,并且只有开启防护时才包含公开站点密钥。防护是可选的:未开启防护的网站不需要 Turnstile 密钥也能生成和使用提示词。手工改代码时,请从表单页面复制与你的防护状态对应的版本;参阅手动代码示例。

5. 两处设置,两项不同的工作

请分别核对这两处配置。它们位于不同的产品中,回答不同的问题:

  • Cloudflare → widget 主机名:www.example.com — widget 被允许在哪个主机名上运行。只填主机名。
  • FormPostbox → 允许的来源:https://www.example.com — 哪些页面地址可以向你的表单提交。协议、主机名和端口,不含路径。

你的表单始终检查页面来源是否在允许列表中。只有开启防护时,widget 也必须获准在该主机名上运行。更新其中一个不会同步更新另一个。来源指南 介绍了允许来源的规则,包括子域名、端口和预览地址。

测试密钥仅用于开发

Cloudflare 的测试 Site Key 和测试 Secret Key 是不同的值,行为应分别查看官方表格:测试 Site Key 可以强制交互,测试 Secret Key 则可以模拟令牌已使用;不要只凭 1x、2x 或 3x 前缀配对。它们让本地开发和自动化测试变得可预期,并且适用于任何域名,包括 localhost。它们不能用于 formpostbox.com 的正式接收端:即使前端页面在 localhost 上,接收端仍是正式服务。请为本地测试使用单独的网站与表单,以及允许本地主机名的真实 widget,或在测试网站上暂不启用防护。虚拟密钥只适用于独立运行、明确开启测试模式的本地接收端。具体取值和行为参见 Cloudflare 的 测试指南。

如果仍然失败

widget 一直不出现、校验被拒绝,或者“已保存”与“邮件”混淆,都有对应的解决办法:请按故障排查页面逐项处理。也可以回顾来源指南中的请求规则。

仍需帮助?联系 support@formpostbox.com. 请附上相关文档主题和脱敏后的错误信息,不要发送密钥或访客消息。

浏览全部主题 ↑