SpringBoot+RustFS保姆级教程！文件管理全场景实战，含分片上传企业级方案

# 拉取最新镜像
docker pull rustfs/rustfs:latest

# 运行RustFS容器
docker run -d \
  -p 9000:9000 \
  -p 9001:9001 \
  --name rustfs \
  -v /mnt/data:/data \
  -e "RUSTFS_ACCESS_KEY=admin" \
  -e "RUSTFS_SECRET_KEY=your_strong_password" \
  rustfs/rustfs:latest

参数说明：

-p 9000:9000：API端口，用于S3接口访问
-p 9001:9001：控制台端口，用于Web管理
-v /mnt/data:/data：数据持久化目录（生产环境务必使用绝对路径）
RUSTFS_ACCESS_KEY和RUSTFS_SECRET_KEY：管理员账号密码

2.2 二进制部署（生产环境）

对于生产环境，我建议采用二进制部署以获得更好性能：

# 下载预编译二进制包
wget https://github.com/rustfs/rustfs/releases/download/v0.9.3/rustfs_0.9.3_linux_amd64.tar.gz

# 解压并安装
tar -zxvf rustfs_0.9.3_linux_amd64.tar.gz
sudo mv rustfs /usr/local/bin/

# 创建数据目录
mkdir -p /data/rustfs
chmod 755 /data/rustfs

# 启动服务
rustfs serve --data-dir /data/rustfs \
  --address 0.0.0.0:9000 \
  --access-key admin \
  --secret-key your_strong_password \
  --console-enable \
  --console-address 0.0.0.0:9001

部署完成后，访问 http://localhost:9001使用设置的账号密码登录管理控制台。

三、SpringBoot集成RustFS：基础文件操作

3.1 项目搭建与依赖配置

首先创建SpringBoot项目，在pom.xml中添加必要依赖：

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- AWS S3 SDK（RustFS兼容S3协议） -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.20.59</version>
    </dependency>

    <!-- 工具库 -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
    </dependency>
    
    <!-- 简化IO操作 -->
    <dependency>
        <groupId>commons-io</groupId>
        <artifactId>commons-io</artifactId>
        <version>2.11.0</version>
    </dependency>
</dependencies>

3.2 配置RustFS连接

在application.yml中配置RustFS连接信息：

rustfs:
  endpoint: http://localhost:9000
  access-key: admin
  secret-key: your_strong_password
  bucket-name: my-bucket

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 100MB

3.3 创建RustFS配置类

@Configuration
@ConfigurationProperties(prefix = "rustfs")
public class RustFSConfig {
    private String endpoint;
    private String accessKey;
    private String secretKey;
    private String bucketName;

    @Bean
    public S3Client s3Client() {
        return S3Client.builder()
                .endpointOverride(URI.create(endpoint))
                .region(Region.US_EAST_1)
                .credentialsProvider(StaticCredentialsProvider.create(
                    AwsBasicCredentials.create(accessKey, secretKey)))
                .forcePathStyle(true)  // 关键配置！RustFS需启用Path-Style
                .build();
    }

    // getters and setters
}

3.4 实现基础文件操作服务

@Service
@Slf4j
public class FileStorageService {
    @Autowired
    private S3Client s3Client;
    
    @Value("${rustfs.bucket-name}")
    private String bucketName;

    /**
     * 上传文件
     */
    public String uploadFile(MultipartFile file) {
        try {
            // 检查存储桶是否存在，不存在则创建
            if (!bucketExists(bucketName)) {
                createBucket(bucketName);
            }

            String fileName = generateFileName(file.getOriginalFilename());
            
            s3Client.putObject(
                PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(fileName)
                    .contentType(file.getContentType())
                    .build(),
                RequestBody.fromInputStream(
                    file.getInputStream(), 
                    file.getSize()
                )
            );
            
            return fileName;
        } catch (Exception e) {
            log.error("文件上传失败", e);
            throw new RuntimeException("文件上传失败: " + e.getMessage());
        }
    }

    /**
     * 下载文件
     */
    public byte[] downloadFile(String fileName) {
        try {
            ResponseInputStream<GetObjectResponse> response = 
                s3Client.getObject(
                    GetObjectRequest.builder()
                        .bucket(bucketName)
                        .key(fileName)
                        .build()
                );
            
            return response.readAllBytes();
        } catch (Exception e) {
            log.error("文件下载失败", e);
            throw new RuntimeException("文件下载失败: " + e.getMessage());
        }
    }

    /**
     * 删除文件
     */
    public void deleteFile(String fileName) {
        try {
            s3Client.deleteObject(
                DeleteObjectRequest.builder()
                    .bucket(bucketName)
                    .key(fileName)
                    .build()
            );
        } catch (Exception e) {
            log.error("文件删除失败", e);
            throw new RuntimeException("文件删除失败: " + e.getMessage());
        }
    }

    /**
     * 检查存储桶是否存在
     */
    private boolean bucketExists(String bucketName) {
        try {
            s3Client.headBucket(
                HeadBucketRequest.builder()
                    .bucket(bucketName)
                    .build()
            );
            return true;
        } catch (NoSuchBucketException e) {
            return false;
        }
    }

    /**
     * 创建存储桶
     */
    private void createBucket(String bucketName) {
        s3Client.createBucket(
            CreateBucketRequest.builder()
                .bucket(bucketName)
                .build()
        );
    }

    /**
     * 生成唯一文件名
     */
    private String generateFileName(String originalFileName) {
        String extension = "";
        if (originalFileName != null && originalFileName.contains(".")) {
            extension = originalFileName.substring(originalFileName.lastIndexOf("."));
        }
        return UUID.randomUUID().toString() + extension;
    }
}

3.5 创建REST控制器

@RestController
@RequestMapping("/api/files")
@Tag(name = "文件管理", description = "文件上传下载管理")
public class FileController {
    @Autowired
    private FileStorageService fileStorageService;

    @PostMapping("/upload")
    @Operation(summary = "上传文件")
    public ResponseEntity<Map<String, String>> uploadFile(
            @RequestParam("file") MultipartFile file) {
        try {
            String fileName = fileStorageService.uploadFile(file);
            return ResponseEntity.ok(Map.of(
                "fileName", fileName,
                "message", "文件上传成功"
            ));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(Map.of("error", e.getMessage()));
        }
    }

    @GetMapping("/download/{fileName}")
    @Operation(summary = "下载文件")
    public ResponseEntity<byte[]> downloadFile(@PathVariable String fileName) {
        try {
            byte[] fileContent = fileStorageService.downloadFile(fileName);
            
            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, 
                            "attachment; filename=\"" + fileName + "\"")
                    .contentType(MediaType.APPLICATION_OCTET_STREAM)
                    .body(fileContent);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }

    @DeleteMapping("/{fileName}")
    @Operation(summary = "删除文件")
    public ResponseEntity<Map<String, String>> deleteFile(@PathVariable String fileName) {
        try {
            fileStorageService.deleteFile(fileName);
            return ResponseEntity.ok(Map.of("message", "文件删除成功"));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(Map.of("error", e.getMessage()));
        }
    }
}

四、企业级分片上传方案实现

在实际项目中，我们经常需要处理大文件上传。传统单次上传方式存在网络不稳定、服务器内存溢出等问题。分片上传技术通过将大文件分割成小块并行上传，有效解决了这些问题。

4.1 分片上传核心原理

分片上传的核心思想是：

文件分块：将大文件分成固定大小的块（如5MB）
并行上传：多个分块可以同时上传，提高效率
断点续传：记录上传进度，中断后可从断点继续
分块合并：所有分块上传完成后在服务器端合并

4.2 分片上传服务实现

@Service
@Slf4j
public class MultipartUploadService {
    @Autowired
    private S3Client s3Client;
    
    @Value("${rustfs.bucket-name}")
    private String bucketName;
    
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;

    /**
     * 初始化分片上传
     */
    public String initiateMultipartUpload(String fileName) {
        CreateMultipartUploadResponse response = s3Client.createMultipartUpload(
            CreateMultipartUploadRequest.builder()
                .bucket(bucketName)
                .key(fileName)
                .build()
        );
        return response.uploadId();
    }

    /**
     * 上传分片
     */
    public String uploadPart(String fileName, String uploadId, 
                           int partNumber, InputStream inputStream, long size) {
        UploadPartResponse response = s3Client.uploadPart(
            UploadPartRequest.builder()
                .bucket(bucketName)
                .key(fileName)
                .uploadId(uploadId)
                .partNumber(partNumber)
                .build(),
            RequestBody.fromInputStream(inputStream, size)
        );

        // 记录已上传分片
        redisTemplate.opsForSet().add("upload:" + fileName, partNumber);
        
        return response.eTag();
    }

    /**
     * 完成分片上传
     */
    public void completeMultipartUpload(String fileName, String uploadId, 
                                      List<CompletedPart> completedParts) {
        s3Client.completeMultipartUpload(
            CompleteMultipartUploadRequest.builder()
                .bucket(bucketName)
                .key(fileName)
                .uploadId(uploadId)
                .multipartUpload(CompletedMultipartUpload.builder()
                    .parts(completedParts)
                    .build())
                .build()
        );
        
        // 清理上传记录
        redisTemplate.delete("upload:" + fileName);
    }

    /**
     * 获取已上传分片列表（用于断点续传）
     */
    public List<Integer> getUploadedParts(String fileName) {
        Set<Object> uploaded = redisTemplate.opsForSet().members("upload:" + fileName);
        return uploaded.stream()
                .map(obj -> Integer.parseInt(obj.toString()))
                .collect(Collectors.toList());
    }
}

4.3 分片上传控制器

@RestController
@RequestMapping("/api/multipart")
@Tag(name = "分片上传", description = "大文件分片上传管理")
public class MultipartUploadController {
    @Autowired
    private MultipartUploadService multipartUploadService;

    @PostMapping("/init")
    @Operation(summary = "初始化分片上传")
    public ResponseEntity<Map<String, String>> initUpload(@RequestParam String fileName) {
        try {
            String uploadId = multipartUploadService.initiateMultipartUpload(fileName);
            return ResponseEntity.ok(Map.of(
                "uploadId", uploadId,
                "fileName", fileName
            ));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(Map.of("error", e.getMessage()));
        }
    }

    @PostMapping("/upload-part")
    @Operation(summary = "上传分片")
    public ResponseEntity<Map<String, String>> uploadPart(
            @RequestParam String fileName,
            @RequestParam String uploadId,
            @RequestParam int partNumber,
            @RequestParam MultipartFile chunk) {
        try {
            String eTag = multipartUploadService.uploadPart(
                fileName, uploadId, partNumber, 
                chunk.getInputStream(), chunk.getSize()
            );
            
            return ResponseEntity.ok(Map.of(
                "partNumber", String.valueOf(partNumber),
                "eTag", eTag
            ));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(Map.of("error", e.getMessage()));
        }
    }

    @PostMapping("/complete")
    @Operation(summary = "完成分片上传")
    public ResponseEntity<Map<String, String>> completeUpload(
            @RequestParam String fileName,
            @RequestParam String uploadId,
            @RequestBody List<CompletedPart> parts) {
        try {
            multipartUploadService.completeMultipartUpload(fileName, uploadId, parts);
            return ResponseEntity.ok(Map.of("message", "文件上传完成"));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(Map.of("error", e.getMessage()));
        }
    }

    @GetMapping("/progress/{fileName}")
    @Operation(summary = "获取上传进度")
    public ResponseEntity<List<Integer>> getUploadProgress(@PathVariable String fileName) {
        try {
            List<Integer> uploadedParts = multipartUploadService.getUploadedParts(fileName);
            return ResponseEntity.ok(uploadedParts);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }
}

4.4 前端分片上传实现（Vue示例）

export default {
  data() {
    return {
      CHUNK_SIZE: 5 * 1024 * 1024, // 5MB分片大小
      concurrentLimit: 3, // 并发上传数
      uploadProgress: {}
    }
  },
  
  methods: {
    // 分片上传文件
    async uploadFile(file) {
      // 初始化上传
      const initResponse = await this.$http.post('/api/multipart/init', {
        fileName: file.name
      });
      
      const { uploadId, fileName } = initResponse.data;
      
      // 计算分片信息
      const totalChunks = Math.ceil(file.size / this.CHUNK_SIZE);
      const uploadPromises = [];
      
      for (let i = 0; i < totalChunks; i++) {
        const start = i * this.CHUNK_SIZE;
        const end = Math.min(file.size, start + this.CHUNK_SIZE);
        const chunk = file.slice(start, end);
        
        // 控制并发数
        if (uploadPromises.length >= this.concurrentLimit) {
          await Promise.race(uploadPromises);
        }
        
        const uploadPromise = this.uploadChunk(chunk, fileName, uploadId, i, totalChunks)
          .finally(() => {
            const index = uploadPromises.indexOf(uploadPromise);
            if (index > -1) {
              uploadPromises.splice(index, 1);
            }
          });
        
        uploadPromises.push(uploadPromise);
      }
      
      // 等待所有分片上传完成
      await Promise.all(uploadPromises);
      
      // 完成上传
      await this.completeUpload(fileName, uploadId);
    },
    
    // 上传单个分片
    async uploadChunk(chunk, fileName, uploadId, chunkIndex, totalChunks) {
      const formData = new FormData();
      formData.append('chunk', chunk);
      formData.append('fileName', fileName);
      formData.append('uploadId', uploadId);
      formData.append('partNumber', chunkIndex);
      
      try {
        const response = await this.$http.post('/api/multipart/upload-part', formData, {
          headers: { 'Content-Type': 'multipart/form-data' },
          onUploadProgress: (progressEvent) => {
            this.updateProgress(fileName, chunkIndex, progressEvent.loaded / progressEvent.total);
          }
        });
        
        return response.data;
      } catch (error) {
        console.error(`分片 ${chunkIndex} 上传失败:`, error);
        throw error;
      }
    },
    
    // 更新上传进度
    updateProgress(fileName, chunkIndex, progress) {
      if (!this.uploadProgress[fileName]) {
        this.uploadProgress[fileName] = {};
      }
      this.uploadProgress[fileName][chunkIndex] = progress;
    }
  }
}

4.5 性能优化建议

根据我的实战经验，分片上传的性能优化至关重要：

分片大小选择：
- 内网环境：10MB-20MB
- 移动网络：1MB-5MB
- 广域网：500KB-1MB
并发控制：根据服务器带宽和处理能力调整并发上传数
内存优化：使用流式处理避免大文件内存溢出
超时重试：为每个分片上传添加超时和重试机制

五、安全与权限管理

在企业级应用中，安全性至关重要。以下是我推荐的安全实践：

5.1 访问控制配置

/**
 * 设置存储桶策略
 */
private void setBucketPolicy(String bucketName) {
    String policy = """
        {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {"AWS": ["*"]},
                    "Action": ["s3:GetObject"],
                    "Resource": ["arn:aws:s3:::%s/*"],
                    "Condition": {
                        "IpAddress": {"aws:SourceIp": ["192.168.1.0/24"]}
                    }
                }
            ]
        }
        """.formatted(bucketName);

    s3Client.putBucketPolicy(
        PutBucketPolicyRequest.builder()
            .bucket(bucketName)
            .policy(policy)
            .build()
    );
}

5.2 文件类型白名单验证

/**
 * 验证文件类型
 */
private boolean validateFileType(MultipartFile file) {
    String[] allowedTypes = {
        "image/jpeg", "image/png", "image/gif",
        "application/pdf", "text/plain"
    };
    
    String fileType = file.getContentType();
    return Arrays.asList(allowedTypes).contains(fileType);
}

六、部署与监控

6.1 Docker Compose部署方案

对于生产环境，我推荐使用Docker Compose部署：

version: '3.8'
services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: rustfs
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - /data/rustfs:/data
    environment:
      - RUSTFS_ACCESS_KEY=admin
      - RUSTFS_SECRET_KEY=your_strong_password
    restart: unless-stopped
    networks:
      - storage-network

  springboot-app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - RUSTFS_ENDPOINT=http://rustfs:9000
    depends_on:
      - rustfs
    restart: unless-stopped
    networks:
      - storage-network

networks:
  storage-network:
    driver: bridge

6.2 监控配置

集成Prometheus监控RustFS性能：

# application.yml 监控配置
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  metrics:
    tags:
      application: ${spring.application.name}