分布式文件存储：MinIO、阿里云 OSS 与 Spring 集成实战

# docker-compose.yml
version: '3.8'
services:
  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"    # API 端口
      - "9001:9001"    # Console 端口
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: changeme123
    volumes:
      - ./data:/data
    command: server /data --console-address ":9001"

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version>
</dependency>

# application.yml
minio:
  endpoint: http://localhost:9000
  access-key: admin
  secret-key: changeme123
  bucket-name: myapp

@Configuration
public class MinioConfig {
    
    @Value("${minio.endpoint}")
    private String endpoint;
    
    @Value("${minio.access-key}")
    private String accessKey;
    
    @Value("${minio.secret-key}")
    private String secretKey;
    
    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
            .endpoint(endpoint)
            .credentials(accessKey, secretKey)
            .build();
    }
}

@Service
@Slf4j
public class MinioStorageService {
    
    @Autowired
    private MinioClient minioClient;
    
    @Value("${minio.bucket-name}")
    private String bucketName;
    
    @PostConstruct
    public void init() throws Exception {
        // 自动创建 bucket
        boolean exists = minioClient.bucketExists(
            BucketExistsArgs.builder().bucket(bucketName).build()
        );
        if (!exists) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build());
            
            // 设置 bucket 策略为只读（公共可访问图片）
            String policy = """
                {"Version":"2012-10-17","Statement":[
                    {"Effect":"Allow","Principal":"*","Action":"s3:GetObject",
                     "Resource":"arn:aws:s3:::%s/*"}
                ]}
                """.formatted(bucketName);
            minioClient.setBucketPolicy(
                SetBucketPolicyArgs.builder().bucket(bucketName).config(policy).build()
            );
        }
    }
    
    public String upload(MultipartFile file, String folder) {
        String originalName = file.getOriginalFilename();
        String ext = FilenameUtils.getExtension(originalName);
        String fileName = folder + "/" + UUID.randomUUID() + "." + ext;
        
        try (InputStream is = file.getInputStream()) {
            minioClient.putObject(PutObjectArgs.builder()
                .bucket(bucketName)
                .object(fileName)
                .stream(is, file.getSize(), -1)
                .contentType(file.getContentType())
                .build()
            );
            return fileName;
        } catch (Exception e) {
            log.error("文件上传失败: {}", originalName, e);
            throw new StorageException("文件上传失败");
        }
    }
    
    public InputStream download(String fileName) {
        try {
            return minioClient.getObject(GetObjectArgs.builder()
                .bucket(bucketName)
                .object(fileName)
                .build()
            );
        } catch (Exception e) {
            throw new StorageException("文件下载失败: " + fileName);
        }
    }
    
    public String getPresignedUrl(String fileName, int expiryMinutes) {
        try {
            return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder()
                .method(Method.GET)
                .bucket(bucketName)
                .object(fileName)
                .expiry(expiryMinutes, TimeUnit.MINUTES)
                .build()
            );
        } catch (Exception e) {
            throw new StorageException("生成预签名 URL 失败");
        }
    }
    
    public void delete(String fileName) {
        try {
            minioClient.removeObject(RemoveObjectArgs.builder()
                .bucket(bucketName)
                .object(fileName)
                .build()
            );
        } catch (Exception e) {
            log.error("文件删除失败: {}", fileName, e);
        }
    }
}

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

aliyun:
  oss:
    endpoint: oss-cn-hangzhou.aliyuncs.com
    access-key-id: ${OSS_ACCESS_KEY_ID}
    access-key-secret: ${OSS_ACCESS_KEY_SECRET}
    bucket-name: myapp-bucket

@Service
public class OssUploadService {
    
    @Autowired
    private OSS ossClient;
    
    @Value("${aliyun.oss.bucket-name}")
    private String bucketName;
    
    /**
     * 生成前端直传的签名信息
     */
    public Map<String, String> generatePostPolicy(String dir, long maxSize) {
        try {
            long expireEndTime = System.currentTimeMillis() + 3600 * 1000;
            Date expiration = new Date(expireEndTime);
            
            PolicyConditions policyConds = new PolicyConditions();
            policyConds.addConditionItem(PolicyConditions.COND_CONTENT_LENGTH_RANGE, 0, maxSize);
            policyConds.addConditionItem(MatchMode.StartWith, PolicyConditions.COND_KEY, dir);
            
            String postPolicy = ossClient.generatePostPolicy(expiration, policyConds);
            byte[] binaryData = postPolicy.getBytes(StandardCharsets.UTF_8);
            String encodedPolicy = BinaryUtil.toBase64String(binaryData);
            String postSignature = ossClient.calculatePostSignature(postPolicy);
            
            Map<String, String> result = new HashMap<>();
            result.put("accessid", accessKeyId);
            result.put("policy", encodedPolicy);
            result.put("signature", postSignature);
            result.put("dir", dir);
            result.put("host", "https://" + bucketName + "." + endpoint);
            result.put("expire", String.valueOf(expireEndTime / 1000));
            return result;
        } catch (Exception e) {
            throw new StorageException("生成上传签名失败");
        }
    }
    
    /**
     * 断点续传
     */
    public String uploadWithCheckpoint(MultipartFile file, String objectName) {
        try {
            UploadFileRequest request = new UploadFileRequest(bucketName, objectName);
            request.setUploadFile(file.getInputStream());
            request.setTaskNum(3);                    // 并发数
            request.setPartSize(1024 * 1024L);        // 分片大小 1MB
            request.setEnableCheckpoint(true);        // 开启断点续传
            request.setCheckpointFile("/tmp/checkpoint/" + objectName);
            
            UploadFileResult result = ossClient.uploadFile(request);
            return result.getMultipartUploadResult().getLocation();
        } catch (Exception e) {
            throw new StorageException("断点上传失败");
        }
    }
}

// Vue/React 前端直传
async function uploadToOSS(file, policy) {
    const formData = new FormData();
    formData.append('OSSAccessKeyId', policy.accessid);
    formData.append('policy', policy.policy);
    formData.append('signature', policy.signature);
    formData.append('key', policy.dir + '${filename}');
    formData.append('success_action_status', '200');
    formData.append('file', file);
    
    const response = await fetch(policy.host, {
        method: 'POST',
        body: formData
    });
    
    if (response.status === 200) {
        return `${policy.host}/${policy.dir}${file.name}`;
    }
    throw new Error('上传失败');
}

@RestController
@RequestMapping("/api/upload")
public class ChunkUploadController {
    
    @PostMapping("/chunk")
    public ResponseEntity<Void> uploadChunk(
        @RequestParam("chunk") MultipartFile chunk,
        @RequestParam("chunkNumber") int chunkNumber,
        @RequestParam("totalChunks") int totalChunks,
        @RequestParam("identifier") String identifier
    ) {
        String chunkDir = "/tmp/chunks/" + identifier;
        File dir = new File(chunkDir);
        dir.mkdirs();
        
        try {
            chunk.transferTo(new File(dir, String.valueOf(chunkNumber)));
        } catch (IOException e) {
            throw new UploadException("分片上传失败");
        }
        
        return ResponseEntity.ok().build();
    }
    
    @PostMapping("/merge")
    public ResponseEntity<String> mergeChunks(
        @RequestParam("identifier") String identifier,
        @RequestParam("filename") String filename,
        @RequestParam("totalChunks") int totalChunks
    ) {
        String chunkDir = "/tmp/chunks/" + identifier;
        String mergedFile = "/tmp/merged/" + filename;
        
        try (FileOutputStream fos = new FileOutputStream(mergedFile)) {
            for (int i = 1; i <= totalChunks; i++) {
                File chunk = new File(chunkDir, String.valueOf(i));
                Files.copy(chunk.toPath(), fos);
                chunk.delete();  // 清理分片
            }
            
            // 上传到对象存储
            String url = minioStorageService.upload(new FileSystemResource(mergedFile), "uploads");
            
            // 清理临时文件
            new File(mergedFile).delete();
            new File(chunkDir).delete();
            
            return ResponseEntity.ok(url);
        } catch (IOException e) {
            throw new UploadException("文件合并失败");
        }
    }
}

@Service
public class ImageProcessService {
    
    public byte[] resize(InputStream input, int width, int height) {
        try {
            BufferedImage original = ImageIO.read(input);
            BufferedImage resized = Thumbnails.of(original)
                .size(width, height)
                .crop(Positions.CENTER)
                .outputQuality(0.85)
                .asBufferedImage();
            
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            ImageIO.write(resized, "jpg", baos);
            return baos.toByteArray();
        } catch (IOException e) {
            throw new ImageProcessException("图片处理失败");
        }
    }
    
    public byte[] addWatermark(InputStream input, String watermarkText) {
        try {
            BufferedImage image = ImageIO.read(input);
            Graphics2D g = image.createGraphics();
            
            g.setColor(new Color(255, 255, 255, 128));
            g.setFont(new Font("Arial", Font.BOLD, 36));
            g.rotate(Math.toRadians(-30), image.getWidth() / 2, image.getHeight() / 2);
            g.drawString(watermarkText, image.getWidth() / 4, image.getHeight() / 2);
            g.dispose();
            
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            ImageIO.write(image, "png", baos);
            return baos.toByteArray();
        } catch (IOException e) {
            throw new ImageProcessException("水印添加失败");
        }
    }
}

@Component
public class FileValidator {
    
    private static final Set<String> ALLOWED_TYPES = Set.of(
        "image/jpeg", "image/png", "image/gif", "image/webp",
        "application/pdf", "application/msword",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    );
    
    private static final Map<String, byte[]> MAGIC_NUMBERS = Map.of(
        "image/jpeg", new byte[]{(byte) 0xFF, (byte) 0xD8, (byte) 0xFF},
        "image/png", new byte[]{0x89, 0x50, 0x4E, 0x47},
        "image/gif", new byte[]{0x47, 0x49, 0x46, 0x38},
        "application/pdf", new byte[]{0x25, 0x50, 0x44, 0x46}
    );
    
    public boolean validate(MultipartFile file) {
        String contentType = file.getContentType();
        if (!ALLOWED_TYPES.contains(contentType)) {
            return false;
        }
        
        // 魔数校验，防止伪装扩展名
        try {
            byte[] header = file.getBytes(0, 4);
            byte[] expected = MAGIC_NUMBERS.get(contentType);
            if (expected != null) {
                for (int i = 0; i < expected.length; i++) {
                    if (header[i] != expected[i]) return false;
                }
            }
        } catch (IOException e) {
            return false;
        }
        
        return true;
    }
}

@Service
public class SecureUrlService {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
    
    /**
     * 生成一次性下载链接
     */
    public String generateOneTimeUrl(String objectName, int ttlSeconds) {
        String token = UUID.randomUUID().toString();
        String key = "download:" + token;
        
        redisTemplate.opsForValue().set(key, objectName, ttlSeconds, TimeUnit.SECONDS);
        
        return "/api/download?token=" + token;
    }
    
    public InputStream downloadByToken(String token) {
        String key = "download:" + token;
        String objectName = redisTemplate.opsForValue().get(key);
        
        if (objectName == null) {
            throw new SecurityException("下载链接已过期或无效");
        }
        
        // 删除 token，确保一次性
        redisTemplate.delete(key);
        
        return minioStorageService.download(objectName);
    }
}

@Service
public class AdaptiveImageService {
    
    public String getOptimizedUrl(String originalUrl, int viewportWidth) {
        // 根据视口宽度返回不同尺寸
        String size;
        if (viewportWidth <= 320) size = "@!small";
        else if (viewportWidth <= 768) size = "@!medium";
        else if (viewportWidth <= 1200) size = "@!large";
        else size = "";
        
        return originalUrl + size;
    }
}

# docker-compose.distributed.yml
version: '3.8'
services:
  minio1:
    image: minio/minio:latest
    hostname: minio1
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: changeme123!
      MINIO_SERVER_URL: http://lb.example.com
    volumes:
      - minio1-data1:/data1
      - minio1-data2:/data2
    command: server --console-address ":9001" \
      http://minio1/data1 http://minio1/data2 \
      http://minio2/data1 http://minio2/data2
    ports:
      - "9000:9000"
      - "9001:9001"
    networks:
      - minio-cluster
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3
      start_period: 40s
  minio2:
    image: minio/minio:latest
    hostname: minio2
    environment:
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: changeme123!
    volumes:
      - minio2-data1:/data1
      - minio2-data2:/data2
    command: server --console-address ":9001" \
      http://minio1/data1 http://minio1/data2 \
      http://minio2/data1 http://minio2/data2
    ports:
      - "9002:9000"
      - "9003:9001"
    networks:
      - minio-cluster

volumes:
  minio1-data1:
  minio1-data2:
  minio2-data1:
  minio2-data2:

networks:
  minio-cluster:
    driver: bridge

@Service
public class MultiCloudSyncService {
    
    @Autowired
    private MinioClient minioClient;    // 主 MinIO
    @Autowired
    private OSS ossClient;              // 阿里云 OSS（灾备）
    
    @Value("${storage.sync.enabled:false}")
    private boolean syncEnabled;
    
    /**
     * 异步跨云同步
     */
    @Async("storageExecutor")
    public CompletableFuture<Void> syncToBackup(String objectName) {
        if (!syncEnabled) return CompletableFuture.completedFuture(null);
        
        try (InputStream is = minioClient.getObject(
                GetObjectArgs.builder().bucket("myapp").object(objectName).build())) {
            
            ossClient.putObject("myapp-backup", objectName, is);
            log.info("跨云同步完成: {}", objectName);
            
        } catch (Exception e) {
            log.error("跨云同步失败: {}", objectName, e);
            // 进入死信队列，后续人工/自动重试
            deadLetterQueue.offer(new SyncTask(objectName, e.getMessage()));
        }
        return CompletableFuture.completedFuture(null);
    }
    
    /**
     * 基于事件的桶复制（MinIO Bucket Replication）
     */
    public void setupBucketReplication() {
        // MinIO 支持服务端自动复制到远端桶
        String replicationConfig = """
            {
              "Rules": [{
                "ID": "backup-rule",
                "Status": "Enabled",
                "Priority": 1,
                "DeleteMarkerReplication": { "Status": "Enabled" },
                "Destination": {
                  "Bucket": "arn:minio:::backup-bucket",
                  "ReplicationSync": true
                }
              }]
            }
            """;
        minioClient.setBucketReplication(
            SetBucketReplicationArgs.builder()
                .bucket("myapp")
                .config(replicationConfig)
                .build()
        );
    }
}

@Service
public class ImageProcessingService {
    
    @Autowired
    private MinioClient minioClient;
    
    private final Map<String, Dimension> THUMBNAIL_SIZES = Map.of(
        "small", new Dimension(150, 150),
        "medium", new Dimension(400, 400),
        "large", new Dimension(800, 800),
        "banner", new Dimension(1920, 600)
    );
    
    /**
     * 上传时生成多尺寸缩略图
     */
    public Map<String, String> uploadWithVariants(MultipartFile file, String folder) {
        String baseName = UUID.randomUUID().toString();
        String ext = FilenameUtils.getExtension(file.getOriginalFilename());
        Map<String, String> urls = new HashMap<>();
        
        try {
            // 1. 保存原图
            String originalKey = folder + "/" + baseName + "_original." + ext;
            uploadOriginal(file, originalKey);
            urls.put("original", getPresignedUrl(originalKey, 60));
            
            // 2. 生成各级缩略图（并行）
            BufferedImage original = ImageIO.read(file.getInputStream());
            Map<String, CompletableFuture<String>> futures = new HashMap<>();
            
            for (Map.Entry<String, Dimension> entry : THUMBNAIL_SIZES.entrySet()) {
                futures.put(entry.getKey(), CompletableFuture.supplyAsync(() -> {
                    try {
                        String key = folder + "/" + baseName + "_" + entry.getKey() + ".jpg";
                        BufferedImage resized = resizeAndCompress(original, entry.getValue());
                        uploadImage(resized, key, "image/jpeg");
                        return getPresignedUrl(key, 60);
                    } catch (Exception e) {
                        throw new RuntimeException(e);
                    }
                }));
            }
            
            for (Map.Entry<String, CompletableFuture<String>> entry : futures.entrySet()) {
                urls.put(entry.getKey(), entry.getValue().join());
            }
            
        } catch (IOException e) {
            throw new ImageProcessException("图片处理失败", e);
        }
        
        return urls;
    }
    
    private BufferedImage resizeAndCompress(BufferedImage original, Dimension target) {
        // 保持宽高比缩放
        double ratio = Math.min(
            (double) target.width / original.getWidth(),
            (double) target.height / original.getHeight()
        );
        int newWidth = (int) (original.getWidth() * ratio);
        int newHeight = (int) (original.getHeight() * ratio);
        
        return Thumbnails.of(original)
            .size(newWidth, newHeight)
            .outputFormat("jpg")
            .outputQuality(0.85)
            .antialiasing(Antialiasing.ON)
            .asBufferedImage();
    }
    
    /**
     * WebP 格式转换（更优压缩比）
     */
    public byte[] convertToWebP(InputStream input) throws IOException {
        // 使用 webp-imageio 库或调用 cwebp 命令行
        ProcessBuilder pb = new ProcessBuilder(
            "cwebp", "-q", "85", "-", "-o", "-"
        );
        Process process = pb.start();
        
        // 写入输入流
        try (OutputStream os = process.getOutputStream()) {
            input.transferTo(os);
        }
        
        // 读取输出
        try (InputStream is = process.getInputStream()) {
            return is.readAllBytes();
        }
    }
    
    /**
     * 智能水印（防盗图）
     */
    public byte[] addInvisibleWatermark(BufferedImage image, String uuid) {
        // 使用最低有效位（LSB）隐写
        // 或使用频域水印（DCT），抗裁剪和压缩
        // 此处示例：半透明文字水印
        Graphics2D g = image.createGraphics();
        g.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, 0.15f));
        g.setColor(Color.WHITE);
        g.setFont(new Font("Arial", Font.BOLD, 48));
        
        // 全图平铺水印
        FontMetrics fm = g.getFontMetrics();
        int textWidth = fm.stringWidth(uuid);
        for (int y = 0; y < image.getHeight(); y += 150) {
            for (int x = 0; x < image.getWidth(); x += textWidth + 100) {
                g.rotate(Math.toRadians(-30), x, y);
                g.drawString(uuid, x, y);
                g.rotate(Math.toRadians(30), x, y);
            }
        }
        g.dispose();
        
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        try {
            ImageIO.write(image, "png", baos);
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
        return baos.toByteArray();
    }
}

@Entity
@Table(name = "file_metadata", indexes = {
    @Index(name = "idx_owner", columnList = "ownerId"),
    @Index(name = "idx_bucket_path", columnList = "bucket,objectPath")
})
public class FileMetadata {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;
    
    private String originalName;
    private String objectPath;        // 存储路径
    private String bucket;
    private String contentType;
    private Long size;
    private String ownerId;
    private String checksum;          // SHA-256
    private Boolean isPublic;         // 是否公开访问
    private LocalDateTime expireAt;   // 过期时间（用于临时文件）
    private Map<String, String> tags; // 业务标签
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

@Service
public class SecureUrlService {
    
    @Autowired
    private StringRedisTemplate redisTemplate;
    
    /**
     * 生成安全预签名 URL（一次性、IP 绑定、时效限制）
     */
    public PresignedUrlResponse generateSecureUrl(SecureUrlRequest request) {
        String token = generateSecureToken(
            request.getObjectName(),
            request.getUserId(),
            request.getClientIp(),
            request.getExpireSeconds()
        );
        
        String metaKey = "file:url:" + token;
        redisTemplate.opsForHash().putAll(metaKey, Map.of(
            "object", request.getObjectName(),
            "user", request.getUserId(),
            "ip", request.getClientIp(),
            "downloads", "0",
            "maxDownloads", String.valueOf(request.getMaxDownloads())
        ));
        redisTemplate.expire(metaKey, request.getExpireSeconds(), TimeUnit.SECONDS);
        
        return PresignedUrlResponse.builder()
            .token(token)
            .url("/api/files/download?token=" + token)
            .expiresAt(Instant.now().plusSeconds(request.getExpireSeconds()))
            .build();
    }
    
    /**
     * 验证并下载（token 校验 + IP 绑定 + 次数限制）
     */
    public InputStream downloadWithToken(String token, String clientIp) {
        String metaKey = "file:url:" + token;
        Map<Object, Object> meta = redisTemplate.opsForHash().entries(metaKey);
        
        if (meta.isEmpty()) {
            throw new SecurityException("下载链接已过期");
        }
        
        // IP 绑定验证
        if (!clientIp.equals(meta.get("ip"))) {
            log.warn("IP 不匹配: expected={}, actual={}", meta.get("ip"), clientIp);
            throw new SecurityException("下载环境异常");
        }
        
        // 下载次数限制
        int downloads = Integer.parseInt((String) meta.get("downloads"));
        int max = Integer.parseInt((String) meta.get("maxDownloads"));
        if (downloads >= max) {
            redisTemplate.delete(metaKey);
            throw new SecurityException("下载次数已用尽");
        }
        
        redisTemplate.opsForHash().increment(metaKey, "downloads", 1);
        
        String objectName = (String) meta.get("object");
        return minioStorageService.download(objectName);
    }
    
    private String generateSecureToken(String object, String userId, String ip, long expiry) {
        String raw = object + ":" + userId + ":" + ip + ":" + expiry + ":" + System.nanoTime();
        return DigestUtils.sha256Hex(raw + SECRET_KEY);
    }
}

// WORM 合规桶配置
@Service
public class ComplianceService {
    
    public void enableObjectLock(String bucketName) throws Exception {
        // 开启对象锁定（不可删除/覆盖）
        minioClient.setObjectLockConfiguration(
            SetObjectLockConfigurationArgs.builder()
                .bucket(bucketName)
                .config(new ObjectLockConfiguration(
                    RetentionMode.COMPLIANCE,
                    new RetentionDurationDays(2555)  // 7 年保留期
                ))
                .build()
        );
    }
    
    /**
     * 敏感文件 DLP 扫描
     */
    public ScanResult scanForSensitiveData(InputStream fileStream) {
        // 集成内容识别服务（如阿里云内容安全）
        // 或正则匹配：身份证号、银行卡、手机号
        String content = new String(fileStream.readAllBytes(), StandardCharsets.UTF_8);
        
        List<String> findings = new ArrayList<>();
        if (content.matches(".*\\d{18}.*")) findings.add("疑似身份证号");
        if (content.matches(".*\\d{16}|\\d{19}.*")) findings.add("疑似银行卡号");
        if (content.matches(".*1[3-9]\\d{9}.*")) findings.add("疑似手机号");
        
        return ScanResult.builder()
            .sensitive(!findings.isEmpty())
            .findings(findings)
            .build();
    }
}