应用与密钥管理 (SiteKey & SecretKey)
为每个对接的网站创建独立 App,支持域名白名单防盗刷与动态难度设置
| 应用名称 | AppId (前端公钥) | SecretKey (后端私钥) | 域名白名单 | 防护难度 | 状态与统计 | 操作 |
|---|
人机验证实时演练场 (Playground)
选择任意应用,体验零外网依赖的 PoW 挑战交互与后端二次验签全流程
点击上方勾选框,浏览器将在后台使用 Web Worker 计算哈希碰撞题解,无任何图像弹窗打扰!
⚡ 极速上手:三步完成第三方网站接入
小林安全遵循业界标准的 Challenge-Response 验证流程,接入体验与 Google reCAPTCHA / Cloudflare Turnstile 高度一致。
创建应用获取密钥
在控制台新建应用,获取公钥 AppId (SiteKey) 与私钥 SecretKey。
前端网页嵌入组件
引入 altcha.min.js,在你的表单中插入 <altcha-widget> 标签。
业务后端请求验证
表单提交后,业务后端携带 secretKey 和 altcha 凭证请求 /siteverify 校验。
前端页面嵌入指南
支持传统 HTML 表单、原生 JavaScript、Vue 2/3、React、Angular 等任何前端技术栈。
方法 1:原生 HTML 表单接入 (推荐最简方式)
将以下代码加入到您的表单(如登录/注册/留言等)中。用户勾选验证通过后,组件会自动在表单中插入一个名为 altcha 的隐藏输入项:
<!-- 1. 引入小林安全本地组件 (将 localhost:3000 替换为您部署的实际域名) -->
<script async defer src="http://localhost:3000/altcha.min.js" type="module"></script>
<!-- 2. 登录/提交表单 -->
<form action="/api/login" method="POST">
<input type="text" name="username" placeholder="用户名" required />
<input type="password" name="password" placeholder="密码" required />
<!-- 3. 插入人机验证小部件 (将 apiKey 替换为您在后台创建的 AppId) -->
<altcha-widget
challengeurl="http://localhost:3000/api/v1/challenge?apiKey=您的_AppId"
strings='{"label":"我是人类 (安全验证)","verifying":"正在验证...","verified":"✓ 验证通过"}'
></altcha-widget>
<button type="submit">登 录</button>
</form>
方法 2:JavaScript 监听验证事件 (适用于前后端分离 / AJAX)
const widget = document.querySelector('altcha-widget');
// 监听人机验证状态变化
widget.addEventListener('statechange', (ev) => {
if (ev.detail.state === 'verified') {
console.log('用户验证通过,凭证为:', ev.detail.payload);
// 可保存 ev.detail.payload,并在 axios/fetch 提交业务数据时一同传给后端
}
});
后端服务端二次校验代码
当用户提交表单时,业务后端必须将客户端提交的 altcha 凭证发送至小林安全的 /api/v1/siteverify 接口进行二次验证。
<?php
// PHP 校验示例 (支持原生 PHP、ThinkPHP、Laravel 等)
$secretKey = '您的_SecretKey'; // 在小林安全后台获取
$payload = $_POST['altcha'] ?? '';
if (empty($payload)) {
die(json_encode(['code' => 400, 'msg' => '请先完成人机安全验证']));
}
$verifyUrl = 'http://localhost:3000/api/v1/siteverify';
$postData = json_encode([
'secretKey' => $secretKey,
'payload' => $payload
]);
$ch = curl_init($verifyUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result && !empty($result['success'])) {
// 校验成功!继续处理业务逻辑 (如登录、注册、下单等)
echo "验证通过,欢迎登录!";
} else {
// 校验失败
$errorMsg = $result['message'] ?? '人机验证失败,请重试';
die(json_encode(['code' => 403, 'msg' => $errorMsg]));
}
?>
// Node.js (Express / Koa / Fastify) 校验示例
async function verifyXiaolinCaptcha(payload) {
const secretKey = '您的_SecretKey';
const res = await fetch('http://localhost:3000/api/v1/siteverify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ secretKey, payload })
});
const data = await res.json();
return data.success === true;
}
// 在路由中使用
app.post('/api/login', async (req, res) => {
const { username, password, altcha } = req.body;
const isHuman = await verifyXiaolinCaptcha(altcha);
if (!isHuman) {
return res.status(403).json({ error: '人机验证未通过或已过期' });
}
// 执行业务登录逻辑...
res.json({ message: '登录成功' });
});
# Python (FastAPI / Flask / Django) 校验示例
import requests
def verify_xiaolin_captcha(payload: str) -> bool:
secret_key = "您的_SecretKey"
try:
resp = requests.post(
"http://localhost:3000/api/v1/siteverify",
json={"secretKey": secret_key, "payload": payload},
timeout=5
)
return resp.json().get("success") is True
except Exception:
return False
# 示例:Flask 接口
@app.route('/login', methods=['POST'])
def login():
altcha_token = request.form.get('altcha')
if not verify_xiaolin_captcha(altcha_token):
return {"code": 403, "msg": "人机验证未通过"}, 403
# 验证通过,继续处理业务...
return {"code": 200, "msg": "登录成功"}
// Go (Gin 框架) 校验示例
package main
import (
"bytes"
"encoding/json"
"net/http"
"time"
)
type VerifyRequest struct {
SecretKey string `json:"secretKey"`
Payload string `json:"payload"`
}
type VerifyResponse struct {
Success bool `json:"success"`
Message string `json:"message"`
}
func verifyXiaolinCaptcha(payload string) bool {
reqBody, _ := json.Marshal(VerifyRequest{
SecretKey: "您的_SecretKey",
Payload: payload,
})
client := &http.Client{Timeout: 5 * time.Second}
resp, err := client.Post("http://localhost:3000/api/v1/siteverify", "application/json", bytes.NewBuffer(reqBody))
if err != nil || resp.StatusCode != 200 {
return false
}
defer resp.Body.Close()
var res VerifyResponse
json.NewDecoder(resp.Body).Decode(&res)
return res.Success
}
// Java (Spring Boot) 校验示例
import org.springframework.web.client.RestTemplate;
import java.util.Map;
import java.util.HashMap;
public class CaptchaService {
private final RestTemplate restTemplate = new RestTemplate();
private final String SECRET_KEY = "您的_SecretKey";
private final String VERIFY_URL = "http://localhost:3000/api/v1/siteverify";
public boolean verify(String payload) {
try {
Map body = new HashMap<>();
body.put("secretKey", SECRET_KEY);
body.put("payload", payload);
Map, ?> response = restTemplate.postForObject(VERIFY_URL, body, Map.class);
return response != null && Boolean.TRUE.equals(response.get("success"));
} catch (Exception e) {
return false;
}
}
}
# 命令行 cURL 测试调用
curl -X POST "http://localhost:3000/api/v1/siteverify" \
-H "Content-Type: application/json" \
-d '{
"secretKey": "xl_sec_xxxxxxxxxxxxxx",
"payload": "eyJhbGdvcml0aG0iOiJTSEEtMjU2Ii...=="
}'
API 接口技术规范
小林安全系统暴露的两个核心接口规格说明。
供客户端组件在渲染时获取加密难题(PoW 挑战包)。
| 参数名 | 类型 | 位置 | 说明 |
|---|---|---|---|
| apiKey | String | Query | 应用公钥 (AppId),必填 |
供第三方业务后端在用户提交表单后核验结果。
| 参数名 | 类型 | 位置 | 说明 |
|---|---|---|---|
| secretKey | String | Body (JSON) | 应用私钥 (SecretKey),必填 |
| payload | String | Body (JSON) | 客户端提交的 Base64 凭证,必填 |
宝塔面板 (aaPanel) 保姆级部署指南
零 C++ 编译、零外部 MySQL 依赖,只需 5 分钟即可在宝塔 Linux 服务器上稳定运行!
1 第一步:在宝塔面板安装「Node.js 版本管理器」
登录宝塔面板后台 -> 点击左侧「软件商店」-> 搜索「Node.js」-> 安装「Node.js版本管理器」或「Node.js项目管理器」。
安装完成后,在版本列表中一键安装 Node v18 / v20 / v22 任意稳定版本(推荐 v20 或更高)。
2 第二步:上传项目文件到服务器
将 xlaq 目录下的所有文件压缩为 xlaq.zip(无需包含 node_modules 目录,上传后再一键安装即可)。
在宝塔面板点击「文件」-> 进入 /www/wwwroot/ 目录 -> 新建目录 xlaq 并将压缩包上传后解压。
3 第三步:在宝塔中创建 Node 项目
进入宝塔「网站」->「Node项目」-> 点击「添加Node项目」:
- 项目目录:选择
/www/wwwroot/xlaq - 项目名称:输入
xiaolin-security - 运行版本:选择您已安装的 Node 版本(如 v20.x)
- 添加方式:自定义配置
- 启动选项:
server.js - 项目端口:
3000 - 执行命令:留空或默认
点击确认后,宝塔会自动调用 npm install 安装依赖,并由 PM2 自动常驻守护与开机自启!
4 第四步:绑定域名与配置 Nginx 反向代理与 SSL
在宝塔该 Node 项目设置中:
- 切换到「域名管理」,添加您的解析域名(例如
captcha.yourdomain.com)。 - 切换到「SSL」,选择「Let's Encrypt」申请免费 HTTPS 证书并开启「强制 HTTPS」。
http://127.0.0.1:3000。现在您可以直接通过 https://captcha.yourdomain.com 访问小林安全控制台及人机校验 API!