1. 项目概述为什么我们需要行为验证码在任何一个需要用户交互的Web应用里验证码都是守护安全大门的第一道也是最直观的一道防线。传统的字符验证码用户需要眯着眼睛辨认扭曲的字母数字体验差不说现在的OCR技术识别起来也越来越容易。而滑块、点选、旋转拼图这类“行为验证码”通过模拟人类的一次简单操作比如拖动滑块到缺口处来区分人和机器体验友好安全性也更高。最近在做一个后台管理系统登录环节的安全升级被提上了日程。经过一番调研和对比我最终选择了AJ-Captcha这个开源组件来集成。选择它的理由很直接功能齐全支持滑块、点选、旋转等多种模式、文档清晰、社区活跃并且与SpringBoot的集成方式非常“Spring”几乎可以做到开箱即用。这篇文章我就来详细拆解一下如何在SpringBoot项目中从零开始集成AJ-Captcha并分享一些在实战中遇到的“坑”和优化技巧。2. 核心组件选型与环境搭建2.1 为什么是AJ-Captcha市面上行为验证码方案不少有商业的如极验、腾讯云验证码也有开源的如AJ-Captcha、tianai-captcha。对于内部系统或对成本敏感的项目开源方案是首选。AJ-Captcha的吸引力在于模式丰富不仅支持基础的滑块验证还有文字点选、图标点选、旋转图片、语序点选等能应对不同场景的安全需求。前后端分离后端提供生成、校验接口前端使用纯JavaScript库进行渲染和交互架构清晰符合现代Web开发趋势。配置灵活验证码的图片资源背景图、滑块图、干扰因素水印、干扰线、校验策略容错值、二次校验都可以通过配置项灵活调整。SpringBoot友好官方提供了starter通过几行配置和注解就能快速集成大大降低了使用门槛。2.2 项目环境与依赖引入我使用的环境是Spring Boot 2.7.xJDK 11。首先在项目的pom.xml文件中引入核心依赖。dependency groupIdcom.anji-plus/groupId artifactIdspring-boot-starter-captcha/artifactId version1.3.0/version /dependency这里有一个关键注意事项一定要去中央仓库Maven Central核对最新版本。AJ-Captcha的GroupId曾有过变动早期版本是com.anji.captcha现在稳定在com.anji-plus。用错GroupId会导致依赖拉取失败。引入依赖后Spring Boot的自动配置机制会生效。但为了能正确使用我们还需要在application.yml中做一些基本配置。# application.yml aj: captcha: # 验证码类型: blockPuzzle-滑块, clickWord-点选文字, 等等 type: blockPuzzle # 缓存类型: 本地内存(默认) 或 redis。生产环境务必用redis cache-type: redis # 滑动验证码的容错偏移量单位像素。值越小越严格 slip-offset: 5 # aes加密开关。前端传回的验证数据是否需要后端aes解密 aes-status: true # 干扰项配置如数字水印 watermark: content: 内部系统 # 历史数据清除开关配合缓存使用 history-data-clear-enable: true配置详解与避坑cache-type: 这是第一个大坑。默认的local本地内存只适用于单机应用。如果你的服务是多实例部署的那么生成验证码的实例和校验验证码的实例可能不是同一个本地缓存会导致校验永远失败。生产环境必须使用redis。aes-status: 建议开启true。开启后前端滑块移动的轨迹、坐标等敏感数据会经过AES加密再传给后端防止被轻易篡改或窥探提升安全性。slip-offset: 这个值需要根据前端UI的实际情况调整。设置太小用户正常操作可能因微小误差而失败体验差设置太大则安全性降低。一般从5开始调试。2.3 Redis配置与连接既然生产环境必须用Redis我们就需要配置Redis连接。假设你已经有了Redis服务在application.yml中补充配置spring: redis: host: localhost port: 6379 # 如果有密码 password: your-redis-password # 选择存储验证码的数据库避免和业务数据混在一起 database: 1 lettuce: pool: max-active: 8 max-wait: -1ms max-idle: 8 min-idle: 0AJ-Captcha的Redis缓存实现默认会使用spring.redis的配置来创建连接。它会把每次验证码会话的键key存入Redis并设置一个较短的过期时间如2分钟。确保你的Redis服务是可达且稳定的否则验证码功能将完全不可用。3. 后端接口开发与核心逻辑AJ-Captcha的starter已经帮我们封装了绝大部分逻辑我们需要做的就是提供两个核心的HTTP接口一个用于获取验证码一个用于校验验证码。3.1 创建验证码控制器CaptchaController首先创建一个RestController。import com.anji.captcha.model.common.ResponseModel; import com.anji.captcha.model.vo.CaptchaVO; import com.anji.captcha.service.CaptchaService; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.annotation.Resource; RestController RequestMapping(/captcha) public class CaptchaController { Resource private CaptchaService captchaService; /** * 获取验证码 */ PostMapping(/get) public ResponseModel get(RequestBody CaptchaVO captchaVO) { return captchaService.get(captchaVO); } /** * 校验验证码 */ PostMapping(/check) public ResponseModel check(RequestBody CaptchaVO captchaVO) { return captchaService.check(captchaService); } }代码非常简单几乎就是CaptchaService的代理。CaptchaVO这个对象包含了前端请求所需的所有参数比如验证码类型captchaType、客户端类型等。实操心得一关于CaptchaVO的客户端参数在调用get接口时前端通常需要传递一个captchaVO对象。其中captchaType验证码类型我们已经全局配置了但clientType客户端类型也建议传上。这个字段通常用于区分不同的前端平台如Web、Android、iOS虽然基础功能用不到但如果你未来需要为不同平台配置不同的验证码策略比如移动端用更简单的模式这个字段就很有用了。前端可以固定传web或h5。3.2 理解校验流程与二次校验这是AJ-Captcha设计的精髓也是安全性的关键我画个简单的时序图来帮助理解前端页面加载 | |--1. 请求/get接口 | 后端生成验证码(图片secretKey) | | | |-- 生成滑块位置、轨迹等核心数据 | |-- 用secretKey加密核心数据生成token | |-- 将token、背景图、滑块图等返回前端 | 前端展示验证码用户操作 | |--2. 用户拖动滑块完成拼图 | 前端计算移动轨迹、缺口位置 |-- 用后端返回的secretKey加密这些数据 | |--3. 携带加密数据和token请求/check接口 | 后端解密并校验 | | | |-- 用token从缓存取出原始secretKey | |-- 用secretKey解密前端数据 | |-- 比对解密出的位置与原始位置考虑容错 | |-- 返回成功/失败 | 前端根据结果进行后续操作如提交登录表单核心安全点二次校验很多初学者会犯一个错误只在前端验证滑块是否拼合成功然后就提交表单了。这是极度危险的因为前端的所有验证逻辑都可以被绕过。 正确的做法是前端验证通过后必须将AJ-Captcha返回的验证数据一个captchaVerification字符串随业务请求如登录请求再次提交到后台。后台需要调用一次校验服务确认这次验证会话是真实有效的。这才是完整的闭环。3.3 实现业务中的二次校验通常我们会在登录的Service或Filter中注入CaptchaService进行二次校验。import com.anji.captcha.service.CaptchaService; import com.anji.captcha.model.common.ResponseModel; import com.anji.captcha.model.vo.CaptchaVO; import org.springframework.stereotype.Service; import javax.annotation.Resource; Service public class LoginService { Resource private CaptchaService captchaService; public LoginResult login(LoginRequest request) { // 1. 首先校验验证码 CaptchaVO captchaVO new CaptchaVO(); captchaVO.setCaptchaVerification(request.getCaptchaVerification()); ResponseModel checkResponse captchaService.verification(captchaVO); if (!checkResponse.isSuccess()) { return LoginResult.fail(验证码错误或已失效); } // 2. 验证码通过再进行用户名密码校验 // ... 你的业务登录逻辑 ... } }verification方法会检查captchaVerification的有效性并在校验成功后自动使该次验证码会话失效防止同一个验证码被重复使用重放攻击。重要提示captchaVerification是一次性的校验成功后务必不能再用于第二次业务请求。AJ-Captcha在Redis中将其标记为已使用第二次校验会失败。4. 前端集成与交互实现后端接口准备好后前端需要集成AJ-Captcha的JavaScript库。官方提供了多种方式对于Vue/React等现代框架推荐使用NPM包。4.1 安装与引入前端库# 在你的前端项目根目录下 npm install anji-plus/captcha --save然后在你需要展示验证码的组件中比如Login.vue引入并初始化。template div form submit.preventhandleLogin !-- 用户名密码输入框... -- div idcaptcha-container/div button typesubmit登录/button /form /div /template script import { initCaptcha } from anji-plus/captcha; export default { name: Login, data() { return { captcha: null, captchaVerification: // 用于存放验证通过后的凭证 }; }, mounted() { this.initCaptchaFun(); }, methods: { initCaptchaFun() { // 初始化验证码挂载到指定容器 this.captcha initCaptcha({ el: #captcha-container, // 容器ID mode: fixed, // 模式fixed-固定弹出pop-点击弹出 apiBaseUrl: http://your-backend-domain:port, // 你的后端API地址 getCaptcha: /captcha/get, checkCaptcha: /captcha/check, vSpace: 5, // 验证码图片与容器的边距 ready: () { console.log(验证码初始化完成); }, success: (data) { // 验证成功回调 console.log(验证成功, data); this.captchaVerification data.captchaVerification; // 保存凭证 this.captcha.reset(); // 重置验证码状态准备下一次验证 }, error: (err) { // 验证失败或出错回调 console.error(验证码错误, err); this.captcha.refresh(); // 刷新一个新的验证码 } }); }, async handleLogin() { // 提交登录前检查是否有有效的验证凭证 if (!this.captchaVerification) { alert(请先完成验证码验证); return; } const loginData { username: this.username, password: this.password, captchaVerification: this.captchaVerification // 将凭证传给后端 }; // 调用你的登录API... const res await this.$http.post(/api/login, loginData); // ... 处理登录结果 } } }; /script4.2 前端配置的细节与优化mode模式选择fixed: 验证码组件始终显示在页面上。适合登录页这种验证码是必经流程的场景。pop: 点击某个按钮如“获取验证码”后弹出。适合注册、找回密码等场景。bind: 需要手动绑定事件触发。更灵活但需要自己写更多代码。成功回调处理在success回调里一定要保存data.captchaVerification。这是后端二次校验的唯一依据。同时调用this.captcha.reset()是个好习惯它会把组件内部状态清空但不会刷新图片。如果希望用户失败后看到新图片应该调用this.captcha.refresh()。错误处理与用户体验在error回调里除了打印日志一定要给用户明确的反馈。比如调用this.captcha.refresh()自动刷新一个新验证码或者显示一个友好的提示语。不要让用户对着一个失败的验证码发呆。样式自定义AJ-Captcha的UI样式是固定的但提供了有限的CSS类名供覆盖。你可以通过深度选择器如Vue的::v-deep来修改其颜色、大小等以匹配你的项目设计风格。不过修改前最好先看看官方文档避免破坏其交互逻辑。5. 生产环境部署与高级配置开发环境跑通了只是第一步要上线还需要考虑更多。5.1 资源文件图片的部署AJ-Captcha需要背景图和滑块图资源。默认配置下它会从项目的classpath:/captcha目录下读取或者从aj.captcha.captcha-resource.path指定的绝对路径读取。生产环境最佳实践不要将图片打包在Jar内这会导致Jar包巨大且无法动态更新图片。建议将图片目录放在服务器的一个固定路径如/data/captcha-images/。使用配置项指定路径aj: captcha: captcha-resource: # 指向服务器上的绝对路径 path: /data/captcha-images/准备多套图库并定期更换安全性很大程度上依赖于图片库的丰富性。你可以在/data/captcha-images/下建立original背景图库和slidingBlock滑块图库目录并定期上传新的图片文件。AJ-Captcha会随机选取。注意文件命名规范背景图通常命名为original-1.jpg滑块图命名为slidingBlock-1.png。具体命名规则需参考官方文档或源码保持一致。5.2 Redis高可用与Key命名空间生产环境的Redis绝不能是单点。使用哨兵或集群模式在spring.redis配置中配置哨兵节点或集群节点。为验证码数据设置独立的数据库或Key前缀避免与业务缓存Key冲突。AJ-Captcha默认的Key前缀是CAPTCHA:。你可以在配置中查看是否支持修改如果不行至少确保你的Redis database是独立的。5.3 安全与风控增强配置默认配置可能不足以应对高强度的攻击需要调整。aj: captcha: # 尝试次数限制。同一客户端根据请求标识在多久内允许失败几次 try-times: 3 # 尝试次数统计的时间范围单位秒 try-times-duration: 300 # 验证成功后验证码凭证的有效期单位秒。不宜过长。 verification-validity: 120try-times和try-times-duration这是防暴力破解的重要参数。假设设置为3次/300秒意味着同一个客户端在5分钟内验证失败3次该客户端将被暂时禁止获取验证码。这个“客户端标识”通常由AJ-Captcha内部根据请求的一些特征如IP、User-Agent生成但需要注意在反向代理如Nginx环境下需要正确配置才能获取到真实IP。verification-validity验证成功后captchaVerification凭证的有效时间。设置太短用户操作慢一点可能就过期了设置太长又增加了重放攻击的风险。120秒是一个比较折中的值。5.4 自定义实现与扩展如果默认行为不满足需求AJ-Captcha也提供了扩展点。场景一自定义缓存实现默认的Redis实现可能不符合你的缓存规范。你可以实现com.anji.captcha.service.CaptchaCacheService接口然后注入到Spring容器中AJ-Captcha会自动使用你的实现。Component public class MyRedisCaptchaCacheService implements CaptchaCacheService { // 注入你自己的RedisTemplate或缓存客户端 Resource private StringRedisTemplate stringRedisTemplate; private static final String KEY_PREFIX “MY_CAPTCHA:”; Override public void set(String key, String value, long expiresInSeconds) { stringRedisTemplate.opsForValue().set(KEY_PREFIX key, value, expiresInSeconds, TimeUnit.SECONDS); } Override public boolean exists(String key) { return Boolean.TRUE.equals(stringRedisTemplate.hasKey(KEY_PREFIX key)); } // ... 实现其他方法 }场景二自定义图片资源加载如果你想把图片放在云存储如OSS、MinIO上可以实现com.anji.captcha.resource.ResourceProvider接口重写图片获取的逻辑从网络URL加载而非本地文件。6. 常见问题排查与性能优化在实际集成过程中我遇到了不少问题这里总结一下。6.1 问题排查清单问题现象可能原因解决方案前端一直显示“加载中”或报错1. 后端/captcha/get接口不可达或报错。2. 前端apiBaseUrl配置错误。3. 跨域问题CORS。1. 检查后端服务日志确保接口正常。2. 核对前端配置的URL、端口。3. 在后端配置CORS允许前端域名。滑动拼图成功但前端success回调不触发1. 前端checkCaptcha接口地址错误。2. 后端/captcha/check接口内部异常。3. 网络问题导致校验请求失败。1. 打开浏览器开发者工具F12的“网络(Network)”标签查看check请求是否发出及响应。2. 查看后端日志排查check接口异常。后端日志显示校验失败“验证失败”1.最常见缓存类型为local但服务是多实例部署。2. Redis连接失败缓存未生效。3. 前端传回的captchaVerification已过期或被使用过。4.slip-offset容差值设置过小。1.确认aj.captcha.cache-typeredis并已正确配置Redis连接。2. 测试Redis连接是否通畅。3. 确保前端每次业务请求使用新的captchaVerification。4. 适当调大slip-offset或在前端检查滑块组件渲染是否正常。验证码图片显示红叉或加载不出1. 图片资源路径配置错误。2. 图片文件损坏或格式不支持。3. 服务器磁盘权限问题无法读取图片。1. 检查aj.captcha.captcha-resource.path配置确保路径存在且包含图片。2. 使用常见的.jpg/.png格式图片。3. 检查应用运行用户对图片目录是否有读权限。同一验证码可重复使用多次二次校验后没有正确使验证码失效。确保在业务校验中调用的是captchaService.verification()方法它会执行“校验并失效”的逻辑。不要自己手动去删Redis key。6.2 性能优化建议图片资源优化压缩图片背景图和滑块图在不影响识别的前提下尽量压缩体积。可以使用TinyPNG等工具将几百KB的图片压缩到几十KB减少网络传输时间。使用CDN如果自定义了图片资源且访问量很大可以考虑将图片目录放到CDN上然后通过自定义ResourceProvider从CDN URL加载。Redis优化验证码的Key通常设置较短的TTL如2-5分钟。确保Redis有足够的内存并监控Key的数量避免内存溢出。可以考虑为验证码相关的Key设置一个统一的前缀方便监控和清理。接口防刷/captcha/get获取验证码接口是容易被刷的入口。除了框架自带的try-times限制可以在网关或拦截器层针对IP地址增加频率限制如每秒最多请求10次。对于/captcha/check校验验证码接口由于需要前端先完成人机交互被刷的风险相对较低但也可以加入一些基本的频率限制。6.3 监控与日志在生产环境为验证码服务添加适当的监控是必要的。日志级别在application.yml中将com.anji.captcha包的日志级别设置为DEBUG或INFO以便在出现问题时能看清内部流程。logging: level: com.anji.captcha: DEBUG监控指标可以收集以下指标验证码获取次数/captcha/get验证码校验总次数/captcha/check验证码校验成功率/失败率Redis中验证码Key的数量 这些指标可以帮助你发现异常流量如某个IP疯狂获取验证码或功能异常如校验失败率突然飙升。集成AJ-Captcha的过程本质上是在用户体验和安全之间寻找平衡点。它提供了坚固的盾牌但如何用好这块盾牌还需要根据自己业务的实际流量和攻击态势进行细致的调优和监控。从最简单的配置开始逐步深入理解其原理和扩展点你就能打造一个既友好又安全的验证码防线。