项目实践 · 演示筹备中
CloudSync
自托管私有云盘与可靠文件传输平台
自托管私有云盘与可靠文件传输实践。从分片校验、断点续传到不可变版本，处理网络中断、并发修改与跨存储一致性。
文件上传与版本机制示意
版本与存储一致性CloudSync
工程机制示意，非在线运行画面
- 项目状态
- 项目实践 · 演示筹备中
- 公开演示
- 公开 Demo 筹备中
- 主要技术
- Java 21 / Spring Boot 3 / PostgreSQL / MinIO
项目背景
面向个人跨设备文件存储与访问，以 Spring Boot 和 MinIO 构建私有云盘。工程重点是文件从上传到读取的完整生命周期：如何安全重试、如何拒绝过期提交，以及数据库事务失败后如何处理已经写入的对象。
架构与职责
Vue 3 浏览器端
文件 / 目录上传 / 历史恢复 / 预览
Spring Boot 3
Spring Security / 上传会话 / 版本控制
PostgreSQL
文件节点 / 不可变版本 / 条件更新
MinIO 对象存储
对象暂存 / 流式读取 / 延迟清理
PostgreSQL 与 MinIO 分别负责元数据和对象存储，并不共享原子事务。
设计与取舍
把中断当作正常路径
- 问题
- 网络中断、分片丢失与重复提交，使大文件上传无法依赖一次请求成功。
- 做法
- 持久化上传会话和分片状态，使用 SHA-256 进行分片及整文件校验，结合缺失分片查询和幂等提交，支持中断续传。
- 边界
- 完整性校验与提交幂等分别解决内容是否正确、重试是否重复创建版本的问题。
用新版本保存变化，而不是抹去历史
- 问题
- 多个设备同时修改同一文件，后提交的过期内容可能覆盖已有变化。
- 做法
- 分离逻辑文件节点与不可变内容版本，使用 baseVersionId 和 PostgreSQL 事务内条件更新实现乐观并发；恢复历史时新增版本。
- 边界
- 冲突时拒绝过期提交；不宣称实现自动内容合并或实时协同编辑。
为跨存储失败设计收尾机制
- 问题
- PostgreSQL 与 MinIO 不能共享同一个本地原子事务，异常时可能产生孤儿对象。
- 做法
- 将对象暂存、完整性校验与元数据事务提交分阶段处理，通过孤儿对象延迟清理、版本引用复核和失败恢复降低不一致风险。
- 边界
- 采用分阶段写入与补偿处理，不将其描述为数据库和对象存储之间的强原子事务。
以流处理大文件
- 问题
- 下载大文件、预览视频和打包目录时，将内容整体载入 JVM 内存会增加内存压力。
- 做法
- 基于 MinIO 对象流下载，利用 HTTP Range 支持视频分段读取和拖动，目录下载采用流式 ZIP。
- 边界
- 展示实现机制，不编造吞吐量、并发数、内存占用或性能测试结论。
当前状态
核心实现
- 浏览器文件及目录上传、断点续传
- SHA-256 分片与整文件校验、幂等提交
- 不可变版本、乐观并发及历史恢复
- 对象暂存、延迟清理与版本引用复核
- HTTP Range 预览与流式 ZIP 下载
公开演示前的规划
- 公开演示账号与独立存储空间
- 文件配额、下载鉴权与定期清理的上线评估
规划事项尚未作为在线服务开放。
当前展示文件传输、版本管理与存储一致性的项目实践。公开演示环境尚未开放，以上实现不代表生产环境上线或性能验收结论。