用户登录

接口信息

• 接口路径: /api/auth/login
• 请求方法: POST
• Content-Type: application/json
• 是否需要认证: 否

请求参数

请求体 (Body)

参数名	类型	必填	说明
username	string	是	用户名（至少3个字符）
password	string	是	密码（至少6个字符）
verifyToken	string	否	滑动验证码 Token
verifyData	object	否	滑动验证数据

verifyData 对象

参数名	类型	必填	说明
trackData	string	否	滑动轨迹数据
slideTime	number	否	滑动时间（毫秒）
accuracy	number	否	滑动精度

请求示例

基础登录

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456"
  }'

带滑动验证码的登录

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456",
    "verifyToken": "abc123",
    "verifyData": {
      "trackData": "[[10,20,100],[30,40,200]]",
      "slideTime": 1500,
      "accuracy": 0.95
    }
  }'

响应示例

成功响应

{
  "success": true,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@demo.com",
      "nickname": "演示管理员",
      "avatar": null,
      "bio": null,
      "role": "admin",
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    },
    "rateLimitInfo": {
      "remaining": 4,
      "resetTime": "2025-01-24T12:30:00.000Z"
    }
  }
}

错误响应

参数验证失败

{
  "success": false,
  "message": "用户名和密码不能为空"
}

登录失败

{
  "success": false,
  "message": "用户名或密码错误"
}

请求过于频繁

{
  "success": false,
  "message": "该账户尝试次数过多，请稍后再试"
}

滑动验证失败

{
  "success": false,
  "message": "滑动验证失败，请重试"
}

安全机制

1. 频率限制

系统实现了多级频率限制机制：

• IP 级限流: 默认 5 次/15分钟
• 用户名级限流: 默认 3 次/15分钟
• 严格模式: 无验证码时 3 次/10分钟

2. 滑动验证码

当触发限流时，需要完成滑动验证码：

• 滑动验证码 Token
• 滑动轨迹数据
• 滑动时间
• 滑动精度

验证成功后会重置频率限制计数器。

3. IP 获取

系统按优先级获取客户端真实 IP：

1. X-Forwarded-For 头（代理服务器）
2. X-Real-IP 头
3. CF-Connecting-IP 头（Cloudflare）
4. Socket 远程地址

Cookie 设置

登录成功后，后端会设置以下 Cookie：

Set-Cookie: auth_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; Path=/; Max-Age=604800; SameSite=Strict; HttpOnly

• 名称: auth_token
• 值: JWT Token
• 路径: /
• 有效期: 7 天（可通过 JWT_EXPIRES_IN 配置）
• SameSite: Strict（防止 CSRF）
• HttpOnly: 仅 HTTP 传输（防止 XSS）

JWT Token 结构

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "userId": 1,
    "username": "admin",
    "role": "admin",
    "iat": 1737705600,
    "exp": 1738310400
  }
}

使用场景

1. 普通登录

直接使用用户名和密码登录，适合正常用户使用。

2. 带验证码的登录

当触发频率限制时，前端应要求用户完成滑动验证码。

3. 前端集成示例

// 使用 fetch
async function login(username, password, verifyData = null) {
  const body = {
    username,
    password
  }
  
  if (verifyData) {
    body.verifyToken = verifyData.token
    body.verifyData = {
      trackData: verifyData.trackData,
      slideTime: verifyData.slideTime,
      accuracy: verifyData.accuracy
    }
  }
  
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify(body)
  })
  
  const result = await response.json()
  
  if (!result.success) {
    // 处理错误
    throw new Error(result.message)
  }
  
  // 登录成功
  return result.data.user
}

注意事项

1. 密码安全: 密码在前端不加密，使用 HTTPS 传输
2. Token 存储: Token 存储在 HttpOnly Cookie 中，无需前端手动存储
3. 限流处理: 前端应根据 rateLimitInfo 显示剩余尝试次数
4. 验证码: 滑动验证码为可选参数，高频触发时需要
5. IP 记录: 系统会记录登录 IP，用于安全分析

相关接口

• 退出登录
• 获取当前用户
• 忘记密码