Free-FS：企业级文件管理系统后端
1. 项目概述
Free-FS 是一个基于 Spring Boot 3.5 + MyBatis Flex + Sa-Token + React/Vue 构建的企业级文件管理系统后端，提供大文件分片上传、多格式预览、多云存储支持、权限控制等功能，并配套 Vue 3 前端。
2. 核心术语
| 术语 | 含义 |
|---|---|
| 分片上传 | 将大文件切割为多个小块分别上传，网络中断后只需上传未完成的分片。 |
| 断点续传 | 记录上传进度，中断后从断点继续，无需重新上传整个文件。 |
| 秒传 | 通过文件哈希值（如 MD5）校验，若服务器已有相同文件，直接建立引用，无需重复上传。 |
3. 解决的问题
- 大文件上传困难：传统方式网络中断需重新上传。
- 存储平台绑定：单一云存储切换成本高。
- 预览能力弱：仅支持少数格式，Office/PDF 预览需额外配置。
- 权限管理粗糙：缺乏细粒度权限控制。
- 部署复杂：依赖多、配置繁琐。
4. 核心功能
4.1 文件管理
- 支持 列表视图 与 网格视图。
- 文件分类、标签、搜索。
4.2 大文件上传与秒传
- 前端分片并行上传，后端通过 SSE 实时推送进度。
- 断点续传：记录每个分片状态，续传从断点继续。
- 秒传：计算文件哈希，服务器已有相同文件时直接建立引用。
4.3 多云存储插件化
- SPI 插件化设计，存储能力抽象为统一接口。
- 内置支持：本地存储、阿里云 OSS、七牛云 Kodo、AWS S3、RustFS。
- 支持多存储平台并存，新增平台只需实现接口，无需修改主业务代码。
4.4 在线预览
| 类型 | 支持格式 |
|---|---|
| 图片 | JPG/PNG/GIF/WebP/SVG 等 |
| Office 文档 | DOC/DOCX/XLS/XLSX/PPT/PPTX（需 LibreOffice） |
| 文本代码 | 30+ 种编程语言语法高亮 |
| 音视频 | 流式播放 |
| 压缩包 | 目录结构查看 |
4.5 权限与安全
- 基于 Sa-Token 的权限认证，支持 JWT 无状态会话。
- 细粒度权限控制：文件查看、下载、编辑、删除等操作。
4.6 文件分享与回收站
- 分享模式：公开链接、授权码（可设有效期、访问次数）。
- 回收站：支持批量还原、永久删除、自动清理。
5. 安装与快速上手
5.1 环境要求
- JDK 17+
- Maven 3.8+
- MySQL 8.0+ 或 PostgreSQL 14+
- Redis
- LibreOffice（可选，用于 Office 预览）
5.2 安装步骤
bash
git clone https://gitee.com/dromara/free-fs.git
cd free-fs
mvn clean install -DskipTests5.3 数据库初始化
-
MySQL ：
sqlCREATE DATABASE `free-fs` CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_general_ci';导入
_sql/mysql/free-fs.sql。 -
PostgreSQL ：
sqlCREATE DATABASE free-fs ENCODING 'UTF8' LC_COLLATE='zh_CN.UTF-8' LC_CTYPE='zh_CN.UTF-8';导入
_sql/postgresql/free-fs_pg.sql。
5.4 配置与运行
-
修改
fs-admin/src/main/resources/application-dev.yml中的数据库和 Redis 配置。 -
启动服务：
bashcd fs-admin mvn spring-boot:run -
访问地址：
- 服务地址：http://localhost:8080
- API 文档：http://localhost:8080/swagger-ui.html
- 默认账号：
admin/admin
6. 技术架构
6.1 技术栈
- 后端：Spring Boot 3.5.4 + MyBatis Flex（ORM） + Sa-Token（认证）
- 数据库：MySQL 8.0+ / PostgreSQL 14+
- 缓存：Caffeine（本地缓存）+ Redis（分布式缓存）
- 存储插件：SPI 设计，支持多云存储扩展
6.2 项目结构
free-fs/
├── fs-admin # 管理后台
├── fs-api # API 模块
├── fs-common # 通用工具
├── storage-plugin-core # 存储插件接口
├── storage-plugin-local # 本地存储实现
└── ... # 其他存储插件7. 与其他方案对比
| 维度 | Free-FS | MinIO | Nextcloud | Seafile |
|---|---|---|---|---|
| 技术栈 | Spring Boot 3.x | Go | PHP | Go/C |
| 定位 | 文件管理后端 | 对象存储 | 完整网盘 | 完整网盘 |
| 大文件上传 | 分片/断点续传/秒传 | 需自行实现 | 支持 | 支持 |
| 在线预览 | 多格式支持 | 需自行实现 | 支持 | 支持 |
| 多云存储 | 插件化切换 | 单一 | 支持 | 支持 |
| 权限管理 | Sa-Token 细粒度 | 简单 | 细粒度 | 细粒度 |
| 部署难度 | 中等（需数据库） | 低 | 中等 | 中等 |
| 开源协议 | Apache 2.0 | AGPL v3 | AGPL v3 | GPL-3.0 |
8. 总结
优势
- 功能完整，开箱即用。
- 大文件上传（分片/断点续传/秒传）。
- 插件化存储扩展，支持多云切换。
- 多格式在线预览。
- Sa-Token 细粒度权限管理。
- Apache 2.0 开源协议。
局限
- 需部署数据库（MySQL/PostgreSQL + Redis）。
- Office 预览需配置 LibreOffice。
适用场景
- 企业级文件管理系统搭建。
- 需要多云存储支持。
- 需要大文件上传与预览能力。
建议
先部署基础版本跑通上传下载流程，再根据需要接入云存储和配置预览功能。
9. 项目地址
提示：建议先体验基础功能，再逐步接入云存储与高级配置。