超级验证码插件（SuperCaptcha）使用文档

版本：1.1.0 | 作者：kuakeba.cn | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

超级验证码为社区前台提供一套统一的验证码接管方案，内置七种主流验证方式，并支持随机切换：

• 滑块拼图（slider）
• 自由拖拽（drag）
• 旋转校正（rotate）
• 点选文字（click）
• 点选图形（icon）
• 字符识别（word）
• 数学算式（math）
• 随机切换（random，每次请求从上述七种中随机抽取）

插件自动识别页面中的 .js-captcha 控件并替换为所选验证方式，无需修改社区模板或主题文件。可接管登录、注册、找回密码、发帖、回帖等场景，也可与原「验证码」插件共存。

二、功能特性

三、环境要求

四、安装与升级

4.1 安装

1. 将 SuperCaptcha 目录整体放入项目 plugins/ 下
2. 进入后台 应用中心，找到「超级验证码」，点击 安装
3. 安装时自动将 plugins/SuperCaptcha/static/ 复制到 public/static/SuperCaptcha/
4. 进入 应用中心 → 超级验证码 → 配置，选择验证方式并按需调整参数
5. 打开社区前台登录、注册、发帖或回帖页面，确认验证码已替换

4.2 升级

1. 覆盖 plugins/SuperCaptcha/ 下的全部文件
2. 回到后台应用中心，对本插件执行一次 安装/更新，以刷新 public/static/SuperCaptcha/ 下的 JS/CSS
3. 前台强制刷新（Ctrl+F5）一次

静态资源 URL 自带 ?v=1.1.0 版本参数，正常升级后浏览器会自动拉取新文件；若仍显示旧样式，可手动删除 public/static/SuperCaptcha/ 后重新安装。

4.3 启用顺序建议

1. 先确认社区插件运行正常
2. 安装并配置超级验证码
3. 在后台开关中按场景逐步启用（建议先只开登录/注册，观察无误后再开发帖与回帖）

五、后台配置

后台路径：应用中心 → 超级验证码 → 配置

mode 可选值：

配置值在服务端会再次做范围收敛，即使误填超范围数值也不会导致异常。

六、验证方式说明

6.1 滑块拼图（slider）

• 用户操作：拖动下方滑块，使拼图块与背景缺口对齐，松开后自动提交
• 判定规则：服务端比较提交的水平坐标与缺口位置，误差不超过「拼图容差」即通过
• 提交内容：{"x":123}
• 调优建议：容差越小越难；移动端用户若反馈难以对齐，可适当放宽到 15–20

6.2 自由拖拽（drag）

• 用户操作：直接按住拼图块，拖到背景缺口位置后松开
• 判定规则：横向与纵向坐标同时落在「拼图容差」范围内才通过
• 提交内容：{"x":123,"y":45}
• 调优建议：难度高于滑块拼图，适合对安全性要求更高的站点；容差建议不低于 16

6.3 旋转校正（rotate）

• 用户操作：拖动滑块，把倾斜的字符图片旋转至水平，松开后自动提交
• 判定规则：服务端比较提交角度与真实倾斜角度，误差不超过「旋转容差」即通过
• 提交内容：{"angle":30}
• 说明：图片随机倾斜 ±20°~65°，滑块范围为 -75°~75°；图片已做调色板压缩（约 9KB），加载较快

6.4 点选文字（click）

• 用户操作：按提示顺序依次点击图中的指定汉字
• 判定规则：按顺序逐点比对坐标，每个点需落在「点选判定半径」内
• 提交内容：{"points":[[x,y],[x,y],...]}
• 说明：未找到中文字体时自动改用字母数字；点数由「点选数量」控制

6.5 点选图形（icon）

• 用户操作：按提示顺序依次点击图中的指定图形（圆形、方形、三角形、菱形、星形、十字）
• 判定规则：与点选文字共用坐标判定逻辑，无需中文字体
• 提交内容：{"points":[[x,y],...]}
• 适用场景：服务器没有中文字体，或希望验证码更偏图形化时

6.6 字符识别（word）

• 用户操作：在输入框中输入图中字符，随表单一起提交
• 判定规则：服务端忽略大小写比对
• 提交内容：纯文本
• 说明：字符集剔除了易混淆的 I/O/0/1；图片含干扰线与噪点，长度由「字符识别长度」控制

6.7 数学算式（math）

• 用户操作：填写算式结果，随表单一起提交
• 判定规则：服务端按数值比对
• 提交内容：纯文本
• 说明：支持加、减、乘法；也是所有图形方式的兜底方案

6.8 随机切换（random）

• 用户操作：与当前随机到的验证方式一致
• 工作机制：每次请求挑战时，服务端从七种方式中随机抽取一种，并把真实模式写入缓存；前端只根据返回的 mode 渲染，无需额外配置
• 建议：日常运营推荐使用该模式，兼顾体验与安全性

七、前台生效场景与交互

7.1 生效场景

7.2 交互流程

1. 页面加载时，脚本扫描 img.js-captcha，找到所属表单及 captcha、captcha_token 字段
2. 隐藏原验证码图片，请求 /supercaptcha/challenge 获取挑战
3. 按返回的 mode 渲染对应控件：

  - slider / drag / rotate / click / icon：操作完成后调用 /supercaptcha/verify 即时校验，通过后显示对勾

  - word / math：用户输入内容，随表单提交时由服务端校验

1. 表单最终提交仍使用社区的 captcha + captcha_token 字段，服务端消费挑战

7.3 失败与刷新

• 验证失败：提示「验证失败，请重试」，挑战保留，可继续尝试
• 连续错误 5 次：挑战作废，提示「错误次数过多，请刷新后重试」
• 超过有效期：提示「验证已过期，请刷新后重试」
• 点击验证码旁的刷新按钮，或重新打开表单，即可获取新挑战

7.4 PJAX 与动态表单

脚本监听 pjax:end、community:pjax 以及 DOM 变化，软跳转或异步插入的新表单会自动完成验证码升级，无需手动初始化。

7.5 与原验证码插件共存

• 超级验证码启用时优先接管，原「验证码」插件自动让位
• 关闭超级验证码总开关后，社区自动回退到原验证码插件
• 若三个场景开关全部关闭，前台不显示任何验证码（与社区原有逻辑一致）

八、安全机制

验证码只能提高自动化攻击成本，无法替代频率限制、IP 风控与行为审计。建议同时开启社区的登录/发帖频率限制。

九、常见问题

Q1：前台没有出现新的验证码？

按顺序排查：

1. 后台确认插件已安装且总开关开启
2. 确认对应场景开关（登录/注册/找回、发帖、回帖）已开启
3. 确认社区插件已安装并启用
4. 检查 public/static/SuperCaptcha/supercaptcha.js 是否存在；不存在则重新安装插件
5. 浏览器控制台查看是否有 404 或 JS 报错

Q2：一直提示「验证已过期，请刷新后重试」？

• 检查系统缓存是否正常（文件缓存需 runtime/ 可写，Redis 需连接正常）
• 检查服务器时间是否准确
• 若有效期设置过短（如 60 秒），可适当调大

Q3：点选文字里显示的是字母数字，不是汉字？

服务器未找到可用中文字体。可任选一种方式解决：

1. 将中文字体（如 simhei.ttf）放入 plugins/SuperCaptcha/static/fonts/
2. 在服务器安装常用中文字体（Windows 的 simhei.ttf、Linux 的文泉驿/Noto CJK）
3. 改用「点选图形」模式，不依赖中文字体

Q4：服务器没有 GD 扩展怎么办？

插件会自动降级为数学算式，功能不受影响。若希望使用图形验证，请在 PHP 中启用 GD 扩展后重启服务。

Q5：修改了 JS/CSS 但前台没变化？

静态资源在安装时复制到 public/static/SuperCaptcha/，直接改插件目录不会自动同步。执行一次插件安装/更新，或手动复制文件后强制刷新浏览器。

Q6：验证码图片加载慢？

• 旋转图已压缩到约 9KB，滑块与点选图通常在几十 KB
• 若服务器性能较弱，可改用「数学算式」或「字符识别」
• 确认未开启过于激进的图片压缩或 CDN 回源策略

Q7：移动端拖拽不跟手或页面跟着滚动？

插件已对拖拽区域设置 touch-action: none。若主题额外绑定了触摸事件，可检查是否阻止了默认行为；必要时切换为「滑块拼图」或「点选」类方式。

Q8：后台修改配置后不生效？

配置保存后即时生效，但已打开的页面仍使用旧挑战。刷新页面即可；若使用 CDN/OPcache，请清理对应缓存。

Q9：关闭插件后表单提交提示验证码错误？

关闭总开关会回退到原验证码插件。若原插件未安装或未启用，而社区仍要求验证码，请安装原「验证码」插件，或重新开启超级验证码。

十、接口说明

10.1 挑战响应示例

{
  "code": 1,
  "msg": "ok",
  "data": {
    "mode": "slider",
    "token": "8f14e45fceea167a5a36dedd4bea2543",
    "expires": 300,
    "theme": "#2563eb",
    "bg": "data:image/png;base64,...",
    "piece": "data:image/png;base64,...",
    "width": 320,
    "height": 160,
    "piece_size": 48,
    "piece_y": 56,
    "prompt": "拖动滑块，将拼图对齐缺口"
  }
}

不同模式返回的字段不同：

服务端返回数据中不包含 answer 与 targets，答案仅保存在缓存中。

10.2 校验响应示例

{
  "code": 0,
  "msg": "验证失败，请重试",
  "data": { "refresh": false }
}

code=1 表示通过；data.refresh=true 表示挑战已作废，需要重新获取。

10.3 各模式提交格式

二次开发时，只需在自有表单中加入隐藏字段 captcha 与 captcha_token，并在服务端调用 SuperCaptchaService::checkUser($input, $token) 即可复用本插件。

十一、卸载与回退

1. 后台关闭「启用超级验证码」总开关，可立即回退原验证码插件
2. 在应用中心卸载插件后，建议手动删除 public/static/SuperCaptcha/ 目录
3. 卸载不会影响社区数据；已生成的挑战会在有效期结束后自动失效

十二、目录结构

plugins/SuperCaptcha/
├── controller/
│   └── Front.php                 前台接口（challenge / verify）
├── service/
│   └── SuperCaptchaService.php   挑战生成、校验、绘图
├── static/
│   ├── supercaptcha.css          前台样式
│   ├── supercaptcha.js           前台自动装配与交互
│   └── fonts/                    可选字体目录（自建）
├── SuperCaptchaPlugin.php        插件入口、配置、资源注入
├── plugin.json                   插件元数据
├── routes.php                    路由注册
├── icon.svg                      插件图标
└── README.md                     使用文档

十三、更新日志

1.1.0

• 新增自由拖拽、旋转校正、点选文字、点选图形、字符识别、随机切换
• 新增旋转容差、字符长度配置
• 旋转图体积优化（约 56KB → 约 9KB）
• 完善 GD 缺失、字体缺失、渲染失败时的自动降级

1.0.0

• 首个版本：滑块拼图、点选、数学算式
• 支持登录/注册/找回、发帖、回帖三类场景接管