从零搭建私有云盘：基于RustFS的全栈实践指南

# 安装Docker
curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

2.2 Docker快速部署（推荐开发环境）

对于开发和测试环境，使用Docker部署是最简单快捷的方式：

# docker-compose.yml
version: '3.8'
services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: rustfs
    ports:
      - "9000:9000"  # API端口
      - "9001:9001"  # 控制台端口
    volumes:
      - ./data:/data  # 数据持久化
    environment:
      - RUSTFS_ROOT_USER=admin
      - RUSTFS_ROOT_PASSWORD=your_strong_password
    restart: unless-stopped

运行以下命令启动服务：

docker-compose up -d

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

2.3 生产环境集群部署

对于生产环境，建议采用多节点集群部署以确保高可用性：

# 下载预编译二进制包
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

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

# 启动集群服务（4节点示例）
rustfs server http://node{1...4}/data{1...4} \
  --address 0.0.0.0:9000 \
  --console-address 0.0.0.0:9001 \
  --access-key admin \
  --secret-key your_strong_password

三、SpringBoot后端服务集成

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.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

3.2 RustFS连接配置

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

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

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

创建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.3 文件服务核心实现

实现完整的文件存储服务：

@Service
@Slf4j
public class FileStorageService {
    @Autowired
    private S3Client s3Client;
    
    @Value("${rustfs.bucket-name}")
    private String bucketName;
    
    /**
     * 上传文件
     */
    public FileUploadResult uploadFile(MultipartFile file, String folder) {
        try {
            // 检查存储桶是否存在
            if (!bucketExists(bucketName)) {
                createBucket(bucketName);
            }
            
            // 生成唯一文件名
            String fileName = generateFileName(file.getOriginalFilename(), folder);
            
            // 上传文件到RustFS
            PutObjectResponse response = s3Client.putObject(
                PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(fileName)
                    .contentType(file.getContentType())
                    .contentLength(file.getSize())
                    .build(),
                RequestBody.fromInputStream(file.getInputStream(), file.getSize())
            );
            
            return FileUploadResult.builder()
                    .fileName(fileName)
                    .originalName(file.getOriginalFilename())
                    .size(file.getSize())
                    .uploadTime(LocalDateTime.now())
                    .url(generateAccessUrl(fileName))
                    .build();
                    
        } catch (Exception e) {
            log.error("文件上传失败", e);
            throw new RuntimeException("文件上传失败: " + e.getMessage());
        }
    }
    
    /**
     * 列出文件
     */
    public List<FileInfo> listFiles(String prefix, int maxKeys) {
        try {
            ListObjectsV2Response response = s3Client.listObjectsV2(
                ListObjectsV2Request.builder()
                    .bucket(bucketName)
                    .prefix(prefix)
                    .maxKeys(maxKeys)
                    .build()
            );
            
            return response.contents().stream()
                    .map(s3Object -> FileInfo.builder()
                            .key(s3Object.key())
                            .size(s3Object.size())
                            .lastModified(s3Object.lastModified())
                            .build())
                    .collect(Collectors.toList());
        } 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());
        }
    }
    
    /**
     * 生成预签名URL用于临时访问
     */
    public String generatePresignedUrl(String fileName, Duration expiry) {
        try {
            GetUrlResponse response = s3Client.utilities().getUrl(
                GetUrlRequest.builder()
                    .bucket(bucketName)
                    .key(fileName)
                    .build()
            );
            return response.url().toString();
        } catch (Exception e) {
            log.error("生成预签名URL失败", e);
            throw new RuntimeException("生成预签名URL失败: " + e.getMessage());
        }
    }
}

3.4 REST API控制器

创建REST API接口：

@RestController
@RequestMapping("/api/files")
@Tag(name = "文件管理", description = "云盘文件上传下载管理")
public class FileController {
    @Autowired
    private FileStorageService fileStorageService;
    
    @PostMapping("/upload")
    @Operation(summary = "上传文件")
    public ResponseEntity<ApiResponse<FileUploadResult>> uploadFile(
            @RequestParam("file") MultipartFile file,
            @RequestParam(value = "folder", defaultValue = "") String folder) {
        try {
            FileUploadResult result = fileStorageService.uploadFile(file, folder);
            return ResponseEntity.ok(ApiResponse.success(result));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(ApiResponse.error(e.getMessage()));
        }
    }
    
    @GetMapping("/list")
    @Operation(summary = "列出文件")
    public ResponseEntity<ApiResponse<List<FileInfo>>> listFiles(
            @RequestParam(value = "prefix", defaultValue = "") String prefix,
            @RequestParam(value = "maxKeys", defaultValue = "100") int maxKeys) {
        try {
            List<FileInfo> files = fileStorageService.listFiles(prefix, maxKeys);
            return ResponseEntity.ok(ApiResponse.success(files));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(ApiResponse.error(e.getMessage()));
        }
    }
    
    @DeleteMapping("/{fileName}")
    @Operation(summary = "删除文件")
    public ResponseEntity<ApiResponse<Void>> deleteFile(@PathVariable String fileName) {
        try {
            fileStorageService.deleteFile(fileName);
            return ResponseEntity.ok(ApiResponse.success(null));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(ApiResponse.error(e.getMessage()));
        }
    }
}

四、前端界面开发（Vue3实现）

4.1 项目初始化与依赖安装

使用Vue3创建前端项目：

npm create vue@latest cloud-drive-frontend
cd cloud-drive-frontend
npm install axios element-plus @element-plus/icons-vue

4.2 文件上传组件实现

创建文件上传组件：

<template>
  <div class="upload-container">
    <el-upload
      class="upload-demo"
      drag
      multiple
      :action="uploadUrl"
      :headers="headers"
      :data="uploadData"
      :on-success="handleSuccess"
      :on-error="handleError"
      :before-upload="beforeUpload"
    >
      <el-icon class="el-icon--upload"><upload-filled /></el-icon>
      <div class="el-upload__text">
        将文件拖到此处，或<em>点击上传</em>
      </div>
      <template #tip>
        <div class="el-upload__tip">
          支持单个或批量上传，单文件不超过10MB
        </div>
      </template>
    </el-upload>
    
    <!-- 上传进度显示 -->
    <div v-if="uploadProgress.visible" class="progress-panel">
      <div class="progress-item" v-for="item in progressList" :key="item.id">
        <div class="file-info">
          <span>{{ item.name }}</span>
          <span>{{ item.percentage }}%</span>
        </div>
        <el-progress :percentage="item.percentage" :status="item.status" />
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'
import { ElMessage } from 'element-plus'
import { UploadFilled } from '@element-plus/icons-vue'

const props = defineProps({
  currentFolder: {
    type: String,
    default: ''
  }
})

const uploadUrl = ref(`${import.meta.env.VITE_API_BASE_URL}/api/files/upload`)
const headers = ref({
  'Authorization': `Bearer ${localStorage.getItem('token')}`
})
const uploadData = computed(() => ({
  folder: props.currentFolder
}))

const uploadProgress = ref({
  visible: false,
  files: new Map()
})

const progressList = computed(() => {
  return Array.from(uploadProgress.value.files.values())
})

const beforeUpload = (file) => {
  // 文件大小校验
  if (file.size > 10 * 1024 * 1024) {
    ElMessage.error('文件大小不能超过10MB')
    return false
  }
  
  // 添加到上传进度
  uploadProgress.value.files.set(file.uid, {
    id: file.uid,
    name: file.name,
    percentage: 0,
    status: 'success'
  })
  uploadProgress.value.visible = true
  return true
}

const handleSuccess = (response, file) => {
  const fileItem = uploadProgress.value.files.get(file.uid)
  if (fileItem) {
    fileItem.percentage = 100
    fileItem.status = 'success'
  }
  ElMessage.success(`文件 ${file.name} 上传成功`)
  
  // 3秒后清除进度显示
  setTimeout(() => {
    uploadProgress.value.files.delete(file.uid)
    if (uploadProgress.value.files.size === 0) {
      uploadProgress.value.visible = false
    }
  }, 3000)
}

const handleError = (error, file) => {
  const fileItem = uploadProgress.value.files.get(file.uid)
  if (fileItem) {
    fileItem.status = 'exception'
  }
  ElMessage.error(`文件 ${file.name} 上传失败: ${error.message}`)
}
</script>

4.3 文件列表组件

创建文件列表展示组件：

<template>
  <div class="file-list">
    <div class="toolbar">
      <el-button type="primary" @click="refreshList">
        <el-icon><Refresh /></el-icon>
        刷新
      </el-button>
      
      <el-input
        v-model="searchText"
        placeholder="搜索文件..."
        style="width: 300px; margin-left: 10px;"
        clearable
      >
        <template #prefix>
          <el-icon><Search /></el-icon>
        </template>
      </el-input>
    </div>
    
    <el-table :data="filteredFiles" style="width: 100%" v-loading="loading">
      <el-table-column prop="name" label="文件名" min-width="200">
        <template #default="scope">
          <div class="file-name-cell">
            <el-icon class="file-icon">
              <Document v-if="!scope.row.isFolder" />
              <Folder v-else />
            </el-icon>
            <span>{{ scope.row.name }}</span>
          </div>
        </template>
      </el-table-column>
      
      <el-table-column prop="size" label="大小" width="120">
        <template #default="scope">
          {{ formatFileSize(scope.row.size) }}
        </template>
      </el-table-column>
      
      <el-table-column prop="lastModified" label="修改时间" width="180">
        <template #default="scope">
          {{ formatDate(scope.row.lastModified) }}
        </template>
      </el-table-column>
      
      <el-table-column label="操作" width="150">
        <template #default="scope">
          <el-button link type="primary" @click="downloadFile(scope.row)">
            下载
          </el-button>
          <el-button link type="danger" @click="deleteFile(scope.row)">
            删除
          </el-button>
        </template>
      </el-table-column>
    </el-table>
  </div>
</template>

<script setup>
import { ref, computed, onMounted } from 'vue'
import { ElMessage, ElMessageBox } from 'element-plus'
import { Document, Folder, Refresh, Search } from '@element-plus/icons-vue'
import { fileApi } from '@/api/file'

const files = ref([])
const loading = ref(false)
const searchText = ref('')

const filteredFiles = computed(() => {
  if (!searchText.value) return files.value
  return files.value.filter(file => 
    file.name.toLowerCase().includes(searchText.value.toLowerCase())
  )
})

const loadFileList = async () => {
  try {
    loading.value = true
    const response = await fileApi.listFiles('', 1000)
    files.value = response.data
  } catch (error) {
    ElMessage.error('获取文件列表失败')
  } finally {
    loading.value = false
  }
}

const downloadFile = async (file) => {
  try {
    const url = await fileApi.generateDownloadUrl(file.key)
    window.open(url, '_blank')
  } catch (error) {
    ElMessage.error('下载文件失败')
  }
}

const deleteFile = async (file) => {
  try {
    await ElMessageBox.confirm(
      `确定要删除文件 "${file.name}" 吗？此操作不可恢复。`,
      '确认删除',
      { type: 'warning' }
    )
    
    await fileApi.deleteFile(file.key)
    ElMessage.success('文件删除成功')
    await loadFileList()
  } catch (error) {
    if (error !== 'cancel') {
      ElMessage.error('删除文件失败')
    }
  }
}

const formatFileSize = (bytes) => {
  if (bytes === 0) return '0 B'
  const k = 1024
  const sizes = ['B', 'KB', 'MB', 'GB']
  const i = Math.floor(Math.log(bytes) / Math.log(k))
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
}

const formatDate = (timestamp) => {
  return new Date(timestamp).toLocaleString()
}

const refreshList = () => {
  loadFileList()
}

onMounted(() => {
  loadFileList()
})
</script>

五、高级功能实现

5.1 大文件分片上传

对于大文件，实现分片上传功能：

@Service
public class LargeFileUploadService {
    
    private static final int PART_SIZE = 5 * 1024 * 1024; // 5MB分片
    
    public String uploadLargeFile(String fileName, InputStream inputStream, long fileSize) {
        try {
            // 初始化分片上传
            String uploadId = initiateMultipartUpload(fileName);
            
            // 分片上传
            List<CompletedPart> completedParts = new ArrayList<>();
            byte[] buffer = new byte[PART_SIZE];
            int bytesRead;
            int partNumber = 1;
            
            while ((bytesRead = inputStream.read(buffer)) != -1) {
                String etag = uploadPart(fileName, uploadId, partNumber, 
                    new ByteArrayInputStream(buffer, 0, bytesRead), bytesRead);
                
                completedParts.add(CompletedPart.builder()
                    .partNumber(partNumber)
                    .eTag(etag)
                    .build());
                
                partNumber++;
            }
            
            // 完成分片上传
            completeMultipartUpload(fileName, uploadId, completedParts);
            return uploadId;
            
        } catch (Exception e) {
            throw new RuntimeException("大文件上传失败", e);
        }
    }
}

5.2 文件预览功能

实现常见文件类型的在线预览：

<template>
  <div class="file-preview">
    <div v-if="previewUrl" class="preview-content">
      <iframe v-if="isOfficeFile" :src="`https://view.officeapps.live.com/op/embed.aspx?src=${previewUrl}`" 
              width="100%" height="600px" frameborder="0"></iframe>
      
      <img v-else-if="isImage" :src="previewUrl" alt="预览" class="preview-image">
      
      <video v-else-if="isVideo" :src="previewUrl" controls class="preview-video">
        您的浏览器不支持视频播放
      </video>
      
      <div v-else class="unsupported-preview">
        <el-icon><Document /></el-icon>
        <p>暂不支持该文件类型的预览</p>
        <el-button type="primary" @click="downloadFile">下载文件</el-button>
      </div>
    </div>
  </div>
</template>

六、安全与权限管理

6.1 访问控制配置

配置存储桶策略，实现细粒度权限控制：

@Service
public class SecurityService {
    
    public void setBucketPolicy(String bucketName, String policyJson) {
        s3Client.putBucketPolicy(
            PutBucketPolicyRequest.builder()
                .bucket(bucketName)
                .policy(policyJson)
                .build()
        );
    }
    
    /**
     * 设置仅允许内网访问的策略
     */
    public void setInternalAccessPolicy(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);
        
        setBucketPolicy(bucketName, policy);
    }
}

6.2 文件类型白名单验证

七、部署与监控

7.1 Docker Compose全栈部署

创建完整的docker-compose部署文件：

version: '3.8'
services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: rustfs
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - rustfs_data:/data
    environment:
      - RUSTFS_ROOT_USER=admin
      - RUSTFS_ROOT_PASSWORD=your_strong_password
    restart: unless-stopped
    
  backend:
    image: cloud-drive-backend:latest
    ports:
      - "8080:8080"
    environment:
      - RUSTFS_ENDPOINT=http://rustfs:9000
      - RUSTFS_ACCESS_KEY=admin
      - RUSTFS_SECRET_KEY=your_strong_password
    depends_on:
      - rustfs
    restart: unless-stopped
    
  frontend:
    image: cloud-drive-frontend:latest
    ports:
      - "80:80"
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  rustfs_data:

7.2 监控与健康检查

配置Spring Boot Actuator进行健康监控：

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,info
  endpoint:
    health:
      show-details: always
  health:
    diskspace:
      enabled: true