vue-driven-cloud-storage/CAPTCHA_README.md

# 登录验证码功能 - 快速开始

## 功能说明

本次更新为"玩玩云"添加了登录验证码功能，提高系统安全性：

✅ **自动触发**：密码输错2次后自动显示验证码
✅ **智能保护**：基于IP和用户名双重维度防护
✅ **易于使用**：点击图片即可刷新验证码
✅ **前后通用**：前台用户和后台管理员登录均适用

## 安装依赖

已为后端安装以下依赖：
```bash
cd backend
npm install svg-captcha express-session
```

## 快速启动

### 1. 启动后端服务
```bash
cd backend
node server.js
```

### 2. 访问登录页面
打开浏览器访问：`http://localhost:40001`

### 3. 测试验证码功能

**方法1：浏览器手动测试**
1. 输入任意用户名和错误密码
2. 点击"登录"按钮2次
3. 第3次尝试时会自动显示验证码输入框
4. 输入验证码后继续登录

**方法2：使用测试脚本**
```bash
# 确保后端服务已启动
./test_captcha.sh
```

## 使用截图流程

### 第1-2次登录失败
![正常登录表单](screenshots/login_normal.png)
- 显示用户名和密码输入框
- 提示"用户名或密码错误"

### 第3次登录失败（触发验证码）
![验证码登录表单](screenshots/login_captcha.png)
- 自动显示验证码输入框
- 显示4位数字验证码图片
- 可点击图片刷新验证码

### 验证码验证
![验证码输入](screenshots/captcha_input.png)
- 输入图片中的4位数字
- 点击"登录"继续

## 配置说明

### 环境变量配置（可选）

在 `backend/.env` 文件中添加：

```env
# Session密钥（建议生产环境修改）
SESSION_SECRET=your-session-secret-here

# Cookie安全（HTTPS环境启用）
COOKIE_SECURE=false
```

### 调整验证码触发次数

编辑 `backend/server.js`，找到以下代码：

```javascript
// 第683行附近
const needCaptcha = ipFailures >= 2 || usernameFailures >= 2;
```

修改 `>= 2` 为你想要的次数（如 `>= 3` 表示第4次才需要验证码）。

### 调整防爆破参数

编辑 `backend/server.js`，找到以下代码：

```javascript
// 第394行附近
const loginLimiter = new RateLimiter({
  maxAttempts: 5,                // 最大失败次数
  windowMs: 15 * 60 * 1000,      // 15分钟
  blockDuration: 30 * 60 * 1000  // 封锁30分钟
});
```

## 文件修改清单

### 后端文件
- ✅ `backend/server.js` - 添加验证码生成API和登录验证逻辑
- ✅ `backend/package.json` - 添加验证码依赖

### 前端文件
- ✅ `frontend/app.html` - 添加验证码输入框和图片显示
- ✅ `frontend/app.js` - 添加验证码逻辑和刷新方法

### 新增文件
- ✅ `CAPTCHA_FEATURE.md` - 详细功能说明文档
- ✅ `CAPTCHA_README.md` - 快速开始指南
- ✅ `test_captcha.sh` - 自动化测试脚本

## 功能特点

### 验证码特性
- **纯数字**：只使用0-9数字，易于识别
- **4位长度**：平衡安全性和用户体验
- **彩色显示**：提高可读性
- **点击刷新**：用户体验友好
- **5分钟有效期**：防止验证码被重复使用

### 安全机制
- **渐进式保护**：
  - 1-2次失败：仅密码验证
  - 3-5次失败：要求验证码
  - 5次失败：封锁30分钟
- **双重维度**：同时基于IP和用户名统计
- **Session存储**：验证码存储在服务器端，防止篡改

## 故障排查

### 验证码不显示
**检查项**：
1. 确认后端服务已启动
2. 检查浏览器控制台是否有错误
3. 确认已输错密码至少2次

### 验证码一直错误
**检查项**：
1. 确认输入的是图片中的数字
2. 刷新验证码重新尝试
3. 检查浏览器是否禁用Cookie

### API返回错误
**检查项**：
1. 查看后端日志：`tail -f backend/logs/error.log`
2. 确认依赖已安装：`cd backend && npm list svg-captcha express-session`
3. 重启后端服务

## 测试清单

- [ ] 第1次登录失败不显示验证码
- [ ] 第2次登录失败不显示验证码
- [ ] 第3次登录失败显示验证码
- [ ] 验证码图片可以正常加载
- [ ] 点击验证码图片可以刷新
- [ ] 输入正确验证码和正确密码可以登录成功
- [ ] 输入错误验证码提示"验证码错误"
- [ ] 管理员登录也受到验证码保护
- [ ] 登录成功后验证码自动隐藏

## 技术支持

详细技术文档：[CAPTCHA_FEATURE.md](./CAPTCHA_FEATURE.md)

如有问题，请：
1. 查看后端日志
2. 检查浏览器控制台
3. 运行测试脚本 `./test_captcha.sh`
4. 查看详细文档