{"id":13678628,"url":"https://github.com/dromara/x-file-storage","last_synced_at":"2026-01-11T16:55:52.171Z","repository":{"id":38323032,"uuid":"321892267","full_name":"dromara/x-file-storage","owner":"dromara","description":"一行代码将文件存储到 本地、FTP、SFTP、WebDAV、谷歌云存储、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、 AWS S3、FastDFS、 Azure Blob Storage、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、 网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台。后续即将支持 Samba、NFS","archived":false,"fork":false,"pushed_at":"2024-08-02T05:46:31.000Z","size":2269,"stargazers_count":1886,"open_issues_count":23,"forks_count":281,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-04-11T19:55:30.449Z","etag":null,"topics":["bos","file-storage","file-upload","ftp","java","kodo","minio","oss","s3","sftp","spring","uss","webdav"],"latest_commit_sha":null,"homepage":"https://x-file-storage.xuyanwu.cn/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dromara.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-16T06:38:58.000Z","updated_at":"2025-04-11T07:17:05.000Z","dependencies_parsed_at":"2023-10-15T16:59:49.063Z","dependency_job_id":"f5c55b99-cf64-4cf9-b603-090e85c8faec","html_url":"https://github.com/dromara/x-file-storage","commit_stats":null,"previous_names":["dromara/x-file-storage","1171736840/spring-file-storage"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fx-file-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fx-file-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fx-file-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fx-file-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dromara","download_url":"https://codeload.github.com/dromara/x-file-storage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bos","file-storage","file-upload","ftp","java","kodo","minio","oss","s3","sftp","spring","uss","webdav"],"created_at":"2024-08-02T13:00:56.285Z","updated_at":"2026-01-03T11:20:17.084Z","avatar_url":"https://github.com/dromara.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003e\n\t\u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/logo.svg\" height=\"200px\"  alt=\"logo\"/\u003e\u003cbr /\u003e\n\t\u003cspan\u003e原名 X Spring File Storage 现已捐赠至 \u003ca target=\"_blank\" href=\"https://dromara.org/zh\"\u003edromara\u003c/a\u003e 开源组织\u003c/span\u003e\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca target=\"_blank\" href=\"https://x-file-storage.dromara.org\"\u003ex-file-storage.dromara.org\u003c/a\u003e |\n\t\u003ca target=\"_blank\" href=\"https://x-file-storage.xuyanwu.cn\"\u003ex-file-storage.xuyanwu.cn\u003c/a\u003e |\n\t\u003ca target=\"_blank\" href=\"https://spring-file-storage.xuyanwu.cn\"\u003espring-file-storage.xuyanwu.cn\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca target=\"_blank\" href=\"https://central.sonatype.com/search?q=org.dromara.x-file-storage\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/maven-central/v/org.dromara.x-file-storage/x-file-storage-core.svg?label=Maven%20Central\" /\u003e\n\t\u003c/a\u003e\n\t\u003ca target=\"_blank\" href=\"https://www.apache.org/licenses/LICENSE-2.0\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/badge/license-Apache%202-green.svg\" /\u003e\n\t\u003c/a\u003e\n\t\u003ca target=\"_blank\" href=\"https://www.oracle.com/technetwork/java/javase/downloads/index.html\"\u003e\n\t\t\u003cimg src=\"https://img.shields.io/badge/JDK-8+-blue.svg\" /\u003e\n\t\u003c/a\u003e\n\t\u003ca target=\"_blank\" href='https://github.com/dromara/x-file-storage'\u003e\n\t\t\u003cimg src=\"https://img.shields.io/github/stars/dromara/x-file-storage.svg?style=social\" alt=\"github star\"/\u003e\n\t\u003c/a\u003e\n    \u003ca href='https://gitee.com/dromara/x-file-storage'\u003e\n        \u003cimg src='https://gitee.com/dromara/x-file-storage/badge/star.svg?theme=dark' alt='star' /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://gitcode.com/dromara/x-file-storage'\u003e\n        \u003cimg src='https://gitcode.com/dromara/x-file-storage/star/badge.svg' alt='star' /\u003e\n    \u003c/a\u003e\n    \u003cbr /\u003e\n    \u003ca href='https://jq.qq.com/?_wv=1027\u0026k=eGfeNqka'\u003e\n        \u003cimg src='https://img.shields.io/badge/QQ%E7%BE%A4-515706495-orange' alt='515706495' /\u003e\n    \u003c/a\u003e\n    \u003ca target=\"_blank\" href='https://x-file-storage.xuyanwu.cn/#/?id=🌶%ef%b8%8fvip交流群'\u003e\n        \u003cimg src='https://img.shields.io/badge/付费-VIP交流群-brightgreen' alt='' /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n-------\n\n### 📚简介\n\n一行代码将文件存储到本地、FTP、SFTP、WebDAV、阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS、MinIO、\nAmazon S3、Amazon S3 V2、GoogleCloud Storage、FastDFS、 Azure Blob Storage、Mongo GridFS、Mongo GridFS、go-fastdfs、\n火山引擎 TOS、Cloudflare R2、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动 云EOS、沃云 OSS、\n网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的存储平台。查看 [所有支持的存储平台](https://x-file-storage.xuyanwu.cn/#/存储平台)\n\n💡 通过 WebDAV 连接到 Alist 后，可以使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务，查看 [Alist 支持的存储平台](https://alist.nn.ci/zh/guide/webdav.html#webdav-%E5%AD%98%E5%82%A8%E6%94%AF%E6%8C%81)\n\n🚚 支持在不同存储平台之间迁移文件，详情查看 [迁移文件](https://x-file-storage.xuyanwu.cn/#/迁移文件)\n\nGitHub：https://github.com/dromara/x-file-storage\n\u003cbr /\u003e\nGitee：https://gitee.com/dromara/x-file-storage\n\u003cbr /\u003e\nGitCode：https://gitcode.com/dromara/x-file-storage\n\n-------\n\n### 📜更新记录\n\n这里是简要的更新记录，查看 [详细的更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录)\n\n`2.3.0` 新增 Mongo GridFS、go-fastdfs、Amazon S3 V2、火山引擎 TOS 存储平台，修复资源泄露、上传等问题 [更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录?id=_230)\n`2.2.1` 修复某些情况下哈希计算错误的问题、七牛云 Kodo 预签名 URL 无法使用的问题 [更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录?id=_221)\n\u003cbr /\u003e\n`2.2.0` 修复大量问题，新增获取文件、列举文件，重构预签名 URL 支持客户端上传、下载、删除等操作，新增 Solon 插件，优化手动分片上传等功能，详情查看 [更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录?id=_220)\n\u003cbr /\u003e\n`2.1.0` 修复大量问题，新增存储平台 FastDFS 和 Azure Blob Storage，新增复制、移动（重命名）文件，手动分片上传（断点续传）和计算哈希等功能，详情查看 [更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录?id=_210)\n\u003cbr /\u003e\n`2.0.0` 捐赠至 [dromara](https://dromara.org/zh) 开源社区，更改项目名、包名，优化项目结构、支持 Metadata 元数据等，从旧版升级需要注意，详情查看 [更新记录](https://x-file-storage.xuyanwu.cn/#/更新记录?id=_200)\n\n-------\n\n### 📅更新计划\n\n- 接入存储平台：HDFS、Samba、NFS\n- 追加缩略图\n- 文件内容预加载\n- 新增 Access 模块，尝试通过 HTTP、FTP、WebDAV 等协议对外提供接口，方便其它程序使用\n- 追加文件\n- 分片下载\n- 直接输出到 HttpServletResponse 的响应流中\n- 其它更多功能\n\n-------\n\n### 📦使用\n\n点击 [快速入门](https://x-file-storage.xuyanwu.cn/#/快速入门) 查看全部存储平台的使用方法！\n\n#### 🔧 配置\n\n这里以阿里云 OSS 为例，`pom.xml` 引入本项目，这里默认是 `SpringBoot` 环境，`Solon` 环境参考 [在 Solon 中使用](https://x-file-storage.xuyanwu.cn/#/在Solon中使用)，其它环境参考 [脱离 SpringBoot 单独使用](https://x-file-storage.xuyanwu.cn/#/脱离SpringBoot单独使用)\n\n```xml\n\u003c!-- 引入本项目 --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.dromara.x-file-storage\u003c/groupId\u003e\n    \u003cartifactId\u003ex-file-storage-spring\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n\u003c!-- 引入 阿里云 OSS SDK，如果使用其它存储平台，就引入对应的 SDK  --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.aliyun.oss\u003c/groupId\u003e\n    \u003cartifactId\u003ealiyun-sdk-oss\u003c/artifactId\u003e\n    \u003cversion\u003e3.16.1\u003c/version\u003e\n\u003c/dependency\u003e\n```  \n\n`application.yml` 配置文件中添加以下基础配置\n\n关于配置文件及 FileInfo 中各种路径（path）的区别，可以参考 [常见问题](https://x-file-storage.xuyanwu.cn/#/常见问题?id=配置文件及-fileinfo-中各种路径（path）的区别？)\n\n```yaml\ndromara:\n  x-file-storage: #文件存储配置\n    default-platform: aliyun-oss-1 #默认使用的存储平台\n    aliyun-oss:\n      - platform: aliyun-oss-1 # 存储平台标识\n        enable-storage: true  # 启用存储\n        access-key: ??\n        secret-key: ??\n        end-point: ??\n        bucket-name: ??\n        domain: ?? # 访问域名，注意“/”结尾，例如：https://abc.oss-cn-shanghai.aliyuncs.com/\n        base-path: test/ # 基础路径\n```\n\n#### 🔨编码\n\n在启动类上加上`@EnableFileStorage`注解\n\n```java\n@EnableFileStorage\n@SpringBootApplication\npublic class SpringFileStorageTestApplication {\n\n    public static void main(String[] args) {\n        SpringApplication.run(SpringFileStorageTestApplication.class,args);\n    }\n\n}\n```\n #### ✨开始上传\n\n 支持 File、MultipartFile、UploadedFile、byte[]、InputStream、URL、URI、String、HttpServletRequest，大文件会自动分片上传。如果想支持更多方式，请阅读 [文件适配器](https://x-file-storage.xuyanwu.cn/#/文件适配器) 章节\n\n```java\n@RestController\npublic class FileDetailController {\n\n    @Autowired\n    private FileStorageService fileStorageService;//注入实列\n\n    /**\n     * 上传文件\n     */\n    @PostMapping(\"/upload\")\n    public FileInfo upload(MultipartFile file) {\n        //只需要这一行代码即可上传成功\n        return fileStorageService.of(file).upload();\n    }\n    \n    /**\n     * 上传文件，成功返回文件 url\n     */\n    @PostMapping(\"/upload2\")\n    public String upload2(MultipartFile file) {\n        FileInfo fileInfo = fileStorageService.of(file)\n                .setPath(\"upload/\") //保存到相对路径下，为了方便管理，不需要可以不写\n                .setSaveFilename(\"image.jpg\") //设置保存的文件名，不需要可以不写，会随机生成\n                .setObjectId(\"0\")   //关联对象id，为了方便管理，不需要可以不写\n                .setObjectType(\"0\") //关联对象类型，为了方便管理，不需要可以不写\n                .putAttr(\"role\",\"admin\") //保存一些属性，可以在切面、保存上传记录、自定义存储平台等地方获取使用，不需要可以不写\n                .upload();  //将文件上传到对应地方\n        return fileInfo == null ? \"上传失败！\" : fileInfo.getUrl();\n    }\n\n    /**\n     * 上传图片，成功返回文件信息\n     * 图片处理使用的是 https://github.com/coobird/thumbnailator\n     */\n    @PostMapping(\"/upload-image\")\n    public FileInfo uploadImage(MultipartFile file) {\n        return fileStorageService.of(file)\n                .image(img -\u003e img.size(1000,1000))  //将图片大小调整到 1000*1000\n                .thumbnail(th -\u003e th.size(200,200))  //再生成一张 200*200 的缩略图\n                .upload();\n    }\n\n    /**\n     * 上传文件到指定存储平台，成功返回文件信息\n     */\n    @PostMapping(\"/upload-platform\")\n    public FileInfo uploadPlatform(MultipartFile file) {\n        return fileStorageService.of(file)\n                .setPlatform(\"aliyun-oss-1\")    //使用指定的存储平台\n                .upload();\n    }\n\n    /**\n     * 直接读取 HttpServletRequest 中的文件进行上传，成功返回文件信息\n     * 使用这种方式有些注意事项，请查看文档 基础功能-上传 章节\n     */\n    @PostMapping(\"/upload-request\")\n    public FileInfo uploadPlatform(HttpServletRequest request) {\n        return fileStorageService.of(request).upload();\n    }\n}\n```\n\n#### 🎨其它操作\n\n```java\n//手动构造文件信息，可用于其它操作\nFileInfo fileInfo = new FileInfo()\n        .setPlatform(\"huawei-obs-1\")\n        .setBasePath(\"test/\")\n        .setPath(\"aa/\")\n        .setFilename(\"image.png\")\n        .setThFilename(\"image.png.min.jpg\");\n\n//文件是否存在\nboolean exists = fileStorageService.exists(fileInfo);\n//下载\nbyte[] bytes = fileStorageService.download(fileInfo).bytes();\n//删除\nfileStorageService.delete(fileInfo);\n//其它更多操作\n\n```\n\n如果将文件记录保存到数据库中，还可以更方便的根据 URL 进行操作了，详情请阅读 [保存上传记录](https://x-file-storage.xuyanwu.cn/#/基础功能?id=保存上传记录) 章节\n\n```java\n//直接从数据库中获取 FileInfo 对象，更加方便执行其它操作\nFileInfo fileInfo = fileStorageService.getFileInfoByUrl(\"https://abc.def.com/test/aa/image.png\");\n\n//文件是否存在\nboolean exists = fileStorageService.exists(\"https://abc.def.com/test/aa/image.png\");\n//下载\nbyte[] bytes = fileStorageService.download(\"https://abc.def.com/test/aa/image.png\").bytes();\n//删除\nfileStorageService.delete(\"https://abc.def.com/test/aa/image.png\");\n//其它更多操作\n```\n\n点击 [快速入门](https://x-file-storage.xuyanwu.cn/#/快速入门) 查看全部存储平台的使用方法！\n\n-------\n\n### 🏗️添砖加瓦\n\n#### 🎋分支说明\n\nX File Storage 的源码分为两个分支，功能如下：\n\n| 分支    | 作用                                              |\n|-------|-------------------------------------------------| \n| main\t | 主分支，release 版本使用的分支，与中央库提交的 jar 一致，不接收任何 pr 或修改 |\n| dev\t  | 开发分支，接受修改或 pr                                   |\n\n#### 🐞提供bug反馈或建议\n\n提交问题反馈请说明正在 X File Storage 版本、相关依赖库版本、配置参数及问题代码\n\n[Gitee issue](https://gitee.com/dromara/x-file-storage/issues)\u003cbr/\u003e\n[GitHub issue](https://github.com/dromara/x-file-storage/issues)\u003cbr/\u003e\n[GitCode issue](https://gitcode.com/dromara/x-file-storage/issues)\n\n#### 🧬贡献代码的步骤\n\n1. 在 Gitee 或者 Github 上 fork 项目到自己的 repo\n2. 把 fork 过去的项目也就是你的项目 clone 到你的本地\n3. 修改代码（记得一定要修改 dev 分支）\n4. commit后push到自己的库（ dev 分支）\n5. 登录 Gitee 或 Github 在你首页可以看到一个 pull request 按钮，点击它，填写一些说明信息，然后提交即可\n6. 等待维护者合并\n\n#### 🧬 开发约定 \u0026 配置\n1. JDK 11+、Maven 3.9.9+\n2. 代码风格，目前代码风格通过 spotless-maven-plugin + palantir-java-format 统一控制，Maven 构建时统一格式化代码\n3. 在开发阶段，IDE 要识别到 spotless-maven-plugin + palantir-java-format 需要安装插件：[palantir-java-format](https://plugins.jetbrains.com/plugin/13180-palantir-java-format)\n\n#### 📐PR遵照的原则\n\n欢迎任何人为 X File Storage 添砖加瓦，贡献代码，为了易用性和可维护性，需要提交的 pr（pull request）符合一些规范，规范如下：\n\n1. 逻辑清晰、注释完备，不易理解的代码段的说明等信息，必要时请添加单元测试，如果愿意，也可以加上你的大名\n2. 提交到 dev 分支，main 分支不接受任何 pr 或修改\n3. 如果我们关闭了你的 issues 或者 pr 请查看回复内容，我们会在回复中做出解释\n\n-------\n\n### 📋使用公司及组织登记\nX File Storage 感谢各位小伙伴的信任与支持，如果您已经在项目中使用了 X File Storage，希望您留下您的公司或组织信息（公司或组织名称、官网地址、展示 Logo 图片）\n\n您的公司信息将在项目官网进行展示：\u003cbr/\u003e\n\u003ca target=\"_blank\" href=\"https://x-file-storage.dromara.org\"\u003ex-file-storage.dromara.org\u003c/a\u003e\u003cbr/\u003e\n\u003ca target=\"_blank\" href=\"https://x-file-storage.xuyanwu.cn\"\u003ex-file-storage.xuyanwu.cn\u003c/a\u003e\u003cbr/\u003e\n\u003ca target=\"_blank\" href=\"https://spring-file-storage.xuyanwu.cn\"\u003espring-file-storage.xuyanwu.cn\u003c/a\u003e\n\n[在 Gitee 上登记](https://gitee.com/dromara/x-file-storage/issues/I83Q6R)\u003cbr/\u003e\n[在 GitHub 上登记](https://github.com/dromara/x-file-storage/issues/114)\u003cbr/\u003e\n[在 GitCode 上登记](https://gitcode.com/dromara/x-file-storage/issues/1)\n\n-------\n\n### 🌏知识星球\n\n\u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/zsxq.png\" height=\"200px\" alt=\"知识星球\"\u003e\n\n-------\n\n### 💳捐赠\n如果你觉得这个项目不错，可以点个 Star 或捐赠请作者吃包辣条~，不想打赏的话用支付宝扫最后一个码可以领取个红包，在此表示感谢^_^\n\n\u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/wx.png\" height=\"300px\" alt=\"微信\"\u003e \u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/zfb.jpg\" height=\"300px\" alt=\"支付宝\"\u003e \u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/zfb2.jpg\" height=\"300px\" alt=\"支付宝2\"\u003e\n\u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/elm.jpg\" height=\"300px\" alt=\"饿了么\"\u003e \u003cimg src=\"https://x-file-storage.xuyanwu.cn/assets/mt.jpeg\" height=\"300px\" alt=\"美团外卖\"\u003e\n\n或者点击以下链接，将页面拉到最下方点击“捐赠”即可\n\n[Gitee上捐赠](https://gitee.com/dromara/x-file-storage)\n\n-------\n\n# 🌶️VIP交流群\n\n扫描上方二维码捐赠 99 元，截图发我 `QQ1171736840` 即可加入 VIP 交流群（超过一年则需要再次捐赠，否则将进行清退）\n\n也可以点击添加免费交流群\n\u003ca target=\"_blank\" href='https://jq.qq.com/?_wv=1027\u0026k=eGfeNqka'\u003e\n\u003cimg src='https://img.shields.io/badge/QQ%E7%BE%A4-515706495-orange' alt='515706495' /\u003e\n\u003c/a\u003e 一起交流\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdromara%2Fx-file-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdromara%2Fx-file-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdromara%2Fx-file-storage/lists"}