这是一个用于与绿联（UGREEN）NAS UGOS Pro 系统进行交互的非官方 Java 客户端。主要目标用户是开发人员,适合用于开发自建轻量级的OSS服务;
本项目通过逆向分析绿联UGOS PRO Web 前端 API，实现了对 NAS 的基本操作，包括安全登录、文件列表和文件上传、下载和删除。
项目以SDK的方式发布,依赖简单干净,适合与任何自己的项目做集成,如spring环境下仅需将必要的类给spring托管即可;
- 🔐 安全登录: 实现了与官方 Web 端一致的 RSA 加密登录流程，确保密码安全。
- 🔄 会话管理: 能够获取并刷新会话凭证 (Cookie, Tokens)，维持登录状态。
- 📂 文件列表: 支持获取指定目录的文件和文件夹列表。
- 📤 文件上传: 实现了完整的文件上传流程，包括预上传（元数据发送）和文件数据传输。
- 📥 文件下载: 支持获取文件的下载令牌并下载文件内容。
- 🗑️ 文件删除: 支持将指定的文件或目录移入回收站或永久删除。
- Java 8 或更高版本
- Gradle7.1.1
- 一台正在运行 UGOS Pro 系统的绿联 NAS,这里以绿联体验账号为例
创建测试账号
在项目的 src/main/resources 修改名为 config.properties 的文件，并填 NAS 信息。
# NAS 的访问协议 (http 或 https)
ugos.protocol=https
# NAS 的 IP 地址或域名
ugos.server=your_nas_ip_or_domain
# NAS 的 Web 访问端口
ugos.port=3340
# 您的 NAS 用户名
ugos.username=your_nas_username
# 您的 NAS 密码
ugos.password=your_nas_password
项目的主要入口点是 com.pewee.ugospro.main 类。您可以直接运行它的 main 方法来执行一个完整的演示流程。 当需要与spring等环境做集成时.具体的会话,client的生命周期需要由开发者自行管理,文件的上传流程与main中的保持一致即可;关于配置文件方面,本项目直接采用了java原生的properties文件,与spring项目集成时,需要将配置写到application.yml中并初始化ugosConfig即可
执行流程如下：
public static void main(String[] args) throws Exception {
// 1. 加载 config.properties 配置文件
// ...
// 2. 根据配置初始化客户端
UgosClient client = new UgosClient(ugosConfig, urlBuilder);
// 3. 请求登录用的 RSA 公钥
String rsa = client.getPasswordRSA();
// 4. 执行登录，获取包含所有会话凭证的 SessionContainer
SessionContainer sessionContainer = client.login(rsa);
// 5. 调用 isLogin 接口刷新会话，确保会话有效
client.isLogin(sessionContainer);
// 6. 列出指定目录的文件
client.listDir(sessionContainer);
// 7. 上传本地文件到 NAS 的用户家目录
String filename = "捕获.JPG";
String dir = "/home/" + ugosConfig.getUsername();
String path = dir + "/" + filename ;
client.uploadFile(sessionContainer, arr, filename , file.lastModified(), dir);
// 8. 下载刚刚上传的文件
InputStream download = client.download(sessionContainer, Lists.newArrayList(path));
// 9. 删除刚刚上传的文件
// (参数 `forever` 为 false 表示移入回收站)
client.deletePaths(sessionContainer, Lists.newArrayList(path), false);
}以某次执行为例
执行结果如下:
由于是面向开发人员,这里不再说明项目如何build
本项目核心在于对绿联 NAS 私有 API 的认证和通信机制的模拟。
认证机制 整个认证流程是多层次的，确保了通信安全。
密码加密: 登录密码使用从服务器动态获取的 RSA 公钥进行加密后传输。
会话凭证: 登录成功后，服务器返回 Cookie、token_id (用于 x-ugreen-security-key 请求头) 和一个动态的 token。
API 令牌: 后续所有 API 请求都必须在请求头中携带一个动态生成的 x-ugreen-token，该令牌是将上一步获取的 token 使用登录时下发的另一个 RSA 公钥加密生成的。
文件上传 文件上传采用两步式流程，这是一种健壮的设计模式。
预上传 (元数据请求): 先发送一个包含文件元数据（如文件名、大小、MD5哈希）但不包含文件内容的 multipart/form-data 请求。服务器进行权限、空间等检查。
数据传输: 在元数据验证通过后，再将文件的二进制流发送到服务器。
com.alibaba:fastjson - 用于处理 JSON 数据。
commons-io:commons-io - 用于简化 IO 操作。
org.apache.httpcomponents:httpclient & httpmime - 用于发送 HTTP 请求和处理 multipart/form-data。
本项目基于对绿联 NAS 私有 API 的逆向工程，并非官方支持的客户端。API 可能会随着 NAS 固件的更新而发生变化，从而导致此客户端失效。
请仅用于学习和个人项目，使用本项目造成任何后果由使用者自行承担。
pewee