Java大文件断点续传实战：管道巡检日志上传系统设计

搞能源化工企业的管道巡检系统这几年我踩过不少坑，其中最让人头疼的就是巡检日志里的超大附件上传问题。以前给某化工集团做管道巡检平台，现场巡检员用工业终端拍现场照片、录设备运行视频，一趟巡检下来轻松攒出十几GB的日志附件，拿手机流量传根本撑不住，传一半断网就得从头再来，一线员工怨声载道。后来我用Java的断点续传方案把整个上传链路重做了一遍，才算把这个问题彻底解决。这篇就把完整方案拆开揉碎讲清楚，适合正在做企业级Java上传功能、尤其是面临弱网大文件传输场景的开发者参考。

1. 先看清问题：为什么管道巡检日志会产生超级大的附件

1.1 巡检日志不只是一张照片

很多人以为管道巡检日志就是记录人员填一张表，勾选“正常”、“异常”，顶多附带几张现场照片。实际干过才知道，能源化工企业的管道巡检数据远不是这么简单。

以我经手的项目为例，一个大型炼化厂区，直径从几百毫米到一米多的管道动辄几十公里，巡检员每天要沿管线步检，人工记录法兰连接处的密封情况、保温层完好度、阀门开闭状态。每个巡检点至少要拍三张以上照片：全景、局部特写、仪表读数。遇到疑似泄露还要录制短视频记录气泡、声响、油渍扩散情况。更专业的做法是带红外热像仪，一条管线扫过去，热像图文件单张就能到几十MB。

无人机巡检在大型能源化工基地也普及了，一架无人机沿管廊飞一个航次，4K视频加高清照片流水般产出，单个架次的数据量轻松上GB甚至十几GB。再叠加现场声纹采集、振动监测数据，一趟巡检产生的日志附件总量经常达到几十GB级别。

这些数据最终都要汇入企业内部的巡检管理系统，与巡检任务、设备台账、隐患记录关联起来，形成完整的可追溯链条。问题就出在“上传”这一步——厂区偏远、管廊架设在野外，4G/5G信号本身就时好时坏，地下管廊里甚至只有专网覆盖，传输速率极不稳定。用最原始的HTTP表单上传，一个2GB的视频传了二十分钟，最后一公里断网，整个文件作废重传，换谁都崩溃。

1.2 普通上传为什么扛不住这种场景

普通上传的逻辑是把整个文件当作一个流，从开头读到结尾，一口气把数据推给服务器。这个过程中，只要TCP连接中断、客户端进程被杀、网络切换导致IP变更，连接就断了，服务端只收到一个不完整的文件。这个半成品通常会被直接丢弃，或者当作损坏数据留在临时目录，前端下次只能从零开始重传。

这不是代码写得不好，而是方案本身不适合弱网环境下的超大附件场景。而断点续传的思路是“化整为零、逐个击破”：先把大文件切成若干固定大小的分片，每个分片独立上传，服务端逐个保存并记录状态。断网时，已传完的分片原地保留，网络恢复后只需要继续传剩余分片，最后合并成完整文件。

这么一改，用户体验从“一次赌二十分钟不断网”变成“每传一个4MB分片只赌几秒钟”，再加上断点续传的自动恢复机制，实际场景里的成功率能提升一个数量级。

1.3 为什么后端首选Java技术栈

能源化工企业的信息化系统大多是老牌的Java技术栈，Spring Boot、Spring Cloud一套体系，数据落Oracle或MySQL，运维监控用Zabbix、Prometheus。企业内部IT团队对Java的熟悉程度远超其他语言，新功能要嵌入现有平台，用Java做后端是成本最低的选择。

而且Java的生态对文件处理、并发控制、服务治理的支持非常成熟。分片上传这个需求本身要处理高并发写入、状态一致性、异常恢复，Java在这些方面有足够多的实践沉淀。哪怕有人觉得Python写起来更快，真到了要跟工业PDA做对接、嵌入企业统一认证、接入既有审批流的阶段，Java的适配性优势立刻体现出来。

2. 断点续传方案的整体设计与选型逻辑

2.1 核心原理：分片、记录、合并三步走

断点续传的实现思路可以提炼成一句话：把一个大文件切分成多个独立上传的分片，服务端为每个分片维护上传状态，文件全部上传完成后按顺序合并成原始文件。

这个思路并不复杂，真正复杂的是细节设计。在实际实现中，我把整个流程拆成了四条核心链路：

一是分片准备。前端读取文件元信息，按固定大小（比如8MB）把文件切成若干分片，计算整个文件的唯一标识（通常用MD5或SHA-256）。

二是分片上传。前端逐个上传分片，每个分片请求都携带文件唯一标识、分片序号、总分片数等信息，服务端将分片写入临时目录。

三是状态查询。前端在重新连接后，先向服务端查询文件的上传进度，拿到已成功上传的分片列表，从未完成的分片继续传。

四是文件合并。所有分片都上传完成后，前端发起合并请求，服务端按分片序号将文件拼接成完整文件，并计算整体校验值，与前端二次确认。

2.2 技术选型：为什么不直接上OSS或第三方组件

提到分片上传，很多人第一反应是直接用云厂商的对象存储SDK，比如阿里云OSS、腾讯云COS的multipart upload功能，或者用MinIO的Java SDK。这些方案本身非常成熟，分片上传、断点续传都是现成的，开发工作量能减少一大半。

但能源化工企业的实际情况往往不是这么理想。很多厂区的数据不能出内网，业务系统部署在私有机房，外网访问受限，根本接不了公有云对象存储。有些企业虽然上了云，但采购流程长，等审批下来项目都黄了。还有一类情况是系统要跟已有的流程引擎、权限体系、文件归档服务紧密集成，OSS的文件管理方式反而成了包袱。

我在这个项目里的选型是：用Java的Spring Boot自行实现分片上传逻辑，存储层对接企业已有的MinIO集群。一开始也想直接用MinIO的分片接口，但后来发现巡检日志不仅要上传，还要跟巡检任务绑定、做签名校验、走后续的审批流，这些业务逻辑自己实现更灵活。

2.3 关键参数的计算方法

分片大小是整个方案里最重要的参数，选得不对会直接影响传输效率和断点恢复粒度。

分片太小，比如1MB，会产生海量分片请求，给服务端造成巨大并发压力，每个请求的HTTP开销也变高。分片太大，比如100MB，单个分片的传输时间过长，在弱网环境下分片本身就可能传输失败，失去断点续传的意义。

我通常用这个公式做初步估算：目标单个分片传输时间控制在5秒到30秒之间，分片大小 = 预估可用带宽 × 目标传输时间。现场环境如果用4G网络，实际下行速率大约是2-6MB/s，那分片大小取8MB到32MB比较合适。结合服务端磁盘IO和并发数，我最终把默认分片大小定为8MB，单个文件最多分片数控制在2048以内，这样理论上能覆盖到16GB的超大附件。

前端并发上传分片数也是关键参数。并发太高，服务端IO容易打满，弱网下的TCP窗口还会互相挤压，反而拖慢整体速度。实测下来，3到5个并发分片是比较稳的区间，既能把带宽用足，又不会把服务打挂。

2.4 断点续传与完整上传的本质区别

网上关于“断点续传和完整上传的区别”讨论很多，核心区别就在两个层面。

资源层面，完整上传要求一次性占用完整的传输资源，链路中断一切归零；断点续传把资源消耗摊薄到每个分片，已完成的传输资源被持久化保护。

状态层面，完整上传的服务端是无状态的，收到多少算多少，断了就没了；断点续传的服务端是有状态的，每接收一个分片都会持久化一条记录，整个文件的完成度随时可查、可恢复。

3. Java后端核心实现实战拆解

3.1 接口设计与参数约定

我按照“初始化、上传分片、查询进度、合并文件”四段式设计了REST接口，所有接口统一走公司网关，鉴权用统一令牌，这里不赘述。

第一个接口是初始化上传，前端在拿到文件后先调这个接口。请求参数包括原始文件名、文件总大小、分片大小等信息。服务端计算分片总数，生成一个文件上传ID作为整次上传的唯一标识，并返回给前端。这个文件ID是后续所有操作的主键。

第二个接口是上传分片，核心参数是文件ID、分片序号、总分片数，以及分片的二进制数据。服务端按文件ID + 分片序号将分片写入临时存储，并记录状态。

第三个接口是查询进度，最简单的实现是返回已上传的分片序号列表，前端拿到后用它决定从哪里续传。

第四个接口是合并文件，前端判断所有分片都已上传后调用，服务端执行合并逻辑，完成后返回文件的最终访问路径和校验值。

接口文档和参数定义如下：

http复制POST /api/pipeline/upload/init
Content-Type: application/json

{
  "fileName": "巡检日志_20250415.mp4",
  "fileSize": 8589934592,
  "chunkSize": 8388608,
  "fileMd5": "d41d8cd98f00b204e9800998ecf8427e"
}

http复制POST /api/pipeline/upload/chunk
Content-Type: multipart/form-data

fileId=xxx
chunkIndex=3
totalChunks=1024
chunkMd5=xxxx
file=@local_chunk_file

3.2 分片落盘：目录结构与本地存储策略

分片数据在服务端要怎么存，这是第一个容易踩坑的地方。直接把分片写入数据库BLOB字段显然不现实，几十GB的二进制数据会让数据库直接瘫痪。我采用的方式是文件系统存储，用数据库只记录元数据。

临时分片目录结构按文件ID隔离：

code复制/data/pipeline_upload/
  {fileId}/
    0.part
    1.part
    2.part
    ...
    metadata.json

每个分片是一个独立的.part文件，分片序号就是文件名。metadata.json用来存放文件的元信息，包括文件ID、总大小、分片大小、总分片数、原始文件名。这样即使数据库临时不可用，文件系统自身也能支撑基本的上传进度判断。

服务端接收分片时，直接用Spring MVC的MultipartFile接收，然后写入到对应目录。要注意的是写入分片时不能只写一次就算完，必须对分片做MD5校验，确认传输过程中数据没有被损坏。

3.3 分片合并的Java实现与细节处理

合并分片是后端实现的重点中的重点。最容易踩的坑是并发场景下分片乱序导致的文件损坏。

每个分片传到服务端后是独立写入的，网络情况不同，到达顺序可能完全随机。合并时如果简单按到达顺序拼接，文件必坏。正确做法是：合并时严格按分片序号顺序读取每个分片文件，用RandomAccessFile按偏移量写入目标文件。

这里给出我实际使用的合并核心代码：

java复制public void mergeChunks(String fileId, String destFilePath) throws IOException {
    List<ChunkMeta> chunks = chunkMetaMapper.getChunks(fileId);
    chunks.sort(Comparator.comparingInt(ChunkMeta::getChunkIndex));
    
    try (RandomAccessFile raf = new RandomAccessFile(destFilePath, "rw")) {
        for (ChunkMeta chunk : chunks) {
            File partFile = new File(partDir, fileId + "/" + chunk.getChunkIndex() + ".part");
            raf.seek(chunk.getChunkOffset());
            Files.copy(partFile.toPath(), Channels.newOutputStream(raf.getChannel()));
        }
    }
}

这段代码里有两个细节值得注意。第一是raf.seek(chunk.getChunkOffset())，每个分片的写入位置通过chunkIndex * chunkSize计算出来，确保分片写入的绝对位置正确，不受其他分片状态影响。第二是合并时逐个读取分片文件，而不是一次性把所有分片加载到内存，避免大文件合并时把JVM堆直接打满。

但RandomAccessFile配合Files.copy这种方式，实测在几百GB级别的文件场景下略有性能瓶颈。如果要追求更高吞吐，可以考虑分片顺序写入合并池。不过对管道巡检日志场景来说，单文件几十GB比较少见，这个方案完全够用。

3.4 分片状态表的数据库设计与事务控制

数据库表是整个断点续传功能的地基。我设计了这么一张表：

sql复制CREATE TABLE t_pipeline_upload_chunk (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    file_id VARCHAR(64) NOT NULL,
    chunk_index INT NOT NULL,
    chunk_size BIGINT NOT NULL,
    chunk_md5 VARCHAR(64),
    upload_status TINYINT NOT NULL DEFAULT 0,
    upload_time DATETIME,
    file_path VARCHAR(512),
    UNIQUE KEY uk_file_chunk (file_id, chunk_index)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

以及文件维度的总进度表：

sql复制CREATE TABLE t_pipeline_upload_task (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    file_id VARCHAR(64) NOT NULL,
    file_name VARCHAR(255) NOT NULL,
    file_size BIGINT NOT NULL,
    chunk_size INT NOT NULL,
    total_chunks INT NOT NULL,
    uploaded_chunks INT NOT NULL DEFAULT 0,
    file_md5 VARCHAR(64),
    merge_status TINYINT NOT NULL DEFAULT 0,
    create_time DATETIME,
    update_time DATETIME,
    UNIQUE KEY uk_file_id (file_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

分片表用file_id和chunk_index做唯一联合索引，保证同一个分片不会被重复插入。上传分片时先检查分片是否已存在，已存在则直接返回成功，实现幂等。文件进度表的uploaded_chunks字段记录已上传分片数量，每次上传成功后更新。

事务控制上有一个容易犯的错误：分片文件写入文件系统成功，但数据库记录更新失败，会造成数据不一致。我把文件写入和数据库更新放在同一个事务里管理，虽然文件系统不是数据库事务的一部分，但可以设计成“应用层两阶段”：先写文件，再写数据库，如果数据库写失败则删除文件和记录，保持一致。实际项目里更稳妥的方案是引入一个补偿任务定期扫描，把落盘但未记录的分片重新登记。

4. 面对弱网与断电：数据一致性如何保证

4.1 状态机设计与FileId的幂等控制

文件上传过程我定义了一个状态机，分五个状态：

INIT表示初始化完成，等待分片上传。UPLOADING表示分片上传中，只要有任意分片上传成功即进入此状态。MERGING表示所有分片已上传完成，正在执行合并。COMPLETED表示合并完成，文件可用。FAILED表示上传或合并中出现异常，需要人工介入或自动重试。

状态机设计的价值在于：无论前端在哪个环节断线，重新连接后只要拿到fileId，就能根据当前状态精确知道该从哪个环节继续。前端通过查询接口拿到这个状态，就能做对应的恢复动作。

为了保证状态机的一致性，我用了一个比较朴素但有用的手段：所有状态变更都通过数据库行锁控制。每个fileId对应一行任务记录，更新状态时使用SELECT ... FOR UPDATE锁住行，再做业务动作，最后更新状态。这个粒度在单机部署下完全够用，分布式场景再用分布式锁替换。

4.2 服务重启后如何恢复未完成的分片

服务端进程频繁重启是在线系统避免不了的情况。最怕的是重启后分片记录丢失，前端的进度信息对不上，断点续传形同虚设。

我的做法是启动时加一个恢复扫描任务。应用启动后，异步扫描文件系统中所有临时目录，读取metadata.json，与数据库中的任务记录进行比对。如果有分片文件存在但数据库没记录，则补齐；如果数据库有记录但分片文件缺失，则将该任务标记为异常。这个扫描任务能自动把不一致的数据修正回来，不需要人工干预。

4.3 文件校验：分片MD5与整体MD5两层防御

只依赖数据库状态记录来保证数据完整性是不够的。网络传输过程中，数据可能因为网络抖动出现损坏，虽然TCP层有校验，但对于需要长时间保存的巡检日志，多一重校验总是好的。

我做了两层校验。第一层是分片级校验，前端在切片时计算每个分片的MD5，上传时携带，服务端收到分片后重新计算MD5，比对通过才落盘。第二层是文件级校验，合并完成后计算整个文件的MD5，与初始化时前端提交的文件MD5比对，一致才标记COMPLETED。

这个大文件的MD5计算也有讲究，不能一次性读入内存，要用分段读取的方式：

java复制public String computeMd5(File file) throws IOException {
    MessageDigest md5 = MessageDigest.getInstance("MD5");
    try (InputStream in = new BufferedInputStream(new FileInputStream(file))) {
        byte[] buffer = new byte[8192];
        int len;
        while ((len = in.read(buffer)) != -1) {
            md5.update(buffer, 0, len);
        }
    }
    return new String(Hex.encodeHex(md5.digest()));
}

实测这个计算一个10GB的合并文件，大约需要三四十秒，在弱网环境下完全可接受，换来的是文件完整性的确凿保证。

5. 能源化工场景下的实战适配与避坑指南

5.1 弱网传输的客户端重试策略

服务端做得好，前端也得跟得上。弱网环境下传输分片失败是常态，关键是前端要有一个聪明的重试策略。

我采用指数退避加重试上限的策略。当分片上传失败时，前端会等待2秒、4秒、8秒、16秒……逐渐拉长间隔重试，最多重试5次。达到上限后，不再盲目重试，而是转入断点续传的恢复流程，回到查询进度接口拿最新的已上传列表，再从未上传的分片开始传。

这里的核心思想是：不要在同一个分片上无限纠缠。一个分片多次传不上，说明整个链路存在问题，继续重试只是浪费流量和电量，还不如停下来重新梳理状态，调整策略再继续。

5.2 分片并发顺序与磁盘IO的平衡

分片并发数如果设置得不当，会使能耗企业的服务器IO出现问题。我之前做过一轮压测，在普通机械磁盘环境下，8个并发分片同时写入，磁盘IO等待时间急剧上升，反而比4个并发还要慢。而采用SSD或企业级阵列后，并发数可以适当提高。

建议前期先以4个并发起步，在目标环境压测后调优。同时要注意合并阶段的并发写入，合并任务如果同时占用了大量IO，会影响正在上传的分片写入速度。可以加一个全局信号量限制并发合并任务，比如默认最多同时执行2个合并任务。

5.3 数据生命周期与归档策略

巡检日志附件是能源化工企业的核心过程数据，通常要保留相当长的期限。上传完成后，文件不能一直留在上传临时目录，需要在一段时间后转移至归档存储。

我的做法是增加一个定时任务，将COMPLETED状态的文件从临时目录移动到正式归档目录，归档目录按日期和巡检任务ID两级分层，便于后续检索。上传临时目录只留着上传中和未完成的数据，定时清理超过7天的垃圾文件。这个设计避免了大文件长期占用临时空间，也能让资本化的归档存储成本得到有效控制。

5.4 常见问题速查表

我把实际运维中遇到的典型问题整理成一个表格，方便排查：

5.5 巡检日志与业务系统的关联设计

最后说一个很容易被忽视的点：断点续传只是解决了“文件怎么传上去”的问题，而巡检系统真正关心的是“这份日志属于哪个巡检任务、哪个设备、哪个巡检员”。

我在设计上传接口时没有把文件上传和业务提交混在一起。前端先把附件逐个上传，服务端返回每个附件对应的fileId，前端再统一提交巡检记录，把一组fileId关联到巡检任务上。这种做法把上传流程与业务逻辑解耦，即使业务提交失败也不需要重新上传附件，只需重新提交业务数据即可。

在实际操作中，我经常这样处理：巡检员在移动终端的App里填完巡检表单后，先自动触发附件上传，上传过程中可以继续填写其他内容，全部就绪后一键提交。用户主观感觉上传过程不再阻塞工作流程，体验提升非常明显。

跑完这个项目以后我的体会是，断点续传看似是一个纯技术问题，实际上考验的是对业务场景的理解深度。能源化工企业的现场环境远比互联网公司要恶劣，网络不稳定、终端性能参差不齐、操作人员素质差异大，这些因素都要在设计之初就考虑进去。分片大小怎么设、并发多少合适、失败重试几次、临时文件何时清理，每一个看似不起眼的参数背后都是无数次现场调试换来的经验。照着这个思路去做，Java下的超大附件断点续传也就没有那么可怕了。