快速开始
Cap 由两部分组成:验证组件在访客的浏览器中运行并完成质询,然后交给你一个令牌;服务端(capd)负责签发质询并验证这些令牌。
1. 搭建 capd
首先需要搭建 capd。它是一个自托管的服务端,自带控制台、数据分析、规则和 API。密钥和设置保存在 Valkey 中。开始之前,你需要做两个选择:
1. 在哪里运行 capd: 你可以用 Docker 在自己的服务器上运行,也可以使用 Railway,或者使用 Workers 这样的无服务器平台。本指南以 Docker 为例。
2. 把数据分析存在哪里: 你可以使用 DuckDB(轻量,适合小型网站)或 ClickHouse(扩展性更好)。两者都已内置,配置起来也都很简单。
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.duckdb.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -dcurl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -d打开 http://localhost:3000,用 .env 中的 ADMIN_KEY 登录,它就是控制台密码。创建一个站点密钥,然后把站点密钥和对应的秘密密钥都复制下来。
验证组件会从访客的浏览器直接访问这个服务端,所以在生产环境中它需要一个公开的 URL。我们推荐使用 Tunnels 这类方案,capd 文档也介绍了其他大多数情况,包括反向代理。
2. 添加验证组件
加载脚本,并从发布页面选一个版本号固定下来:
<script src="https://cdn.jsdelivr.net/npm/cap-widget@<version>"></script>把验证组件放进你的表单:
<form action="/submit" method="POST">
<cap-widget data-cap-api-endpoint="https://cap.example.com/<site-key>/"></cap-widget>
<button type="submit">Submit</button>
</form>端点是 https://<your-instance>/<site-key>/。
访客完成验证后,验证组件会往表单里加一个隐藏的 cap-token 字段。如果不在表单里,就改为监听 solve 事件:
document.querySelector("cap-widget").addEventListener("solve", (e) => {
const token = e.detail.token;
});验证组件页面提供了 React、Vue、Svelte 等框架的代码片段。
3. 验证令牌
在信任一次提交之前,先从你的服务端把它的令牌发送到 /siteverify:
const res = await fetch("https://cap.example.com/<site-key>/siteverify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ secret: "<secret>", response: token }),
});
const { success } = await res.json();import requests
success = requests.post(
"https://cap.example.com/<site-key>/siteverify",
json={"secret": "<secret>", "response": token},
).json()["success"]$res = file_get_contents("https://cap.example.com/<site-key>/siteverify", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Content-Type: application/json",
"content" => json_encode(["secret" => "<secret>", "response" => $token]),
],
]));
$success = json_decode($res, true)["success"] ?? false;curl -X POST "https://cap.example.com/<site-key>/siteverify" \
-H "Content-Type: application/json" \
-d '{"secret": "<secret>", "response": "<token>"}'<secret> 是站点密钥对应的秘密密钥,不是你的 ADMIN_KEY。把这两者搞混是最常见的配置错误。
如果你正在从 reCAPTCHA 迁移,/siteverify 接受相同的请求格式,你的验证代码只需改用你服务器的主机名即可。
有效的令牌会返回 { "success": true }。每个令牌只能使用一次,所以对同一个令牌进行第二次验证会失败。把同一个令牌发送两次,就能快速地端到端检查整个配置。
改用核心库
如果你更想在自己的后端里签发和检查质询,核心库是一个只做这件事的精简 npm 包。令牌存放在你自己的数据库中,也没有控制台、数据分析和速率限制。
