快速开始

Capcat 由两部分组成：一个在页面里运行挑战、显示复选框的前端组件，和一个签发挑战、校验结果的服务端。整个接入过程大约 5 分钟。

先看在线体验 →

准备条件

• Docker（运行服务端最快的方式）
• 一台用户浏览器能访问到的服务器
• 几分钟时间

1. 启动服务端

创建 docker-compose.yml：

services:
  cap:
    image: tiago2/cap:latest
    container_name: cap
    ports:
      - "3000:3000"
    environment:
      ADMIN_KEY: your_secret_password
      REDIS_URL: redis://valkey:6379
    depends_on:
      valkey:
        condition: service_healthy
    restart: unless-stopped

  valkey:
    image: valkey/valkey:9-alpine
    container_name: cap-valkey
    volumes:
      - valkey-data:/data
    command: valkey-server --save 60 1 --loglevel warning --maxmemory-policy noeviction
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  valkey-data:

启动：

docker compose up -d

打开 http://<你的服务器>:3000，用 ADMIN_KEY 登录管理后台，创建一个站点密钥。你会得到 site key 和 secret key，下面两步都会用到。

提示

• ADMIN_KEY 是后台登录密码，建议 32 位以上随机字符串。
• 端口冲突时修改 3000:3000 的映射即可。

2. 页面加入组件

组件是一个独立的 Web Component，通过一个 <script> 引入（生产环境建议钉住具体版本或自托管该文件）：

<script src="https://cdn.jsdelivr.net/npm/cap-widget@latest"></script>

放进 <form> 里时无需写任何 JavaScript，组件会自动注入隐藏的 cap-token 字段并随表单提交：

<form action="/submit" method="POST">
  <!-- 你的表单字段 -->
  <cap-widget data-cap-api-endpoint="https://<你的实例>/<site-key>/"></cap-widget>
  <button type="submit">提交</button>
</form>

• <你的实例> 是服务端的公网地址（如 api.capcat.ai），必须能被访客浏览器访问，不能是 localhost。
• <site-key> 是后台创建的站点密钥。

SPA 或自定义流程见前端组件。

3. 服务端校验 token

信任任何提交之前，先把 token 发到 /siteverify 校验：

curl "https://<你的实例>/<site-key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<secret_key>", "response": "<captcha_token>" }'

校验通过返回：

{ "success": true }

token 一次性有效，校验一次后即失效。更多语言示例见服务端验证 API。

最常见的配置错误

secret 要填站点的 secret key，不是后台登录用的 ADMIN_KEY，两者混用是校验失败的最常见原因。

4. 端到端确认

1. 打开页面，复选框应自动打勾，表单里出现 cap-token 字段；
2. 把 token 发给 /siteverify，应返回 { "success": true }；
3. 用同一个 token 再发一次，应当失败——说明一次性机制正常。