> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 垃圾信息防护

通过环境变量切换的 Turnstile 校验，覆盖公开表单与认证端点。

## 初学者演练

先决条件：阅读下面的两个初学者指南，完成 Web 本地设置，并在编辑器的根目录中打开此 monorepo。网页设置属于`apps/web/.env.local`； Next.js不读取根`.env`。默认fake模式下的`/dashboard`是无数据库演示； `/auth` 需要迁移数据库。

简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。

1. 为确切的本地/部署主机名创建 Turnstile 测试小部件。在`apps/web/.env.local`中，设置`CAPTCHA_PROVIDER=turnstile`和`NEXT_PUBLIC_TURNSTILE_SITE_KEY`；仅将 `TURNSTILE_SECRET_KEY` 放入服务器秘密存储中。

2. 重新启动并提交测试联系表。

3. 期待挑战和成功的有效令牌响应。如果每个请求都失败，则比较主机名和密钥对；永远不要泄露秘密密钥。

对于自定义代码，请从提供的 `prompts/README.md` 开始，然后复制最接近的提示：对于应用程序屏幕为 `prompts/new-app-screen.md`，对于公共页面为 `prompts/new-landing-page.md`。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。

[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[网络本地设置](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/docs/web/agents.md)


## 启用两个键

`CAPTCHA_PROVIDER=off` 是默认值。选择 `turnstile`，在 Turnstile 应用程序中配置匹配的主机名并提供两个密钥。 `NEXT_PUBLIC_TURNSTILE_SITE_KEY` 为公开； `TURNSTILE_SECRET_KEY`仅供服务器验证者使用。

```
CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.
```


## 保护受保护的表面

该门涵盖联系/新闻通讯表格以及 Better Auth 登录、注册、OTP 和密码重置凭证端点。它补充了验证/速率限制；它不能替代会话或工作区授权。


## 验证拒绝和恢复

测试有效令牌、丢失/过期/无效令牌、验证器失败以及客户端小部件重置后的重试。保留可操作的人工检查副本和键盘访问；在切换提供商之前检查所选身份验证引擎的覆盖范围。

[受保护的形式](https://supastack.dev/zh/docs/web/project-structure.md)

[验证引擎差异](https://supastack.dev/zh/docs/web/project-structure.md)


## 安装与配置

CAPTCHA_PROVIDER 选择验证器：off（默认，本地开发无需凭据）或 turnstile。启用 turnstile 需要服务端配置 TURNSTILE_SECRET_KEY，客户端组件使用 NEXT_PUBLIC_TURNSTILE_SITE_KEY——任一缺失时 config schema 会让启动直接失败。

apps/web/src/captcha.ts 组合出一个进程级共享验证器，将 token 以十秒超时发送到 Cloudflare 的 siteverify 端点，并采用失败即拒绝策略——无法验证的 token 永远不算人类证明。

```
CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms
```


## 实现流程

CaptchaWidget（src/captcha-widget.tsx）渲染组件并把 cf-turnstile-response 字段注入父表单，认证客户端调用则通过 x-captcha-response 头携带 token。联系与订阅动作在写入前完成校验——校验失败会返回 status=captcha，而不会创建线索。

当 provider 开启时，packages/auth 挂载 better-auth 的 captcha 插件；CAPTCHA_ENDPOINTS 覆盖凭据输入与签发 token 的路由——登录、注册、OTP 发送、密码重置。check-verification-otp 这类消费型端点被有意排除在外：那里 OTP 或 token 本身就是证明。


## 验证与排障

对每个受保护表单分别提交缺失 token 与畸形 token——两者都必须失败即拒绝。验证 siteverify 不可达时是拒绝而不是放行，provider=off 时本地开发保持开放，且 secret 永远不会出现在客户端打包产物或日志中。


## 下一篇

[管理控制台](https://supastack.dev/zh/docs/web/admin.md)