尧图网站开发 
简介一套基于Java的FastDFS大文件上传与断点续传源码项目面向需要实现文件上传模块的Java开发者解决H5与FastDFS之间大文件传输不稳、重复上传浪费流量等场景问题。项目将高性能断点续传、秒传与Redis文件锁结合覆盖文件上传、文件处理、文件存储等完整链路可帮助读者理解分片校验、锁竞争与模板页面渲染的实际写法。压缩包共36个文件、约563KB核心是13个Java源文件辅以JavaScript、CSS与FTL模板支撑前端交互和页面渲染XML与properties用于配置。FTL与前端资源配合可还原可操作界面Java与配置文件则展示FastDFS客户端接入及Redis锁落地方式。压缩包内附重要说明与readme.txt降低上手门槛已有705人学习下载适合需要在大文件上传、秒传或并发控制场景中借鉴工程代码的开发者。1. FastDFS大文件上传与断点续传先厘清「切块、索引、续传」三板斧FastDFS大文件上传在Java后端里最常见的结局不是写满磁盘而是内存被整文件读取打死、或者传了一半网络抖动全盘重来。FastDFS本身只保证单文件在storage上的存储与读取它不感知“这个大文件应该分几片、哪些片成功了”所以断点续传的复杂度全部在应用层切块、记索引、失败续传、合并校验。这套设计适合做网盘、音视频课程、离线资源包上传的Java服务端也常被java面试题拿来考“断点续传和完整上传的区别”。下面按一个能真实跑通的Java分块上传源码方案来讲配置、代码、坑和调参都会落到具体值上。2. 基于Java的FastDFS上传链路从Tracker寻址到Storage分块写入2.1 Tracker与Storage的角色为什么分块前先理解寻址FastDFS集群里Tracker只负责调度不存文件数据Storage负责落地存储一个文件最终写到某个storage的某个store_path下并返回一个file_id。很多人仿照完整上传的方式把一个2GB文件读进byte[]再调用uploadFile这在内存和超时上都会直接翻车。分块方案的价值是每个分片独立走一遍“找Tracker、选Storage、写入并返回fileId”的流程某一片失败只影响这一片而不是把整个文件拖回原点。复习一下这个寻址模型还有个好处它能解释为什么Storage连接池、网络超时这些参数会直接影响大文件上传的稳定性——所有分片都在抢占同一条到Storage的数据通道。在Java工程里我常用的是fastdfs-client这个客户端库完整的寻址被封装成两步先创建TrackerClient并拿到TrackerServer再基于它创建StorageClient。下载和上传都通过StorageClient的uploadFile、downloadFile、deleteFile这几个方法完成。注意不同版本的客户端类名基本一致但配置项和异常类型有些差异所以搜fastdfs下载客户端包时优先找和你JDK版本匹配的构建而不是一上来拿最新源码编。2.2 初始化客户端与连接参数最小配置能跑起来先给一个能直接编译运行的初始化代码import org.csource.fastdfs.ClientGlobal; import org.csource.fastdfs.StorageClient; import org.csource.fastdfs.TrackerClient; import org.csource.fastdfs.TrackerServer; import java.io.IOException; public class FastDfsInitializer { // 全局只初始化一次不要在每次上传请求里重复init public static StorageClient init(String confPath) throws IOException { ClientGlobal.init(confPath); TrackerServer trackerServer null; try { // TrackerClient内部会从配置的tracker列表里选一个可用节点 trackerServer new TrackerClient().getTrackerServer(); // 第二个参数传null代表使用默认的StorageServer信息 return new StorageClient(trackerServer, null); } finally { // StorageClient内部持有TrackerServer的引用用完要显式释放 if (trackerServer ! null) { try { trackerServer.close(); } catch (IOException ignored) { } } } } }逻辑说明代码里最容易被忽略的是finally块。StorageClient构造时需要TrackerServer但真正上传时它还要跟Storage建立连接try-with-resources不能直接管理这个非AutoCloseable对象所以手动close更稳妥。实际项目中我会把StorageClient放进连接池而不是每次new一个因为TrackerServer的获取有网络开销高频上传时反复握手会拖慢整体吞吐。对应的fastdfs.conf配置如下tracker_server192.168.1.10:22122 tracker_server192.168.1.11:22122 connect_timeout5000 network_timeout60参数说明connect_timeout是建立TCP连接的超时默认5秒即可不要把负载高误判成不可用network_timeout是每次socket.read()的等待时间默认30秒对大文件分片来说太短。分片越大或网络越差这个值越要放大。我的换算经验是分片大小 / 最低保障带宽 * 1.5 10秒比如8MB分片按200KB/s最低带宽算60秒左右配置里写60到90之间比较稳。2.3 分块上传的Java实现切块后逐片传file_id要落库分块上传的核心是把“读本地文件”和“上传FastDFS”解耦。每个分片在FastDFS上是独立文件应用层记录它们的fileId和顺序合并阶段再拼回完整文件。代码public ListString uploadByChunks(String filePath, long chunkSizeBytes) throws Exception { ListString fileIds new ArrayList(); File file new File(filePath); long totalSize file.length(); // 向上取整保证最后一块即使不满chunkSize也会被算进去 long totalChunks (totalSize chunkSizeBytes - 1) / chunkSizeBytes; try (FileInputStream fis new FileInputStream(file)) { // chunkSizeBytes在4MB左右int范围内没问题 byte[] buffer new byte[(int) chunkSizeBytes]; for (int i 0; i totalChunks; i) { int readLen fis.read(buffer); if (readLen 0) { break; } // 最后一块可能比buffer短需要裁剪 byte[] chunkBytes (readLen buffer.length) ? buffer : Arrays.copyOf(buffer, readLen); // 每个分片单独上传返回独立fileId String fileId storageClient.uploadFile(chunkBytes, bin, null); fileIds.add(fileId); // 注意这里不能只打印要把chunkIndex和fileId落库 System.out.println(chunk i uploaded, fileId fileId); // 重置buffer避免残留上次数据 if (readLen buffer.length) { Arrays.fill(buffer, (byte) 0); } } } return fileIds; }逻辑说明每次循环只读一个分片的大小内存占用被限制在chunkSizeBytes而不是整个文件。这里最关键的落库动作没有写进代码块但生产环境必须在uploadFile返回后立刻把chunkIndex、fileId、size写进数据库否则进程崩溃这个fileId就再也找不回来了。完整上传失败重来要传整个文件断点续传则是跳过这些已落库的块差别就在这里。参数说明块大小决定断点粒度。局域网内我常用8MB公网上2到4MB。块太小会导致分片数和Tracker交互次数大幅上升块太大则弱网重传成本高。另外buffer的清理不能省FastDFS返回的byte[]长度和实际传入相等但Java里byte数组复用后旧内容仍在最后一片裁剪或重传时可能把脏数据带进去。 这段用干净数组 裁剪从源头避免这个隐患。3. 断点续传的Java实现分块索引、断点判定与MD5校验3.1 分块索引用一个小类记录每块的状态断点续传的底线是“程序知道每个分片是否完成”。FastDFS的fileId是随机字符串无法从文件名推断所以索引数据结构必须有。我用两个类ChunkRecord负责单块状态UploadProgress负责整体进度。public class ChunkRecord { private int chunkIndex; // 分块序号从0开始 private String fileId; // FastDFS返回的文件ID private long size; // 该分块实际字节数 private String md5; // 分块内容MD5合并阶段用 private boolean uploaded; // 是否上传完成 // getter/setter省略 } public class UploadProgress { private String clientFileKey; // 业务方自定义的同一文件标识 private ListChunkRecord chunks; private int totalChunks; public boolean isAllUploaded() { return chunks.size() totalChunks chunks.stream().allMatch(ChunkRecord::isUploaded); } }逻辑说明clientFileKey是整个续传流程的锚点。前端在上传前先请求后端生成一个uploadToken后端创建一个UUID作为clientFileKey并记录totalChunks。之后每个分片请求都带clientFileKey和chunkIndex后端只按index查表决定是返回已有fileId还是新接收分片。前端如果使用worker上传大文件多个worker并发传不同chunkIndex只要索引表按index记录天然就是并行安全的。参数说明索引存数据库比存本地文件可靠得多。单机演示时可以用ConcurrentHashMap但进程重启就丢多节点部署时本地文件会各说各话。我在项目里用一张upload_chunk表字段对应ChunkRecord的四个核心字段加上complete_time唯一索引建立在(clientFileKey, chunkIndex)上。3.2 续传判定哪些块能跳过哪些必须重传续传最怕的错误是“以为传过其实只传了一半”。所以后端收到续传请求后不能只看有没有chunkIndex记录还要校验size是否一致。这里给出一个判定逻辑public UploadProgress checkAndFill(UploadProgress progress, MapString, ChunkRecord uploadedMap) { for (ChunkRecord record : progress.getChunks()) { ChunkRecord existed uploadedMap.get(String.valueOf(record.getChunkIndex())); // 1. 索引存在 // 2. 分块大小一致 // 3. fileId对应的文件仍存在于FastDFS if (existed ! null existed.getSize() record.getSize() isFileExists(existed.getFileId())) { record.setUploaded(true); record.setFileId(existed.getFileId()); } } return progress; }逻辑说明三条判断缺一不可。大小一致能排除“传了另一个同名文件”fileId存在性探测能排除FastDFS垃圾清理或人工误删。这里我刻意不加MD5比对因为比对MD5要先下载FastDFS上已有的分片大文件场景下网络开销比重传一块还高。更实用的轻量校验是前端在分片头尾各取1KB内容一起上传后端只校验这两个小片段能过滤掉绝大多数内容错位问题。这也正好是java面试题里常聊的点断点续传和完整上传的区别不是“中途会不会断”而是失败后能否复用已传分片的校验结果。完整上传失败后重试从第0字节开始断点续传重试时跳过已确认的块。类比git clone断点续传不是重新clone全量而是接着已有进度继续。参数说明这里的isFileExists在fastdfs-client里没有直接方法我会包装一层调用storageClient.getFileInfo(fileId)返回非null即可。这个操作会访问一次Storage元数据比下载整个文件轻量得多可以在合并前对全部分片批量执行。3.3 合并与校验把分片拼回完整文件分片都上传成功后FastDFS上是一堆独立文件。合并有两类常见做法我第一次做时纠结了很久现在把各自适用场景说清楚。第一种是应用层合并后重新上传按chunkIndex顺序从FastDFS下载每个分片到本地临时文件流式追加成一个完整文件再把这个文件用uploadFile上传最后删除分片。它的优点是任何fastdfs-client版本都支持完全不依赖服务端附加写特性缺点是文件经历了第二次全量上传带宽翻倍。第二种是FastDFS的appender文件首次用appendFile创建文件后续用appendFile把每个分片追加到同一个fileId上。省掉“合并后重新上传”这一步但要确认客户端版本支持追加接口且Storage配置开启了相应开关。我一般首选第一种因为它的失败域更可控。第一种方案的关键代码public String mergeAndUpload(ListString fileIds, String tempDir) throws Exception { File merged new File(tempDir /merge_ UUID.randomUUID() .bin); try (FileOutputStream fos new FileOutputStream(merged)) { for (String fileId : fileIds) { // offset传0、length传0是fastdfs-client约定的“全量下载” byte[] chunk storageClient.downloadFile(fileId, 0, 0); fos.write(chunk); } } String finalFileId storageClient.uploadFile( merged.getAbsolutePath(), bin, null); // 合并成功后清理分片释放Storage空间 for (String fileId : fileIds) { storageClient.deleteFile(fileId); } return finalFileId; }逻辑说明合并顺序完全依赖传入list的排序调用前必须按chunkIndex升序排好否则拼出来的文件顺序错乱。合并成功后要立刻把final_file_id更新到upload_file表并把status改成完成态这样前端才能拿到最终下载地址。deleteFile阶段如果某个分片删除失败不能阻塞主流程记录日志后由后台任务补偿清理。参数说明合并临时目录的磁盘占用等于最终文件大小并发高时要预留足够空间。多个上传任务同时合并时磁盘IO是瓶颈我用clientFileKey做互斥锁防止同一个文件被两次合并触发。临时文件写完后要校验merged.length() 所有分片size之和对不上直接抛异常不要把这个残缺文件上传上去。4. 大文件上传的避坑指南连接重置、文件损坏与进度丢失排查4.1 连接被重置network_timeout按默认值设导致误杀现象传一个500MB的zip分片16MB传到一半抛出IOException“connection reset”重试几次都断在同一位置附近。原因network_timeout默认30秒指的是单次socket.read()的等待时间不是整个分片的总耗时。16MB分片在200KB/s的带宽下光传输就要80秒客户端30秒没等到数据就把连接判死Storage端随后重置连接。解决按分片大小和最低预期带宽换算超时时间。公式为chunkSizeBytes / 最低带宽Bps * 1.5 10结果取整到秒。同时把弱网下的分片大小动态降级客户端在连续两次失败后主动把分片从8MB降到2MB重传成功率会明显提升。4.2 分片合并后文件打不开顺序错乱比缺块更难发现现象所有分片都显示上传成功合并后zip报“压缩包已损坏”或视频播放卡在某一秒。原因合并list的顺序不是按chunkIndex排列。前端并发上传分片时数据库返回记录如果不按chunk_index排序或者list在异步回调里按完成顺序添加fileIds就会乱序。解决合并前强制按chunkIndex升序排序并校验“前N块累计长度等于第N块的起始offset”。我在ChunkRecord里加了expectedOffset字段合并时逐块检查顺序错乱或长度不匹配直接抛异常不做补救。磁盘上留一个坏文件比留一个假完整文件好处理得多。4.3 服务重启后进度丢失索引只存在于内存里现象上传一半Tomcat重启前端续传时后端返回“找不到上传记录”被迫从头传。原因把UploadProgress存在ConcurrentHashMap里进程一重启内存索引全部消失。FastDFS上的分片文件其实还在但应用层已经不知道哪些块传过、哪些块没传。解决每个分片上传成功后立即把ChunkRecord写入数据库而不是等全部完成再汇总。上传状态表建唯一索引(clientFileKey, chunkIndex)重复提交同一分片时靠唯一约束直接忽略或返回已有fileId实现幂等。4.4 多用户并发上传时Storage连接被拖垮连接没释放现象两三个用户同时传大文件刚开始正常几分钟后连小文件上传也变慢Storage机器负载不高但连接数持续攀升。原因常见实现是每次上传都new一个StorageClient用完不放进连接池也不释放storage端的并发连接很快被耗尽。解决给分片上传单独做一个半连接池核心线程数等于本机CPU核数队列容量控制在几十。分片内部的并行度不是越高越好机械硬盘的Storage上并行分片反而加剧随机IO串行或低并行度更稳。4.5 合并时提示“file not exist”分片被服务端清理了现象断点续传隔了一天后触发合并downloadFile时抛FileNotFoundException但数据库里fileId和size都正常。原因FastDFS的Storage有定时清理策略或者文件被运维手动清理。分片文件上传时间越久被清理的概率越大而应用层索引还标记为“已上传”。解决在合并和续传判定前对每个已标记上传的fileId执行一次getFileInfo探测。文件不存在就把该块打回未上传状态重新传这一块。这个逻辑要放在“懒清理”流程里否则会形成一个永远无法完成的合并任务。5. 把断点续传工程化参数调优、元数据管理与异常恢复策略5.1 关键参数表把这些值写进配置而不是写死在代码里大文件上传的稳定性从来不是靠一个参数而是参数组合。下面这张表是我在多个项目里沉淀下来的默认值可以直接抄进配置中心。参数建议值作用说明tracker_server数量至少2个Tracker容灾只配一个时Tracker挂掉整个上传链路不可用connect_timeout5000msTCP建连超时过小会误判负载高的Trackernetwork_timeout按分片大小与带宽换算单次读写超时默认30秒对大分片明显不够chunk_size内网8MB公网2-4MB分块粒度块越小断点粒度越细交互次数越多连接池核心线程数CPU核数*2并发连接上限不限制会把Storage连接池打满分片重试次数2-3次单块重试上限不要无限重试配合指数退避merge临时目录磁盘剩余2倍文件大小合并缓存磁盘满时优先清理oldest临时文件分片清理时机合并成功后异步执行释放Storage空间不要提前删否则合并必失败参数说明network_timeout这一行最关键很多老项目默认值30秒从没改过一上大文件分片就频繁断连。chunk_size的设置还要考虑前端策略如果前端用worker上传大文件并已经切片后端chunk_size最好和前端切片大小保持一致避免服务端再二次切片。5.2 元数据设计分片表怎么建才能支持秒级续传判定断点续传的性能瓶颈主要在“判定哪些块已传完”这一步。两张表加两个索引就能做到毫秒级查询下面是建表SQLCREATE TABLE upload_chunk ( id BIGINT PRIMARY KEY AUTO_INCREMENT, client_file_key VARCHAR(64) NOT NULL, chunk_index INT NOT NULL, file_id VARCHAR(255) NOT NULL, chunk_size BIGINT NOT NULL, file_md5 VARCHAR(32) DEFAULT NULL, complete_time DATETIME, UNIQUE KEY uk_file_chunk (client_file_key, chunk_index), KEY idx_file_key (client_file_key) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE upload_file ( client_file_key VARCHAR(64) PRIMARY KEY, file_name VARCHAR(255) NOT NULL, total_size BIGINT NOT NULL, total_chunks INT NOT NULL, final_file_id VARCHAR(255) DEFAULT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0上传中 1合并中 2完成 3失败, create_time DATETIME, update_time DATETIME );逻辑说明upload_file表记录文件维度状态upload_chunk表记录分片维度状态。续传请求只需要带clientFileKey后端执行一条SELECT chunk_index, file_id FROM upload_chunk WHERE client_file_key ?就能在内存里组装出UploadProgress对象。已经上传的块直接返回给前端前端只重传缺失块进度条恢复的延迟几乎为零。这里的查询要保证只返回必要的字段不要select *把fileId列表全部拉出来后还在应用层内存里做二次过滤。chunk_index是int类型排序由chunk_index天然升序合并时直接按这个结果集顺序取fileId即可不需要单独排序。5.3 异常恢复合并失败怎么处理残留分片合并是断点续传流程里最脆弱的阶段网络、磁盘、Storage都可能中途失败。我的做法是把合并设计成幂等任务而不是一次性的“临时动作”。状态机的流转是这样的合并前把upload_file.status改成1合并中同时把所有缺失的chunk_index清单写入一张merge_task表合并成功改成2并写入final_file_id失败改成3并记录error_msg。有一个定时任务扫描status3且update_time超过10分钟的记录把对应clientFileKey的未上传块重新标记并清理本地临时目录里的半成品文件。// 定时任务伪代码失败后的补偿清理 public void recoverFailedMerge() { ListString failedKeys mergeTaskMapper.findFailedKeys(10 * 60 * 1000); for (String key : failedKeys) { // 1. 删除本地临时合并文件 File temp new File(mergeTempDir / key .bin); if (temp.exists()) { temp.delete(); } // 2. 把upload_file状态重置回0允许前端再次触发合并 uploadFileMapper.updateStatus(key, 0); // 3. 清掉本次merge_task记录 mergeTaskMapper.deleteByKey(key); } }逻辑说明补偿任务只重置状态不删除FastDFS上的分片文件。分片必须等合并明确成功后才能清理否则下一次触发合并会因为找不到fileId而失败。FastDFS侧的分片清理放到合并成功后的异步队列里执行失败也不影响主流程由另一个清理任务补偿删除。参数说明定时任务的扫描间隔和超时阈值要按业务容忍度调。文件越大合并耗时越长阈值设太短会把“还在正常合并”的任务误判为失败。我的经验是阈值至少是预估合并耗时的2倍扫描间隔取阈值的1/5避免同一批任务被反复扫描。6. 最小可运行样例用Java代码验证上传、续传与完整性把前面的逻辑收拢成一个main方法适合在本地FastDFS集群上做快速验证。这个样例省略了数据库索引直接演示“分块上传、合并、下载校验”的最小闭环public class FastDfsUploadDemo { public static void main(String[] args) throws Exception { // 1. 初始化客户端 StorageClient storageClient FastDfsInitializer.init(fastdfs.conf); // 2. 模拟大文件按4MB分块上传 String filePath /tmp/bigfile.bin; long chunkSize 4 * 1024 * 1024; ListString fileIds uploadByChunks(filePath, chunkSize); // 3. 按chunkIndex排序后合并 Collections.sort(fileIds); // 生产环境按数据库chunk_index排序这里仅演示 String finalFileId mergeAndUpload(fileIds, /tmp); // 4. 下载完整文件并校验长度 byte[] downloaded storageClient.downloadFile(finalFileId, 0, 0); long expected new File(filePath).length(); System.out.println(expected expected , actual downloaded.length); if (downloaded.length ! expected) { throw new IllegalStateException(merge check failed); } } }逻辑说明这个样例把分片上传和合并都放进了同一个JVM进程验证的是“上传-合并-下载”是否自洽。实际工程里main方法内要换成从数据库读取UploadProgress把已上传分片的fileId直接复用才能验证断点续传路径。验证时重点看两个输出一是每个分片的fileId是否按顺序打印二是最终校验长度是否等于原文件长度。验证断点续传的完整步骤我建议按这三步走。第一步传一个1GB文件传到一半杀掉进程重启后从数据库查询已传块数确认前端只重传剩余块。第二步在合并前人为delete掉一个分片文件观察getFileInfo探测逻辑是否把它标记为未上传并自动重传。第三步用网络工具把带宽限到100KB/s验证network_timeout换算是否生效连接是否还能稳定完成整个上传。进阶方向是把分块上传的存储层抽象成接口因为后端暴露给前端的只有“clientFileKey chunkIndex chunkData”三个概念FastDFS只是其中一个实现将来换成MinIO或OSS分片接口时上层逻辑基本不用动。我第一版做断点续传时也以为只要把块传上去就行结果被合并顺序、超时设置、进程重启丢进度三个问题轮流教育了一轮现在写代码会先把状态表结构定下来再写传输逻辑。先让数据落库再谈传输效率这是大文件上传这条路上最值的一笔投入。希望帮到你。本文还有配套的精品资源点击获取 
简介一套基于Java的FastDFS大文件上传与断点续传源码项目面向需要实现文件上传模块的Java开发者解决H5与FastDFS之间大文件传输不稳、重复上传浪费流量等场景问题。项目将高性能断点续传、秒传与Redis文件锁结合覆盖文件上传、文件处理、文件存储等完整链路可帮助读者理解分片校验、锁竞争与模板页面渲染的实际写法。压缩包共36个文件、约563KB核心是13个Java源文件辅以JavaScript、CSS与FTL模板支撑前端交互和页面渲染XML与properties用于配置。FTL与前端资源配合可还原可操作界面Java与配置文件则展示FastDFS客户端接入及Redis锁落地方式。压缩包内附重要说明与readme.txt降低上手门槛已有705人学习下载适合需要在大文件上传、秒传或并发控制场景中借鉴工程代码的开发者。1. FastDFS大文件上传与断点续传先厘清「切块、索引、续传」三板斧FastDFS大文件上传在Java后端里最常见的结局不是写满磁盘而是内存被整文件读取打死、或者传了一半网络抖动全盘重来。FastDFS本身只保证单文件在storage上的存储与读取它不感知“这个大文件应该分几片、哪些片成功了”所以断点续传的复杂度全部在应用层切块、记索引、失败续传、合并校验。这套设计适合做网盘、音视频课程、离线资源包上传的Java服务端也常被java面试题拿来考“断点续传和完整上传的区别”。下面按一个能真实跑通的Java分块上传源码方案来讲配置、代码、坑和调参都会落到具体值上。2. 基于Java的FastDFS上传链路从Tracker寻址到Storage分块写入2.1 Tracker与Storage的角色为什么分块前先理解寻址FastDFS集群里Tracker只负责调度不存文件数据Storage负责落地存储一个文件最终写到某个storage的某个store_path下并返回一个file_id。很多人仿照完整上传的方式把一个2GB文件读进byte[]再调用uploadFile这在内存和超时上都会直接翻车。分块方案的价值是每个分片独立走一遍“找Tracker、选Storage、写入并返回fileId”的流程某一片失败只影响这一片而不是把整个文件拖回原点。复习一下这个寻址模型还有个好处它能解释为什么Storage连接池、网络超时这些参数会直接影响大文件上传的稳定性——所有分片都在抢占同一条到Storage的数据通道。在Java工程里我常用的是fastdfs-client这个客户端库完整的寻址被封装成两步先创建TrackerClient并拿到TrackerServer再基于它创建StorageClient。下载和上传都通过StorageClient的uploadFile、downloadFile、deleteFile这几个方法完成。注意不同版本的客户端类名基本一致但配置项和异常类型有些差异所以搜fastdfs下载客户端包时优先找和你JDK版本匹配的构建而不是一上来拿最新源码编。2.2 初始化客户端与连接参数最小配置能跑起来先给一个能直接编译运行的初始化代码import org.csource.fastdfs.ClientGlobal; import org.csource.fastdfs.StorageClient; import org.csource.fastdfs.TrackerClient; import org.csource.fastdfs.TrackerServer; import java.io.IOException; public class FastDfsInitializer { // 全局只初始化一次不要在每次上传请求里重复init public static StorageClient init(String confPath) throws IOException { ClientGlobal.init(confPath); TrackerServer trackerServer null; try { // TrackerClient内部会从配置的tracker列表里选一个可用节点 trackerServer new TrackerClient().getTrackerServer(); // 第二个参数传null代表使用默认的StorageServer信息 return new StorageClient(trackerServer, null); } finally { // StorageClient内部持有TrackerServer的引用用完要显式释放 if (trackerServer ! null) { try { trackerServer.close(); } catch (IOException ignored) { } } } } }逻辑说明代码里最容易被忽略的是finally块。StorageClient构造时需要TrackerServer但真正上传时它还要跟Storage建立连接try-with-resources不能直接管理这个非AutoCloseable对象所以手动close更稳妥。实际项目中我会把StorageClient放进连接池而不是每次new一个因为TrackerServer的获取有网络开销高频上传时反复握手会拖慢整体吞吐。对应的fastdfs.conf配置如下tracker_server192.168.1.10:22122 tracker_server192.168.1.11:22122 connect_timeout5000 network_timeout60参数说明connect_timeout是建立TCP连接的超时默认5秒即可不要把负载高误判成不可用network_timeout是每次socket.read()的等待时间默认30秒对大文件分片来说太短。分片越大或网络越差这个值越要放大。我的换算经验是分片大小 / 最低保障带宽 * 1.5 10秒比如8MB分片按200KB/s最低带宽算60秒左右配置里写60到90之间比较稳。2.3 分块上传的Java实现切块后逐片传file_id要落库分块上传的核心是把“读本地文件”和“上传FastDFS”解耦。每个分片在FastDFS上是独立文件应用层记录它们的fileId和顺序合并阶段再拼回完整文件。代码public ListString uploadByChunks(String filePath, long chunkSizeBytes) throws Exception { ListString fileIds new ArrayList(); File file new File(filePath); long totalSize file.length(); // 向上取整保证最后一块即使不满chunkSize也会被算进去 long totalChunks (totalSize chunkSizeBytes - 1) / chunkSizeBytes; try (FileInputStream fis new FileInputStream(file)) { // chunkSizeBytes在4MB左右int范围内没问题 byte[] buffer new byte[(int) chunkSizeBytes]; for (int i 0; i totalChunks; i) { int readLen fis.read(buffer); if (readLen 0) { break; } // 最后一块可能比buffer短需要裁剪 byte[] chunkBytes (readLen buffer.length) ? buffer : Arrays.copyOf(buffer, readLen); // 每个分片单独上传返回独立fileId String fileId storageClient.uploadFile(chunkBytes, bin, null); fileIds.add(fileId); // 注意这里不能只打印要把chunkIndex和fileId落库 System.out.println(chunk i uploaded, fileId fileId); // 重置buffer避免残留上次数据 if (readLen buffer.length) { Arrays.fill(buffer, (byte) 0); } } } return fileIds; }逻辑说明每次循环只读一个分片的大小内存占用被限制在chunkSizeBytes而不是整个文件。这里最关键的落库动作没有写进代码块但生产环境必须在uploadFile返回后立刻把chunkIndex、fileId、size写进数据库否则进程崩溃这个fileId就再也找不回来了。完整上传失败重来要传整个文件断点续传则是跳过这些已落库的块差别就在这里。参数说明块大小决定断点粒度。局域网内我常用8MB公网上2到4MB。块太小会导致分片数和Tracker交互次数大幅上升块太大则弱网重传成本高。另外buffer的清理不能省FastDFS返回的byte[]长度和实际传入相等但Java里byte数组复用后旧内容仍在最后一片裁剪或重传时可能把脏数据带进去。 这段用干净数组 裁剪从源头避免这个隐患。3. 断点续传的Java实现分块索引、断点判定与MD5校验3.1 分块索引用一个小类记录每块的状态断点续传的底线是“程序知道每个分片是否完成”。FastDFS的fileId是随机字符串无法从文件名推断所以索引数据结构必须有。我用两个类ChunkRecord负责单块状态UploadProgress负责整体进度。public class ChunkRecord { private int chunkIndex; // 分块序号从0开始 private String fileId; // FastDFS返回的文件ID private long size; // 该分块实际字节数 private String md5; // 分块内容MD5合并阶段用 private boolean uploaded; // 是否上传完成 // getter/setter省略 } public class UploadProgress { private String clientFileKey; // 业务方自定义的同一文件标识 private ListChunkRecord chunks; private int totalChunks; public boolean isAllUploaded() { return chunks.size() totalChunks chunks.stream().allMatch(ChunkRecord::isUploaded); } }逻辑说明clientFileKey是整个续传流程的锚点。前端在上传前先请求后端生成一个uploadToken后端创建一个UUID作为clientFileKey并记录totalChunks。之后每个分片请求都带clientFileKey和chunkIndex后端只按index查表决定是返回已有fileId还是新接收分片。前端如果使用worker上传大文件多个worker并发传不同chunkIndex只要索引表按index记录天然就是并行安全的。参数说明索引存数据库比存本地文件可靠得多。单机演示时可以用ConcurrentHashMap但进程重启就丢多节点部署时本地文件会各说各话。我在项目里用一张upload_chunk表字段对应ChunkRecord的四个核心字段加上complete_time唯一索引建立在(clientFileKey, chunkIndex)上。3.2 续传判定哪些块能跳过哪些必须重传续传最怕的错误是“以为传过其实只传了一半”。所以后端收到续传请求后不能只看有没有chunkIndex记录还要校验size是否一致。这里给出一个判定逻辑public UploadProgress checkAndFill(UploadProgress progress, MapString, ChunkRecord uploadedMap) { for (ChunkRecord record : progress.getChunks()) { ChunkRecord existed uploadedMap.get(String.valueOf(record.getChunkIndex())); // 1. 索引存在 // 2. 分块大小一致 // 3. fileId对应的文件仍存在于FastDFS if (existed ! null existed.getSize() record.getSize() isFileExists(existed.getFileId())) { record.setUploaded(true); record.setFileId(existed.getFileId()); } } return progress; }逻辑说明三条判断缺一不可。大小一致能排除“传了另一个同名文件”fileId存在性探测能排除FastDFS垃圾清理或人工误删。这里我刻意不加MD5比对因为比对MD5要先下载FastDFS上已有的分片大文件场景下网络开销比重传一块还高。更实用的轻量校验是前端在分片头尾各取1KB内容一起上传后端只校验这两个小片段能过滤掉绝大多数内容错位问题。这也正好是java面试题里常聊的点断点续传和完整上传的区别不是“中途会不会断”而是失败后能否复用已传分片的校验结果。完整上传失败后重试从第0字节开始断点续传重试时跳过已确认的块。类比git clone断点续传不是重新clone全量而是接着已有进度继续。参数说明这里的isFileExists在fastdfs-client里没有直接方法我会包装一层调用storageClient.getFileInfo(fileId)返回非null即可。这个操作会访问一次Storage元数据比下载整个文件轻量得多可以在合并前对全部分片批量执行。3.3 合并与校验把分片拼回完整文件分片都上传成功后FastDFS上是一堆独立文件。合并有两类常见做法我第一次做时纠结了很久现在把各自适用场景说清楚。第一种是应用层合并后重新上传按chunkIndex顺序从FastDFS下载每个分片到本地临时文件流式追加成一个完整文件再把这个文件用uploadFile上传最后删除分片。它的优点是任何fastdfs-client版本都支持完全不依赖服务端附加写特性缺点是文件经历了第二次全量上传带宽翻倍。第二种是FastDFS的appender文件首次用appendFile创建文件后续用appendFile把每个分片追加到同一个fileId上。省掉“合并后重新上传”这一步但要确认客户端版本支持追加接口且Storage配置开启了相应开关。我一般首选第一种因为它的失败域更可控。第一种方案的关键代码public String mergeAndUpload(ListString fileIds, String tempDir) throws Exception { File merged new File(tempDir /merge_ UUID.randomUUID() .bin); try (FileOutputStream fos new FileOutputStream(merged)) { for (String fileId : fileIds) { // offset传0、length传0是fastdfs-client约定的“全量下载” byte[] chunk storageClient.downloadFile(fileId, 0, 0); fos.write(chunk); } } String finalFileId storageClient.uploadFile( merged.getAbsolutePath(), bin, null); // 合并成功后清理分片释放Storage空间 for (String fileId : fileIds) { storageClient.deleteFile(fileId); } return finalFileId; }逻辑说明合并顺序完全依赖传入list的排序调用前必须按chunkIndex升序排好否则拼出来的文件顺序错乱。合并成功后要立刻把final_file_id更新到upload_file表并把status改成完成态这样前端才能拿到最终下载地址。deleteFile阶段如果某个分片删除失败不能阻塞主流程记录日志后由后台任务补偿清理。参数说明合并临时目录的磁盘占用等于最终文件大小并发高时要预留足够空间。多个上传任务同时合并时磁盘IO是瓶颈我用clientFileKey做互斥锁防止同一个文件被两次合并触发。临时文件写完后要校验merged.length() 所有分片size之和对不上直接抛异常不要把这个残缺文件上传上去。4. 大文件上传的避坑指南连接重置、文件损坏与进度丢失排查4.1 连接被重置network_timeout按默认值设导致误杀现象传一个500MB的zip分片16MB传到一半抛出IOException“connection reset”重试几次都断在同一位置附近。原因network_timeout默认30秒指的是单次socket.read()的等待时间不是整个分片的总耗时。16MB分片在200KB/s的带宽下光传输就要80秒客户端30秒没等到数据就把连接判死Storage端随后重置连接。解决按分片大小和最低预期带宽换算超时时间。公式为chunkSizeBytes / 最低带宽Bps * 1.5 10结果取整到秒。同时把弱网下的分片大小动态降级客户端在连续两次失败后主动把分片从8MB降到2MB重传成功率会明显提升。4.2 分片合并后文件打不开顺序错乱比缺块更难发现现象所有分片都显示上传成功合并后zip报“压缩包已损坏”或视频播放卡在某一秒。原因合并list的顺序不是按chunkIndex排列。前端并发上传分片时数据库返回记录如果不按chunk_index排序或者list在异步回调里按完成顺序添加fileIds就会乱序。解决合并前强制按chunkIndex升序排序并校验“前N块累计长度等于第N块的起始offset”。我在ChunkRecord里加了expectedOffset字段合并时逐块检查顺序错乱或长度不匹配直接抛异常不做补救。磁盘上留一个坏文件比留一个假完整文件好处理得多。4.3 服务重启后进度丢失索引只存在于内存里现象上传一半Tomcat重启前端续传时后端返回“找不到上传记录”被迫从头传。原因把UploadProgress存在ConcurrentHashMap里进程一重启内存索引全部消失。FastDFS上的分片文件其实还在但应用层已经不知道哪些块传过、哪些块没传。解决每个分片上传成功后立即把ChunkRecord写入数据库而不是等全部完成再汇总。上传状态表建唯一索引(clientFileKey, chunkIndex)重复提交同一分片时靠唯一约束直接忽略或返回已有fileId实现幂等。4.4 多用户并发上传时Storage连接被拖垮连接没释放现象两三个用户同时传大文件刚开始正常几分钟后连小文件上传也变慢Storage机器负载不高但连接数持续攀升。原因常见实现是每次上传都new一个StorageClient用完不放进连接池也不释放storage端的并发连接很快被耗尽。解决给分片上传单独做一个半连接池核心线程数等于本机CPU核数队列容量控制在几十。分片内部的并行度不是越高越好机械硬盘的Storage上并行分片反而加剧随机IO串行或低并行度更稳。4.5 合并时提示“file not exist”分片被服务端清理了现象断点续传隔了一天后触发合并downloadFile时抛FileNotFoundException但数据库里fileId和size都正常。原因FastDFS的Storage有定时清理策略或者文件被运维手动清理。分片文件上传时间越久被清理的概率越大而应用层索引还标记为“已上传”。解决在合并和续传判定前对每个已标记上传的fileId执行一次getFileInfo探测。文件不存在就把该块打回未上传状态重新传这一块。这个逻辑要放在“懒清理”流程里否则会形成一个永远无法完成的合并任务。5. 把断点续传工程化参数调优、元数据管理与异常恢复策略5.1 关键参数表把这些值写进配置而不是写死在代码里大文件上传的稳定性从来不是靠一个参数而是参数组合。下面这张表是我在多个项目里沉淀下来的默认值可以直接抄进配置中心。参数建议值作用说明tracker_server数量至少2个Tracker容灾只配一个时Tracker挂掉整个上传链路不可用connect_timeout5000msTCP建连超时过小会误判负载高的Trackernetwork_timeout按分片大小与带宽换算单次读写超时默认30秒对大分片明显不够chunk_size内网8MB公网2-4MB分块粒度块越小断点粒度越细交互次数越多连接池核心线程数CPU核数*2并发连接上限不限制会把Storage连接池打满分片重试次数2-3次单块重试上限不要无限重试配合指数退避merge临时目录磁盘剩余2倍文件大小合并缓存磁盘满时优先清理oldest临时文件分片清理时机合并成功后异步执行释放Storage空间不要提前删否则合并必失败参数说明network_timeout这一行最关键很多老项目默认值30秒从没改过一上大文件分片就频繁断连。chunk_size的设置还要考虑前端策略如果前端用worker上传大文件并已经切片后端chunk_size最好和前端切片大小保持一致避免服务端再二次切片。5.2 元数据设计分片表怎么建才能支持秒级续传判定断点续传的性能瓶颈主要在“判定哪些块已传完”这一步。两张表加两个索引就能做到毫秒级查询下面是建表SQLCREATE TABLE upload_chunk ( id BIGINT PRIMARY KEY AUTO_INCREMENT, client_file_key VARCHAR(64) NOT NULL, chunk_index INT NOT NULL, file_id VARCHAR(255) NOT NULL, chunk_size BIGINT NOT NULL, file_md5 VARCHAR(32) DEFAULT NULL, complete_time DATETIME, UNIQUE KEY uk_file_chunk (client_file_key, chunk_index), KEY idx_file_key (client_file_key) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE upload_file ( client_file_key VARCHAR(64) PRIMARY KEY, file_name VARCHAR(255) NOT NULL, total_size BIGINT NOT NULL, total_chunks INT NOT NULL, final_file_id VARCHAR(255) DEFAULT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0上传中 1合并中 2完成 3失败, create_time DATETIME, update_time DATETIME );逻辑说明upload_file表记录文件维度状态upload_chunk表记录分片维度状态。续传请求只需要带clientFileKey后端执行一条SELECT chunk_index, file_id FROM upload_chunk WHERE client_file_key ?就能在内存里组装出UploadProgress对象。已经上传的块直接返回给前端前端只重传缺失块进度条恢复的延迟几乎为零。这里的查询要保证只返回必要的字段不要select *把fileId列表全部拉出来后还在应用层内存里做二次过滤。chunk_index是int类型排序由chunk_index天然升序合并时直接按这个结果集顺序取fileId即可不需要单独排序。5.3 异常恢复合并失败怎么处理残留分片合并是断点续传流程里最脆弱的阶段网络、磁盘、Storage都可能中途失败。我的做法是把合并设计成幂等任务而不是一次性的“临时动作”。状态机的流转是这样的合并前把upload_file.status改成1合并中同时把所有缺失的chunk_index清单写入一张merge_task表合并成功改成2并写入final_file_id失败改成3并记录error_msg。有一个定时任务扫描status3且update_time超过10分钟的记录把对应clientFileKey的未上传块重新标记并清理本地临时目录里的半成品文件。// 定时任务伪代码失败后的补偿清理 public void recoverFailedMerge() { ListString failedKeys mergeTaskMapper.findFailedKeys(10 * 60 * 1000); for (String key : failedKeys) { // 1. 删除本地临时合并文件 File temp new File(mergeTempDir / key .bin); if (temp.exists()) { temp.delete(); } // 2. 把upload_file状态重置回0允许前端再次触发合并 uploadFileMapper.updateStatus(key, 0); // 3. 清掉本次merge_task记录 mergeTaskMapper.deleteByKey(key); } }逻辑说明补偿任务只重置状态不删除FastDFS上的分片文件。分片必须等合并明确成功后才能清理否则下一次触发合并会因为找不到fileId而失败。FastDFS侧的分片清理放到合并成功后的异步队列里执行失败也不影响主流程由另一个清理任务补偿删除。参数说明定时任务的扫描间隔和超时阈值要按业务容忍度调。文件越大合并耗时越长阈值设太短会把“还在正常合并”的任务误判为失败。我的经验是阈值至少是预估合并耗时的2倍扫描间隔取阈值的1/5避免同一批任务被反复扫描。6. 最小可运行样例用Java代码验证上传、续传与完整性把前面的逻辑收拢成一个main方法适合在本地FastDFS集群上做快速验证。这个样例省略了数据库索引直接演示“分块上传、合并、下载校验”的最小闭环public class FastDfsUploadDemo { public static void main(String[] args) throws Exception { // 1. 初始化客户端 StorageClient storageClient FastDfsInitializer.init(fastdfs.conf); // 2. 模拟大文件按4MB分块上传 String filePath /tmp/bigfile.bin; long chunkSize 4 * 1024 * 1024; ListString fileIds uploadByChunks(filePath, chunkSize); // 3. 按chunkIndex排序后合并 Collections.sort(fileIds); // 生产环境按数据库chunk_index排序这里仅演示 String finalFileId mergeAndUpload(fileIds, /tmp); // 4. 下载完整文件并校验长度 byte[] downloaded storageClient.downloadFile(finalFileId, 0, 0); long expected new File(filePath).length(); System.out.println(expected expected , actual downloaded.length); if (downloaded.length ! expected) { throw new IllegalStateException(merge check failed); } } }逻辑说明这个样例把分片上传和合并都放进了同一个JVM进程验证的是“上传-合并-下载”是否自洽。实际工程里main方法内要换成从数据库读取UploadProgress把已上传分片的fileId直接复用才能验证断点续传路径。验证时重点看两个输出一是每个分片的fileId是否按顺序打印二是最终校验长度是否等于原文件长度。验证断点续传的完整步骤我建议按这三步走。第一步传一个1GB文件传到一半杀掉进程重启后从数据库查询已传块数确认前端只重传剩余块。第二步在合并前人为delete掉一个分片文件观察getFileInfo探测逻辑是否把它标记为未上传并自动重传。第三步用网络工具把带宽限到100KB/s验证network_timeout换算是否生效连接是否还能稳定完成整个上传。进阶方向是把分块上传的存储层抽象成接口因为后端暴露给前端的只有“clientFileKey chunkIndex chunkData”三个概念FastDFS只是其中一个实现将来换成MinIO或OSS分片接口时上层逻辑基本不用动。我第一版做断点续传时也以为只要把块传上去就行结果被合并顺序、超时设置、进程重启丢进度三个问题轮流教育了一轮现在写代码会先把状态表结构定下来再写传输逻辑。先让数据落库再谈传输效率这是大文件上传这条路上最值的一笔投入。希望帮到你。本文还有配套的精品资源点击获取