vue-driven-cloud-storage/CAPTCHA_FEATURE.md

登录验证码功能说明

功能概述

本次更新为"玩玩云"云存储系统添加了登录验证码功能，提高了系统的安全性。该功能会在用户输错密码一定次数后自动显示验证码，要求用户输入验证码才能继续尝试登录。

功能特性

1. 智能验证码触发

• 自动触发：当用户输错密码2次后，系统会自动显示验证码输入框
• 适用范围：前台用户登录和后台管理员登录均适用
• 双重保护：基于IP地址和用户名两个维度进行失败次数统计

2. 验证码特点

• 纯数字验证码：4位数字，易于识别和输入
• 彩色显示：验证码图片使用彩色显示，提高可读性
• 点击刷新：点击验证码图片即可刷新获取新的验证码
• 有效期限：验证码有效期为5分钟，过期后需要刷新
• 安全存储：验证码存储在服务器端session中，防止客户端篡改

3. 防爆破机制

• 失败限制：15分钟内失败5次将被封锁30分钟
• 渐进式保护：
  • 第1-2次失败：仅提示密码错误
  • 第3-5次失败：显示验证码要求输入
  • 第5次失败：封锁IP和用户名30分钟

技术实现

后端改动

1. 新增依赖

• svg-captcha: 用于生成SVG格式的验证码图片
• express-session: 用于管理session存储验证码

2. 新增API端点

GET /api/captcha

• 功能：生成并返回SVG格式的验证码图片
• 返回：SVG图片数据
• Session存储：验证码文本和生成时间

3. 修改登录API

POST /api/login

新增参数：

• captcha (可选): 验证码输入值

验证逻辑：

1. 检查IP和用户名的失败次数
2. 如果失败次数 >= 2，则要求提供验证码
3. 验证验证码的有效性（是否存在、是否过期、是否正确）
4. 验证码错误返回 needCaptcha: true

4. RateLimiter增强

• 新增 getFailureCount() 方法：获取指定key的失败次数
• recordFailure() 返回值新增 needCaptcha 字段

前端改动

1. 数据字段

新增：

showCaptcha: false,      // 是否显示验证码
captchaUrl: '',          // 验证码图片URL
loginForm.captcha: ''    // 验证码输入值

2. UI组件

在登录表单中添加：

• 验证码输入框（条件显示）
• 验证码图片显示区域
• 点击刷新提示文字

3. 逻辑方法

新增 refreshCaptcha() 方法：

refreshCaptcha() {
  this.captchaUrl = `${this.apiBase}/api/captcha?t=${Date.now()}`;
}

修改 handleLogin() 方法：

• 登录失败时检查 response.data.needCaptcha
• 如果需要验证码，显示验证码并调用 refreshCaptcha()
• 登录成功后隐藏验证码并清空输入

使用说明

用户使用流程

1. 首次登录尝试

   • 输入用户名和密码
   • 点击"登录"按钮
   • 如果密码错误，会提示"用户名或密码错误"

2. 第三次登录尝试（触发验证码）

   • 输入用户名和密码
   • 系统自动显示验证码输入框
   • 输入图片中显示的4位数字
   • 如果看不清，点击图片刷新验证码
   • 点击"登录"按钮

3. 验证码验证

   • 如果验证码错误，会提示"验证码错误"，验证码会自动刷新
   • 如果验证码过期，会提示"验证码已过期，请刷新验证码"
   • 验证码正确且密码正确，登录成功

4. 账号封锁

   • 如果连续失败5次，账号将被封锁30分钟
   • 封锁期间尝试登录会提示"账号已被封禁"

管理员说明

管理员登录时同样受到验证码保护，流程与普通用户完全一致。

配置说明

Session配置

在 backend/server.js 中配置session：

app.use(session({
  secret: process.env.SESSION_SECRET || 'your-session-secret-change-in-production',
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: process.env.COOKIE_SECURE === 'true',
    httpOnly: true,
    maxAge: 10 * 60 * 1000 // 10分钟
  }
}));

建议在 .env 文件中设置：

SESSION_SECRET=你的session密钥

验证码参数

在 backend/server.js 的验证码生成代码中可调整：

const captcha = svgCaptcha.create({
  size: 4,                // 验证码长度（4位数字）
  noise: 2,               // 干扰线条数
  color: true,            // 使用彩色
  background: '#f0f0f0',  // 背景色
  width: 120,             // 宽度
  height: 40,             // 高度
  fontSize: 50,           // 字体大小
  charPreset: '0123456789' // 只使用数字
});

防爆破参数

在 backend/server.js 中配置RateLimiter：

const loginLimiter = new RateLimiter({
  maxAttempts: 5,                // 最大失败次数
  windowMs: 15 * 60 * 1000,      // 统计窗口（15分钟）
  blockDuration: 30 * 60 * 1000  // 封锁时长（30分钟）
});

验证码触发阈值在登录逻辑中设置：

const needCaptcha = ipFailures >= 2 || usernameFailures >= 2;

可以修改 >= 2 来调整触发次数。

安全建议

1. 设置SESSION_SECRET

   • 在生产环境中务必设置强随机的SESSION_SECRET
   • 使用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成

2. 启用HTTPS

   • 在生产环境中设置 COOKIE_SECURE=true
   • 确保使用HTTPS协议

3. 定期审计

   • 定期检查登录失败日志
   • 关注异常的登录尝试

4. 调整参数

   • 根据实际使用情况调整失败次数阈值
   • 根据用户反馈调整验证码难度

测试方法

测试验证码显示

1. 启动服务器：cd backend && node server.js
2. 访问登录页面
3. 使用错误的用户名或密码登录2次
4. 第3次尝试时应该看到验证码输入框

测试验证码API

curl "http://localhost:40001/api/captcha" > test.svg

查看生成的 test.svg 文件，应该显示一个4位数字的验证码。

测试登录流程

# 第一次失败（无验证码）
curl -X POST http://localhost:40001/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"wrong"}'

# 第二次失败（无验证码）
curl -X POST http://localhost:40001/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"wrong"}'

# 第三次失败（需要验证码）
curl -X POST http://localhost:40001/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"wrong"}'
# 返回: {"success":false,"message":"请输入验证码","needCaptcha":true}

故障排查

问题1：验证码不显示

可能原因：

• Session未正确配置
• 前端未正确接收 needCaptcha 标志

解决方法：

• 检查浏览器控制台是否有错误
• 检查后端日志是否有session相关错误
• 确认 express-session 依赖已安装

问题2：验证码一直提示错误

可能原因：

• Session未持久化
• 验证码大小写不匹配

解决方法：

• 验证码已统一转换为小写进行比较
• 检查浏览器是否禁用了Cookie

问题3：验证码图片不加载

可能原因：

• CORS配置问题
• API路径错误

解决方法：

• 检查 ALLOWED_ORIGINS 环境变量配置
• 确认API基础路径配置正确

更新日志

版本：1.1.0

• 新增登录验证码功能
• 密码错误2次后自动显示验证码
• 支持点击刷新验证码
• 验证码有效期5分钟
• 前台和后台登录均支持

技术支持

如有问题，请查看：

• 项目README.md
• GitHub Issues
• 后端日志文件