网盘系统 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/drive/**	drive-service	网盘管理
/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
  }
}

userType 说明

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

POST /api/register 用户注册

请求体

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

GET /api/token/validate 令牌验证

请求头

Authorization: Bearer <token>

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

用户管理

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,
  "data": {
    "total": 5,
    "list": [
      { "id": 7, "username": "lrq", "userType": 0, "status": 1, ... }
    ],
    "pageNo": 1,
    "pageSize": 20
  }
}

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	说明
400	用户名或密码为空
409	用户名已被占用
401	未登录或 Token 无效
403	非管理员，无权限操作
500	服务器内部错误

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	目标用户不存在
400	没有需要更新的字段
403	非管理员
500	服务器内部错误

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

路径参数

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

说明

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

成功响应

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

错误码

code	说明
404	目标用户不存在
400	删除失败（可能已被删除）
403	非管理员
500	服务器内部错误

网盘管理服务

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

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	更新时间

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	更新时间

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

请求体

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

参数说明

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

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

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

请求体

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

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

查询参数

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

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	更新时间

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

路径参数

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

请求体（部分更新）

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

参数说明

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

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": "电影名称",        // 必填
  "folderId": 0,               // 可选，默认0（根目录）
  "subtitle": "副标题",           // 可选
  "description": "描述",        // 可选
  "fileData": "Base64编码的文件数据", // 必填
  "rating": 85,                  // 可选，评分0-100
  "tags": "标签1,标签2"          // 可选
}

参数说明

参数	类型	必填	说明
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）。

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	每页条数

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	更新时间

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

路径参数

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

请求体（部分更新）

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

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

路径参数

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

说明

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

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"
  }
}

错误码

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

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 不存在或无权删除

TMDB 刮削服务

wangpan-tmdb-service : 8083

GET /api/movies/recommend 今日推荐（随机推荐3部电影）需Token

功能说明

从当前用户的电影库中随机抽取3部电影用于首页展示，每次请求返回不同的推荐结果。

成功响应示例

{
  "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）

错误码

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

GET /api/movies 电影列表查询需Token

查询参数

参数	类型	必填	说明
keyword	String	否	搜索关键词
status	String	否	pending / scraped / failed
category	String	否	分类
scrapeType	String	否	刮削类型
pageNo	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 20

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

POST /api/movies 创建电影需Token

请求体

{ "title": "电影名称" }

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

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

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

请求体

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

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

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

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

请求体

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

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

请求体

{ "movieId": 1 }

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

请求体

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

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

查询参数

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

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

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

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

查询参数

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

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

通用响应格式

{
  "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>