====================================
玩玩云 - 登录验证码功能更新说明
====================================

更新时间：2025年11月21日
版本：v1.1.0

一、功能概述
----------------------------------

为"玩玩云"云存储系统添加了登录验证码功能，显著提升了系统的安全性。

核心特性：
✅ 密码输错2次后自动显示验证码
✅ 前台和后台登录均支持
✅ 验证码可点击刷新
✅ 基于IP和用户名双重防护
✅ 失败5次封锁30分钟

二、使用方法
----------------------------------

1. 正常登录流程：
   - 输入用户名和密码
   - 点击"登录"按钮
   - 如果密码正确，直接登录成功

2. 触发验证码流程：
   - 第1次密码错误：提示"用户名或密码错误"
   - 第2次密码错误：提示"用户名或密码错误"
   - 第3次尝试：自动显示验证码输入框
   - 输入验证码和密码
   - 点击"登录"按钮

3. 验证码操作：
   - 看不清？点击图片刷新验证码
   - 验证码是4位纯数字
   - 验证码有效期5分钟

三、技术实现
----------------------------------

后端改动：
1. 安装依赖：svg-captcha, express-session
2. 新增API：GET /api/captcha (生成验证码)
3. 修改API：POST /api/login (验证码验证)
4. 增强防爆破机制

前端改动：
1. 添加验证码显示区域
2. 添加验证码输入框
3. 实现自动触发逻辑
4. 支持点击刷新

四、文件清单
----------------------------------

修改的文件：
  backend/server.js          - 后端主文件
  backend/package.json       - 依赖配置
  frontend/app.html          - 前端页面
  frontend/app.js            - 前端逻辑

新增的文件：
  CAPTCHA_FEATURE.md         - 详细功能文档
  CAPTCHA_README.md          - 快速开始指南
  test_captcha.sh            - 测试脚本
  更新说明_验证码功能.txt    - 本文件

五、启动说明
----------------------------------

1. 安装依赖（如果尚未安装）：
   cd backend
   npm install

2. 启动后端服务：
   cd backend
   node server.js

3. 访问系统：
   打开浏览器访问 http://localhost:40001

六、测试方法
----------------------------------

方法1：浏览器手动测试
1. 访问登录页面
2. 输入任意用户名和错误密码
3. 连续点击"登录"按钮2次
4. 第3次尝试时应该看到验证码

方法2：自动化测试脚本
   ./test_captcha.sh

七、配置调整（可选）
----------------------------------

1. 修改验证码触发次数：
   编辑 backend/server.js 第683行附近
   const needCaptcha = ipFailures >= 2 || usernameFailures >= 2;
   修改 >= 2 为你想要的次数

2. 修改防爆破参数：
   编辑 backend/server.js 第394行附近
   const loginLimiter = new RateLimiter({
     maxAttempts: 5,                // 最大失败次数
     windowMs: 15 * 60 * 1000,      // 15分钟
     blockDuration: 30 * 60 * 1000  // 封锁30分钟
   });

3. 设置Session密钥（生产环境推荐）：
   编辑 backend/.env 文件
   SESSION_SECRET=your-random-secret-key

八、安全建议
----------------------------------

✅ 已实现的安全措施：
- 验证码采用SVG格式，防止OCR识别
- 验证码存储在服务器端Session
- 验证码有5分钟有效期
- 基于IP和用户名双重防护
- 失败5次自动封锁30分钟

🔒 建议的额外措施：
- 在生产环境设置强随机SESSION_SECRET
- 启用HTTPS并设置COOKIE_SECURE=true
- 定期检查登录日志
- 考虑添加登录通知功能

九、故障排查
----------------------------------

问题1：验证码不显示
解决：
- 确认后端服务已启动
- 检查浏览器控制台错误
- 确认已输错密码至少2次

问题2：验证码一直错误
解决：
- 刷新验证码重试
- 检查浏览器是否禁用Cookie
- 清除浏览器缓存

问题3：验证码API 500错误
解决：
- 检查依赖是否安装：npm list svg-captcha express-session
- 重新安装：npm install
- 查看后端日志

十、技术支持
----------------------------------

详细文档：
- CAPTCHA_FEATURE.md  - 完整功能说明和技术文档
- CAPTCHA_README.md   - 快速入门指南

测试工具：
- test_captcha.sh     - 自动化测试脚本

遇到问题：
1. 查看后端日志
2. 检查浏览器控制台
3. 运行测试脚本
4. 查看详细文档

====================================
更新完成！享受更安全的云存储体验！
====================================