Spring Boot 私有文件保护：签名 URL + 权限控制 + 限流一体化方案

在现代 Web 应用中，保护私有文件的安全访问是一个核心需求。Spring Boot 提供了灵活的方式来实现文件访问控制，其中 签名 URL（Signed URL） 是一种高效、常用的解决方案。

方案概述

签名 URL 的基本工作流程：

1. 客户端 请求访问私有文件
2. 服务端 验证权限并生成带有签名的临时 URL
3. 客户端 使用签名 URL 访问文件
4. 服务端 验证签名与有效期 → 返回文件

通过这种方式，可以避免文件被直接暴露，同时控制访问的有效期。

实现步骤

1. 添加依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
</dependencies>

2. 配置文件存储

# application.properties
file.storage.path=/path/to/upload/directory
# 签名有效期（秒）
signed.url.expiration=300
# 密钥用于签名生成
signed.url.secret=your-secret-key

3. 实现签名 URL 生成器

@Component
public class SignedUrlGenerator {
    
    @Value("${signed.url.expiration}")
    private long expirationTime;
    
    @Value("${signed.url.secret}")
    private String secretKey;
    
    public String generateSignedUrl(String filePath) {
        long expiration = System.currentTimeMillis() + expirationTime * 1000;
        String data = filePath + "|" + expiration;
        String signature = calculateSignature(data, secretKey);
        
        return "/download?file=" + URLEncoder.encode(filePath, StandardCharsets.UTF_8) +
               "&expires=" + expiration +
               "&signature=" + URLEncoder.encode(signature, StandardCharsets.UTF_8);
    }
    
    private String calculateSignature(String data, String key) {
        try {
            Mac hmac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            hmac.init(secretKeySpec);
            byte[] signatureBytes = hmac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getUrlEncoder().withoutPadding().encodeToString(signatureBytes);
        } catch (Exception e) {
            throw new RuntimeException("Error calculating signature", e);
        }
    }
    
    public boolean verifySignature(String filePath, long expiration, String signature) {
        if (expiration < System.currentTimeMillis()) {
            return false;
        }
        String data = filePath + "|" + expiration;
        String expectedSignature = calculateSignature(data, secretKey);
        return secureEquals(expectedSignature, signature);
    }

    // 防止时序攻击的安全比较
    private boolean secureEquals(String a, String b) {
        if (a == null || b == null || a.length() != b.length()) return false;
        int result = 0;
        for (int i = 0; i < a.length(); i++) {
            result |= a.charAt(i) ^ b.charAt(i);
        }
        return result == 0;
    }
}

4. 创建文件下载控制器

@RestController
public class FileDownloadController {
    
    @Value("${file.storage.path}")
    private String storagePath;
    
    @Autowired
    private SignedUrlGenerator signedUrlGenerator;
    
    @GetMapping("/generate-signed-url")
    public ResponseEntity<String> generateSignedUrl(@RequestParam String filePath, Authentication auth) {
        if (!hasAccess(auth, filePath)) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
        }
        return ResponseEntity.ok(signedUrlGenerator.generateSignedUrl(filePath));
    }
    
    @GetMapping("/download")
    public ResponseEntity<Resource> downloadFile(@RequestParam String file,
                                                @RequestParam long expires,
                                                @RequestParam String signature) {
        if (!signedUrlGenerator.verifySignature(file, expires, signature)) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
        }
        try {
            Path filePath = Paths.get(storagePath).resolve(file).normalize();
            // 路径校验，防止越权访问
            if (!filePath.startsWith(Paths.get(storagePath))) {
                return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
            }
            Resource resource = new UrlResource(filePath.toUri());
            if (resource.exists() && resource.isReadable()) {
                return ResponseEntity.ok()
                        .header(HttpHeaders.CONTENT_DISPOSITION, 
                                "attachment; filename=\"" + resource.getFilename() + "\"")
                        .body(resource);
            }
            return ResponseEntity.notFound().build();
        } catch (Exception e) {
            return ResponseEntity.internalServerError().build();
        }
    }
    
    private boolean hasAccess(Authentication authentication, String filePath) {
        // 自定义权限检查逻辑
        return true;
    }
}

5. 安全配置

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/download").permitAll()
                .antMatchers("/generate-signed-url").authenticated()
                .and()
            .formLogin()
                .and()
            .csrf().disable();
    }
}

进阶优化

1. 云存储集成

如果文件存储在 AWS S3 / 阿里云 OSS / MinIO，可以直接使用它们的 内置签名 URL 功能，避免服务端流量开销。

示例（AWS S3）：

public String generateS3SignedUrl(String bucketName, String objectKey) {
    AmazonS3 s3Client = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
    Date expiration = new Date(System.currentTimeMillis() + 5 * 60 * 1000);
    GeneratePresignedUrlRequest req =
        new GeneratePresignedUrlRequest(bucketName, objectKey)
            .withMethod(HttpMethod.GET)
            .withExpiration(expiration);
    return s3Client.generatePresignedUrl(req).toString();
}

2. 访问日志和监控

@Component
public class DownloadLogger {
    private static final Logger logger = LoggerFactory.getLogger(DownloadLogger.class);
    public void logDownload(String filePath, String user, String ip) {
        logger.info("文件下载: file={}, user={}, ip={}", filePath, user, ip);
    }
}

3. 限流保护

• 单机版本（内存计数器）
• 分布式版本（Redis + Lua / Bucket4j）

@Component
public class RateLimiter {
    private final Map<String, List<Long>> accessRecords = new ConcurrentHashMap<>();
    private static final int MAX_REQUESTS = 10;
    private static final long TIME_WINDOW = 60000;
    
    public boolean allowRequest(String ip) {
        long now = System.currentTimeMillis();
        List<Long> requests = accessRecords.getOrDefault(ip, new ArrayList<>());
        requests.removeIf(time -> time < now - TIME_WINDOW);
        if (requests.size() < MAX_REQUESTS) {
            requests.add(now);
            accessRecords.put(ip, requests);
            return true;
        }
        return false;
    }
}

4. CDN 集成

签名 URL 可直接作为 CDN 回源验证参数，既保证安全性，又减少应用服务器带宽压力。

5. 短链化（可选）

长签名 URL 可映射为短链（如 /s/abc123 → 签名 URL），提升分享与使用体验。

测试方案

@SpringBootTest
public class SignedUrlTest {
    
    @Autowired
    private SignedUrlGenerator signedUrlGenerator;
    
    @Test
    public void testUrlGenerationAndVerification() {
        String filePath = "test.txt";
        String signedUrl = signedUrlGenerator.generateSignedUrl(filePath);
        
        Map<String, String> params = parseQueryParams(signedUrl);
        assertTrue(signedUrlGenerator.verifySignature(
            params.get("file"), 
            Long.parseLong(params.get("expires")), 
            params.get("signature")));
    }
    
    private Map<String, String> parseQueryParams(String url) {
        return Arrays.stream(url.split("\\?")[1].split("&"))
                     .map(s -> s.split("="))
                     .collect(Collectors.toMap(a -> a[0], a -> a[1]));
    }
}

流程图

sequenceDiagram
    participant Client as 客户端
    participant Server as Spring Boot
    participant Auth as 权限验证
    participant Gen as 签名生成器
    participant FS as 文件存储

    Client->>Server: 请求签名URL(filePath)
    Server->>Auth: 验证权限
    Auth-->>Server: 验证通过
    Server->>Gen: 生成签名URL
    Gen-->>Server: 返回签名URL
    Server-->>Client: 返回URL
    
    Client->>Server: 使用签名URL访问 /download
    Server->>Gen: 验证签名与过期时间
    alt 验证失败
        Server-->>Client: 403 Forbidden
    else 验证成功
        Server->>FS: 读取文件
        FS-->>Server: 文件流
        Server-->>Client: 返回文件
    end

总结

通过 Spring Boot 动态签名 URL 方案，你可以：

• 有效保护私有文件免遭未授权访问
• 控制文件访问的有效期
• 记录日志与限流保护
• 灵活集成本地/云存储/CDN

在生产环境中，推荐开启：

• 路径校验（防目录穿越）
• 常量时间比较（防时序攻击）
• Redis 限流（防刷接口）
• 结合 CDN（降低回源压力）

这样，既保证安全，又能高效扩展。