人机盾（Renjidun）
优雅草科技的人机验证平台。给网站和应用的注册、登录、下单等关键动作加上滑块与点选验证：真人顺手通过，脚本批量注册在服务端被拦住。
2026 年 10 月 31 日，公测完毕。v1.0.0 优雅草人机盾正式运营上线。
生产站点：人机盾
产品介绍
人机盾是一套可独立接入的验证服务，也是优雅草后续产品统一使用的人机验证能力。它包含四部分：
- 客户控制台：创建应用、签发密钥、查看额度与订单，并提供接入文档和在线演示。
- 嵌入式验证组件（Widget）：滑块、点选两种题型，支持弹窗（popup）和页面内嵌（inline）。
- 前端 SDK ：业务页面只需
mount，用户完成后拿到一次性pass_token。 - 校验 API 与运营后台 ：业务服务器持私钥调用
POST /captchaapi/v1/validate；运营侧基于 likeadmin 管理平台配置。
一次完整验证分成两段，职责分开：
- 浏览器里，用户完成当场生成的滑块或点选，组件颁发
pass_token。 - 业务服务器把这个 token，连同场景
action、网站来源expected_origin、会话context一起交给人机盾校验。只有success = true且这几项与出题时一致，注册、登录或下单才会继续。
浏览器里滑过，只说明「这一次挑战有了凭证」。账号是否创建、订单是否提交，以服务端校验为准。私钥 key_id.secret 只放在服务器环境变量 CAPTCHA_SECRET，不进入网页、Git、App 包或日志。
适合这些场景：
- 开放注册、登录、找回密码、下单、领券、发帖、短信发送等会被脚本撞库或批量灌入的入口。
- 希望验证码、题面和校验规则有人持续维护，而不是每个业务自己养一套引擎。
- 已有网站或后台，希望少改协议、尽快接到现成验证上。
在线体验：人机盾
接入文档：人机盾
截图
挡住批量注册
人机盾面向的就是「防人机注册」。脚本、注册机、协议重放这一类自动化开户，是它要拦住的主要流量。
对注册、登录这类入口，人机盾可以解决 99% 的防人机注册问题：大多数批量脚本过不了「当场看图、按原图坐标作答、再经业务服务器复核」这一关，假注册在进入业务之前就被丢掉。加载题目、刷新、答错、仅仅拿到 pass_token 都不计入成功验证；第一次校验通过才算一次有效核销。
人机盾负责把明显的机器流量挡在业务之前。注册频控、手机号或邮箱校验、风控策略仍然由业务自己保留，和人机盾叠在同一条链路上。
滑块为什么难被机器跳过
滑块的难度在于：机器必须在不知道答案的情况下，对一张当场生成的图做出正确位移，并且整条链路还要能被业务后端复核。想用模拟人手的方式稳定跳过，难度很大。
题面由验证码引擎在服务端生成。缺口的真实位置不写在网页源码里，业务页面也不能自己调用出题和判题接口，也不能自己拼接组件地址。前端提交的是换算回原图的坐标：组件按当前显示尺寸把拖动位置映射回去。脚本若按屏幕像素、固定偏移或一段录好的轨迹去拖，换一张背景、换一次缩放或裁切，落点就会偏掉。挑战有过期时间，过期后凭证作废，需要重新出题。
点选是同一套原则的另一种题：服务端判定三个坐标，页面不能自己宣布「已经是人」。
即便脚本在浏览器里把滑块拖到了看似正确的位置，业务服务器仍要用私钥向人机盾核销 pass_token。核销时 site_key、场景 action、来源 Origin、会话 context 必须和出题时一致，token 用过即失效。来源精确到「协议 + 主机 + 端口」，不接受通配符；http://localhost:5173 和 http://127.0.0.1:5173 是两个来源。expected_origin 填的是业务网站自己的地址，例如 https://www.example.com。
所以，一条能长期用来批量注册的绕过，通常要同时做到：看图找缺口、按原图坐标系提交、维持有效会话和精确来源、跟上题面与校验规则的变化。改一个请求参数，或重放一次接口，完成不了这种长期绕过。
持续更新，让绕过得不偿失
一次碰巧滑过去，花费有限。真正持续烧钱的，是每次题面、引擎和校验规则更新之后，还要把绕过重新做稳。
人机盾会持续更新背景图、题型资源和校验约束。专门维护视觉识别、坐标换算和协议适配的一方，每次更新都要重做一轮。对想跨过人机盾、用机器批量注册的人来说，这笔持续投入相对能拿到的假账号，成本过高，得不偿失。只要更新不停，这条成本曲线就还在。
优雅草后续产品默认接入
从 v1.0.0 正式运营起，优雅草后续所有产品默认接入人机盾。之后推出的网站、控制台和业务系统，在注册、登录等关键入口统一使用人机盾。
人机盾因此是优雅草自己的验证底座，也按同一套控制台、SDK 和校验接口对外提供。外部团队创建自己的应用和密钥，即可把同一套验证接到自己的产品上。
智能接入
智能接入是接入文档最前面的能力，也是当前最快的接入方式。你不需要先通读每种语言的示例。控制台根据你选中的应用，生成一段可直接交给编程助手的提示词；助手按这段提示词改你的仓库，把验证接到注册或登录流程里。
文档入口：人机盾
怎么用
- 登录控制台，创建应用。填写允许来源（精确到协议、主机、端口），填写场景（如
register、login），得到公开的site_key。 - 在「密钥」页创建私钥。完整的
key_id.secret只显示一次，写入服务器环境变量CAPTCHA_SECRET。 - 打开接入文档，选择该应用的
site_key、场景，以及你自己网站的 Origin。 - 点击「复制提示词给 AI」。
- 把提示词发给 Cursor、Claude、ChatGPT、通义千问或 GitHub Copilot，让它直接修改当前仓库并跑通，而不是只回一段教程。
尚未创建应用时，site_key 会保持 YOUR_SITE_KEY。助手会用环境变量占位，并提醒先到控制台创建应用和密钥。
提示词里已经写明的事实
助手不需要再猜测接口路径或凭据放在哪里。提示词会带上这些内容：
|-----------------------|-----------------------------------------------------------------------------|
| 项 | 内容 |
| 平台 Origin | 当前人机盾站点，例如 https://renjidun.youyacao.com |
| 业务网站 Origin | 你在文档页填写的地址，校验时作为 expected_origin |
| site_key / action | 所选应用和场景 |
| 前端 SDK | 优先使用 IIFE：/sdk/captcha-client.iife.js，全局对象 CaptchaClient |
| 校验接口 | POST /captchaapi/v1/validate，请求头 Authorization: Bearer <CAPTCHA_SECRET> |
| 私钥 | 只读服务器环境变量 CAPTCHA_SECRET，格式 key_id.secret |
提示词同时约束助手遵守这些接入规则：
- 私钥只出现在服务器环境变量，不写入网页、Git、App 包、小程序或前端环境变量。
expected_origin使用业务网站 Origin。- 页面通过
<script src=".../captcha-client.iife.js">加载 SDK。Vue、React、Vite、Webpack 若要使用 ESM，先把/sdk/captcha-client.mjs下载到自己的静态目录再本地 import。 context由业务后端生成：32 字节随机数，编码为 64 位十六进制，写入服务端会话后再交给页面。页面自己不生成context，也不调用/captchaapi/v1/challenge和/solve。- 默认弹窗必须调用
inst.open()才会显示；组件卸载时调用destroy()。表单内嵌使用display: 'inline'。 - 只有响应里
success === true，且action、origin、context与本地会话一致，才执行真正的注册、登录或下单。
助手会改哪些地方
- 扫描仓库，判断前端框架和后端语言，定位该场景对应的页面与接口。
- 后端增加下发
context的接口（例如GET /captcha-context）。 - 前端在对应页面挂载 SDK。
- 注册或登录接口增加
pass_token校验，校验未通过则不进入业务。 - 在
.env.example中增加CAPTCHA_SECRET、CAPTCHA_SITE_KEY、CAPTCHA_ORIGIN占位，不提交真实私钥。 - 改完后列出动过的文件，以及本地如何验证。
智能接入解决的是「怎样改到你的项目里」。一次验证是否有效，仍然只认业务后端拿到的校验结果。
手工接入仍然可用。文档页提供 HTML、Vue 和 ESM 说明；仓库 examples/captcha 提供 HTML、PHP、Node、Python 示例。完整字段、错误码和计费说明以控制台文档页为准。
接入时序
业务页 → 你们的后端：申请 context（写入 session）
业务页 → SDK 组件：出题 / 答题
业务页 → 你们的后端：提交 pass_token
你们的后端 → POST /captchaapi/v1/validate （Bearer 私钥）
校验通过后，再执行真正的注册 / 登录 / 下单计费口径：加载、刷新、答错、拿到 pass_token 都不扣费。第一次成功校验扣 1 次。同一 request_id 在 24 小时内、相同指纹的重放返回同一个 validation_id，不再扣费。
仓库结构
|-------------------|--------------------------------------------------------|
| 目录 | 说明 |
| admin/ | 管理后台前端（Vue 3 + Vite + Element Plus） |
| server/ | 后端 API（ThinkPHP 8，含 adminapi / api / captchaapi） |
| web/ | 人机盾控制台、Widget、SDK（Vue 3 + Vite） |
| deploy/captcha/ | 验证码引擎部署脚本与 Docker Compose |
| examples/ | 多语言接入示例（HTML、PHP、Node、Python） |
技术栈
- 后端：PHP ≥ 8.2、ThinkPHP 8、MySQL
- 管理端：Vue 3、Vite、Element Plus、Pinia
- 人机盾 Web：Vue 3、Vite、Element Plus、go-captcha-jslib
- 验证码引擎 ：Go Captcha 服务（见
deploy/captcha）
环境准备
- Node.js 18+（建议 LTS）
- PHP 8.2+、Composer 2
- MySQL 5.7+ / 8.x
- （可选）验证码引擎运行时，按
deploy/captcha脚本准备
快速开始
以下步骤用于在本地运行人机盾平台本身。把验证接到你自己的网站，走上一节的智能接入或控制台文档即可。
1. 后端 server
cpp
`cd server
composer install
cp .example.env .env
# 编辑 .env：数据库、项目标识等
php think`按需导入 server/sql 中的数据库脚本，并将 Web 服务器文档根目录指向 server/public。
2. 管理后台 admin
cd admin
cp .env.development.example .env.development
# 配置 VITE_APP_BASE_URL 指向后端
npm install
npm run dev构建并发布到后端静态目录：
npm run build3. 人机盾前端 web
cd web
cp .env.production .env.development # 或按实际新建本地 env
npm install
npm run dev生产构建（控制台 + Widget + SDK）：
npm run build构建产物会发布到 server/public 下的 console / widget / sdk 等目录。
4. 验证码引擎（可选）
cd deploy/captcha
# 预检、启动、备份等见同目录 *.ps1 与 docker-compose.production.yml本地 Go 工具链、引擎 runtime 二进制默认不入库，需在部署机单独准备。
主要能力
- 控制台：应用、密钥、额度、订单、接入文档、智能接入提示词与在线演示
- Widget / SDK：滑块、点选；
mount后取得pass_token；弹窗与内嵌两种展示 - 服务端校验：
POST /captchaapi/v1/validate（业务后端持私钥校验） - 来源与场景绑定：允许来源精确到协议、主机、端口；场景如
register、login - 管理后台：基于 likeadmin 的运营与系统配置
开发说明
- 提交前请确认未把
.env、上传文件、vendor/node_modules、构建产物推入仓库（见根目录.gitignore）。 package-lock.json、composer.lock建议一并提交，保证依赖一致。server/public/pc为 PC 端静态资源；admin/console/sdk/widget的构建拷贝默认忽略，需本地或 CI 构建后再部署。