📖 人机认证平台 - 接入指南

← 返回首页

概述

本平台基于 Cloudflare Turnstile 提供无状态的人机验证服务。外部服务通过 REST API 创建验证实例，用户访问生成的链接完成 Turnstile 验证后，服务端可查询并一次性取走验证结果。

Next.js 14TurnstilePostgreSQLVercel Serverless

基础 URL

所有 API 请求均基于以下基础地址：

https://hmauth.hibernet.top

API 接口

POST/api/instances

创建验证实例，返回 Token 和认证 URL。

响应示例：

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://hmauth.hibernet.top/verify/550e8400-e29b-41d4-a716-446655440000"
}

GET/api/instances/:token/status

查询 Token 状态。若已验证，则返回 verified: true 并销毁该 Token。

响应（未验证）：

{ "verified": false }

响应（已验证并销毁）：

{ "verified": true }

响应（Token 不存在或已过期）：

404 Not Found

DELETE/api/instances/:token

手动删除指定的 Token 实例。

响应：

{ "success": true }

POST/api/verify

前端页面提交 Turnstile 验证结果（由认证页面自动调用，一般无需手动调用）。

集成示例

cURL

# 创建实例
curl -X POST https://hmauth.hibernet.top/api/instances

# 查询状态
curl https://hmauth.hibernet.top/api/instances/550e8400-e29b-41d4-a716-446655440000/status

# 删除实例
curl -X DELETE https://hmauth.hibernet.top/api/instances/550e8400-e29b-41d4-a716-446655440000

Python

import requests
import time

# 创建实例
resp = requests.post('https://hmauth.hibernet.top/api/instances')
data = resp.json()
token = data['token']
url = data['url']
print(f"认证URL: {url}")

# 轮询状态
while True:
    status = requests.get(f'https://hmauth.hibernet.top/api/instances/{token}/status')
    if status.status_code == 404:
        print("验证已取走")
        break
    if status.json().get('verified'):
        print("验证成功")
        break
    time.sleep(3)

Node.js (axios)

const axios = require('axios');

(async () => {
  const { data } = await axios.post('https://hmauth.hibernet.top/api/instances');
  const { token, url } = data;
  console.log('认证URL:', url);

  while (true) {
    try {
      const status = await axios.get(`https://hmauth.hibernet.top/api/instances/${token}/status`);
      if (status.data.verified) {
        console.log('验证成功');
        break;
      }
    } catch (err) {
      if (err.response?.status === 404) {
        console.log('验证已取走');
        break;
      }
    }
    await new Promise(r => setTimeout(r, 3000));
  }
})();

前端 HTML + JS（嵌入 iframe）

<!DOCTYPE html>
<html>
<body>
  <iframe id="authFrame" width="400" height="400"></iframe>
  <div id="status"></div>
  <script>
    const BASE = 'https://hmauth.hibernet.top';
    fetch(BASE + '/api/instances')
      .then(r => r.json())
      .then(({ token, url }) => {
        document.getElementById('authFrame').src = url;
        const timer = setInterval(() => {
          fetch(BASE + '/api/instances/' + token + '/status')
            .then(r => {
              if (r.status === 404 || r.ok) return r.json();
            })
            .then(data => {
              if (data?.verified) {
                document.getElementById('status').textContent = '✅ 验证成功';
                clearInterval(timer);
              }
            });
        }, 3000);
      });
  </script>
</body>
</html>

测试页面

平台内置测试页面，可快速验证网络连通性和验证流程：
/test

常见问题

Token 有效期多长？

Token 自创建起有效期为 5 分钟，超时后自动失效。

验证后 Token 会怎样？

验证通过后，状态变为 verified。外部服务首次查询时会返回 verified: true 并删除该记录，确保一次性使用。

如何配置管理员认证？

管理员认证通过 config/admin.ts 或环境变量 ADMIN_USERS 配置，详情请参考项目 README。

数据库表结构如何初始化？

平台启动时自动创建表并补齐缺失列，无需手动执行 SQL。

最后更新：2026-09-03