Spring Boot 实现大文件断点续传：3GB 文件上传不断网

你是否有过这样的经历？上传一个 3GB 的高清视频素材，进度条走到 90% 时网络突然波动，导致上传失败，一切必须从头再来。这不仅仅是糟糕的用户体验，更是平台稳定性的巨大挑战。本文将为你彻底拆解大文件上传的痛点，并从 HTTP 协议原理出发，提供一个从前端到后端、可直接落地的 Spring Boot 断点续传完整解决方案。

一、大文件上传的“死亡三问”

为什么传统的表单上传方式注定会失败？

• 内存爆炸：传统的 MultipartFile 上传通常会将整个文件加载到内存中，一个 3GB 的文件足以让大多数 JVM 直接 OOM（内存溢出）。
• 连接超时：HTTP 请求通常有默认的超时时间（例如 Nginx 默认为 60 秒），而大文件传输耗时远超此限制，必然导致连接中断。
• 状态丢失：一旦网络断开或页面刷新，服务器没有任何关于已传输进度的持久化记录，无法从中断点恢复。

真实案例：某在线教育平台最初采用原始表单上传 4GB 的课程视频，用户平均需要重试 3.7 次才能成功，相关的客服投诉量占技术类问题的 23%，最终导致近 30% 的用户因体验太差而流失。

二、断点续传核心原理：从 TCP 到应用层

2.1 协议层基础：HTTP Range 请求

断点续传的底层基石是 HTTP/1.1 协议中定义的 Range 请求头。它允许客户端只请求资源的一部分。

# 客户端请求：获取文件的第 200MB 到 300MB 部分
GET /video.mp4 HTTP/1.1
Range: bytes=209715200-314572800

服务器会响应部分内容：

HTTP/1.1 206 Partial Content
Content-Range: bytes 209715200-314572800/3221225472
Content-Length: 104857600

关键状态码：

• 206：部分内容传输成功。
• 416：请求的范围无效（例如超出文件大小）。
• 503：服务暂时不可用（此时需要记录当前进度以便恢复）。

2.2 应用层架构：七层断点续传模型

要实现健壮的上传服务，我们需要在应用层构建一个更完善的模型。

1. 分片层：将大文件切割为固定大小的块（推荐 5MB - 20MB），这是并行上传和断点恢复的基础。
2. 校验层：为每个分片生成唯一标识（如 MD5 或 SHA-1），用于验证分片完整性和防止篡改。
3. 传输层：支持多个分片并行上传，并具备从断点恢复单个分片的能力。
4. 存储层：临时存储上传成功的分片，待所有分片上传完成后合并为原始文件，并清理临时文件。
5. 状态层：记录每个文件所有分片的上传状态（已上传/未上传），这是实现断点续传的关键。通常使用 Redis 这类高性能缓存。
6. 通知层：上传完成后的回调通知，以及上传过程中的实时进度更新。
7. 重试层：针对失败的分片上传，实现指数退避等重试策略，提高最终成功率。

三、实现方案：从前端到后端

3.1 前端实现（基于 Web Uploader）

前端负责文件分片、并发控制以及与后端的状态校验。

// 初始化上传组件
const uploader = WebUploader.create({
    swf: '/path/Uploader.swf',
    server: '/upload/chunk',
    pick: '#filePicker',
    chunked: true, // 开启分片
    chunkSize: 10 * 1024 * 1024, // 10MB 分片
    chunkRetry: 3, // 失败重试 3 次
    threads: 3, // 3 线程并行上传
    formData: {
        fileId: generateFileId() // 生成唯一文件 ID
    },
    // 断点续传核心：检查已上传分片
    prepareUpload: function() {
        $.get('/upload/check', {
            fileId: this.options.formData.fileId
        }).done(res => {
            // 跳过已上传分片
            this.options.uploadedChunks = res.uploaded;
        });
    }
});

// 监听上传进度
uploader.on('uploadProgress', (file, percentage) => {
    $('#progress').text(`已上传: ${(percentage * 100).toFixed(2)}%`);
});

3.2 后端实现（Java Spring Boot）

后端是整套机制的核心，负责分片接收、状态管理和文件合并。

3.2.1 分片上传接口

@PostMapping("/upload/chunk")
public ResponseEntity<ChunkResponse> uploadChunk(
        @RequestParam String fileId,
        @RequestParam int chunk,
        @RequestParam int chunks,
        @RequestParam MultipartFile file) throws IOException {

    // 1. 存储分片到临时目录
    Path chunkPath = Paths.get(temporaryDir, fileId, chunk + ".part");
    Files.createDirectories(chunkPath.getParent());
    file.transferTo(chunkPath);

    // 2. 记录上传状态到 Redis
    String key = "upload:" + fileId;
    redisTemplate.opsForSet().add(key, chunk);
    redisTemplate.expire(key, 24, TimeUnit.HOURS);

    // 3. 检查是否所有分片上传完成
    long uploaded = redisTemplate.opsForSet().size(key);
    if (uploaded == chunks) {
        // 异步合并文件
        executorService.submit(() -> mergeChunks(fileId, chunks));
        return ResponseEntity.ok(new ChunkResponse(true, “所有分片上传完成”));
    }

    return ResponseEntity.ok(new ChunkResponse(false, “分片上传成功”));
}

3.2.2 文件合并逻辑

private void mergeChunks(String fileId, int totalChunks) throws IOException {
    Path tempDir = Paths.get(temporaryDir, fileId);
    Path targetFile = Paths.get(uploadDir, fileId + “.mp4”);

    try (SequenceInputStream sequence = new SequenceInputStream(
            IntStream.range(0, totalChunks)
                    .mapToObj(i -> {
                        try {
                            return new FileInputStream(tempDir.resolve(i + “.part”).toFile());
                        } catch (FileNotFoundException e) {
                            throw new RuntimeException(e);
                        }
                    })
                    .iterator())) {

        Files.copy(sequence, targetFile, StandardCopyOption.REPLACE_EXISTING);
    }

    // 清理临时文件
    Files.walk(tempDir)
            .sorted(Comparator.reverseOrder())
            .forEach(path -> {
                try {
                    Files.delete(path);
                } catch (IOException e) {
                    log.error(“删除临时文件失败”, e);
                }
            });
}

3.3 断点续传状态存储设计

我们使用 Redis 来高效管理上传状态。

Redis 存储结构：

# 已上传分片集合
SET upload:file123 {0, 1, 2, 4, 5}

# 文件元信息
HASH file:meta:file123
    name “video.mp4”
    size 3221225472
    chunks 317
    chunkSize 10485760
    status “uploading”
    createTime 1710345678

过期策略：为上传承诺设置 24 小时的过期时间，自动清理未完成的文件，避免浪费磁盘和内存资源。

四、高级优化：从可靠性到性能

4.1 分片校验机制

确保分片在传输过程中未被篡改或损坏。

// 生成分片 MD5 并校验
try (InputStream is = file.getInputStream()) {
    String chunkMd5 = DigestUtils.md5Hex(is);
    // 与客户端传递的 MD5 比对
    if (!chunkMd5.equals(request.getChunkMd5())) {
        return ResponseEntity.status(400).body(“分片校验失败”);
    }
}

4.2 并行上传策略

根据网络状况动态调整并发数。

• 网络良好时（延迟 < 50ms）：可开启 5-8 个线程并行上传，充分利用带宽。
• 网络较差时（延迟 > 200ms）：减少至 2-3 个线程，避免因并发过多导致请求超时。

4.3 断点续传扩展方案对比

方案	适用场景	实现复杂度	优势
基于 HTTP Range	浏览器直传	低	标准协议，兼容性最好
基于 FTP	专业客户端工具	中	协议原生支持断点续传
基于 WebSocket	需实时进度反馈	高	双向通信，反馈实时
基于 P2P	超大文件分发（如游戏更新）	极高	极大减轻中心服务器压力

五、生产环境避坑指南

5.1 Nginx 配置优化

作为流量入口，Nginx 的配置至关重要。

# 增加客户端请求体大小和超时时间
client_max_body_size 4G;
proxy_connect_timeout 300s;
proxy_read_timeout 300s;
proxy_send_timeout 300s;

# 启用分块传输编码，支持流式上传
chunked_transfer_encoding on;

5.2 常见问题解决方案

问题	可能原因	解决方案
分片丢失	临时目录被定时任务清理	将未完成文件状态持久化，定期清理时排除这些文件
合并失败	磁盘空间不足	监控磁盘使用率，预留 20% 以上空间
网络抖动	传输不稳定	实现指数退避重试机制（如间隔 1s, 2s, 4s 重试）
大文件存储	单机存储容量有限	最终文件对接云对象存储（如 S3, OSS）

六、完整架构方案与总结

一套可用于生产环境的大文件上传架构通常包含以下层次：

1. 负载均衡层：使用 Nginx 进行请求分发和高可用。
2. 应用服务层：Spring Boot 应用集群，处理分片上传、校验、合并等核心逻辑。
3. 缓存层：Redis 集群，用于存储上传状态和文件元信息，保证高性能和高并发。
4. 存储层：对象存储服务或分布式文件系统，用于持久化最终合并好的文件。
5. 监控层：集成 Prometheus 和 Grafana，监控上传成功率、平均耗时、失败率等关键指标。

选型建议

文件大小	典型场景	推荐技术方案
小文件 (< 100MB)	图片、文档	原生 FormData 直接上传
中等文件 (100MB - 2GB)	视频、设计稿	WebUploader / Resumable.js + 服务端分片
大文件 (> 2GB)	系统镜像、备份文件	专用客户端（如 rsync）或本文介绍的完整分片断点续传方案

最佳实践总结

• 分片大小：5MB - 20MB，在减少请求次数和降低单次失败代价之间取得平衡。
• 校验算法：MD5（速度快）或 SHA-256（安全性更高）。
• 状态存储：高并发选 Redis，需强持久化可考虑数据库（但需注意性能）。
• 监控指标：必须关注上传成功率、平均耗时、失败分片重试率等。

在 云栈社区 的 后端 & 架构 板块，你可以找到更多关于高并发系统设计、分布式存储等深度讨论，欢迎与大家一起交流实战中遇到的挑战。