基于 RustFS 与 Spring Boot 构建高性能 S3 文件服务

curl -O https://rustfs.com/install_rustfs.sh && bash install_rustfs.sh

RustFS has been installed and started successfully!Service port: 9000,  Console port: 9001,  Data directory: /data/rustfs0[SECURITY WARNING] Please change the default value for RUSTFS_ACCESS_KEY/RUSTFS_SECRET_KEY immediately ...  Config file: /etc/default/rustfs

sudo firewall-cmd --zone=public --add-port=9000/tcp --permanent
sudo firewall-cmd --zone=public --add-port=9001/tcp --permanent
sudo firewall-cmd --reload

spring-rustfs/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── com/
                └── amoon/
    				└── springrustfs/
                    	└── RustfsS3Example.java

<dependencies>
  <dependency>
   <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.25.27</version>
  </dependency>
</dependencies>

package com.amoon.springrustfs;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.*;
import java.net.URI;
import java.nio.file.Paths;
/**
 * @ClassName: RustfsS3Example
 * @Description: TODO
 * @Author: ZM
 * @Date: 2026年09月12日  21:37
 **/
public class RustfsS3Example {
    public static void main(String[] args) {
        // 1. Initialize S3 client
        S3Client s3 = S3Client.builder()
                .endpointOverride(URI.create("https://rustfsapi.zhangmeng.me")) // RustFS S3 API address
                .region(Region.US_EAST_1) // RustFS default region
                .credentialsProvider(
                        StaticCredentialsProvider.create(
                                AwsBasicCredentials.create("<your-access-key>", "<your-secret-key>")
                        )
                )
                // RustFS uses path-style URLs by default; virtual-host style requires RUSTFS_SERVER_DOMAINS
                .forcePathStyle(true)
                .build();
        // 2. Create bucket
        String bucket = "example-bucket";
        try {
            s3.createBucket(CreateBucketRequest.builder().bucket(bucket).build());
            System.out.println("Bucket created: " + bucket);
        } catch (BucketAlreadyExistsException | BucketAlreadyOwnedByYouException e) {
            System.out.println("Bucket already exists.");
        }
        // 3. Upload file
        s3.putObject(
                PutObjectRequest.builder().bucket(bucket).key("hello.txt").build(),
                Paths.get("/path/to/hello.txt")
        );
        System.out.println("Uploaded hello.txt");
        // 4. Download file
        s3.getObject(
                GetObjectRequest.builder().bucket(bucket).key("hello.txt").build(),
                Paths.get("/path/to/downloaded-hello.txt")
        );
        System.out.println("Downloaded hello.txt");
        // 5. List objects
        ListObjectsV2Response listResponse = s3.listObjectsV2(ListObjectsV2Request.builder().bucket(bucket).build());
        listResponse.contents().forEach(obj -> System.out.println("Found object: " + obj.key()));
        // 6. Delete object
        s3.deleteObject(DeleteObjectRequest.builder().bucket(bucket).key("hello.txt").build());
        System.out.println("Deleted hello.txt");
        // 7. Delete bucket (optional)
        // s3.deleteBucket(DeleteBucketRequest.builder().bucket(bucket).build());
    }
}

Bucket created: my-bucket
Uploaded hello.txt
Downloaded hello.txt
Found object: hello.txt
Deleted hello.txt

<dependencies>
  <dependency>
   <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.25.27</version>
  </dependency>
</dependencies>

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.amoon</groupId>
    <artifactId>spring-rustfs</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-rustfs</name>
    <description>spring-rustfs</description>
    <url/>
    <licenses>
        <license/>
    </licenses>
    <developers>
        <developer/>
    </developers>
    <scm>
        <connection/>
        <developerConnection/>
        <tag/>
        <url/>
    </scm>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- AWS S3 Java SDK相依赖 -->
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>s3</artifactId>
            <version>2.25.27</version>
        </dependency>
        <!-- Swagger接口文档 相关依赖 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.8.6</version>
        </dependency>
        <!-- hutool 工具类 相关依赖 -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.38</version>
        </dependency>
    </dependencies>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <executions>
                    <execution>
                        <id>default-compile</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                        <configuration>
                            <annotationProcessorPaths>
                                <path>
                                    <groupId>org.projectlombok</groupId>
                                    <artifactId>lombok</artifactId>
                                </path>
                                <path>
                                    <groupId>org.springframework.boot</groupId>
                                    <artifactId>spring-boot-configuration-processor</artifactId>
                                </path>
                            </annotationProcessorPaths>
                        </configuration>
                    </execution>
                    <execution>
                        <id>default-testCompile</id>
                        <phase>test-compile</phase>
                        <goals>
                            <goal>testCompile</goal>
                        </goals>
                        <configuration>
                            <annotationProcessorPaths>
                                <path>
                                    <groupId>org.projectlombok</groupId>
                                    <artifactId>lombok</artifactId>
                                </path>
                            </annotationProcessorPaths>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

server:
  port: 8080

spring:
 application:
    name: spring-rustfs

rustfs:
  # RustFS S3 API address
  endpoint: https://rustfsapi.zhangmeng.me
  bucketName: simple
  accessKey: your-access-key
  secretKey: your-secret-key

package com.amoon.springrustfs.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;

import java.net.URI;

/**
 * @ClassName: RustFSConfig
 * @Description: 初始化RustFS配置
 * @Author: ZM
 * @Date: 2026年09月12日  22:23
 **/
@Configuration
public class RustFSConfig {

    @Value("${rustfs.endpoint}")
    private String ENDPOINT;
    @Value("${rustfs.accessKey}")
    private String ACCESS_KEY;
    @Value("${rustfs.secretKey}")
    private String SECRET_KEY;

    @Bean
    public S3Client s3Client() {
        //初始化 S3 客户端
        return S3Client.builder()
                //RustFS地址
                .endpointOverride(URI.create(ENDPOINT))
                //可写死，RustFS 不校验 region
                .region(Region.US_EAST_1)
                .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(ACCESS_KEY, SECRET_KEY)))
                //关键配置! RustFS需启用Path-Style
                .forcePathStyle(true)
                .build();
    }
}

package com.amoon.springrustfs.config;

import cn.hutool.core.collection.CollUtil;
import com.amoon.springrustfs.dto.BucketPolicyConfigDto;

import java.util.List;

/**
 * @ClassName: BucketPolicyConfig
 * @Description: 创建存储桶的访问策略，设置为只读权限
 * @Author: ZM
 * @Date: 2026年09月13日  1:15
 **/
public class BucketPolicyConfig {

    /**
     * 创建存储桶的访问策略，设置为只读权限
     * @param bucketName
     * @return
     */
    public static BucketPolicyConfigDto createBucketPolicyConfigDto(String bucketName) {
        BucketPolicyConfigDto.Statement statement = BucketPolicyConfigDto.Statement.builder()
                .Effect("Allow")
                .Principal(BucketPolicyConfigDto.Principal.builder().AWS(List.of(new String[]{"*"})).build())
                .Action(List.of(new String[]{"s3:GetObject"}))
                .Resource(List.of(new String[]{"arn:aws:s3:::" + bucketName + "/*"}))
                .build();
        return BucketPolicyConfigDto.builder()
                .Version("2012-10-17")
                .Statement(CollUtil.toList(statement))
                .build();
    }

}

package com.amoon.springrustfs.common.api;

import lombok.Data;

/**
 * @ClassName: CommonResult
 * @Description: 统一接口返回格式
 * @Author: ZM
 * @Date: 2026年09月12日  22:58
 **/
@Data
public class CommonResult<T> {

    private Integer code;
    private String message;
    private T data;

    public CommonResult() {
    }

    public CommonResult(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    // 快捷成功方法
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<>(200, "操作成功", data);
    }

    // 快捷失败方法
    public static <T> CommonResult<T> error(String message) {
        return new CommonResult<>(500, message, null);
    }

}

package com.amoon.springrustfs.common.api;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * @ClassName: RustFSUploadResult
 * @Description: RustFS文件上传返回结果
 * @Author: ZM
 * @Date: 2026年09月12日  23:55
 **/
@Data
public class RustFSUploadResult {
    @Schema(title = "文件访问URL")
    private String url;
    @Schema(title = "文件名称")
    private String name;
}

package com.amoon.springrustfs.dto;

/**
 * @ClassName: BucketPolicyConfigDto
 * @Description: RustFS 存储桶策略配置 DTO，
 * @Author: ZM
 * @Date: 2026年09月12日  23:26
 * 对应标准的 S3 Bucket Policy JSON 结构
 * {
 *   "Version": "2012-10-17",
 *   "Statement": [
 *     {
 *       "Sid": "",
 *       "Effect": "Allow",
 *       "Principal": {
 *         "AWS": ["*"]
 *       },
 *       "Action": ["s3:GetObject"],
 *       "Resource": ["arn:aws:s3:::image-hosting/*"]
 *     }
 *   ]
 * }
 **/
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Builder;
import lombok.Data;

import java.util.List;

@Data
@Builder
public class BucketPolicyConfigDto {

    /**
     * 策略版本，通常为 "2012-10-17"
     */
    @JsonProperty("Version")
    private String Version;

    /**
     * 策略语句列表
     */
    @JsonProperty("Statement")
    private List<Statement> Statement;

    @Data
    @Builder
    public static class Statement {
        /**
         * 语句 ID，可选
         */
        @JsonProperty("Sid")
        private String Sid;

        /**
         * 效果：Allow 或 Deny
         */
        @JsonProperty("Effect")
        private String Effect;

        /**
         * 主体（被授权者）
         */
        @JsonProperty("Principal")
        private Principal Principal;

        /**
         * 允许或拒绝的操作列表
         */
        @JsonProperty("Action")
        private List<String> Action;

        /**
         * 资源 ARN 列表
         */
        @JsonProperty("Resource")
        private List<String> Resource;
    }

    @Data
    @Builder
    public static class Principal {
        /**
         * AWS 主体列表，["*"] 表示所有用户
         */
        @JsonProperty("AWS")
        private List<String> AWS;
    }
}

 {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "",
        "Effect": "Allow",
        "Principal": {
          "AWS": ["*"]
        },
        "Action": ["s3:GetObject"],
        "Resource": ["arn:aws:s3:::image-hosting/*"]
      }
    ]
  }

package com.amoon.springrustfs.controller;

import cn.hutool.json.JSONUtil;
import com.amoon.springrustfs.common.api.RustFSUploadResult;
import com.amoon.springrustfs.config.BucketPolicyConfig;
import com.amoon.springrustfs.common.api.CommonResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.util.StreamUtils;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import software.amazon.awssdk.core.ResponseInputStream;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.*;

import java.io.IOException;

/**
 * @ClassName: RustFSController
 * @Description: TODO
 * @Author: ZM
 * @Date: 2026年09月12日  22:33
 **/
@Slf4j
@Controller
@Tag(name = "RustFSController", description = "RustFS对象存储管理")
@RequestMapping("/rustfs")
public class RustFSController {

    @Autowired
    private S3Client s3Client;
    @Value("${rustfs.bucketName}")
    private String BUCKET_NAME;
    @Value("${rustfs.endpoint}")
    private String ENDPOINT;

    /**
     * 文件上传
     * @param file
     * @return
     */
    @Operation(summary = "文件上传")
    @RequestMapping(value = "/upload",method = RequestMethod.POST,consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    @ResponseBody
    public CommonResult<RustFSUploadResult> uploadFile(@RequestPart("file") MultipartFile file) {
        // TODO: 文件上传逻辑
        // 尝试创建桶，如果已存在则忽略
        try {
            s3Client.createBucket(CreateBucketRequest.builder()
                    .bucket(BUCKET_NAME)
                    .build());
            log.info("Bucket created: {}", BUCKET_NAME);
        } catch (BucketAlreadyExistsException | BucketAlreadyOwnedByYouException e) {
            log.info("Bucket already exists: {}", BUCKET_NAME);
        }
        // 设置Bucket的访问策略（幂等操作，重复设置也没关系）
        try {
            String policy = JSONUtil.toJsonStr(BucketPolicyConfig.createBucketPolicyConfigDto(BUCKET_NAME));
            log.info("Bucket policy: {}", policy);
            s3Client.putBucketPolicy(PutBucketPolicyRequest.builder()
                    .bucket(BUCKET_NAME)
                    .policy(policy)
                    .build());
        } catch (Exception e) {
            log.warn("Failed to set bucket policy: {}", e.getMessage());
        }

        // 上传文件
        try {
            s3Client.putObject(PutObjectRequest.builder()
                            .bucket(BUCKET_NAME)
                            .key(file.getOriginalFilename())
                            .contentType(file.getContentType())
                            .build(), RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
            RustFSUploadResult uploadResult = new RustFSUploadResult();
            uploadResult.setName(file.getOriginalFilename());
            uploadResult.setUrl(ENDPOINT + "/" + BUCKET_NAME + "/" + file.getOriginalFilename());
            return CommonResult.success(uploadResult);
        } catch (IOException e) {
            e.printStackTrace();
        }
        return CommonResult.error("上传失败");
    }

    /**
     * 文件下载
     * @param fileName
     * @return
     */
    @Operation(summary = "文件下载")
    @RequestMapping(value = "/download",method = RequestMethod.GET)
    @ResponseBody
    public void downloadFile(@RequestParam("fileName") String fileName, HttpServletResponse response) {
        // TODO: 文件下载逻辑
        try {
            // 1. 从 RustFS 获取文件流，返回给客户端
            ResponseInputStream<GetObjectResponse> s3Object = s3Client.getObject(
                    GetObjectRequest.builder()
                            .bucket(BUCKET_NAME)
                            .key(fileName)
                            .build());

            // 2. 设置响应头，告诉浏览器这是一个附件
            response.setContentType(s3Object.response().contentType());
            response.setHeader("Content-Disposition", "attachment; filename=\"" + fileName + "\"");
            response.setContentLengthLong(s3Object.response().contentLength());

            // 3. 把文件流拷贝到 HttpServletResponse 的输出流
            StreamUtils.copy(s3Object, response.getOutputStream());
            response.flushBuffer();
        } catch (S3Exception e) {
            log.error("文件下载失败: {}", e.getMessage());
            throw new RuntimeException("文件下载失败");
        } catch (IOException e) {
            log.error("文件流写入失败: {}", e.getMessage());
            throw new RuntimeException("文件流写入失败");
        }
    }

    /**
     * 文件删除
     * @param fileName
     * @return
     */
    @Operation(summary = "文件删除")
    @RequestMapping(value = "/delete",method = RequestMethod.POST)
    @ResponseBody
    public CommonResult deleteFile(@RequestParam("fileName") String fileName) {
        //删除文件
        s3Client.deleteObject(DeleteObjectRequest.builder()
                .bucket(BUCKET_NAME)
                .key(fileName)
                .build());
        return CommonResult.success(null);
    }

}