yoyuz/my_site

Fork 0

Files

yoyuzh 30a9bbc1e7 Refactor backend and frontend modules for architecture alignment

2026-04-12 00:32:21 +08:00

15 KiB

Raw Blame History

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

用途：

创建目录
分页列目录
最近文件

关键规则：

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. 接口层已知风险

管理员权限规则不由单一领域字段决定，容易在前后端或测试里误判。
旧分享和 v2 分享并存，后续加需求时容易加错接口组。
旧上传与 v2 上传会话并存，规则变更时容易只改一边。
/api/transfer/** 安全层公开、业务层局部要求登录，这个边界必须在测试里显式覆盖。
当前没有一份单独文档明确“哪些接口是兼容保留，哪些接口是后续唯一主线”，后续若继续演进应优先补这条决策。

13. 2026-04-11 Admin 审计能力补充

管理台新增审计查询接口（只读）：

GET /api/admin/audits

用途：

查询管理端治理写操作的审计日志；
支持按 actorQuery、actionType、targetType、targetId 过滤；
返回字段包含 actor、action、target、summary、detailsJson、createdAt。

当前接入审计记录的写路径：

设置治理：邀请码更新/轮换、离线快传容量上限更新
用户治理：角色、封禁、密码、配额、上传上限、重置密码
资源治理：删除分享、删除文件
存储治理：策略创建、更新、启停、迁移任务创建

15 KiB Raw Blame History Unescape Escape

API 参考文档

1. 接口分层总览

1.1 公开接口

1.2 登录后接口

1.3 管理接口

2. 认证与用户模块

2.1 POST /api/auth/register

2.2 POST /api/auth/login

2.3 POST /api/auth/refresh

2.4 POST /api/auth/dev-login

2.5 GET /api/user/profile

2.6 PUT /api/user/profile

2.7 POST /api/user/password

2.8 头像接口

3. Android 发布接口

3.1 GET /api/app/android/latest

3.2 下载接口

4. 网盘主接口（旧主线，仍在使用）

4.1 上传接口

4.2 目录与列表

4.3 下载

4.4 文件操作

4.5 回收站

4.6 旧分享接口

5. v2 文件接口

5.1 v2 上传会话

5.2 文件搜索

5.3 文件事件流

6. v2 分享接口

6.1 创建与管理

6.2 公共访问

6.3 导入分享

7. 快传接口

7.1 会话创建与查询

7.2 离线快传文件

7.3 在线快传信令

8. v2 后台任务接口

8.1 列表与详情

8.2 取消与重试

8.3 创建任务

9. 管理接口

9.1 概览与系统设置

9.2 用户治理

9.3 文件、分享、任务、实体

9.4 存储策略

10. 站点健康接口

10.1 GET /api/v2/site/ping

10.2 GET /

11. 当前接口演进状态

11.1 当前稳定主线

11.2 当前并存边界

12. 接口层已知风险

13. 2026-04-11 Admin 审计能力补充

15 KiB

Raw Blame History

2.1 `POST /api/auth/register`

2.2 `POST /api/auth/login`

2.3 `POST /api/auth/refresh`

2.4 `POST /api/auth/dev-login`

2.5 `GET /api/user/profile`

2.6 `PUT /api/user/profile`

2.7 `POST /api/user/password`

3.1 `GET /api/app/android/latest`

10.1 `GET /api/v2/site/ping`

10.2 `GET /`