图形验证码安全

一、插件简介

图形验证码插件为系统提供图片/算术验证码能力，可独立开关后台登录验证码与前台用户操作验证码（登录、注册、发帖、回复），基于 topthink/think-captcha 实现。

URL 后缀说明：前台验证码地址示例 /captcha.html，路径可在社区 route_extras 中配置 captcha 键；后缀继承社区 url_suffix。

二、核心能力

三、依赖与安装

1. 前台验证码展示依赖 `community`（BBS社区）——验证码图片路由注册在社区 FrontRoute，表单字段由社区模板 _captcha_field.html 渲染。
2. 后台登录验证码仅依赖本插件，无需社区。
3. 无数据库表，安装/卸载为空操作。
4. 需 PHP 环境支持 GD 或 think-captcha 所需图像扩展。

四、应用中心基础配置

字段来自 CaptchaPlugin::configSchema()：

五、后台/重点配置

无独立后台菜单，全部在应用中心配置。

校验逻辑说明

• 后台：CaptchaService::adminEnabled() 控制登录页
• 前台：CaptchaService::userEnabled() 控制社区 FrontBase 中 user_captcha 变量及提交校验
• 提交时需传 captcha（用户输入）与 captcha_token（图片 URL 携带的 token）

六、前台用户流程

1. 用户打开登录/注册弹窗或发帖/回复表单。
2. 若 user_enabled 开启，表单显示验证码输入框与图片（data-src 指向 community_url('captcha')）。
3. 用户输入验证码，点击图片可刷新。
4. 提交时服务端 CaptchaService 校验；失败返回错误提示。
5. 验证码图片由社区控制器 Index@captcha 输出，内部调用 CaptchaService::output()。

七、后台审核与运维

无审核流程。建议：

• 生产环境保持后台登录验证码开启
• 若遇暴力注册可开启前台验证码
• 算术题类型对用户更友好，可降低 OCR 识别率同时保持可读性

八、特殊说明

无独立 routes.php

验证码路由注册在社区插件 FrontRoute 中，默认键 captcha → 路径 captcha。

CaptchaService 要点

• 前台 token 缓存前缀 uc_captcha:，TTL 1800 秒
• syncConfig() 将长度、类型同步到 think-captcha 配置
• 算术题模式 math 时 length 不生效

社区模板变量

user_captcha：布尔值，控制是否渲染 _captcha_field.html。

与光鸭等代理

注释说明前台 token 走 Cache 而非 Session，避免与光鸭代理等并发请求争用 Session。

九、推荐上线清单

• 安装 captcha 插件
• 开启后台登录验证码
• 若开放注册，视情况开启前台用户验证码
• 确认社区已安装，前台 /captcha 可正常出图
• 测试登录、注册、发帖、回复提交校验
• 确认服务器 GD/图像扩展正常

十、常见问题

Q：验证码图片 404？ 需安装 community 插件；检查社区是否启用及 captcha 路由是否被 route_extras 改写。

Q：总是提示验证码错误？ 检查服务器 Cache 是否正常；多节点部署需共享 Cache。刷新图片后使用新 token 提交。

Q：只想后台验证码，不要前台？ enabled 开启、user_enabled 关闭即可。

Q：验证码看不清？ 可改用 math 算术题类型，或调整 length（不宜过长）。

Q：后台登录没有验证码？ 确认 enabled 开启；与 user_enabled 相互独立。