X File Storage 技术文档

2026-02-04 05:10:47作者：羿妍玫Ivan

一行代码将文件存储到本地、FTP、SFTP、WebDAV、谷歌云存储、阿里云OSS、华为云OBS、七牛云Kodo、腾讯云COS、百度云 BOS、又拍云USS、MinIO、 AWS S3、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动云 EOS、沃云 OSS、网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的平台。后续即将支持 Samba、NFS

项目地址：https://gitcode.com/dromara/x-file-storage

1. 安装指南

环境要求

JDK 8+
Maven 3.0+
Spring Boot 2.x+（可选）
Solon（可选）

Maven 依赖配置

在项目的 pom.xml 文件中添加以下依赖：

<!-- 核心依赖 -->
<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.3.0</version>
</dependency>

<!-- 存储平台SDK（以阿里云OSS为例） -->
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>

2. 项目使用说明

基础配置

在 application.yml 中配置存储平台信息：

dromara:
  x-file-storage:
    default-platform: aliyun-oss-1
    aliyun-oss:
      - platform: aliyun-oss-1
        enable-storage: true
        access-key: your-access-key
        secret-key: your-secret-key
        end-point: your-endpoint
        bucket-name: your-bucket
        domain: https://your-domain.com/
        base-path: test/

启用服务

在Spring Boot启动类上添加注解：

@EnableFileStorage
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3. API使用文档

文件上传

@RestController
public class FileController {
    
    @Autowired
    private FileStorageService fileStorageService;

    // 基础上传
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        return fileStorageService.of(file).upload();
    }

    // 带参数上传
    @PostMapping("/upload2")
    public String upload2(MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file)
                .setPath("upload/")
                .setSaveFilename("custom.jpg")
                .setObjectId("123")
                .setObjectType("user")
                .putAttr("role","admin")
                .upload();
        return fileInfo.getUrl();
    }
}

图片处理

// 图片缩放+缩略图
@PostMapping("/upload-image")
public FileInfo uploadImage(MultipartFile file) {
    return fileStorageService.of(file)
            .image(img -> img.size(1000,1000))
            .thumbnail(th -> th.size(200,200))
            .upload();
}

文件操作

// 文件存在检查
boolean exists = fileStorageService.exists(fileInfo);

// 文件下载
byte[] bytes = fileStorageService.download(fileInfo).bytes();

// 文件删除
fileStorageService.delete(fileInfo);

// 通过URL操作
fileStorageService.delete("https://example.com/file.jpg");