700 lines
15 KiB
Markdown
700 lines
15 KiB
Markdown
# API 参考文档
|
||
|
||
本文档是当前后端接口边界的快速参考，不是 OpenAPI 替代品。
|
||
目标是帮助开发、重构、测试和 Code Review 快速回答三个问题：
|
||
|
||
- 这个能力现在走哪组接口
|
||
- 这组接口是否需要登录或管理员身份
|
||
- 这组接口当前属于稳定主线、兼容保留，还是正在迁移中的边界
|
||
|
||
如果接口细节和本文档冲突，以当前控制器和安全配置为准：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/config/SecurityConfig.java`
|
||
- `backend/src/main/java/com/yoyuzh/**/**/*Controller.java`
|
||
|
||
## 1. 接口分层总览
|
||
|
||
### 1.1 公开接口
|
||
|
||
无需登录即可访问：
|
||
|
||
- `/api/auth/**`
|
||
- `/api/app/android/**`
|
||
- `GET /api/v2/site/ping`
|
||
- `GET /api/v2/shares/{token}`
|
||
- `GET /api/v2/shares/{token}?download`
|
||
- `POST /api/v2/shares/{token}/verify-password`
|
||
- `/api/transfer/**`
|
||
- `GET /api/files/share-links/{token}`
|
||
- `/`
|
||
|
||
注意：
|
||
|
||
- `/api/transfer/**` 在安全层面是公开的，但其中“发送离线快传”“查看自己的离线快传”“导入到网盘”等操作会在控制器或业务层再要求登录。
|
||
|
||
### 1.2 登录后接口
|
||
|
||
需要 Bearer Token：
|
||
|
||
- `/api/user/**`
|
||
- `/api/files/**`
|
||
- `/api/v2/files/**`
|
||
- `/api/v2/tasks/**`
|
||
- `POST /api/v2/shares`
|
||
- `GET /api/v2/shares/mine`
|
||
- `DELETE /api/v2/shares/{id}`
|
||
- `POST /api/v2/shares/{token}/import`
|
||
|
||
### 1.3 管理接口
|
||
|
||
- `/api/admin/**`
|
||
|
||
要求：
|
||
|
||
- 已登录
|
||
- 通过 `@adminAccessEvaluator.isAdmin(authentication)` 校验
|
||
|
||
当前管理员事实源：
|
||
|
||
- 当前由 `@adminAccessEvaluator.isAdmin(authentication)` 统一判定。
|
||
- 实际判定基于认证里的角色 authority，而不是用户名白名单。
|
||
- 当前允许进入 `/api/admin/**` 的角色是 `ROLE_MODERATOR` 与 `ROLE_ADMIN`。
|
||
- 因此这里已经不再依赖 `app.admin.usernames` 作为管理权限来源。
|
||
|
||
## 2. 认证与用户模块
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/auth/AuthController.java`
|
||
- `backend/src/main/java/com/yoyuzh/auth/DevAuthController.java`
|
||
- `backend/src/main/java/com/yoyuzh/auth/UserController.java`
|
||
|
||
### 2.1 `POST /api/auth/register`
|
||
|
||
用途：
|
||
|
||
- 注册并直接签发登录态
|
||
|
||
关键规则：
|
||
|
||
- 需要邀请码
|
||
- 用户名、邮箱、手机号必须唯一
|
||
- 成功注册后自动创建默认目录
|
||
- 支持可选请求头 `X-Yoyuzh-Client: desktop|mobile`
|
||
|
||
### 2.2 `POST /api/auth/login`
|
||
|
||
用途：
|
||
|
||
- 普通登录
|
||
|
||
关键规则：
|
||
|
||
- 支持可选 `X-Yoyuzh-Client`
|
||
- 同一用户桌面端和移动端可以同时在线
|
||
- 同一客户端类型再次登录会挤掉旧会话
|
||
|
||
### 2.3 `POST /api/auth/refresh`
|
||
|
||
用途：
|
||
|
||
- 刷新 access token 和 refresh token
|
||
|
||
关键规则：
|
||
|
||
- refresh token 会旋转，旧 token 失效
|
||
- 默认按 `desktop` 兜底
|
||
- 若 refresh token 本身带有客户端类型，则沿用原客户端类型
|
||
|
||
### 2.4 `POST /api/auth/dev-login`
|
||
|
||
用途：
|
||
|
||
- 开发环境免密登录
|
||
|
||
约束：
|
||
|
||
- 仅 `dev` profile 下可用
|
||
- 支持可选 `X-Yoyuzh-Client`
|
||
|
||
### 2.5 `GET /api/user/profile`
|
||
|
||
用途：
|
||
|
||
- 获取当前登录用户资料
|
||
|
||
### 2.6 `PUT /api/user/profile`
|
||
|
||
用途：
|
||
|
||
- 修改个人资料
|
||
|
||
关键规则：
|
||
|
||
- 邮箱、手机号仍需保持唯一
|
||
|
||
### 2.7 `POST /api/user/password`
|
||
|
||
用途：
|
||
|
||
- 用户自行修改密码
|
||
|
||
关键规则：
|
||
|
||
- 旧密码必须正确
|
||
- 修改后旧会话和旧 refresh token 失效
|
||
- 会重新签发新的登录态
|
||
|
||
### 2.8 头像接口
|
||
|
||
- `POST /api/user/avatar/upload/initiate`
|
||
- `POST /api/user/avatar/upload`
|
||
- `POST /api/user/avatar/upload/complete`
|
||
- `GET /api/user/avatar/content`
|
||
|
||
用途：
|
||
|
||
- 用户头像上传与读取
|
||
|
||
关键规则：
|
||
|
||
- 头像属于资料域，不属于普通网盘目录
|
||
- 支持直传初始化和代理上传
|
||
- 完成上传时会替换旧头像引用
|
||
|
||
## 3. Android 发布接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/config/AndroidReleaseController.java`
|
||
|
||
### 3.1 `GET /api/app/android/latest`
|
||
|
||
用途：
|
||
|
||
- 获取最新 Android 安装包元信息
|
||
|
||
特点：
|
||
|
||
- 公开接口
|
||
- 读取后端当前发布元数据
|
||
|
||
### 3.2 下载接口
|
||
|
||
- `GET /api/app/android/download`
|
||
- `GET /api/app/android/download/{fileName}`
|
||
|
||
用途：
|
||
|
||
- 下载当前或指定名称的 Android 安装包
|
||
|
||
特点：
|
||
|
||
- 公开接口
|
||
|
||
## 4. 网盘主接口（旧主线，仍在使用）
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/files/core/FileController.java`
|
||
|
||
这组接口仍然是当前网盘主业务入口，尤其是：
|
||
|
||
- 列表
|
||
- 目录创建
|
||
- 文件操作
|
||
- 下载
|
||
- 回收站
|
||
- 旧分享接口
|
||
|
||
### 4.1 上传接口
|
||
|
||
- `POST /api/files/upload`
|
||
- `POST /api/files/upload/initiate`
|
||
- `POST /api/files/upload/complete`
|
||
|
||
用途：
|
||
|
||
- 兼容旧上传流程
|
||
|
||
当前定位：
|
||
|
||
- 仍可用
|
||
- 但新上传主线已经转向 v2 上传会话
|
||
|
||
关键规则：
|
||
|
||
- 路径和文件名必须合法
|
||
- 同目录禁止重名
|
||
- 受系统限制、用户限制、默认存储策略限制共同约束
|
||
|
||
### 4.2 目录与列表
|
||
|
||
- `POST /api/files/mkdir`
|
||
- `GET /api/files/list`
|
||
- `GET /api/files/recent`
|
||
|
||
用途：
|
||
|
||
- 创建目录
|
||
- 分页列目录
|
||
- 最近文件
|
||
|
||
关键规则：
|
||
|
||
- `path` 必须是合法目录路径
|
||
- 创建目录时根目录 `/` 不能再次创建
|
||
|
||
### 4.3 下载
|
||
|
||
- `GET /api/files/download/{fileId}`
|
||
- `GET /api/files/download/{fileId}/url`
|
||
|
||
用途：
|
||
|
||
- 下载文件或目录压缩包
|
||
- 获取可直接下载的 URL
|
||
|
||
关键规则：
|
||
|
||
- 目录下载会被压缩为 zip
|
||
- 普通文件优先返回直链或重定向
|
||
- 特定公开安装包走专用下载逻辑
|
||
|
||
### 4.4 文件操作
|
||
|
||
- `PATCH /api/files/{fileId}/rename`
|
||
- `PATCH /api/files/{fileId}/move`
|
||
- `POST /api/files/{fileId}/copy`
|
||
- `DELETE /api/files/{fileId}`
|
||
|
||
用途：
|
||
|
||
- 重命名
|
||
- 移动
|
||
- 复制
|
||
- 删除
|
||
|
||
关键规则：
|
||
|
||
- `DELETE` 语义是“移入回收站”，不是立即物理删除
|
||
- 目录不能移动或复制到自己或自己的子目录
|
||
- 所有写操作都要经过同名冲突和配额判断
|
||
|
||
### 4.5 回收站
|
||
|
||
- `GET /api/files/recycle-bin`
|
||
- `POST /api/files/recycle-bin/{fileId}/restore`
|
||
|
||
用途：
|
||
|
||
- 查看回收站根条目
|
||
- 恢复回收站条目
|
||
|
||
关键规则：
|
||
|
||
- 恢复按整组恢复
|
||
- 恢复前检查原路径冲突和配额
|
||
|
||
### 4.6 旧分享接口
|
||
|
||
- `POST /api/files/{fileId}/share-links`
|
||
- `GET /api/files/share-links/{token}`
|
||
- `POST /api/files/share-links/{token}/import`
|
||
|
||
用途：
|
||
|
||
- 旧版分享创建、查看、导入
|
||
|
||
当前定位：
|
||
|
||
- 仍存在
|
||
- 但新分享主线已经转向 `/api/v2/shares/**`
|
||
|
||
注意：
|
||
|
||
- 旧接口和 v2 分享接口能力并不完全一致
|
||
- 后续开发应优先确认是否继续沿用这套接口
|
||
|
||
## 5. v2 文件接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/files/UploadSessionV2Controller.java`
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/files/FileSearchV2Controller.java`
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/files/FileEventsV2Controller.java`
|
||
|
||
这组接口当前承担的是“新能力”而不是完整替代旧 `/api/files/**`。
|
||
|
||
### 5.1 v2 上传会话
|
||
|
||
- `POST /api/v2/files/upload-sessions`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}`
|
||
- `DELETE /api/v2/files/upload-sessions/{sessionId}`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}/prepare`
|
||
- `POST /api/v2/files/upload-sessions/{sessionId}/content`
|
||
- `GET /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}/prepare`
|
||
- `PUT /api/v2/files/upload-sessions/{sessionId}/parts/{partIndex}`
|
||
- `POST /api/v2/files/upload-sessions/{sessionId}/complete`
|
||
|
||
用途：
|
||
|
||
- 统一上传会话生命周期
|
||
|
||
上传模式：
|
||
|
||
- `PROXY`
|
||
- `DIRECT_SINGLE`
|
||
- `DIRECT_MULTIPART`
|
||
|
||
关键规则：
|
||
|
||
- 上传模式由默认存储策略能力决定
|
||
- 会话只属于创建者
|
||
- 已完成、已取消、已过期、已失败会话不能继续上传
|
||
- multipart 必须先准备分片上传，再记录分片，再完成会话
|
||
|
||
### 5.2 文件搜索
|
||
|
||
- `GET /api/v2/files/search`
|
||
|
||
用途：
|
||
|
||
- 组合条件搜索当前用户文件
|
||
|
||
支持条件：
|
||
|
||
- 名称
|
||
- 类型 `file|directory|all`
|
||
- 大小上下界
|
||
- 创建时间上下界
|
||
- 更新时间上下界
|
||
- 分页
|
||
|
||
### 5.3 文件事件流
|
||
|
||
- `GET /api/v2/files/events`
|
||
|
||
用途：
|
||
|
||
- SSE 订阅文件变更事件
|
||
|
||
关键参数：
|
||
|
||
- `path`，默认 `/`
|
||
- 可选请求头 `X-Yoyuzh-Client-Id`
|
||
|
||
## 6. v2 分享接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/shares/ShareV2Controller.java`
|
||
|
||
这是当前更完整的分享接口组。
|
||
|
||
### 6.1 创建与管理
|
||
|
||
- `POST /api/v2/shares`
|
||
- `GET /api/v2/shares/mine`
|
||
- `DELETE /api/v2/shares/{id}`
|
||
|
||
用途：
|
||
|
||
- 创建分享
|
||
- 查看自己创建的分享
|
||
- 删除自己的分享
|
||
|
||
关键规则：
|
||
|
||
- 当前只支持文件，不支持目录
|
||
- 可设置密码、过期时间、最大次数、是否允许下载、是否允许导入
|
||
|
||
### 6.2 公共访问
|
||
|
||
- `GET /api/v2/shares/{token}`
|
||
- `GET /api/v2/shares/{token}?download`
|
||
- `POST /api/v2/shares/{token}/verify-password`
|
||
|
||
用途：
|
||
|
||
- 查看分享
|
||
- 下载分享
|
||
- 验证密码
|
||
|
||
关键规则：
|
||
|
||
- 公开可访问
|
||
- 过期或次数耗尽后失效
|
||
- 有密码时需要先验密，或下载时携带密码
|
||
|
||
### 6.3 导入分享
|
||
|
||
- `POST /api/v2/shares/{token}/import`
|
||
|
||
用途：
|
||
|
||
- 把分享文件导入自己的网盘
|
||
|
||
关键规则：
|
||
|
||
- 必须登录
|
||
- 受 `allowImport` 开关控制
|
||
- 当前实现中会消耗同一个分享次数额度
|
||
|
||
## 7. 快传接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/transfer/TransferController.java`
|
||
|
||
### 7.1 会话创建与查询
|
||
|
||
- `POST /api/transfer/sessions`
|
||
- `GET /api/transfer/sessions/lookup`
|
||
- `POST /api/transfer/sessions/{sessionId}/join`
|
||
|
||
用途：
|
||
|
||
- 创建在线或离线快传会话
|
||
- 通过取件码查找会话
|
||
- 加入在线会话或确认离线会话
|
||
|
||
关键规则：
|
||
|
||
- 创建在线快传允许匿名
|
||
- 创建离线快传要求登录
|
||
- 在线快传只允许首个接收者加入
|
||
|
||
### 7.2 离线快传文件
|
||
|
||
- `GET /api/transfer/sessions/offline/mine`
|
||
- `POST /api/transfer/sessions/{sessionId}/files/{fileId}/content`
|
||
- `GET /api/transfer/sessions/{sessionId}/files/{fileId}/download`
|
||
- `POST /api/transfer/sessions/{sessionId}/files/{fileId}/import`
|
||
|
||
用途：
|
||
|
||
- 查看自己的离线快传记录
|
||
- 上传离线快传文件
|
||
- 下载离线快传文件
|
||
- 导入离线快传文件到网盘
|
||
|
||
关键规则：
|
||
|
||
- 查看自己的离线快传记录需要登录
|
||
- 上传离线快传文件需要登录且必须是发送者本人
|
||
- 下载可匿名，但会话必须已 `ready`
|
||
- 导入需要登录
|
||
|
||
### 7.3 在线快传信令
|
||
|
||
- `POST /api/transfer/sessions/{sessionId}/signals`
|
||
- `GET /api/transfer/sessions/{sessionId}/signals`
|
||
|
||
用途：
|
||
|
||
- WebRTC/在线快传信令交换
|
||
|
||
特点：
|
||
|
||
- 公开访问
|
||
- 仅对在线会话有意义
|
||
|
||
## 8. v2 后台任务接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/tasks/BackgroundTaskV2Controller.java`
|
||
|
||
### 8.1 列表与详情
|
||
|
||
- `GET /api/v2/tasks`
|
||
- `GET /api/v2/tasks/{id}`
|
||
|
||
用途：
|
||
|
||
- 查看当前用户自己的后台任务
|
||
|
||
### 8.2 取消与重试
|
||
|
||
- `DELETE /api/v2/tasks/{id}`
|
||
- `POST /api/v2/tasks/{id}/retry`
|
||
|
||
用途：
|
||
|
||
- 取消自己的任务
|
||
- 重试失败任务
|
||
|
||
关键规则：
|
||
|
||
- 只有失败任务可以重试
|
||
|
||
### 8.3 创建任务
|
||
|
||
- `POST /api/v2/tasks/archive`
|
||
- `POST /api/v2/tasks/extract`
|
||
- `POST /api/v2/tasks/media-metadata`
|
||
|
||
用途：
|
||
|
||
- 为当前用户文件创建归档、解压、媒体元数据任务
|
||
|
||
关键规则：
|
||
|
||
- 任务目标文件必须属于当前用户
|
||
- 提交的 `path` 必须与文件当前逻辑路径一致
|
||
- 不同任务类型对文件类型有额外要求
|
||
|
||
## 9. 管理接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/admin/AdminController.java`
|
||
|
||
当前管理端覆盖的是真实治理能力，不只是统计看板。
|
||
|
||
### 9.1 概览与系统设置
|
||
|
||
- `GET /api/admin/summary`
|
||
- `GET /api/admin/settings`
|
||
- `PATCH /api/admin/settings/registration/invite-code`
|
||
- `POST /api/admin/settings/registration/invite-code/rotate`
|
||
- `GET /api/admin/filesystem`
|
||
- `PATCH /api/admin/settings/offline-transfer-storage-limit`
|
||
|
||
用途：
|
||
|
||
- 查看全局指标
|
||
- 查看系统设置快照
|
||
- 修改邀请码
|
||
- 轮换邀请码
|
||
- 查看文件系统与存储能力
|
||
- 修改离线快传总容量上限
|
||
|
||
注意：
|
||
|
||
- 当前管理台“可写设置”边界很窄，很多设置只是只读快照
|
||
|
||
### 9.2 用户治理
|
||
|
||
- `GET /api/admin/users`
|
||
- `PATCH /api/admin/users/{userId}/role`
|
||
- `PATCH /api/admin/users/{userId}/status`
|
||
- `PUT /api/admin/users/{userId}/password`
|
||
- `PATCH /api/admin/users/{userId}/storage-quota`
|
||
- `PATCH /api/admin/users/{userId}/max-upload-size`
|
||
- `POST /api/admin/users/{userId}/password/reset`
|
||
|
||
用途：
|
||
|
||
- 用户查询与治理
|
||
|
||
关键规则：
|
||
|
||
- 封禁用户会让旧登录态失效
|
||
- 管理员修改用户密码会让旧登录态失效
|
||
- 密码仍需满足密码规则
|
||
|
||
### 9.3 文件、分享、任务、实体
|
||
|
||
- `GET /api/admin/files`
|
||
- `DELETE /api/admin/files/{fileId}`
|
||
- `GET /api/admin/file-blobs`
|
||
- `GET /api/admin/shares`
|
||
- `DELETE /api/admin/shares/{shareId}`
|
||
- `GET /api/admin/tasks`
|
||
- `GET /api/admin/tasks/{taskId}`
|
||
|
||
用途：
|
||
|
||
- 全局文件治理
|
||
- 全局分享治理
|
||
- 全局任务治理
|
||
- 全局文件实体 / blob 视图
|
||
|
||
### 9.4 存储策略
|
||
|
||
- `GET /api/admin/storage-policies`
|
||
- `POST /api/admin/storage-policies`
|
||
- `PUT /api/admin/storage-policies/{policyId}`
|
||
- `PATCH /api/admin/storage-policies/{policyId}/status`
|
||
- `POST /api/admin/storage-policies/migrations`
|
||
|
||
用途：
|
||
|
||
- 查询、创建、修改、启停存储策略
|
||
- 创建迁移任务
|
||
|
||
关键规则：
|
||
|
||
- 默认策略不能被禁用
|
||
- 迁移当前只支持同运行时后端类型
|
||
- 目标策略必须已启用
|
||
|
||
## 10. 站点健康接口
|
||
|
||
控制器：
|
||
|
||
- `backend/src/main/java/com/yoyuzh/api/v2/site/SiteV2Controller.java`
|
||
- `backend/src/main/java/com/yoyuzh/config/ApiRootController.java`
|
||
|
||
### 10.1 `GET /api/v2/site/ping`
|
||
|
||
用途：
|
||
|
||
- v2 站点健康检查
|
||
|
||
### 10.2 `GET /`
|
||
|
||
用途：
|
||
|
||
- 根路径可用性检查
|
||
|
||
## 11. 当前接口演进状态
|
||
|
||
### 11.1 当前稳定主线
|
||
|
||
- 认证与用户资料：`/api/auth/**`、`/api/user/**`
|
||
- 网盘主操作：`/api/files/**`
|
||
- 快传：`/api/transfer/**`
|
||
- 管理台：`/api/admin/**`
|
||
- 新分享主线：`/api/v2/shares/**`
|
||
- 新上传主线：`/api/v2/files/upload-sessions/**`
|
||
- 新任务主线：`/api/v2/tasks/**`
|
||
|
||
### 11.2 当前并存边界
|
||
|
||
- 旧分享：`/api/files/share-links/**`
|
||
- 新分享：`/api/v2/shares/**`
|
||
- 旧上传：`/api/files/upload/**`
|
||
- 新上传：`/api/v2/files/upload-sessions/**`
|
||
|
||
这些边界当前是“并存”，不是“完全迁移完成”。
|
||
|
||
## 12. 接口层已知风险
|
||
|
||
1. 管理员权限规则不由单一领域字段决定，容易在前后端或测试里误判。
|
||
2. 旧分享和 v2 分享并存，后续加需求时容易加错接口组。
|
||
3. 旧上传与 v2 上传会话并存，规则变更时容易只改一边。
|
||
4. `/api/transfer/**` 安全层公开、业务层局部要求登录，这个边界必须在测试里显式覆盖。
|
||
5. 当前没有一份单独文档明确“哪些接口是兼容保留，哪些接口是后续唯一主线”，后续若继续演进应优先补这条决策。
|
||
|
||
## 13. 2026-04-11 Admin 审计能力补充
|
||
|
||
管理台新增审计查询接口（只读）：
|
||
|
||
- `GET /api/admin/audits`
|
||
|
||
用途：
|
||
|
||
- 查询管理端治理写操作的审计日志；
|
||
- 支持按 `actorQuery`、`actionType`、`targetType`、`targetId` 过滤；
|
||
- 返回字段包含 actor、action、target、summary、detailsJson、createdAt。
|
||
|
||
当前接入审计记录的写路径：
|
||
|
||
- 设置治理：邀请码更新/轮换、离线快传容量上限更新
|
||
- 用户治理：角色、封禁、密码、配额、上传上限、重置密码
|
||
- 资源治理：删除分享、删除文件
|
||
- 存储治理：策略创建、更新、启停、迁移任务创建
|