网盘系统 API 接口文档

服务架构图

前端

→

Gateway:8888

→

User:8081

前端

→

Gateway

→

Drive:8082

前端

→

Gateway

→

TMDB:8083

路由规则

请求路径	转发服务	说明
/api/login, /api/register	user-service	登录注册
/api/token/, /api/login-logs/	user-service	令牌/日志
/api/users/**	user-service	用户管理
/api/profile/**	user-service	个人资料
/api/drive/**	drive-service	网盘管理
/api/icon/**	drive-service	Icon管理
/api/movies/**	tmdb-service	电影管理
/api/tmdb/, /api/tmdb-scraper/	tmdb-service	TMDB刮削

用户认证服务

wangpan-user-service : 8081

POST /api/login 用户登录

请求体

{
  "username": "用户名",
  "password": "密码"
}

成功响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "id": 7,
    "username": "lrq",
    "userType": 0,        // 0=普通用户, 1=VIP, 2=管理员
    "status": 1,
    "email": "xxx@xx.com",
    "phone": "138****0000",
    "realName": "张三",
    "avatarUrl": "",
    "lastLoginIp": "127.0.0.1",
    "lastLoginTime": "2026-06-10T11:20:21",
    "hasTmdbKey": false,
    "token": "tk_xxx...",
    "tokenType": "Bearer",
    "expireIn": 604800
  }
}

失败响应示例 — 用户名或密码错误

{
  "code": 400,
  "message": "用户名或密码错误",
  "data": null
}

失败响应示例 — 账号被禁用

{
  "code": 403,
  "message": "账号已被禁用，请联系管理员",
  "data": null
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "用户名和密码不能为空",
  "data": null
}

userType 说明

值	角色	权限说明
0	普通用户	仅访问自己的数据（如日志只看自己的）
1	VIP 用户	普通用户 + 更多存储空间
2	管理员	可查看所有用户数据（如全部日志）

POST /api/register 用户注册

请求体

{
  "username": "用户名",
  "password": "密码"
}

成功响应示例

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "id": 10,
    "username": "newuser"
  }
}

失败响应示例 — 用户名已存在

{
  "code": 409,
  "message": "用户名已被占用",
  "data": null
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "用户名和密码不能为空",
  "data": null
}

GET /api/token/validate 令牌验证

请求头

Authorization: Bearer <token>

成功响应示例 — Token 有效

{
  "code": 200,
  "message": "Token 有效",
  "data": {
    "valid": true,
    "userId": 7,
    "username": "lrq",
    "expireTime": "2026-06-17T11:20:21"
  }
}

失败响应示例 — Token 无效或已过期

{
  "code": 401,
  "message": "Token 无效或已过期",
  "data": null
}

GET /api/login-logs 登录日志查询需Token

权限说明

用户类型	可见范围
普通用户（userType=0/1）	仅自己的登录记录
管理员（userType=2）	所有用户的登录记录

查询参数

参数	类型	必填	说明
username	String	否	按用户名模糊筛选（管理员可用）
result	String	否	登录结果：success / fail
startDate	String	否	开始日期（含），格式：yyyy-MM-dd，如 2026-06-01
endDate	String	否	结束日期（含），格式：yyyy-MM-dd，如 2026-06-10
pageNo	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 20

提示：可组合使用多个筛选条件，如 ?result=fail&startDate=2026-06-01&endDate=2026-06-10

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 10,
    "list": [
      {
        "id": 1,
        "userId": 7,
        "username": "lrq",
        "loginIp": "127.0.0.1",
        "loginTime": "2026-06-10T11:20:21",
        "result": "success",
        "userAgent": "Mozilla/5.0..."
      }
    ],
    "pageNo": 1,
    "pageSize": 20
  }
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "权限不足，无法查看其他用户的登录日志",
  "data": null
}

用户管理

wangpan-user-service : 8081 仅管理员 (userType=2)

GET /api/users 查询用户列表需Token + 管理员

权限说明

角色	访问权限
普通/VIP 用户	403 权限不足
管理员	可查看所有用户列表

查询参数

参数	类型	必填	说明
username	String	否	用户名模糊搜索
status	int	否	状态：0=禁用, 1=正常, 2=锁定
userType	int	否	角色：0=普通, 1=VIP, 2=管理员
pageNo	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 20

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 5,
    "list": [
      { "id": 7, "username": "lrq", "userType": 0, "status": 1, ... }
    ],
    "pageNo": 1,
    "pageSize": 20
  }
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "权限不足，仅管理员可访问",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

POST /api/users 新增用户需Token + 管理员

请求体

{
  "username": "必填",
  "password": "必填",
  "email": "可选",
  "phone": "可选",
  "realName": "可选",
  "status": 1,       // 可选：0=禁用, 1=正常, 默认1
  "userType": 0      // 可选：0=普通, 1=VIP, 2=管理员, 默认0
}

成功响应

{
  "code": 200,
  "message": "用户创建成功",
  "data": {
    "id": 10,
    "username": "newuser",
    "email": "new@test.com",
    "status": 1,
    "userType": 0
  }
}

失败响应示例 — 用户名已存在

{
  "code": 409,
  "message": "用户名已被占用",
  "data": null
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "用户名或密码不能为空",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "非管理员，无权限操作",
  "data": null
}

失败响应示例 — 服务器错误

{
  "code": 500,
  "message": "服务器内部错误",
  "data": null
}

PUT /api/users/{userId} 修改用户信息需Token + 管理员

路径参数

参数	类型	说明
userId	Long	目标用户 ID

请求体（部分更新，只传需要修改的字段）

{
  "email": "新邮箱",     // 可选
  "phone": "新手机号",   // 可选
  "realName": "新姓名",   // 可选
  "status": 0,           // 可选：0=禁用, 1=正常, 2=锁定
  "userType": 1         // 可选：0=普通, 1=VIP, 2=管理员
}

成功响应

{
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "id": 10,
    "username": "newuser",
    "email": "new@test.com",
    "status": 1,
    "userType": 0
  }
}

失败响应示例 — 用户不存在

{
  "code": 404,
  "message": "目标用户不存在",
  "data": null
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "没有需要更新的字段",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "非管理员，无权限操作",
  "data": null
}

失败响应示例 — 服务器错误

{
  "code": 500,
  "message": "服务器内部错误",
  "data": null
}

DELETE /api/users/{userId} 删除用户（软删除）需Token + 管理员

路径参数

参数	类型	说明
userId	Long	要删除的用户 ID

说明

软删除操作，将 is_deleted 设为 1，不物理删除数据。

成功响应

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

失败响应示例 — 用户不存在

{
  "code": 404,
  "message": "目标用户不存在",
  "data": null
}

失败响应示例 — 删除失败

{
  "code": 400,
  "message": "删除失败，用户可能已被删除",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "非管理员，无权限操作",
  "data": null
}

失败响应示例 — 服务器错误

{
  "code": 500,
  "message": "服务器内部错误",
  "data": null
}

个人资料

wangpan-user-service : 8081

GET /api/profile 获取当前用户个人资料需Token

功能说明

获取当前登录用户的基本信息（不含密码等敏感字段）。

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "phone": "13800138000",
    "realName": "管理员",
    "avatarUrl": "http://...",
    "userType": 2,
    "status": 1,
    "createTime": "2024-01-01T00:00:00"
  }
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

失败响应示例 — 用户不存在

{
  "code": 404,
  "message": "用户不存在",
  "data": null
}

PUT /api/profile/username 修改用户名需Token

功能说明

修改当前登录用户的用户名。

校验规则：

用户名不能为空
新用户名不能与当前用户名相同
新用户名不能被其他用户占用

请求体

{
  "username": "新用户名"
}

成功响应示例

{
  "code": 200,
  "message": "用户名修改成功",
  "data": null
}

失败响应示例 — 用户名已存在

{
  "code": 409,
  "message": "用户名已被其他用户使用",
  "data": null
}

失败响应示例 — 参数错误

{
  "code": 400,
  "message": "新用户名不能为空或与当前用户名相同",
  "data": null
}

PUT /api/profile/avatar 修改头像需Token

功能说明

修改当前登录用户的头像。

流程：

接收 Base64 编码的图片数据
解析 MIME 类型和 Base64 内容
上传到 MinIO（路径：avatar/{userId}_{timestamp}.{ext}）
更新数据库中的 avatar_url 字段

支持的图片格式：PNG、JPG/JPEG、GIF、WebP

请求体

{
  "avatarData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

成功响应示例

{
  "code": 200,
  "message": "头像更新成功",
  "data": {
    "avatarUrl": "http://118.178.238.159:39000/wangpan/avatar/1_1719234567890.png?..."
  }
}

失败响应示例 — 图片格式不支持

{
  "code": 400,
  "message": "不支持的图片格式，仅支持 PNG、JPG、GIF、WebP",
  "data": null
}

失败响应示例 — MinIO 上传失败

{
  "code": 500,
  "message": "头像上传失败，请稍后重试",
  "data": null
}

网盘管理服务

wangpan-drive-service : 8082

POST /api/drive 创建网盘需Token

请求体

{
  "name": "网盘名称",
  "description": "网盘描述",
  "logoData": "data:image/png;base64,iVBOR..."
}

参数说明

参数	类型	必填	说明
name	String	是	网盘名称
description	String	否	网盘描述
logoData	String	否	Logo图片Base64编码，支持 data:image/xxx;base64, 前缀格式，上传后存储到MinIO，数据库仅保存URL

成功响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "name": "我的网盘",
    "description": "个人网盘",
    "logoUrl": "http://118.178.238.159:39000/wangpan/drive/1/logo.png",
    "createTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "网盘名称不能为空",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

GET /api/drive 查询网盘列表需Token

查询参数

参数	默认值	说明
pageNo	1	页码
pageSize	20	每页条数

响应字段

字段	类型	说明
id	Long	网盘ID
name	String	网盘名称
description	String	网盘描述
logoUrl	String	网盘Logo图片链接（MinIO存储地址）
folderCount	Integer	文件夹数量
fileCount	Integer	文件数量
totalSize	Long	总大小（字节）
status	String	状态
createTime	String	创建时间
updateTime	String	更新时间

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 2,
    "list": [
      {
        "id": 1,
        "name": "我的网盘",
        "description": "个人网盘",
        "logoUrl": "http://118.178.238.159:39000/wangpan/drive/1/logo.png",
        "folderCount": 5,
        "fileCount": 20,
        "totalSize": 10737418240,
        "status": "active",
        "createTime": "2026-06-26T10:00:00",
        "updateTime": "2026-06-26T10:00:00"
      }
    ],
    "pageNo": 1,
    "pageSize": 20
  }
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

GET /api/drive/{id} 查询网盘详情需Token

路径参数

参数	类型	说明
id	Long	网盘ID

响应字段

字段	类型	说明
id	Long	网盘ID
name	String	网盘名称
description	String	网盘描述
logoUrl	String	网盘Logo图片链接（MinIO存储地址）
folderCount	Integer	文件夹数量
fileCount	Integer	文件数量
totalSize	Long	总大小（字节）
status	String	状态
createTime	String	创建时间
updateTime	String	更新时间

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "name": "我的网盘",
    "description": "个人网盘",
    "logoUrl": "http://118.178.238.159:39000/wangpan/drive/1/logo.png",
    "folderCount": 5,
    "fileCount": 20,
    "totalSize": 10737418240,
    "status": "active",
    "createTime": "2026-06-26T10:00:00",
    "updateTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

PUT /api/drive/{id} 更新网盘需Token

请求体

{
  "name": "新网盘名称",
  "description": "新描述",
  "logoData": "data:image/png;base64,iVBOR..."
}

参数说明

参数	类型	必填	说明
name	String	否	网盘名称
description	String	否	网盘描述
logoData	String	否	新的Logo图片Base64编码，传入后覆盖旧Logo；不传则保留原Logo

成功响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "新网盘名称",
    "description": "新描述",
    "logoUrl": "http://118.178.238.159:39000/wangpan/drive/1/logo.png",
    "updateTime": "2026-06-26T11:00:00"
  }
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "无权修改该网盘",
  "data": null
}

DELETE /api/drive/{id} 删除网盘需Token

路径参数

参数	类型	说明
id	Long	网盘ID

成功响应示例

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "无权删除该网盘",
  "data": null
}

POST /api/drive/{driveId}/folders 创建文件夹需Token

请求体

{
  "name": "文件夹名称",
  "parentId": 0
}

成功响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "parentId": 0,
    "name": "我的电影",
    "description": "",
    "depth": 0,
    "createTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "文件夹名称不能为空",
  "data": null
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

GET /api/drive/{driveId}/folders 查询文件夹列表需Token

查询参数

参数	默认值	说明
parentId	0	父文件夹 ID

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "driveId": 1,
      "parentId": 0,
      "name": "我的电影",
      "description": "",
      "depth": 0,
      "childFolderCount": 2,
      "fileCount": 5,
      "createTime": "2026-06-26T10:00:00"
    }
  ]
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

GET /api/drive/{driveId}/folders/{folderId} 查询文件夹详情需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
folderId	Long	文件夹ID

响应字段

字段	类型	说明
id	Long	文件夹ID
driveId	Long	所属网盘ID
parentId	Long	父文件夹ID（0表示根目录）
name	String	文件夹名称
description	String	文件夹描述
depth	Integer	层级深度
childFolderCount	Integer	子文件夹数量
fileCount	Integer	文件数量
totalSize	Long	总大小（字节）
createTime	String	创建时间
updateTime	String	更新时间

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "parentId": 0,
    "name": "我的电影",
    "description": "收藏的电影",
    "depth": 0,
    "childFolderCount": 2,
    "fileCount": 5,
    "totalSize": 5368709120,
    "createTime": "2026-06-26T10:00:00",
    "updateTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 文件夹不存在

{
  "code": 404,
  "message": "文件夹不存在",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

PUT /api/drive/{driveId}/folders/{folderId} 更新文件夹需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
folderId	Long	文件夹ID

请求体（部分更新）

{
  "name": "新文件夹名称",
  "description": "新描述",
  "parentId": 0
}

参数说明

参数	类型	必填	说明
name	String	否	文件夹名称
description	String	否	文件夹描述
parentId	Long	否	父文件夹ID（可移动文件夹）

成功响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "parentId": 0,
    "name": "新文件夹名称",
    "description": "新描述",
    "updateTime": "2026-06-26T11:00:00"
  }
}

失败响应示例 — 文件夹不存在

{
  "code": 404,
  "message": "文件夹不存在",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "无权修改该文件夹",
  "data": null
}

DELETE /api/drive/{driveId}/folders/{folderId} 删除文件夹需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
folderId	Long	文件夹ID

说明

删除文件夹前会检查文件夹是否为空，如果包含子文件夹或电影文件则拒绝删除。

错误码

code	说明
400	文件夹不为空或数据库操作失败
401	未登录或Token无效
403	无权访问该文件夹

POST /api/drive/{driveId}/movies 创建电影（只传文件名）需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID

请求体

{
  "title": "文件名.mp4",     // 必填，文件名（同时作为电影标题）
  "folderId": 0                // 可选，默认0（根目录）
}

参数说明

参数	类型	必填	说明
title	String	是	文件名（同时作为电影标题，后续通过 TMDB 刮削补充信息）
folderId	Long	否	目标文件夹ID，默认0（根目录）

说明

只记录文件名，不上传文件数据。创建后通过 TMDB 刮削接口补充电影的海报、描述、评分等信息。自动检测 MIME 类型（mp4/mkv/avi → video/mp4）。

成功响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "folderId": 0,
    "title": "电影.mp4",
    "originalName": "电影.mp4",
    "mimeType": "video/mp4",
    "createTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 参数缺失

{
  "code": 400,
  "message": "文件名不能为空",
  "data": null
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

GET /api/drive/{driveId}/folders/{folderId}/movies 查询电影文件列表需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
folderId	Long	文件夹ID（0表示根目录）

查询参数

参数	默认值	说明
pageNo	1	页码
pageSize	20	每页条数（最大100）

响应字段

字段	类型	说明
list[].id	Long	电影ID
list[].title	String	电影名称
list[].originalName	String	原始文件名
list[].mimeType	String	MIME类型
list[].fileSize	Long	文件大小（字节）
list[].extension	String	文件扩展名
list[].minioUrl	String	MinIO文件访问URL
list[].rating	Integer	评分
list[].tags	String	标签
total	Integer	总数
pageNo	Integer	当前页码
pageSize	Integer	每页条数

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 5,
    "pageNo": 1,
    "pageSize": 20,
    "list": [
      {
        "id": 1,
        "title": "电影.mp4",
        "originalName": "电影.mp4",
        "mimeType": "video/mp4",
        "fileSize": 1073741824,
        "extension": "mp4",
        "minioUrl": "http://...",
        "rating": 85,
        "tags": "动作,科幻"
      }
    ]
  }
}

失败响应示例 — 网盘不存在

{
  "code": 404,
  "message": "网盘不存在",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

GET /api/drive/{driveId}/movies/{movieId} 查询电影文件详情需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
movieId	Long	电影ID

响应字段

字段	类型	说明
id	Long	电影ID
driveId	Long	所属网盘ID
folderId	Long	所属文件夹ID
title	String	电影名称
subtitle	String	副标题
originalName	String	原始文件名
mimeType	String	MIME类型
fileSize	Long	文件大小（字节）
extension	String	文件扩展名
description	String	描述
resourceLibrary	String	资源库
maintainer	String	维护者
status	String	状态
category	String	分类
scrapeType	String	刮削类型
rating	Integer	评分
tags	String	标签
minioUrl	String	MinIO文件访问URL
posterUrl	String	海报URL
createTime	String	创建时间
updateTime	String	更新时间

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "folderId": 0,
    "title": "电影.mp4",
    "subtitle": "副标题",
    "originalName": "电影.mp4",
    "mimeType": "video/mp4",
    "fileSize": 1073741824,
    "extension": "mp4",
    "description": "电影描述",
    "rating": 85,
    "tags": "动作,科幻",
    "posterUrl": "http://...",
    "minioUrl": "http://...",
    "createTime": "2026-06-26T10:00:00",
    "updateTime": "2026-06-26T10:00:00"
  }
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

PUT /api/drive/{driveId}/movies/{movieId} 更新电影文件信息需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
movieId	Long	电影ID

请求体（部分更新，所有字段可选）

{
  "title": "新电影名称",
  "originalName": "新文件名.mp4",
  "subtitle": "新副标题",
  "description": "新描述",
  "rating": 90,
  "tags": "新标签",
  "category": "新分类"
}

参数说明

参数	类型	说明
title	String	电影名称
originalName	String	原始文件名（用于 TMDB 刮削有误时修改）
subtitle	String	副标题
description	String	描述
rating	Integer	评分 0-100
tags	String	标签
category	String	分类

说明

用于 TMDB 刮削有误时，用户可自定义修改文件名等信息。所有字段均为可选，只更新传入的字段。

成功响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "title": "新电影名称",
    "rating": 90,
    "updateTime": "2026-06-26T11:00:00"
  }
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "无权修改该电影",
  "data": null
}

DELETE /api/drive/{driveId}/movies/{movieId} 删除电影文件需Token

路径参数

参数	类型	说明
driveId	Long	网盘ID
movieId	Long	电影ID

说明

逻辑删除（软删除），删除后自动更新网盘和文件夹的统计信息。

成功响应示例

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在",
  "data": null
}

失败响应示例 — 权限不足

{
  "code": 403,
  "message": "无权删除该电影",
  "data": null
}

GET /api/drive/movies/duplicates 检查重复电影需Token

功能说明

查询当前用户所有网盘下所有文件夹中的电影，按标题（title）分组找出重复的电影。返回每组重复电影的详细信息，包括所在文件夹的完整路径，前端可让用户选择删除其中一个。

成功响应

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "duplicateGroups": [
      {
        "title": "电影名称",
        "count": 2,
        "movies": [
          {
            "id": 10,
            "driveId": 1,
            "folderId": 5,
            "title": "电影名称",
            "originalName": "电影名称.mp4",
            "fileSize": 1073741824,
            "extension": "mp4",
            "category": "sci-fi",
            "rating": 85,
            "createTime": "2025-01-01T10:00:00",
            "folderPath": "我的电影库/科幻/2024"
          },
          {
            "id": 20,
            "driveId": 1,
            "folderId": 8,
            "title": "电影名称",
            "originalName": "电影名称.mkv",
            "fileSize": 2147483648,
            "extension": "mkv",
            "category": "sci-fi",
            "rating": null,
            "createTime": "2025-02-01T15:00:00",
            "folderPath": "我的电影库/动作"
          }
        ]
      }
    ],
    "totalGroups": 1,
    "totalDuplicates": 2
  }
}

返回字段说明

字段	类型	说明
duplicateGroups	Array	重复电影分组列表
duplicateGroups[].title	String	重复的电影标题
duplicateGroups[].count	Integer	该标题下的重复数量
duplicateGroups[].movies	Array	该标题下的所有电影记录
duplicateGroups[].movies[].id	Long	电影ID（可用于删除接口）
duplicateGroups[].movies[].folderPath	String	所在文件夹完整路径，如"网盘名/文件夹1/文件夹2"
totalGroups	Integer	重复组总数
totalDuplicates	Integer	涉及重复的电影总数

错误码

code	说明
401	未登录或 Token 无效
500	服务器内部错误

Icon 管理服务

wangpan-drive-service : 8082

POST /api/icon 创建 Icon需Token

请求体（JSON）

字段	类型	必填	说明
name	String	是	Icon 名称（最大100字符）
url	String	条件必填	外网链接 URL（最大500字符，linkType为external或both时必填）
internalUrl	String	条件必填	内网链接 URL（最大500字符，linkType为internal或both时必填）
linkType	String	否	链接类型：external（仅外网，默认）/ internal（仅内网）/ both（内外网）
description	String	否	Icon 描述（最大500字符）
sortOrder	Integer	否	排序值，数字越小越靠前，默认0

请求示例（仅外网）

{
  "name": "百度",
  "url": "https://www.baidu.com",
  "linkType": "external",
  "description": "搜索引擎",
  "sortOrder": 1
}

请求示例（内外网都有）

{
  "name": "内部系统",
  "url": "https://system.example.com",
  "internalUrl": "http://192.168.1.100:8080",
  "linkType": "both",
  "description": "内部管理系统",
  "sortOrder": 2
}

成功响应（200）

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "name": "百度",
    "url": "https://www.baidu.com",
    "internalUrl": null,
    "linkType": "external",
    "description": "搜索引擎",
    "sortOrder": 1,
    "status": "active",
    "logoUrl": "http://118.178.238.159:39000/wangpan/icons/2/1718265600000.png",
    "createTime": "2026-06-13T16:00:00"
  }
}

GET /api/icon 查询当前用户的 Icon 列表需Token

功能说明

查询当前登录用户的所有 Icon，按 sortOrder 升序、createTime 降序排列。每个用户只能看到自己创建的 Icon。

成功响应（200）

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "百度",
        "url": "https://www.baidu.com",
        "internalUrl": null,
        "linkType": "external",
        "description": "搜索引擎",
        "sortOrder": 1,
        "status": "active",
        "logoUrl": "http://118.178.238.159:39000/wangpan/icons/2/1718265600000.png",
        "createTime": "2026-06-13T16:00:00",
        "updateTime": "2026-06-13T16:00:00"
      }
    ],
    "total": 1
  }
}

GET /api/icon/{id} 查询单个 Icon 详情需Token

路径参数

参数	类型	说明
id	Long	Icon ID

成功响应（200）

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "name": "百度",
    "url": "https://www.baidu.com",
    "internalUrl": null,
    "linkType": "external",
    "description": "搜索引擎",
    "sortOrder": 1,
    "status": "active",
    "logoUrl": "http://118.178.238.159:39000/wangpan/icons/2/1718265600000.png",
    "createTime": "2026-06-13T16:00:00",
    "updateTime": "2026-06-13T16:00:00"
  }
}

失败响应示例 — Icon 不存在

{
  "code": 404,
  "message": "Icon 不存在或无权访问",
  "data": null
}

失败响应示例 — 未登录

{
  "code": 401,
  "message": "未登录或 Token 无效",
  "data": null
}

PUT /api/icon/{id} 更新 Icon需Token

路径参数

参数	类型	说明
id	Long	Icon ID

请求体（JSON，所有字段可选）

字段	类型	说明
name	String	Icon 名称
url	String	外网链接
internalUrl	String	内网链接
linkType	String	链接类型：external / internal / both
description	String	Icon 描述
sortOrder	Integer	排序值

请求示例

{
  "name": "新名称",
  "url": "https://new-url.com",
  "internalUrl": "http://192.168.1.100:8080",
  "linkType": "both",
  "sortOrder": 2
}

成功响应（200）

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "新名称",
    "url": "https://new-url.com",
    "internalUrl": "http://192.168.1.100:8080",
    "linkType": "both",
    "description": "搜索引擎",
    "sortOrder": 2,
    "status": "active",
    "logoUrl": "http://118.178.238.159:39000/wangpan/icons/2/1718265600000.png",
    "createTime": "2026-06-13T16:00:00",
    "updateTime": "2026-06-13T17:00:00"
  }
}

错误码

code	说明
401	未登录或 Token 无效
500	Icon 不存在或无权修改

DELETE /api/icon/{id} 删除 Icon需Token

路径参数

参数	类型	说明
id	Long	Icon ID

成功响应（200）

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

错误码

code	说明
401	未登录或 Token 无效
500	Icon 不存在或无权删除

POST /api/icon/{id}/logo 上传自定义图标图片需Token

功能说明

上传自定义图标图片替换自动抓取的 logo。上传后会自动删除旧的 MinIO 图片，防止硬盘空间浪费。系统每 24 小时自动清理无用图片。

路径参数

参数	类型	说明
id	Long	Icon ID

请求格式

multipart/form-data

字段	类型	必填	说明
file	File	是	图片文件（png/jpg/jpeg/gif/webp/ico，最大 1MB）

请求示例（curl）

curl -X POST http://localhost:8888/api/icon/1/logo \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/icon.png"

成功响应（200）

{
  "code": 200,
  "message": "图标上传成功",
  "data": {
    "id": 1,
    "name": "百度",
    "logoUrl": "http://118.178.238.159:39000/wangpan/icons/2/1718265600000.png",
    "updateTime": "2026-06-15T10:00:00"
  }
}

失败响应示例 — 文件为空

{
  "code": 400,
  "message": "上传文件为空",
  "data": null
}

失败响应示例 — 文件格式不支持

{
  "code": 400,
  "message": "不支持的文件格式，仅支持 png/jpg/jpeg/gif/webp/ico",
  "data": null
}

失败响应示例 — 文件超过 1MB

{
  "code": 400,
  "message": "文件大小超过限制（最大 1MB）",
  "data": null
}

失败响应示例 — Icon 不存在

{
  "code": 404,
  "message": "Icon 不存在",
  "data": null
}

TMDB 刮削服务

wangpan-tmdb-service : 8083

GET /api/movies/recommend 今日推荐（每天固定3部电影）需Token

功能说明

从当前用户的电影库中随机抽取3部电影用于首页展示。

推荐规则：

从 00:00 到 23:59 返回固定的3部电影
当天不管查询多少次都返回相同的结果
第二天 00:00 后重新随机挑选3部
推荐结果缓存在 wp_daily_recommend 表中

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 10,
        "title": "电影名称1",
        "subtitle": "副标题",
        "posterUrl": "海报URL",
        "rating": 85,
        "category": "动作",
        "tags": "标签1,标签2",
        "createTime": "2025-01-01T10:00:00"
      },
      {
        "id": 20,
        "title": "电影名称2",
        ...
      },
      {
        "id": 30,
        "title": "电影名称3",
        ...
      }
    ],
    "count": 3
  }
}

返回字段说明

字段	类型	说明
list	Array	推荐的电影列表（最多3部）
list[].id	Long	电影ID
list[].title	String	电影标题
list[].subtitle	String	副标题
list[].posterUrl	String	海报URL
list[].rating	Integer	评分（0-100）
list[].category	String	分类
list[].tags	String	标签
list[].createTime	String	创建时间
count	Integer	实际返回的电影数量（可能小于3）

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

失败响应示例 — 服务器内部错误

{
  "code": 500,
  "message": "服务器内部错误，请稍后重试",
  "data": null
}

GET /api/movies 电影列表查询（按文件夹分组，每组最多10条）需Token

功能说明

从 wp_drive_movie 表查询当前用户所有电影，按文件夹分组返回，每个文件夹最多返回 10 条电影数据。支持分页：pageNo 控制文件夹分页。

查询参数

参数	类型	必填	说明
keyword	String	否	搜索关键词
status	String	否	电影状态：active（正常）/ deleted（已删除）
scrapeType	String	否	刮削类型：tmdb / manual / none
sortBy	String	否	排序字段（如 createTime、rating、title）
sortOrder	String	否	排序方向：asc / desc
pageNo	int	否	页码，默认 1
pageSize	int	否	每页条数（文件夹数），默认 20

响应字段说明

字段	类型	说明
totalFolders	Integer	文件夹总数
pageNo	Integer	当前页码
pageSize	Integer	每页条数
folderGroups[].folderId	Long	文件夹ID
folderGroups[].movieCount	Integer	该文件夹下返回的电影数量
folderGroups[].movies[].id	Long	电影ID
folderGroups[].movies[].driveId	Long	所属网盘ID
folderGroups[].movies[].folderId	Long	所属文件夹ID
folderGroups[].movies[].title	String	电影名称
folderGroups[].movies[].subtitle	String	副标题
folderGroups[].movies[].originalName	String	原始文件名
folderGroups[].movies[].mimeType	String	MIME类型
folderGroups[].movies[].fileSize	Long	文件大小（字节）
folderGroups[].movies[].extension	String	文件扩展名
folderGroups[].movies[].description	String	描述
folderGroups[].movies[].scrapeStatus	String	刮削状态
folderGroups[].movies[].rating	Integer	评分（0-100）
folderGroups[].movies[].tags	String	标签
folderGroups[].movies[].posterUrl	String	竖版海报URL（2:3 比例）
folderGroups[].movies[].backdropUrl	String	横版背景图URL（16:9 比例）
folderGroups[].movies[].minioUrl	String	MinIO 文件访问URL
folderGroups[].movies[].createTime	String	创建时间
folderGroups[].movies[].updateTime	String	更新时间

响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "totalFolders": 5,
    "pageNo": 1,
    "pageSize": 20,
    "folderGroups": [
      {
        "folderId": 3,
        "movieCount": 2,
        "movies": [
          {
            "id": 1,
            "driveId": 1,
            "folderId": 3,
            "title": "肖申克的救赎",
            "posterUrl": "http://...:39000/wangpan/posters/1/poster_xxx.jpg",
            "backdropUrl": "http://...:39000/wangpan/posters/1/backdrop_xxx.jpg",
            "rating": 93,
            ...
          }
        ]
      }
    ]
  }
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

失败响应示例 — 参数错误

{
  "code": 400,
  "message": "请求参数错误",
  "data": null
}

GET /api/movies/{id} 电影详情查询需Token

功能说明

查询单部电影的完整详情信息，包括基本信息、海报、评分等。

路径参数

参数	类型	说明
id	Long	电影ID

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "driveId": 1,
    "folderId": 3,
    "title": "肖申克的救赎",
    "subtitle": "The Shawshank Redemption",
    "originalName": "肖申克的救赎.mp4",
    "mimeType": "video/mp4",
    "fileSize": 2147483648,
    "extension": "mp4",
    "description": "电影描述",
    "scrapeStatus": "success",
    "rating": 93,
    "posterUrl": "http://...:39000/wangpan/posters/1/poster_xxx.jpg",
    "backdropUrl": "http://...:39000/wangpan/posters/1/backdrop_xxx.jpg",
    "tags": "剧情,犯罪",
    "createTime": "2025-01-01T10:00:00",
    "updateTime": "2025-01-15T10:00:00"
  }
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在或无权访问",
  "data": null
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

GET /api/movies/{id}/scrape-status 查询单部电影刮削状态需Token

功能说明

查询单部电影的刮削状态，返回三种状态：刮削中（scraping）、刮削失败（failed）、刮削成功（success）。

路径参数

参数	类型	说明
id	Long	电影ID

响应字段说明

字段	类型	说明
movieId	Long	电影ID
title	String	电影名称
status	String	刮削状态：scraping / failed / success / unknown
message	String	状态描述信息
error	String	失败原因（仅 status=failed 时返回）
posterUrl	String	竖版海报URL（仅 status=success 时返回）
backdropUrl	String	横版背景图URL（仅 status=success 时返回）
rating	Integer	评分（仅 status=success 时返回）
category	String	分类（仅 status=success 时返回）
tags	String	标签（仅 status=success 时返回）

响应示例 - 刮削中

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "movieId": 1,
    "title": "电影名称",
    "status": "scraping",
    "message": "正在刮削中，请稍候..."
  }
}

响应示例 - 刮削失败

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "movieId": 1,
    "title": "电影名称",
    "status": "failed",
    "message": "刮削失败",
    "error": "TMDB API 请求失败"
  }
}

响应示例 - 刮削成功

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "movieId": 1,
    "title": "电影名称",
    "status": "success",
    "message": "刮削成功",
    "posterUrl": "http://...:39000/wangpan/posters/1/poster_xxx.jpg",
    "backdropUrl": "http://...:39000/wangpan/posters/1/backdrop_xxx.jpg",
    "rating": 85,
    "category": "动作",
    "tags": "动作,科幻"
  }
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在或无权访问",
  "data": null
}

POST /api/movies 创建电影需Token

功能说明

创建新的电影记录，title 为必填字段。

请求体（所有字段可选，title 必填）

{
  "title": "电影名称",           // 必填
  "subtitle": "副标题",         // 可选
  "resourceLibrary": "资源库", // 可选
  "maintainer": "维护者",       // 可选
  "status": "active",          // 可选：active / deleted
  "category": "动作",           // 可选
  "scrapeType": "tmdb",          // 可选：tmdb / manual / none
  "rating": 85,                 // 可选：0-100
  "posterUrl": "海报URL",       // 可选
  "tags": "标签1,标签2"       // 可选
}

成功响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "title": "电影名称",
    "subtitle": "副标题",
    "createTime": "2025-01-01T10:00:00"
  }
}

失败响应示例 — 缺少必填字段

{
  "code": 400,
  "message": "电影名称不能为空",
  "data": null
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

PUT /api/movies/{id} 更新电影需Token

功能说明

更新指定电影的信息，支持部分更新。

路径参数

参数	类型	说明
id	Long	电影ID

请求体（部分更新，所有字段可选）

{
  "title": "新电影名称",
  "subtitle": "新副标题",
  "resourceLibrary": "新资源库",
  "maintainer": "新维护者",
  "status": "active",
  "category": "新分类",
  "scrapeType": "tmdb",
  "rating": 90,
  "posterUrl": "新海报URL",
  "tags": "新标签"
}

成功响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "title": "新电影名称",
    "updateTime": "2025-01-15T10:00:00"
  }
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在",
  "data": null
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

DELETE /api/movies/{id} 删除电影需Token

功能说明

删除指定的电影记录。

路径参数

参数	类型	说明
id	Long	电影ID

成功响应示例

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

失败响应示例 — 电影不存在

{
  "code": 404,
  "message": "电影不存在",
  "data": null
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

POST /api/movies/batch-delete 批量删除电影需Token

功能说明

批量删除多个电影记录。

请求体

{ "ids": [1, 2, 3] }

成功响应示例

{
  "code": 200,
  "message": "批量删除成功",
  "data": {
    "deletedCount": 3
  }
}

失败响应示例 — 参数错误

{
  "code": 400,
  "message": "电影ID列表不能为空",
  "data": null
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

GET /api/movies/stats 电影统计需Token

功能说明

获取当前用户的电影数量统计，按刮削类型和分类分组。

响应示例

{
  "code": 200,
  "data": {
    "totalCount": 10,
    "scrapedCount": 8,
    "pendingCount": 2
  }
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

GET /api/tmdb/key 获取 TMDB API Key需Token

功能说明

获取当前用户配置的 TMDB API Key。

成功响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "tmdbApiKey": "your_api_key_here"
  }
}

失败响应示例 — 未登录或 Token 无效

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}

POST /api/tmdb/key 设置 TMDB API Key需Token

请求体

{ "tmdbApiKey": "你的API Key" }

POST /api/tmdb-scraper/scrape 单部电影刮削需Token

请求方式

支持两种方式传递 movieId：

1. URL 查询参数：?movieId=1

2. 请求体 JSON：

{ "movieId": 1 }

响应示例

{
  "code": 200,
  "message": "刮削完成",
  "data": {
    "movieId": 1,
    "title": "电影名称",
    "rating": 85,
    "posterUrl": "海报URL"
  }
}

POST /api/tmdb-scraper/batch-scrape 批量刮削需Token

请求体（movieIds 可选）

{ "movieIds": [1, 2, 3] }  // 可选：不传则自动查找需要刮削的电影

响应示例

{
  "code": 200,
  "message": "批量刮削完成",
  "data": {
    "successCount": 2,
    "failCount": 0,
    "total": 2
  }
}

GET /api/tmdb-scraper/caches 查询缓存列表需Token

查询参数

参数	默认值	说明
pageNo	1	页码
pageSize	20	每页条数

GET /api/tmdb-scraper/stats 刮削统计需Token

响应示例

{
  "code": 200,
  "data": {
    "totalCaches": 5,
    "activeCaches": 3,
    "expiredCaches": 2,
    "userId": 2
  }
}

POST /api/tmdb-scraper/trigger 手动触发定时任务需Token

功能说明

手动触发 TMDB 定时扫描任务，查找需要刮削的电影并执行刮削。无需请求体。

响应示例

{
  "code": 200,
  "message": "扫描任务已触发",
  "data": {
    "message": "扫描任务已触发",
    "triggeredBy": 2,
    "triggerType": "manual"
  }
}

GET /api/tmdb-scraper/scraper-logs 查询刮削日志需Token

查询参数

参数	默认值	说明
pageNo	1	页码
pageSize	20	每页条数

响应示例

{
  "code": 200,
  "data": {
    "total": 10,
    "list": [
      {
        "id": 1,
        "scanTime": "2026-06-18T10:00:00",
        "totalMovies": 5,
        "successCount": 4,
        "failCount": 1
      }
    ],
    "pageNo": 1,
    "pageSize": 20
  }
}

DELETE /api/tmdb-scraper/cache/{movieId} 删除缓存需Token

路径参数

参数	类型	说明
movieId	Long	电影ID

功能说明

删除指定电影的 TMDB 刮削缓存，下次刮削时将重新从 TMDB 获取数据。

响应示例

{
  "code": 200,
  "message": "缓存删除成功",
  "data": null
}

通用响应格式

{
  "code": 200,
  "message": "操作结果描述",
  "data": { ... }
}

状态码说明

状态码	说明
200	请求成功
400	请求参数错误
401	未授权 / 令牌无效
403	权限不足
404	资源不存在
500	服务器内部错误

认证说明

除以下 3 个接口 外，所有接口都需要在请求头中携带访问令牌：

无需 Token 的接口：
  POST /api/login  用户登录
  POST /api/register  用户注册
  GET /api/token/validate?token=xxx  令牌验证（token 通过 URL 参数传递）

需要 Token 的接口（带需Token 标识）：
  在请求头中添加：Authorization: Bearer <token>