用户管理 API 文档#

基础路径#

/user

接口列表#

用户登录#

POST /login

请求体

{
  username: string,  // 用户名
  password: string   // 密码
}

注意

• 限制速率：每15分钟最多100次请求

用户登出#

POST /logout

更新用户信息#

PUT /

请求体

{
  username: string,  // 用户名
  password: string   // 密码
}

获取用户信息#

GET /

两步验证相关#

初始化两步验证#

GET /two-factor/init

激活两步验证#

PUT /two-factor/active

请求体

{
  code: string  // 验证码
}

停用两步验证#

PUT /two-factor/deactivate

两步验证登录#

PUT /two-factor/login

请求体

{
  code: string,     // 验证码
  username: string, // 用户名
  password: string  // 密码
}

两步验证登录每 15 分钟最多 20 次请求。

登录日志#

GET /login-log

IP 黑名单#

GET /ip-blacklist 查询黑名单；PUT /ip-blacklist 加入黑名单；DELETE /ip-blacklist 移出黑名单。后两者使用 JSON 请求体：

{"ip":"192.0.2.1"}

ip 必填，支持单个 IPv4 或 IPv6 地址，不支持 CIDR 网段。

通知设置#

获取通知设置#

GET /notification

更新通知设置#

PUT /notification

初始化设置#

初始化用户信息#

PUT /init

请求体

{
  username: string,  // 用户名
  password: string   // 密码
}

初始化通知设置#

PUT /notification/init

更新头像#

PUT /avatar

请求体

• Content-Type: multipart/form-data
• 字段: avatar (文件)
• 仅允许一个文件，最大 5 MiB；支持 PNG、JPEG、GIF、WebP、AVIF，扩展名必须与 MIME 类型匹配。

错误处理#

• 所有接口遵循统一的错误处理机制
• 成功响应返回 { code: 200, data: ... }
• 错误日志由 Winston logger 处理

注意事项#

• 使用 celebrate/Joi 进行参数验证
• 文件上传使用 multer 处理
• 头像文件名使用 UUID 生成
• 演示环境下部分功能受限