SpringBoot實(shí)現(xiàn)文件訪問安全的方法詳解

更新時(shí)間：2025年12月08日 08:15:05 作者：風(fēng)象南

在Web應(yīng)用開發(fā)中,文件上傳、下載和讀取功能是常見需求,然而,不安全的文件訪問實(shí)現(xiàn)可能導(dǎo)致嚴(yán)重的任意文件讀取/寫入漏洞,下面我們就來看看SpringBoot實(shí)現(xiàn)文件訪問安全的相關(guān)方法吧

前言

在Web應(yīng)用開發(fā)中，文件上傳、下載和讀取功能是常見需求。然而，不安全的文件訪問實(shí)現(xiàn)可能導(dǎo)致嚴(yán)重的任意文件讀取/寫入漏洞，攻擊者可能借此讀取服務(wù)器上的敏感配置文件、數(shù)據(jù)庫憑據(jù)，甚至系統(tǒng)文件，造成嚴(yán)重的數(shù)據(jù)泄露。

常見的文件訪問安全風(fēng)險(xiǎn)

1. 任意路徑遍歷（Path Traversal）

路徑遍歷是最常見的文件訪問安全問題，攻擊者通過../、..\\等序列來訪問目錄外的文件。

// 危險(xiǎn)代碼示例 - 存在路徑遍歷漏洞
@GetMapping("/files")
public ResponseEntity<Resource> getFile(@RequestParam String filename) {
    // 極度危險(xiǎn)！用戶可以直接訪問任意文件
    File file = new File("/uploads/" + filename);
    return ResponseEntity.ok()
        .body(new FileSystemResource(file));
}

// 攻擊示例：
// GET /files?filename=../../../../etc/passwd
// GET /files?filename=..\\..\\..\\windows\\system32\\config\\sam

2. 文件類型繞過

不充分的文件類型驗(yàn)證可能導(dǎo)致惡意文件上傳。

// 不安全的文件類型檢查
@PostMapping("/upload")
public String upload(@RequestParam MultipartFile file) {
    String filename = file.getOriginalFilename();
    if (filename.endsWith(".jpg") || filename.endsWith(".png")) {
        // 危險(xiǎn)：僅檢查文件名后綴，攻擊者可以上傳
        // shell.php.jpg 或 double-header.php%00.jpg
    }
}

3. 符號(hào)鏈接攻擊

符號(hào)鏈接可能被用來繞過訪問限制，指向系統(tǒng)敏感文件。

4. 文件包含漏洞

不當(dāng)?shù)奈募赡軐?dǎo)致代碼執(zhí)行。

Spring Boot 安全文件訪問實(shí)現(xiàn)

1. 路徑白名單驗(yàn)證

import org.springframework.util.StringUtils;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

@Service
public class SecureFileService {

    // 允許訪問的基礎(chǔ)目錄
    private static final Set<Path> ALLOWED_BASE_PATHS = new HashSet<>(Arrays.asList(
        Paths.get("/app/uploads").normalize(),
        Paths.get("/app/public").normalize()
    ));

    // 允許的文件擴(kuò)展名
    private static final Set<String> ALLOWED_EXTENSIONS = new HashSet<>(Arrays.asList(
        "jpg", "jpeg", "png", "gif", "pdf", "txt", "doc", "docx"
    ));

    public boolean isPathSafe(String requestedPath) {
        if (!StringUtils.hasText(requestedPath)) {
            return false;
        }

        try {
            // 規(guī)范化路徑，解析所有 . 和 ..
            Path normalizedPath = Paths.get(requestedPath).normalize();

            // 檢查是否在允許的基礎(chǔ)目錄內(nèi)
            for (Path basePath : ALLOWED_BASE_PATHS) {
                if (normalizedPath.startsWith(basePath)) {
                    // 檢查文件擴(kuò)展名
                    String extension = getFileExtension(normalizedPath.toString());
                    return ALLOWED_EXTENSIONS.contains(extension.toLowerCase());
                }
            }

            return false;
        } catch (Exception e) {
            return false;
        }
    }

    private String getFileExtension(String filename) {
        int lastDot = filename.lastIndexOf('.');
        return lastDot > 0 ? filename.substring(lastDot + 1) : "";
    }
}

2. 安全的文件訪問控制器

@RestController
@RequestMapping("/api/files")
@Validated
public class SecureFileController {

    private final SecureFileService fileService;

    public SecureFileController(SecureFileService fileService) {
        this.fileService = fileService;
    }

    @GetMapping("/download/**")
    public ResponseEntity<Resource> downloadFile(HttpServletRequest request) {
        try {
            // 提取請(qǐng)求路徑中的文件路徑部分
            String requestURI = request.getRequestURI();
            String filePath = requestURI.substring("/api/files/download/".length());

            // 安全驗(yàn)證
            if (!fileService.isPathSafe(filePath)) {
                return ResponseEntity.badRequest()
                    .body((Resource) new StringResource("Invalid file path"));
            }

            Path path = Paths.get(filePath).normalize();
            Resource resource = new UrlResource(path.toUri());

            if (!resource.exists() || !resource.isReadable()) {
                return ResponseEntity.notFound().build();
            }

            // 檢查文件大小限制
            long fileSize = resource.contentLength();
            if (fileSize > 100 * 1024 * 1024) { // 100MB limit
                return ResponseEntity.badRequest()
                    .body((Resource) new StringResource("File too large"));
            }

            String contentType = Files.probeContentType(path);
            if (contentType == null) {
                contentType = "application/octet-stream";
            }

            return ResponseEntity.ok()
                .contentType(MediaType.parseMediaType(contentType))
                .header(HttpHeaders.CONTENT_DISPOSITION,
                        "attachment; filename=\"" + path.getFileName() + "\"")
                .body(resource);

        } catch (Exception e) {
            return ResponseEntity.internalServerError().build();
        }
    }
}

3. 安全的文件上傳實(shí)現(xiàn)

import org.springframework.web.multipart.MultipartFile;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.lang3.RandomStringUtils;

@Service
public class SecureFileUploadService {

    private static final long MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
    private static final Path UPLOAD_DIR = Paths.get("/app/uploads").toAbsolutePath().normalize();

    @PostConstruct
    public void init() {
        try {
            Files.createDirectories(UPLOAD_DIR);
        } catch (IOException e) {
            throw new RuntimeException("Could not create upload directory", e);
        }
    }

    public String uploadFile(MultipartFile file) {
        // 1. 基本驗(yàn)證
        if (file.isEmpty()) {
            throw new IllegalArgumentException("File is empty");
        }

        if (file.getSize() > MAX_FILE_SIZE) {
            throw new IllegalArgumentException("File size exceeds limit");
        }

        // 2. 文件名驗(yàn)證和處理
        String originalFilename = file.getOriginalFilename();
        if (!isValidFilename(originalFilename)) {
            throw new IllegalArgumentException("Invalid filename");
        }

        // 3. 文件類型驗(yàn)證（使用魔術(shù)字節(jié)，而不僅僅是擴(kuò)展名）
        if (!isValidFileType(file)) {
            throw new IllegalArgumentException("Invalid file type");
        }

        // 4. 生成安全的文件名
        String extension = FilenameUtils.getExtension(originalFilename);
        String safeFilename = generateSafeFilename(extension);

        try {
            Path targetLocation = UPLOAD_DIR.resolve(safeFilename);

            // 確保文件在允許的目錄內(nèi)
            if (!targetLocation.normalize().startsWith(UPLOAD_DIR)) {
                throw new SecurityException("Attempted path traversal attack");
            }

            Files.copy(file.getInputStream(), targetLocation, StandardCopyOption.REPLACE_EXISTING);

            return safeFilename;

        } catch (IOException e) {
            throw new RuntimeException("Failed to store file", e);
        }
    }

    private boolean isValidFilename(String filename) {
        if (filename == null || filename.trim().isEmpty()) {
            return false;
        }

        // 檢查危險(xiǎn)字符
        if (filename.contains("..") || filename.contains("/") ||
            filename.contains("\\") || filename.contains(":")) {
            return false;
        }

        // 檢查文件名長(zhǎng)度
        return filename.length() <= 255;
    }

    private boolean isValidFileType(MultipartFile file) throws IOException {
        String filename = file.getOriginalFilename();
        String extension = FilenameUtils.getExtension(filename).toLowerCase();

        // 允許的文件類型
        Set<String> allowedExtensions = Set.of("jpg", "jpeg", "png", "gif", "pdf", "txt");
        if (!allowedExtensions.contains(extension)) {
            return false;
        }

        // 文件頭驗(yàn)證（魔術(shù)字節(jié)）
        byte[] fileBytes = file.getBytes();
        return isValidFileHeader(fileBytes, extension);
    }

    private boolean isValidFileHeader(byte[] fileBytes, String extension) {
        if (fileBytes.length < 4) {
            return false;
        }

        // 簡(jiǎn)化的文件頭驗(yàn)證, 可以使用 Apache Tika庫來判斷
        switch (extension) {
            case "jpg":
            case "jpeg":
                return fileBytes[0] == (byte) 0xFF && fileBytes[1] == (byte) 0xD8;
            case "png":
                return fileBytes[0] == (byte) 0x89 && fileBytes[1] == 0x50 &&
                       fileBytes[2] == 0x4E && fileBytes[3] == 0x47;
            case "pdf":
                return fileBytes[0] == 0x25 && fileBytes[1] == 0x50 &&
                       fileBytes[2] == 0x44 && fileBytes[3] == 0x46;
            default:
                return true; // 對(duì)于文本文件，放寬檢查
        }
    }

    private String generateSafeFilename(String extension) {
        String randomPart = RandomStringUtils.randomAlphanumeric(16);
        String timestamp = String.valueOf(System.currentTimeMillis());
        return String.format("%s_%s.%s", timestamp, randomPart, extension);
    }
}

4. 配置安全過濾器

@Component
public class FileSecurityFilter implements Filter {

    private static final Set<String> DANGEROUS_PATHS = Set.of(
        "..", "../", "..\\", "%2e%2e%2f", "%2e%2e\\",
        "etc/passwd", "windows/system32", "boot.ini"
    );

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                        FilterChain chain) throws IOException, ServletException {

        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String requestURI = httpRequest.getRequestURI();
        String queryString = httpRequest.getQueryString();

        // 檢查路徑遍歷攻擊
        if (containsPathTraversal(requestURI, queryString)) {
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST,
                                  "Invalid request - potential path traversal");
            return;
        }

        chain.doFilter(request, response);
    }

    private boolean containsPathTraversal(String uri, String queryString) {
        String fullRequest = uri;
        if (queryString != null) {
            fullRequest += "?" + queryString;
        }

        String lowerCaseRequest = fullRequest.toLowerCase();

        return DANGEROUS_PATHS.stream()
            .anyMatch(lowerCaseRequest::contains);
    }
}

高級(jí)安全措施

1. 使用虛擬文件系統(tǒng)

@Service
public class VirtualFileSystemService {

    // 將文件映射到虛擬路徑，隱藏真實(shí)文件系統(tǒng)結(jié)構(gòu)
    private final Map<String, FileInfo> virtualFileMap = new ConcurrentHashMap<>();

    @PostConstruct
    public void init() {
        // 初始化虛擬文件映射
        scanAndMapFiles(Paths.get("/app/uploads"), "/virtual/files");
    }

    private void scanAndMapFiles(Path realPath, String virtualBasePath) {
        try {
            Files.walk(realPath)
                .filter(Files::isRegularFile)
                .forEach(realFile -> {
                    String relativePath = realPath.relativize(realFile).toString();
                    String virtualPath = virtualBasePath + "/" + relativePath;
                    virtualFileMap.put(virtualPath, new FileInfo(realFile, virtualPath));
                });
        } catch (IOException e) {
            log.error("Failed to scan files", e);
        }
    }

    public Optional<Resource> getFileByVirtualPath(String virtualPath) {
        FileInfo fileInfo = virtualFileMap.get(virtualPath);
        if (fileInfo == null) {
            return Optional.empty();
        }

        try {
            Resource resource = new UrlResource(fileInfo.getRealPath().toUri());
            return Optional.of(resource);
        } catch (Exception e) {
            return Optional.empty();
        }
    }

    @Data
    @AllArgsConstructor
    private static class FileInfo {
        private Path realPath;
        private String virtualPath;
    }
}

2. 文件訪問權(quán)限控制

@Service
public class FileAccessControlService {

    public boolean canAccessFile(String userId, String virtualPath, String action) {
        // 基于用戶角色的文件訪問控制
        UserInfo userInfo = getUserInfo(userId);
        FileInfo fileInfo = getFileInfo(virtualPath);

        if (fileInfo == null) {
            return false;
        }

        // 檢查文件所有權(quán)
        if (userInfo.getRole() == UserRole.ADMIN) {
            return true; // 管理員可以訪問所有文件
        }

        // 普通用戶只能訪問自己的文件
        return fileInfo.getOwnerId().equals(userId);
    }

    public void logFileAccess(String userId, String virtualPath, String action, boolean success) {
        FileAccessLog log = FileAccessLog.builder()
            .userId(userId)
            .virtualPath(virtualPath)
            .action(action)
            .success(success)
            .timestamp(LocalDateTime.now())
            .userAgent(getCurrentUserAgent())
            .clientIp(getClientIp())
            .build();

        fileAccessLogRepository.save(log);
    }
}

3. 文件完整性檢查

@Component
public class FileIntegrityChecker {

    public String calculateFileHash(Path filePath) throws IOException {
        byte[] fileBytes = Files.readAllBytes(filePath);
        return DigestUtils.sha256Hex(fileBytes);
    }

    public boolean verifyFileIntegrity(Path filePath, String expectedHash) throws IOException {
        String actualHash = calculateFileHash(filePath);
        return MessageDigest.isEqual(
            actualHash.getBytes(StandardCharsets.UTF_8),
            expectedHash.getBytes(StandardCharsets.UTF_8)
        );
    }

    public void generateIntegrityReport() {
        // 定期掃描上傳目錄，生成文件完整性報(bào)告
        Map<String, String> fileHashes = new HashMap<>();

        try {
            Files.walk(Paths.get("/app/uploads"))
                .filter(Files::isRegularFile)
                .forEach(file -> {
                    try {
                        String hash = calculateFileHash(file);
                        fileHashes.put(file.toString(), hash);
                    } catch (IOException e) {
                        log.error("Failed to calculate hash for file: " + file, e);
                    }
                });

            // 保存或比較完整性報(bào)告
            saveIntegrityReport(fileHashes);

        } catch (IOException e) {
            log.error("Failed to scan upload directory", e);
        }
    }
}

4. 應(yīng)用配置文件

# application.yml
spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB
      enabled: true

file:
  upload:
    base-path: /app/uploads
    max-size: 10485760  # 10MB
    allowed-extensions: jpg,jpeg,png,gif,pdf,txt,doc,docx
    allowed-mime-types:
      - image/jpeg
      - image/png
      - image/gif
      - application/pdf
      - text/plain
      - application/msword
      - application/vnd.openxmlformats-officedocument.wordprocessingml.document
  security:
    enable-path-traversal-protection: true
    enable-file-integrity-check: true
    enable-access-logging: true