认证管理API

认证管理API提供用户认证、权限管理和API密钥管理的功能，支持JWT Token和API Key两种认证方式。

1. 基础路径

所有认证管理API的基础路径为：/api/v1/auth

2. 认证方式

本API部分支持匿名访问的接口（如登录、注册），其他接口需要通过JWT Token认证。

3. 登录接口

3.1 用户登录

请求URL：/api/v1/auth/login

请求方法：POST

请求头：

Content-Type: application/json

请求体：

{
  "username": "admin",
  "password": "password123",
  "remember_me": false
}

参数说明：

username：用户名，必填
password：密码，必填
remember_me：是否记住登录状态，可选，默认为false

响应示例：

{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2023-06-01T12:00:00Z",
    "user_info": {
      "id": "1",
      "username": "admin",
      "email": "admin@example.com",
      "roles": ["admin", "user"],
      "permissions": ["read", "write", "admin"]
    }
  }
}

3.2 刷新Token

请求URL：/api/v1/auth/refresh

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求体：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

参数说明：

token：当前的JWT Token，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2023-06-02T12:00:00Z"
  }
}

3.3 登出

请求URL：/api/v1/auth/logout

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应示例：

{
  "success": true,
  "code": 200,
  "message": "登出成功",
  "data": {}
}

4. 用户管理接口

4.1 获取用户列表

请求URL：/api/v1/auth/users

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求参数：

page：页码，默认1
page_size：每页数量，默认20
username：用户名搜索，可选
email：邮箱搜索，可选
status：状态筛选，可选（active/inactive/locked）

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "users": [
      {
        "id": "1",
        "username": "admin",
        "email": "admin@example.com",
        "status": "active",
        "roles": ["admin", "user"],
        "created_at": "2023-01-01T00:00:00Z",
        "last_login": "2023-05-01T12:00:00Z"
      },
      ...
    ]
  }
}

4.2 获取用户详情

请求URL：/api/v1/auth/users/{user_id}

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

user_id：用户ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": "1",
    "username": "admin",
    "email": "admin@example.com",
    "status": "active",
    "roles": ["admin", "user"],
    "permissions": ["read", "write", "admin"],
    "profile": {
      "real_name": "管理员",
      "phone": "13800138000",
      "department": "IT运维部",
      "position": "高级运维工程师"
    },
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-05-01T00:00:00Z",
    "last_login": "2023-05-01T12:00:00Z",
    "login_count": 100
  }
}

4.3 创建用户

请求URL：/api/v1/auth/users

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

请求体：

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "Password123!",
  "roles": ["user"],
  "profile": {
    "real_name": "新用户",
    "phone": "13900139000",
    "department": "开发部",
    "position": "开发工程师"
  }
}

参数说明：

username：用户名，必填
email：邮箱，必填
password：密码，必填，需要符合密码复杂度要求
roles：角色列表，必填
profile：用户资料，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "用户创建成功",
  "data": {
    "id": "2",
    "username": "newuser",
    "email": "newuser@example.com",
    "status": "active",
    "roles": ["user"],
    "created_at": "2023-05-01T13:00:00Z"
  }
}

4.4 更新用户信息

请求URL：/api/v1/auth/users/{user_id}

请求方法：PUT

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

路径参数：

user_id：用户ID，必填

请求体：

{
  "email": "updated@example.com",
  "roles": ["user", "analyst"],
  "status": "active",
  "profile": {
    "real_name": "更新用户",
    "phone": "13700137000",
    "department": "数据分析部",
    "position": "数据分析师"
  }
}

响应示例：

{
  "success": true,
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "id": "2",
    "username": "newuser",
    "email": "updated@example.com",
    "status": "active",
    "roles": ["user", "analyst"],
    "updated_at": "2023-05-01T14:00:00Z"
  }
}

4.5 删除用户

请求URL：/api/v1/auth/users/{user_id}

请求方法：DELETE

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

user_id：用户ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "用户删除成功",
  "data": {}
}

4.6 修改密码

请求URL：/api/v1/auth/users/{user_id}/password

请求方法：PUT

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

路径参数：

user_id：用户ID，必填

请求体：

{
  "current_password": "Password123!",
  "new_password": "NewPassword456!"
}

参数说明：

current_password：当前密码，必填
new_password：新密码，必填，需要符合密码复杂度要求

响应示例：

{
  "success": true,
  "code": 200,
  "message": "密码修改成功",
  "data": {}
}

4.7 重置密码

请求URL：/api/v1/auth/users/{user_id}/reset-password

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

路径参数：

user_id：用户ID，必填

请求体：

{
  "send_email": true
}

参数说明：

send_email：是否发送重置邮件，可选，默认为true

响应示例：

{
  "success": true,
  "code": 200,
  "message": "密码重置成功，新密码已发送至用户邮箱",
  "data": {
    "temporary_password": "TempPass789!",
    "expires_in": 86400
  }
}

5. 角色管理接口

5.1 获取角色列表

请求URL：/api/v1/auth/roles

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求参数：

page：页码，默认1
page_size：每页数量，默认20
name：角色名称搜索，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "roles": [
      {
        "id": "1",
        "name": "admin",
        "description": "系统管理员",
        "permissions": ["read", "write", "admin"],
        "created_at": "2023-01-01T00:00:00Z",
        "user_count": 5
      },
      {
        "id": "2",
        "name": "user",
        "description": "普通用户",
        "permissions": ["read", "write"],
        "created_at": "2023-01-01T00:00:00Z",
        "user_count": 100
      },
      ...
    ]
  }
}

5.2 获取角色详情

请求URL：/api/v1/auth/roles/{role_id}

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

role_id：角色ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": "1",
    "name": "admin",
    "description": "系统管理员",
    "permissions": ["read", "write", "admin"],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-05-01T00:00:00Z",
    "user_count": 5
  }
}

5.3 创建角色

请求URL：/api/v1/auth/roles

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

请求体：

{
  "name": "analyst",
  "description": "数据分析人员",
  "permissions": ["read", "report", "analytics"]
}

参数说明：

name：角色名称，必填
description：角色描述，可选
permissions：权限列表，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "角色创建成功",
  "data": {
    "id": "3",
    "name": "analyst",
    "description": "数据分析人员",
    "permissions": ["read", "report", "analytics"],
    "created_at": "2023-05-01T15:00:00Z"
  }
}

5.4 更新角色

请求URL：/api/v1/auth/roles/{role_id}

请求方法：PUT

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

路径参数：

role_id：角色ID，必填

请求体：

{
  "name": "senior-analyst",
  "description": "高级数据分析人员",
  "permissions": ["read", "report", "analytics", "export"]
}

响应示例：

{
  "success": true,
  "code": 200,
  "message": "角色更新成功",
  "data": {
    "id": "3",
    "name": "senior-analyst",
    "description": "高级数据分析人员",
    "permissions": ["read", "report", "analytics", "export"],
    "updated_at": "2023-05-01T16:00:00Z"
  }
}

5.5 删除角色

请求URL：/api/v1/auth/roles/{role_id}

请求方法：DELETE

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

role_id：角色ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "角色删除成功",
  "data": {}
}

5.6 获取角色关联的用户

请求URL：/api/v1/auth/roles/{role_id}/users

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

role_id：角色ID，必填

请求参数：

page：页码，默认1
page_size：每页数量，默认20

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 5,
    "page": 1,
    "page_size": 20,
    "users": [
      {
        "id": "1",
        "username": "admin",
        "email": "admin@example.com",
        "status": "active",
        "added_at": "2023-01-01T00:00:00Z"
      },
      ...
    ]
  }
}

6. API密钥管理接口

6.1 获取API密钥列表

请求URL：/api/v1/auth/api-keys

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求参数：

page：页码，默认1
page_size：每页数量，默认20
name：密钥名称搜索，可选
status：状态筛选，可选（active/inactive/expired）

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "api_keys": [
      {
        "id": "1",
        "name": "Integration Key",
        "key_prefix": "ak_123456",
        "status": "active",
        "permissions": ["read", "write"],
        "created_by": "admin",
        "created_at": "2023-01-01T00:00:00Z",
        "expires_at": "2024-01-01T00:00:00Z",
        "last_used_at": "2023-05-01T12:00:00Z"
      },
      ...
    ]
  }
}

6.2 创建API密钥

请求URL：/api/v1/auth/api-keys

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

请求体：

{
  "name": "New Integration Key",
  "description": "用于第三方系统集成",
  "permissions": ["read", "metrics", "logs"],
  "expires_in_days": 365
}

参数说明：

name：密钥名称，必填
description：密钥描述，可选
permissions：权限列表，必填
expires_in_days：过期天数，可选，默认为365天

响应示例：

{
  "success": true,
  "code": 200,
  "message": "API密钥创建成功",
  "data": {
    "id": "2",
    "name": "New Integration Key",
    "key": "ak_1234567890abcdef1234567890abcdef12345678",
    "permissions": ["read", "metrics", "logs"],
    "created_at": "2023-05-01T17:00:00Z",
    "expires_at": "2024-05-01T17:00:00Z"
  }
}

注意：API密钥只在创建时显示一次，请妥善保存。

6.3 禁用API密钥

请求URL：/api/v1/auth/api-keys/{key_id}/disable

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

key_id：API密钥ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "API密钥已禁用",
  "data": {
    "id": "2",
    "status": "inactive",
    "disabled_at": "2023-05-01T18:00:00Z"
  }
}

6.4 启用API密钥

请求URL：/api/v1/auth/api-keys/{key_id}/enable

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

key_id：API密钥ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "API密钥已启用",
  "data": {
    "id": "2",
    "status": "active",
    "enabled_at": "2023-05-01T19:00:00Z"
  }
}

6.5 删除API密钥

请求URL：/api/v1/auth/api-keys/{key_id}

请求方法：DELETE

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

key_id：API密钥ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "API密钥已删除",
  "data": {}
}

6.6 获取API密钥使用统计

请求URL：/api/v1/auth/api-keys/{key_id}/stats

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

路径参数：

key_id：API密钥ID，必填

请求参数：

time_range：时间范围，可选，默认为7d

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total_requests": 1000,
    "success_requests": 950,
    "error_requests": 50,
    "daily_stats": [
      {"date": "2023-04-25", "requests": 120},
      {"date": "2023-04-26", "requests": 150},
      ...
    ],
    "top_endpoints": [
      {"endpoint": "/api/v1/metrics", "count": 500},
      {"endpoint": "/api/v1/logs", "count": 300},
      ...
    ],
    "last_used_at": "2023-05-01T12:00:00Z",
    "last_ip": "192.168.1.100"
  }
}

7. 权限管理接口

7.1 获取权限列表

请求URL：/api/v1/auth/permissions

请求方法：GET

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求参数：

page：页码，默认1
page_size：每页数量，默认20
name：权限名称搜索，可选
category：权限分类筛选，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 50,
    "page": 1,
    "page_size": 20,
    "permissions": [
      {
        "id": "1",
        "name": "read",
        "category": "general",
        "description": "读取数据权限",
        "created_at": "2023-01-01T00:00:00Z"
      },
      {
        "id": "2",
        "name": "write",
        "category": "general",
        "description": "写入数据权限",
        "created_at": "2023-01-01T00:00:00Z"
      },
      ...
    ]
  }
}

7.2 创建权限

请求URL：/api/v1/auth/permissions

请求方法：POST

请求头：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

请求体：

{
  "name": "export",
  "category": "data",
  "description": "导出数据权限"
}

参数说明：

name：权限名称，必填
category：权限分类，可选
description：权限描述，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "权限创建成功",
  "data": {
    "id": "51",
    "name": "export",
    "category": "data",
    "description": "导出数据权限",
    "created_at": "2023-05-01T20:00:00Z"
  }
}

8. 常见问题

8.1 登录失败

问题：登录接口返回401错误

可能原因：

用户名或密码错误
用户账号已被锁定
用户账号已过期
IP地址限制

解决方案：

确认用户名和密码是否正确
联系管理员检查账号状态
检查是否在允许的IP地址范围内登录

8.2 Token过期

问题：API调用返回401错误，提示Token过期

解决方案：

使用刷新Token接口获取新的Token
重新登录获取新的Token

8.3 权限不足

问题：API调用返回403错误，提示权限不足

解决方案：

确认当前用户是否有执行该操作的权限
联系管理员检查角色和权限配置
对于API密钥，检查密钥的权限范围