TokenGX CAPTCHA

自托管的人机验证服务，为现代 Web 而生

开源 · 免费 · 无广告

产品介绍

TokenGX CAPTCHA 是一个自托管的人机验证服务，基于 SHA-256 工作量证明机制，无需追踪用户行为即可有效区分人类和机器人。完全替代传统图片验证码和第三方验证服务。

本服务部署在您的服务器上，数据完全自主可控，不依赖任何第三方服务。适合需要保护登录、注册、表单提交等场景的 Web 应用。

核心特性

🔒

自托管

数据完全自主可控，部署在您自己的服务器上，不依赖第三方

🛡️

隐私优先

不追踪用户行为，不收集个人数据，符合 GDPR 等隐私法规

⚡

SHA-256 工作量证明

基于密码学挑战，而非行为追踪，安全可靠

🚫

无广告

纯净的用户体验，无第三方广告干扰

💰

开源免费

基于 MIT 协议开源，零授权费用，可自由定制

♿

无障碍支持

无需识别扭曲文字，对视障用户友好

对比方案

特性	图片验证码	Google reCAPTCHA	TokenGX CAPTCHA
用户体验	差（识别困难）	中（需点击图片）	优（一键验证）
隐私保护	✅	❌ 追踪用户	✅ 不追踪
自主可控	✅	❌ 依赖 Google	✅ 完全自主
费用	免费	免费/付费	免费
广告	无	有	无
无障碍	差	中	优

快速接入

只需 3 步，即可将 TokenGX CAPTCHA 集成到您的网站。

1 创建站点

访问 cap.tokengx.cn 管理后台，创建一个新的站点，获取 Site Key 和 Secret Key。

2 前端集成

在您的前端项目中安装并使用 Cap Widget。

# 安装
npm install cap-widget

3 后端验证

在后端验证 Cap Widget 返回的 token。

前端集成

React / Next.js

// 1. 导入 cap-widget
import 'cap-widget'

// 2. 在组件中使用
function LoginPage() {
  const handleSolve = (token) => {
    // 将 token 发送到后端
    console.log('验证通过，token:', token)
  }

  return (
    <cap-widget
      data-cap-api-endpoint="https://cap.tokengx.cn/{你的SiteKey}/"
    />
  )
}

// 3. 监听验证事件
useEffect(() => {
  const widget = document.querySelector('cap-widget')
  widget?.addEventListener('solve', (e) => {
    const token = e.detail.token
    // 发送到后端验证
  })
  widget?.addEventListener('error', (e) => {
    console.error('验证失败:', e.detail)
  })
}, [])

Vue

<template>
  <cap-widget
    :data-cap-api-endpoint="`https://cap.tokengx.cn/${siteKey}/`"
    @solve="onSolve"
    @error="onError"
  />
</template>

<script>
import 'cap-widget'

export default {
  methods: {
    onSolve(e) {
      const token = e.detail.token
      // 发送到后端验证
    },
    onError(e) {
      console.error('验证失败:', e.detail)
    }
  }
}
</script>

原生 HTML

<!-- 引入 cap-widget（TokenGX 品牌版） -->
<script src="https://cap.tokengx.cn/cap-widget.js"></script>

<!-- 或使用官方 CDN 版本 -->
<!-- <script src="https://cdn.jsdelivr.net/npm/cap-widget"></script> -->

<!-- 使用 -->
<cap-widget
  data-cap-api-endpoint="https://cap.tokengx.cn/{你的SiteKey}/"
></cap-widget>

<script>
  const widget = document.querySelector('cap-widget')
  widget.addEventListener('solve', (e) => {
    const token = e.detail.token
    // 发送到后端验证
  })
</script>

💡 提示

data-cap-api-endpoint 的格式为： https://cap.tokengx.cn/{SiteKey}/
注意末尾需要有斜杠 /。

后端验证

Node.js / Next.js

// lib/cap.ts
const CAP_SERVER = process.env.CAP_SERVER || 'https://cap.tokengx.cn'
const CAP_SECRET = process.env.CAP_SECRET_KEY || ''

export async function verifyCaptcha(token: string): Promise<boolean> {
  try {
    const response = await fetch(`${CAP_SERVER}/siteverify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        response: token,  // 前端传来的 token
        secret: CAP_SECRET
      })
    })
    const data = await response.json()
    return data.success === true
  } catch (error) {
    console.error('Cap verification error:', error)
    return false
  }
}

API 路由示例

// api/auth/send-code/route.ts
import { verifyCaptcha } from '@/lib/cap'

export async function POST(request: Request) {
  const { phone, captchaToken } = await request.json()

  // 验证 Cap token
  if (!captchaToken || !(await verifyCaptcha(captchaToken))) {
    return Response.json(
      { success: false, error: '验证失败，请重试' },
      { status: 400 }
    )
  }

  // 验证通过，发送验证码
  // ...
}

Python / Flask

import requests
from flask import request, jsonify

CAP_SERVER = 'https://cap.tokengx.cn'
CAP_SECRET = 'sk-你的密钥'

def verify_captcha(token):
    try:
        response = requests.post(f'{CAP_SERVER}/siteverify', json={
            'response': token,
            'secret': CAP_SECRET
        })
        data = response.json()
        return data.get('success', False)
    except Exception as e:
        print(f'Cap verification error: {e}')
        return False

@app.route('/api/send-code', methods=['POST'])
def send_code():
    data = request.json
    token = data.get('captchaToken')

    if not token or not verify_captcha(token):
        return jsonify({'success': False, 'error': '验证失败'}), 400

    # 验证通过，发送验证码
    # ...

环境变量配置

# .env
CAP_SERVER="https://cap.tokengx.cn"
CAP_SECRET_KEY="sk-你的SecretKey"
NEXT_PUBLIC_CAP_SITE_KEY="你的SiteKey"

API 参考

获取挑战

POST /{siteKey}/challenge

前端 Widget 自动调用，获取验证挑战。

兑换验证

POST /{siteKey}/redeem

前端 Widget 自动调用，兑换验证结果。

服务端验证

POST /siteverify

后端调用，验证 token 的有效性。

// 请求
{
  "response": "siteKey:challenge:signature",  // 三段式 token
  "secret": "sk-你的SecretKey"
}

// 响应
{
  "success": true
}

⚠️ 注意

response 参数必须是三段式格式： siteKey:challenge:signature
这是 Cap Widget 自动生成的格式，直接传递即可。

常见问题

Q: Cap Widget 不显示怎么办？

1. 确认已安装 cap-widget 包
2. 确认 data-cap-api-endpoint 格式正确（末尾有斜杠）
3. 检查浏览器控制台是否有错误
4. 确认 CSP 配置允许加载 cap.tokengx.cn 的资源

Q: 验证失败怎么办？

1. 检查 Secret Key 是否正确
2. 确认 token 是三段式格式
3. 检查网络连接是否正常
4. 查看服务器日志获取详细错误信息

Q: 如何自定义样式？

Cap Widget 支持通过 CSS 自定义属性修改样式：

cap-widget {
  --cap-widget-width: 280px;
  --cap-widget-height: 60px;
  --cap-background: #ffffff;
  --cap-border-color: #e0e0e0;
  --cap-color: #333333;
  --cap-border-radius: 12px;
}

Q: 支持哪些框架？

Cap Widget 是标准的 Web Component，支持所有现代框架： React、Vue、Angular、Svelte、Next.js、Nuxt 等。也可以在原生 HTML 中直接使用。