Project Icon

x-file-storage

跨平台一站式文件存储框架

x-file-storage是一个开源的文件存储框架,支持本地存储及多种云存储平台。框架提供统一的API接口,实现文件上传、下载、删除等基础功能。同时支持文件迁移、图片处理、大文件分片上传等高级特性。x-file-storage可以轻松集成到Spring Boot等Java项目中,为开发者提供灵活且可扩展的文件存储解决方案。

logo
原名 X Spring File Storage 现已捐赠至 dromara 开源组织

x-file-storage.dromara.org | x-file-storage.xuyanwu.cn | spring-file-storage.xuyanwu.cn

github star star
515706495


📚简介

只需一行代码即可将文件存储到本地、FTP、SFTP、WebDAV、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云BOS、又拍云USS、MinIO、Amazon S3、Google Cloud Storage、FastDFS、Azure Blob Storage、Cloudflare R2、金山云KS3、美团云MSS、京东云OSS、天翼云OOS、移动云EOS、沃云OSS、网易数帆NOS、Ucloud US3、青云QingStor、平安云OBS、首云OSS、IBM COS以及其他兼容S3协议的存储平台。查看所有支持的存储平台

💡 通过WebDAV连接到Alist后,可以使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务,查看Alist支持的存储平台

🚚 支持在不同存储平台之间迁移文件,详情查看迁移文件

GitHub:https://github.com/dromara/x-file-storage
Gitee:https://gitee.com/dromara/x-file-storage


📜更新记录

以下是简要的更新记录,查看详细的更新记录

2.2.1 修复某些情况下哈希计算错误的问题、七牛云Kodo预签名URL无法使用的问题 更新记录
2.2.0 修复大量问题,新增获取文件、列举文件,重构预签名URL支持客户端上传、下载、删除等操作,新增Solon插件,优化手动分片上传等功能,详情查看更新记录
2.1.0 修复大量问题,新增存储平台FastDFS和Azure Blob Storage,新增复制、移动(重命名)文件,手动分片上传(断点续传)和计算哈希等功能,详情查看更新记录
2.0.0 捐赠至dromara开源社区,更改项目名、包名,优化项目结构、支持Metadata元数据等,从旧版升级需要注意,详情查看更新记录


📅更新计划

  • 支持的存储平台:HDFS、火山云 TOS、Samba、NFS
  • 添加缩略图功能
  • 文件内容预加载
  • 新增 Access 模块,尝试通过 HTTP、FTP、WebDAV 等协议对外提供接口,方便其他程序使用
  • 追加文件功能
  • 分片下载
  • 直接输出到 HttpServletResponse 的响应流中
  • 其他更多功能

📦使用

点击快速入门查看所有存储平台的使用方法!

🔧 配置

以阿里云 OSS 为例,在 pom.xml 中引入本项目。这里默认是 SpringBoot 环境,Solon 环境请参考在 Solon 中使用,其他环境请参考脱离 SpringBoot 单独使用

<!-- 引入本项目 -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.2.1</version>
</dependency>
<!-- 引入阿里云 OSS SDK,如果使用其他存储平台,请引入相应的 SDK  -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>

application.yml 配置文件中添加以下基础配置

关于配置文件及 FileInfo 中各种路径(path)的区别,可以参考常见问题

dromara:
  x-file-storage: #文件存储配置
    default-platform: aliyun-oss-1 #默认使用的存储平台
    aliyun-oss:
      - platform: aliyun-oss-1 # 存储平台标识
        enable-storage: true  # 启用存储
        access-key: ??
        secret-key: ??
        end-point: ??
        bucket-name: ??
        domain: ?? # 访问域名,注意"/"结尾,例如:https://abc.oss-cn-shanghai.aliyuncs.com/
        base-path: test/ # 基础路径

🔨编码

在启动类上添加 @EnableFileStorage 注解

@EnableFileStorage
@SpringBootApplication
public class SpringFileStorageTestApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringFileStorageTestApplication.class,args);
    }

}

✨开始上传

支持 File、MultipartFile、UploadedFile、byte[]、InputStream、URL、URI、String、HttpServletRequest,大文件会自动分片上传。如果想支持更多方式,请阅读文件适配器章节

@RestController
public class FileDetailController {

    @Autowired
    private FileStorageService fileStorageService;//注入实例

    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        //只需要这一行代码即可上传成功
        return fileStorageService.of(file).upload();
    }
    
    /**
     * 上传文件,成功返回文件 url
     */
    @PostMapping("/upload2")
    public String upload2(MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file)
                .setPath("upload/") //保存到相对路径下,为了方便管理,不需要可以不写
                .setSaveFilename("image.jpg") //设置保存的文件名,不需要可以不写,会随机生成
                .setObjectId("0")   //关联对象id,为了方便管理,不需要可以不写
                .setObjectType("0") //关联对象类型,为了方便管理,不需要可以不写
                .putAttr("role","admin") //保存一些属性,可以在切面、保存上传记录、自定义存储平台等地方获取使用,不需要可以不写
                .upload();  //将文件上传到对应地方
        return fileInfo == null ? "上传失败!" : fileInfo.getUrl();
    }

    /**
     * 上传图片,成功返回文件信息
     * 图片处理使用的是 https://github.com/coobird/thumbnailator
     */
    @PostMapping("/upload-image")
    public FileInfo uploadImage(MultipartFile file) {
        return fileStorageService.of(file)
                .image(img -> img.size(1000,1000))  //将图片大小调整到 1000*1000
                .thumbnail(th -> th.size(200,200))  //再生成一张 200*200 的缩略图
                .upload();
    }

    /**
     * 上传文件到指定存储平台,成功返回文件信息
     */
    @PostMapping("/upload-platform")
    public FileInfo uploadPlatform(MultipartFile file) {
        return fileStorageService.of(file)
                .setPlatform("aliyun-oss-1")    //使用指定的存储平台
                .upload();
    }

    /**
     * 直接读取 HttpServletRequest 中的文件进行上传,成功返回文件信息
     * 使用这种方式有些注意事项,请查看文档 基础功能-上传 章节
     */
    @PostMapping("/upload-request")
    public FileInfo uploadPlatform(HttpServletRequest request) {
        return fileStorageService.of(request).upload();
    }
}

🎨其他操作

//手动构造文件信息,可用于其他操作
FileInfo fileInfo = new FileInfo()
        .setPlatform("huawei-obs-1")
        .setBasePath("test/")
        .setPath("aa/")
        .setFilename("image.png")
        .setThFilename("image.png.min.jpg");

//文件是否存在
boolean exists = fileStorageService.exists(fileInfo);
//下载
byte[] bytes = fileStorageService.download(fileInfo).bytes();
//删除
fileStorageService.delete(fileInfo);
//其他更多操作

如果将文件记录保存到数据库中,还可以更方便地根据 URL 进行操作,详情请阅读保存上传记录章节

//直接从数据库中获取 FileInfo 对象,更加方便执行其他操作
FileInfo fileInfo = fileStorageService.getFileInfoByUrl("https://abc.def.com/test/aa/image.png");

//检查文件是否存在 boolean exists = fileStorageService.exists("https://abc.def.com/test/aa/image.png"); //下载 byte[] bytes = fileStorageService.download("https://abc.def.com/test/aa/image.png").bytes(); //删除 fileStorageService.delete("https://abc.def.com/test/aa/image.png"); //其他更多操作


点击[快速入门](https://x-file-storage.xuyanwu.cn/#/快速入门)查看所有存储平台的使用方法!

-------

### 🏗️贡献代码

#### 🎋分支说明

X File Storage的源代码分为两个分支,功能如下:

| 分支    | 作用                                              |
|-------|-------------------------------------------------| 
| main	 | 主分支,用于发布版本,与中央仓库提交的jar包一致,不接受任何pr或修改 |
| dev	  | 开发分支,接受修改或pr                                   |

#### 🐞提供bug反馈或建议

提交问题反馈时请说明正在使用的X File Storage版本、相关依赖库版本、配置参数及问题代码

[Gitee issue](https://gitee.com/dromara/x-file-storage/issues)<br/>
[GitHub issue](https://github.com/dromara/x-file-storage/issues)

#### 🧬贡献代码的步骤

1. 在Gitee或GitHub上fork项目到自己的仓库
2. 将fork的项目克隆到本地
3. 修改代码(请务必修改dev分支)
4. commit后push到自己的仓库(dev分支)
5. 登录Gitee或GitHub,在你的首页可以看到一个pull request按钮,点击它,填写一些说明信息,然后提交即可
6. 等待维护者合并

#### 🧬开发约定 & 配置
1. JDK 11+、Maven 3.8.1+
2. 代码风格通过spotless-maven-plugin + palantir-java-format统一控制,Maven构建时会统一格式化代码
3. 在开发阶段,为了让IDE识别spotless-maven-plugin + palantir-java-format,需要安装插件:[palantir-java-format](https://plugins.jetbrains.com/plugin/13180-palantir-java-format)

#### 📐PR遵循的原则

欢迎任何人为X File Storage贡献代码。为了保证易用性和可维护性,提交的pr(pull request)需要符合以下规范:

1. 逻辑清晰、注释完备,对难以理解的代码段提供说明,必要时请添加单元测试,如果愿意,也可以加上你的大名
2. 提交到dev分支,main分支不接受任何pr或修改
3. 如果我们关闭了你的issue或pr,请查看回复内容,我们会在回复中做出解释

-------

### 📋使用公司及组织登记
X File Storage感谢各位小伙伴的信任与支持,如果您已经在项目中使用了X File Storage,希望您留下您的公司或组织信息(公司或组织名称、官网地址、展示Logo图片)

您的公司信息将在项目官网展示:<br/>
<a target="_blank" href="https://x-file-storage.dromara.org">x-file-storage.dromara.org</a><br/>
<a target="_blank" href="https://x-file-storage.xuyanwu.cn">x-file-storage.xuyanwu.cn</a><br/>
<a target="_blank" href="https://spring-file-storage.xuyanwu.cn">spring-file-storage.xuyanwu.cn</a>

[在Gitee上登记](https://gitee.com/dromara/x-file-storage/issues/I83Q6R)<br/>
[在GitHub上登记](https://github.com/dromara/x-file-storage/issues/114)

-------

### 🌏知识星球

<img src="https://yellow-cdn.veclightyear.com/835a84d5/d771d8b7-737d-4e2f-810d-2422f81b8739.png" height="200px" alt="知识星球">

-------

### 💳捐赠
如果你觉得这个项目不错,可以点个Star或捐赠请作者吃包辣条~,不想打赏的话用支付宝扫最后一个码可以领取个红包,在此表示感谢^_^

<img src="https://yellow-cdn.veclightyear.com/835a84d5/e07bbc47-1501-4d61-9848-0d454a7ec110.png" height="300px" alt="微信"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/f12dd4f6-5afa-4e74-852d-c367cfd3d250.jpg" height="300px" alt="支付宝"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/f74fa02d-1ab2-40a8-8cb9-b159eecfd919.jpg" height="300px" alt="支付宝2">
<img src="https://yellow-cdn.veclightyear.com/835a84d5/4b6ce6e7-b487-4763-8aff-88fb4bb0e459.jpg" height="300px" alt="饿了么"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/ad44a1b7-69ea-4a46-97dc-4041311b4077.jpeg" height="300px" alt="美团外卖">

或者点击以下链接,将页面拉到最下方点击"捐赠"即可

[在Gitee上捐赠](https://gitee.com/dromara/x-file-storage)

-------

# 🌶️VIP交流群

扫描上方二维码捐赠99元,截图发送至QQ 1171736840即可加入VIP交流群(超过一年需再次捐赠,否则将被清退)

也可以点击加入免费交流群
<a target="_blank" href='https://jq.qq.com/?_wv=1027&k=eGfeNqka'>
<img src='https://img.shields.io/badge/QQ%E7%BE%A4-515706495-orange' alt='515706495' />
</a> 一起交流
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台,能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐,Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持,能够阅读和理解用户上传的文件内容,解析网页信息,并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题,Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型,免费访问各种图像生成与AI训练工具,从Stable Diffusion等基础模型开始,轻松实现创新图像生成。体验前沿的AI技术,推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器,它将改变您观看视频的方式!SubCat结合了先进的人工智能技术,为您提供即时视频字幕翻译,无论是本地视频还是网络流媒体,让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台,利用前沿AI技术,为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图,再到文案生成,美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号