服务架构图
+路由规则
+| 请求路径 | 转发服务 | 说明 |
|---|---|---|
| /api/login, /api/register | user-service | 登录注册 |
| /api/token/**, /api/login-logs/** | user-service | 令牌/日志 |
| /api/drive/** | drive-service | 网盘管理 |
| /api/movies/** | tmdb-service | 电影管理 |
| /api/tmdb/**, /api/tmdb-scraper/** | tmdb-service | TMDB刮削 |
用户认证服务
+ wangpan-user-service : 8081 +请求体
+成功响应示例
+userType 说明
+| 值 | 角色 | 权限说明 |
|---|---|---|
| 0 | 普通用户 | 仅访问自己的数据(如日志只看自己的) |
| 1 | VIP 用户 | 普通用户 + 更多存储空间 |
| 2 | 管理员 | 可查看所有用户数据(如全部日志) |
请求体
+请求头
+权限说明
+| 用户类型 | 可见范围 |
|---|---|
| 普通用户(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
+用户管理
+ wangpan-user-service : 8081 + 仅管理员 (userType=2) +权限说明
+| 角色 | 访问权限 |
|---|---|
| 普通/VIP 用户 | 403 权限不足 |
| 管理员 | 可查看所有用户列表 |
查询参数
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | String | 否 | 用户名模糊搜索 |
| status | int | 否 | 状态:0=禁用, 1=正常, 2=锁定 |
| userType | int | 否 | 角色:0=普通, 1=VIP, 2=管理员 |
| pageNo | int | 否 | 页码,默认 1 |
| pageSize | int | 否 | 每页条数,默认 20 |
响应示例
+请求体
+成功响应
+错误码
+| code | 说明 |
|---|---|
| 400 | 用户名或密码为空 |
| 409 | 用户名已被占用 |
| 401 | 未登录或 Token 无效 |
| 403 | 非管理员,无权限操作 |
| 500 | 服务器内部错误 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| userId | Long | 目标用户 ID |
请求体(部分更新,只传需要修改的字段)
+成功响应
+错误码
+| code | 说明 |
|---|---|
| 404 | 目标用户不存在 |
| 400 | 没有需要更新的字段 |
| 403 | 非管理员 |
| 500 | 服务器内部错误 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| userId | Long | 要删除的用户 ID |
说明
+软删除操作,将 is_deleted 设为 1,不物理删除数据。
成功响应
+错误码
+| code | 说明 |
|---|---|
| 404 | 目标用户不存在 |
| 400 | 删除失败(可能已被删除) |
| 403 | 非管理员 |
| 500 | 服务器内部错误 |
网盘管理服务
+ wangpan-drive-service : 8082 +请求体
+参数说明
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 网盘名称 |
| description | String | 否 | 网盘描述 |
| logoData | String | 否 | Logo图片Base64编码,支持 data:image/xxx;base64, 前缀格式,上传后存储到MinIO,数据库仅保存URL |
查询参数
+| 参数 | 默认值 | 说明 |
|---|---|---|
| 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 | 更新时间 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| 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 | 更新时间 |
请求体
+参数说明
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 否 | 网盘名称 |
| description | String | 否 | 网盘描述 |
| logoData | String | 否 | 新的Logo图片Base64编码,传入后覆盖旧Logo;不传则保留原Logo |
请求体
+查询参数
+| 参数 | 默认值 | 说明 |
|---|---|---|
| parentId | 0 | 父文件夹 ID |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| 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 | 更新时间 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| driveId | Long | 网盘ID |
| folderId | Long | 文件夹ID |
请求体(部分更新)
+参数说明
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 否 | 文件夹名称 |
| description | String | 否 | 文件夹描述 |
| parentId | Long | 否 | 父文件夹ID(可移动文件夹) |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| driveId | Long | 网盘ID |
| folderId | Long | 文件夹ID |
说明
+删除文件夹前会检查文件夹是否为空,如果包含子文件夹或电影文件则拒绝删除。
+错误码
+| code | 说明 |
|---|---|
| 400 | 文件夹不为空或数据库操作失败 |
| 401 | 未登录或Token无效 |
| 403 | 无权访问该文件夹 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| driveId | Long | 网盘ID |
请求体
+参数说明
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | String | 是 | 电影名称(同时作为文件名) |
| folderId | Long | 否 | 目标文件夹ID,默认0(根目录) |
| subtitle | String | 否 | 副标题 |
| description | String | 否 | 描述 |
| fileData | String | 是 | Base64编码的视频文件数据 |
| rating | Integer | 否 | 评分 |
| tags | String | 否 | 标签 |
说明
+文件通过 Base64 编码上传,服务端解码后存储到 MinIO,返回文件访问 URL。自动检测 MIME 类型(mp4/mkv/avi → video/mp4)。
+路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| 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 | 每页条数 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| 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 | 更新时间 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| driveId | Long | 网盘ID |
| movieId | Long | 电影ID |
请求体(部分更新)
+路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| driveId | Long | 网盘ID |
| movieId | Long | 电影ID |
说明
+逻辑删除(软删除),删除后自动更新网盘和文件夹的统计信息。
+功能说明
+查询当前用户所有网盘下所有文件夹中的电影,按标题(title)分组找出重复的电影。返回每组重复电影的详细信息,包括所在文件夹的完整路径,前端可让用户选择删除其中一个。
+成功响应
+返回字段说明
+| 字段 | 类型 | 说明 |
|---|---|---|
| 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 +请求体(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 |
请求示例(仅外网)
+请求示例(内外网都有)
+成功响应(200)
+功能说明
+查询当前登录用户的所有 Icon,按 sortOrder 升序、createTime 降序排列。每个用户只能看到自己创建的 Icon。
+成功响应(200)
+路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| id | Long | Icon ID |
成功响应(200)
+错误码
+| code | 说明 |
|---|---|
| 401 | 未登录或 Token 无效 |
| 500 | Icon 不存在或无权访问 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| id | Long | Icon ID |
请求体(JSON,所有字段可选)
+| 字段 | 类型 | 说明 |
|---|---|---|
| name | String | Icon 名称 |
| url | String | 外网链接 |
| internalUrl | String | 内网链接 |
| linkType | String | 链接类型:external / internal / both |
| description | String | Icon 描述 |
| sortOrder | Integer | 排序值 |
请求示例
+成功响应(200)
+错误码
+| code | 说明 |
|---|---|
| 401 | 未登录或 Token 无效 |
| 500 | Icon 不存在或无权修改 |
路径参数
+| 参数 | 类型 | 说明 |
|---|---|---|
| id | Long | Icon ID |
成功响应(200)
+错误码
+| code | 说明 |
|---|---|
| 401 | 未登录或 Token 无效 |
| 500 | Icon 不存在或无权删除 |
TMDB 刮削服务
+ wangpan-tmdb-service : 8083 +功能说明
+从当前用户的电影库中随机抽取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) |
错误码
+| code | 说明 |
|---|---|
| 401 | 未登录或 Token 无效 |
| 500 | 服务器内部错误 |
查询参数
+| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | String | 否 | 搜索关键词 |
| status | String | 否 | pending / scraped / failed |
| category | String | 否 | 分类 |
| scrapeType | String | 否 | 刮削类型 |
| pageNo | int | 否 | 页码,默认 1 |
| pageSize | int | 否 | 每页条数,默认 20 |
请求体
+请求体
+请求体
+请求体
+请求体
+查询参数
+| 参数 | 默认值 | 说明 |
|---|---|---|
| pageNo | 1 | 页码 |
| pageSize | 20 | 每页条数 |
查询参数
+| 参数 | 默认值 | 说明 |
|---|---|---|
| pageNo | 1 | 页码 |
| pageSize | 20 | 每页条数 |
通用响应格式
+状态码说明
+| 状态码 | 说明 |
|---|---|
| 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>
+