# Capcat 文档（全量单文件版）
> 本文件由 https://capcat.ai 构建时自动生成，汇总了 Capcat 全部使用文档，供 AI 与程序一次抓取。文档索引：https://capcat.ai/llms.txt
---
# 快速开始
> 来源：https://capcat.ai/guide/index.md
Capcat 是托管人机验证服务：你不需要部署或维护任何服务端，在控制台创建站点获得密钥，页面里放入**前端组件**，业务后端调一个**校验接口**即可。整个接入过程大约 5 分钟。
[先看在线体验 →](https://capcat.ai/guide/demo.md)
## 1. 创建站点，获取密钥
打开 [console.capcat.ai](https://console.capcat.ai)，用邮箱和密码注册并登录，点「新建站点」。你会得到两把密钥：
- **site key** —— 公开值，写在页面代码里；
- **secret** —— 保密值，只在创建时展示一次，供你的后端调用校验接口。
建好站点后建议顺手[绑定域名](https://capcat.ai/guide/console.md#_3-绑定域名-强烈建议)，防止别人盗用你的 site key。
## 2. 页面加入组件
组件是一个独立的 Web Component，通过一个 `
```
放进 `
```
把 `` 换成控制台里的 site key 即可。SPA 或自定义流程见[前端组件](https://capcat.ai/guide/widget.md)。
## 3. 服务端校验 token
信任任何提交之前，先把 token 发到 `/siteverify` 校验：
```sh
curl "https://api.capcat.ai//siteverify" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "secret": "", "response": "" }'
```
校验通过返回：
```json
{ "success": true }
```
token 一次性有效，校验一次后即失效。更多语言示例见[服务端验证 API](https://capcat.ai/guide/siteverify.md)。
> **注意**
>
> `secret` 绝不能出现在前端代码里——它只属于你的服务器。丢失后可在控制台轮换（旧 secret 有 1 小时宽限期）。
## 4. 端到端确认
1. 打开页面，复选框应自动打勾，表单里出现 `cap-token` 字段；
2. 把 token 发给 `/siteverify`，应返回 `{ "success": true }`；
3. 用同一个 token 再发一次，应当失败——说明一次性机制正常。
## 接口与迁移
`/siteverify` 与 reCAPTCHA / hCaptcha 的接口兼容：从它们迁移时，服务端通常只需要改一个 URL，前端把组件换成 `` 即可。Capcat 基于开源项目 [Cap](https://github.com/tiagozip/cap)（Apache 2.0）构建。
---
# 获取密钥（控制台）
> 来源：https://capcat.ai/guide/console.md
Capcat 是托管验证服务：你不需要部署任何服务端，在控制台注册后即可获得接入密钥。
## 1. 注册 / 登录
打开 [console.capcat.ai](https://console.capcat.ai)，用邮箱和密码注册账号；已注册的账号直接登录。
## 2. 创建站点
点击「新建站点」，填写站点名称，系统会生成一对密钥：
| 密钥 | 用途 | 保密性 |
| --- | --- | --- |
| **site key** | 前端组件标识，出现在页面代码里 | 公开 |
| **secret** | 业务后端调用 `/siteverify` 时使用 | **绝不能泄露；仅创建时展示一次** |
> **secret 只显示一次**
>
> 创建和轮换时请立即保存 secret。丢失后无法找回，只能在控制台轮换（旧 secret 有 1 小时宽限期）。
## 3. 绑定域名（强烈建议）
在站点详情的「域名绑定」中填入你的网站域名。绑定后，只有来自这些域名的页面才能使用你的 site key，防止他人盗用你的额度。
支持的格式：
- `example.com` —— 该域名及其所有子域
- `*.example.com` —— 仅子域
- `https://example.com` —— 精确 origin
- `http://localhost:*` —— 本地开发（任意端口）
不绑定时任何网站都可使用你的 site key（控制台会显示警告）。变更约 1 分钟内全球生效。
## 4. 接入
前端引入组件（详见[前端组件](https://capcat.ai/guide/widget.md)）：
```html
```
后端校验 token（详见[服务端验证 API](https://capcat.ai/guide/siteverify.md)）：
```bash
curl -X POST https://api.capcat.ai/你的siteKey/siteverify \
-H "content-type: application/json" \
-d '{"secret":"你的secret","response":"cap-token 的值"}'
```
## 用量与限额
控制台可查看每个站点近 7 天的验证次数、通过率与拦截数。当前默认限额：单站点 600 次/分钟、单 IP 30 次/分钟，超限返回 `429`。如需更高额度请联系我们。
---
# 在线体验
> 来源：https://capcat.ai/guide/demo.md
下面是一个模拟的评论表单，验证组件连接的就是 Capcat 部署在 Cloudflare Workers 上的**生产服务**。点一下复选框，工作量证明会在你的浏览器后台完成，通过后「发表评论」按钮才会解锁；点击提交，服务端会真实执行一次 [`/siteverify`](https://capcat.ai/guide/siteverify.md) 校验，并把 API 的响应原样回显在下方。
> （此处是一个交互式演示区域，Markdown 版本无法呈现；在浏览器中打开 https://capcat.ai/guide/demo.html 即可体验。）
## 这背后发生了什么
1. 组件向验证服务请求挑战，服务端签发一个带签名的 JWT；
2. 你的浏览器在后台完成两层挑战：工作量证明（Web Worker 并行求解），加上一段每次动态生成的环境校验程序——确认求解发生在真实浏览器里，而不是直连 API 的脚本（通常 1～3 秒，全程无感）；
3. 解答提交回服务端校验，通过后签发一次性 `cap-token`——业务后端拿它调用 [`/siteverify`](https://capcat.ai/guide/siteverify.md) 完成最终确认，token 用过即废。本页的「发表评论」就真实执行了这一步，上面回显的就是 `/siteverify` 的原始响应。
> **说明**
>
> 本演示与生产站点同配置：PoW + instrumentation 环境校验（含无头浏览器识别）默认开启，可在控制台按站点调整。
## 场景演示
想看看 Capcat 放进真实页面里的样子？[在线 Demo](https://capcat.ai/demo/) 集合了三个常见场景，关键操作都先经过 Capcat 验证：
- **评论与留言** —— 发表按钮锁在验证之后，垃圾评论机器人灌水成本立刻不划算；
- **账号注册** —— 每次提交都要先付出真实算力并通过环境校验，批量注册与撞库脚本的吞吐大幅下降；
- **AI 问答 / 昂贵接口** —— 调用前先通过验证，抬高刷接口的成本，同时不打扰正常用户。
准备接入自己的项目？从[快速开始](https://capcat.ai/guide/index.md)出发，5 分钟搞定。
---
# 前端组件
> 来源：https://capcat.ai/guide/widget.md
验证组件是一个标准 Web Component（``），一行 `
```
> **提示**
>
> 该文件由 Capcat 官方托管（capcat.ai），不依赖第三方 CDN，国内外访问都稳定。
## 表单方式（零 JavaScript）
组件放在 `
```
## JavaScript 方式（SPA / 自定义流程）
监听 `solve` 事件拿到 token，自行决定何时发送：
```js
const widget = document.querySelector("cap-widget");
widget.addEventListener("solve", (e) => {
const token = e.detail.token;
// 把 token 发给你的服务端、解锁提交按钮等
});
```
## 常用属性
| 属性 | 说明 |
| --- | --- |
| `data-cap-api-endpoint` | 验证服务地址，格式 `https://api.capcat.ai//`（site key 在[控制台](https://capcat.ai/guide/console.md)创建站点时获得），必填 |
| `data-cap-worker-count` | 求解使用的 Web Worker 数量，默认按设备核数 |
更完整的属性、主题定制与 React / Vue / Svelte 等框架接入示例，参见上游文档 [Widget 章节](https://trycap.dev/guide/widget.html)。
---
# 服务端验证 API
> 来源：https://capcat.ai/guide/siteverify.md
前端拿到的 token 必须在**服务端**校验后才可信任。接口与 reCAPTCHA / hCaptcha 的 siteverify 兼容（请求体 JSON 与表单编码都接受），从它们迁移时服务端通常只需改一个 URL——对照步骤见[迁移指南](https://capcat.ai/guide/migrate.md)。
## 接口
```
POST https://api.capcat.ai//siteverify
Content-Type: application/json
{ "secret": "", "response": "" }
```
- `secret` — 控制台创建站点时生成的 **secret**（仅创建/轮换时展示一次）；
- `response` — 前端组件产出的 token（表单里的 `cap-token` 字段，或 `solve` 事件的 `e.detail.token`）。
校验通过返回：
```json
{ "success": true }
```
token **一次性有效**：校验成功一次后立即失效，重放会返回失败。
## 多语言示例
```sh [curl]
curl "https://api.capcat.ai//siteverify" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "secret": "", "response": "" }'
```
```js [Node.js]
const { success } = await (
await fetch("https://api.capcat.ai//siteverify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ secret: "", response: "" }),
})
).json();
if (!success) throw new Error("人机验证未通过");
```
```py [Python]
import requests
success = requests.post(
"https://api.capcat.ai//siteverify",
json={"secret": "", "response": ""},
).json().get("success")
```
```php [PHP]
[
"method" => "POST",
"header" => "Content-Type: application/json",
"content" => json_encode([
"secret" => "",
"response" => "",
]),
],
]);
$data = json_decode(file_get_contents(
"https://api.capcat.ai//siteverify", false, $ctx
), true);
var_dump($data["success"] ?? false);
```
---
# 迁移指南
> 来源：https://capcat.ai/guide/migrate.md
从 reCAPTCHA / hCaptcha / Turnstile 迁移到 Capcat 只有两处改动：
1. **前端**：换 `
```
`` 放在 `