有一次在某项目里做管理后台客户要往网页端传好几个G的视频文件。我按网上最常见的说法把 Spring Boot 的 multipart 限制调到了 2GB还顺手改了应用容器参数结果浏览器转了几分钟直接失败后端日志刷出一堆内存溢出SpringCloud 网关那边跟着报 502。后来才意识到SpringCloud 网页端上传超大附件这件事难点根本不在“调大一个参数”而是整条链路上每一层都在限制你反向代理、网关、应用容器、业务框架甚至前端本身。这篇文章我就把这套东西完整梳理一遍从限制点在哪、分片怎么做、断点续传和秒传怎么落地到实际踩过的坑都写出来。这篇文章适合正在被“上传超大附件”折磨的后端同学也适合准备做文件模块的初学者。不论你是想快速救火还是要设计一个能支撑几个 G 级文件上传的稳定模块下面这些内容都能直接拿来参考。1. 先盘清楚超限这件事到底卡在哪几层1.1 一条上传请求要闯过的关卡网页端上传一个文件请求路径要比大部分人想的更长。以典型架构来看请求从浏览器出发先经过反向代理再进入 SpringCloud 网关然后被转发到某个业务服务业务服务再写磁盘或转发到对象存储。中间任何一环对请求体大小、请求头大小、连接超时时间有限制文件都传不上去。问题在于这些限制的默认值普遍是“按普通请求设计的”根本不适合大文件。反向代理默认对请求体大小的限制通常很小改小不改大网关层除了 body 大小还有请求头大小限制应用容器对 POST 表单和 multipart 请求也有自己的最大尺寸最后才是 Spring Boot 框架里的 multipart 配置。大多数人只改了最后一层所以问题依然存在。1.2 各层默认限制值速览层级常见默认限制超出后的典型表现反向代理请求体默认限制 1MB 左右请求直接被拒返回 413SpringCloud 网关请求头大小限制 8KB~16KB返回 400 或 431应用容器内嵌容器maxPostSize默认 2MB返回 404 或请求体被丢弃Spring Boot multipart单文件默认 1MB总请求默认 10MB抛MaxUploadSizeExceededException服务器对外带宽/超时时间无统一默认看部署上传到一半连接断开表现为 502/504这个表格值得保存下来。排查的时候按从外到内的顺序一层层看很多“改了配置没生效”的案例其实是改错了层。比如只改 Spring Boot 的max-file-size但反向代理那边还是默认值那请求在最外层就被拦了应用层的配置压根没机会生效。1.3 一个真实案例明明是文件模块的问题最后卡在网关上某公司的管理后台要上传 1.2GB 的安装包。当时开发人员把 Spring Boot 的spring.servlet.multipart.max-file-size和max-request-size都改成了 2GB本地测试通过部署到测试环境之后就失败。浏览器连续转几分钟后报错后端日志没有任何异常但网关日志里出现了请求体过大的提示。最后发现是网关层没有做任何放行处理。因为 SpringCloud 网关默认对请求体大小是有限制的尤其是用表单方式提交大文件时整个请求体都要经网关缓冲。把网关层的请求体限制同步调大并开启流式读取相关配置之后文件才顺利通过。这个案例说明一个原则在 SpringCloud 架构里超限问题必须按整条链路排查业务层配置只是最后一环。2. 想清楚再动手你要的是“能传”还是“传得好”2.1 调大参数为什么不是长久方案把所有限制都调大确实能让一个文件传上去但代价很高。第一个问题是内存。普通上传方式会把整个请求体或分片缓冲到内存里文件越大内存占用越吓人。一个 2GB 文件在多实例服务里同时来几路上传服务内存直接告急甚至触发 OOM。第二个问题是体验。没有断点续传的话用户传到一半网络波动整个文件就得重来。第三个问题是并发。大文件上传耗时动辄几分钟甚至更久如果每个请求都长时间占用一个连接和线程网关和业务服务的线程池很容易被打满。所以在面对超大附件时单纯“放开限制”只能解决“能不能传”解决不了“传得好不好”。2.2 分片上传的整体思路分片上传的本质是把一个大文件切成若干个小块前端一片一片上传后端收到所有分片后再合并成完整文件。这样做有几个直接好处。内存压力被切小了每次只处理一个小分片比如 5MB即使并发几路占用也远小于直接缓冲几 GB。断点续传变简单了已传过的分片可以跳过只需要记录哪些分片还没有传。进度展示也天然精准以“已完成分片数/总分片数”来算进度比前端瞎猜剩余秒数准确得多。2.3 两种落地路径自建分片接口与对象存储直传实现分片上传有两条主流路线。一条是自建接口后端自己做分片接收、临时存储、合并逻辑。另一条是直传对象存储前端把文件分片后直接上传到对象存储服务服务端只负责生成临时凭证。对比项自建分片接口对象存储直传开发成本较高要处理合并、校验、清理较低主要是生成凭证和回调可控性高合并逻辑、存储位置自己掌握受制于第三方服务的规则服务器带宽压力集中在自己服务器分散到对象存储侧适合场景文件需要先经过业务处理、内网环境面向公网、文件量大、追求稳定自建方案适合文件要落本地、后续要做扫描或转码的业务直传方案适合希望把带宽压力外置、不想维护临时文件系统的场景。很多团队最终是混合方案对内走自建接口对外走直传。2.4 我的建议怎么选才不后悔我个人建议先看文件大小和业务形态。如果文件基本在 500MB 以下、并发不高调大限制合理超时也许够用。但凡是声称“支持 GB 级附件”的需求直接按分片上传设计不要犹豫。如果公司服务器带宽紧张又希望用户上传稳定对象存储直传其实是更省心的选择。若在内网环境、数据不能出网那就老老实实自建分片接口。这个决策要在动手写代码之前做不要等上线了再重构。3. 自建分片上传的接口设计从初始化到合并完成的完整协议3.1 分片大小与并发数怎么定分片大小没有一个绝对标准但经验区间很明确单分片 5MB 到 10MB 最合适。分片太小比如 1MB请求次数会爆炸服务端和网络都要承担大量额外开销分片太大比如 50MB单分片的内存压力又上来了失去分片的意义。并发数建议控制在 2 到 3。不要以为并发开得越大越快。浏览器对同一域名有并发连接限制同时分片上传本身也会挤占带宽。多路争抢导致每个分片变慢整体速度反而下降。实测中5MB 分片、并发 3 路的组合最稳也容易排查问题。3.2 前端需要维护的核心字段分片上传的前端并不是简单把文件slice之后axios发出去而是要维护一套结构化的信息否则服务端不知道如何重组文件。通常要携带这些字段fileId本次上传任务的唯一标识前端生成可以是 UUIDfileName与fileSize完整文件的名称和总大小chunkIndex当前分片的序号从 0 开始totalChunks总分片数chunkSize约定的单分片大小最后一片可能不足需要按实际大小处理这里的fileId是整个流程的主键。合并、查询进度、断点续传都依赖它。注意fileId一定要在初始化时确定不要每次上传分片时生成一个新 ID否则服务端会认为这是不同的文件。3.3 后端三个核心接口自建分片上传的后端一般提供三个接口初始化、上传分片、合并。初始化接口负责接收元数据并建立一个上传任务记录返回fileId给前端上传分片接口接收单个分片以fileId加chunkIndex作为标识存储合并接口负责把所有分片按顺序拼接成完整文件。核心逻辑大致如下这里用伪代码说明思路// 初始化接口 PostMapping(/upload/init) public UploadInitVO init(RequestBody FileMeta meta) { String fileId UUID.randomUUID().toString(); uploadTaskRepository.save(new UploadTask(fileId, meta)); return new UploadInitVO(fileId, meta.getTotalChunks()); } // 上传分片接口 PostMapping(/upload/chunk) public Response uploadChunk(RequestParam(fileId) String fileId, RequestParam(chunkIndex) int index, MultipartFile chunk) { // 流式写入分片目录避免把整个分片读入内存 chunk.transferTo(new File(chunkDir, fileId _ index)); uploadTaskRepository.markChunkDone(fileId, index); return Response.ok(index); } // 合并接口 PostMapping(/upload/merge) public Response merge(RequestParam(fileId) String fileId) { // 校验所有分片存在然后顺序拼接 ListInteger indexes uploadTaskRepository.getMissingChunks(fileId); if (!indexes.isEmpty()) { return Response.error(missing chunks: indexes); } mergeFile(fileId); uploadTaskRepository.markCompleted(fileId); return Response.ok(); }这里最关键的写法是分片文件按“目录 fileId 序号”命名存储合并时按序号顺序读取拼接。写分片时用流式写入绝不把整个分片再缓冲到内存。3.4 合并前为什么必须做完整性校验合并接口如果只看“是否传来 100 个分片”的布尔值早晚会出问题。网络传输中可能发生分片丢失、并发请求乱序、某个分片传了一半就断连。虽然实际上前端一般会重试但后端必须做硬性校验。校验有三层。第一层是分片数量已上传分片数是否等于totalChunks。第二层是分片大小除了最后一片其余每个分片大小必须等于约定的chunkSize如果某个分片只有 4MB说明它传得不完整。第三层是可选的整体校验合并完成后对最终文件计算摘要和初始化时前端提供的摘要比对不一致就整个任务标记失败并触发重传。不要省这三步。合并时发现缺块重建成本远低于一个“合并成功但文件损坏”的线上事故。4. 断点续传核心不在前端记忆而在服务端状态设计4.1 状态机上传任务不是简单的“传完/没传完”很多人理解的断点续传是“前端把已传列表存到浏览器里下次上传时跳过”。这个方案看起来简单但换台电脑、清缓存、换浏览器就失效了。真正可靠的断点续传必须让服务端来记录状态。一个上传任务可以拆成三个状态UPLOADING、MERGING、COMPLETED。初始化时创建为UPLOADING分片逐个上传当所有分片都到达后任务进入MERGING此时合并接口执行合并合并成功后才进入COMPLETED。如果任务合并失败或中途宕机它仍然停留在MERGING或回退到UPLOADING下次查询状态时就能继续处理。4.2 “查询已传分片”和“幂等上传”缺一不可断点续传要提供两个能力。第一是查询已传分片前端在开始上传前先调用一个接口传入fileId拿到已完成的chunkIndex列表只上传缺失部分。第二是幂等上传同一个fileId chunkIndex的重复上传请求不应该导致分片损坏或任务错乱。实现幂等很简单分片文件以固定路径保存重复上传时直接覆盖同时把“标记完成”的操作做成幂等写入。这样即使前端并发请求重复发送后端也不会出问题。这个能力在弱网环境尤其重要一个分片超时后前端重试结果其实之前已经写入成功了如果后端不幂等就会产生脏分片。4.3 多实例部署时临时分片放哪SpringCloud 服务一般是多实例部署这给分片上传带来一个隐蔽问题。假设负载均衡把第 1 个分片发给实例 A第 2 个分片发给实例 B如果实例 A 和 B 各自写本地磁盘那么合并时谁都不掌握全部分片合并必然失败。解决方案有三种。最简单粗暴的是配置一个上传专用实例所有分片请求都路由到同一个节点不让其他实例处理上传接口更合理的方案是使用共享文件系统或对象存储保存临时分片再不济把分片写到 Redis 之类的集中存储但大分片对 Redis 压力大不建议。优先考虑共享存储或者对象存储充当临时分片目录。4.4 临时分片的过期清理分片上传经常有用户传了一半放弃的情况如果不清理临时文件会堆满磁盘。清理策略一般是定时扫描临时目录或任务表把“超过 24 小时仍处于UPLOADING状态”的任务标记为过期并删除对应分片。在分布式环境下清理任务最好做成一个独立的后台调度只跑一次。实现上可以依赖定时任务框架或者直接用数据库定时任务。要注意的是清理和业务查询之间要做并发控制别把一个正在上传中的任务当过期任务清掉。稳妥的做法是清理前检查分片最近更新时间超过阈值才处理。5. 秒传的实现与文件指纹同一份文件没必要传两次5.1 文件指纹的两种计算策略秒传的前提是识别“同一个文件”。判断文件是否相同最可靠的依据是内容摘要也就是对整个文件算一个哈希值比如 MD5 或 SHA-1。问题来了一个几个 GB 的文件在浏览器里完整算出哈希值可能要几十秒甚至几分钟这段时间用户已经在等待了很不友好。工程上常用两种策略。一种是整体计算适合文件不太大的场景另一种是抽样指纹取文件开头、中间、结尾的几个数据块组成一个样本然后对样本计算摘要速度快得多。抽样指纹有极小概率把不同文件判成同一个所以抽样命中后后端应对比文件大小或者后台异步做一次完整校验。5.2 秒传的完整流程秒传流程贯穿前端和后端。前端在用户选中文件后先计算文件指纹然后调用秒传检查接口把指纹和文件大小发给服务端。服务端查询是否存在“指纹相同、大小相同”的已完成文件记录如果存在直接把这个文件资源绑定到当前用户或当前业务记录上返回“秒传成功”。如果不存在服务端返回一个新的fileId前端再走正常的分片上传流程。这里有一个值得注意的地方秒传并不是“跳过整个上传”而是“跳过传输全量内容”。服务端必须把这个文件作为一个真实存在的资源登记进文件表后续业务才能引用。如果只是校验通过但没有建立关联文件就是悬空的用户下载时会 404。5.3 防止误判指纹必须和大小一起用指纹碰撞的概率极低但不是零。尤其是抽样指纹本来就不完整只要抽样区间落在文件内容相同的部分哪怕其他位置完全不同也可能得到一样的摘要。所以判断秒传时必须同时比对文件大小。大小和指纹都匹配了基本可以认为同一文件。但如果业务对文件准确性要求极高比如医疗影像、合同扫描件建议在秒传命中后异步做一个完整校验校验失败再回退到全量上传。这个兜底逻辑一定要加别为了省事埋雷。6. 实测中那些没写在文档里的坑与排查思路6.1 报错 413/400反向代理和网关限制是重灾区分片方案上线后测试环境正常一到生产环境就报 413。查了半天业务代码没发现任何问题后来发现是生产环境的反向代理配置和测试环境不一致。分片上传虽然每个请求只有几 MB但总有一个配置把请求体上限限制在了 1MB 左右分片稍大就触发。排查这类问题要沿着请求链路逐段看日志浏览器到反向代理、反向代理到网关、网关到业务服务每一段的错误码特征不一样。413 基本可以断定是前置层限制400 则要看是否请求头超限。解决办法就是对应层同步调整限制同时压测验证。6.2 OOM 和内存暴涨不是并发太高是你把流接成了全量有一次某个服务在分片上传时内存一路飙升最后 OOM。堆转储分析发现问题出在接收分片的代码里虽然前端是按 5MB 分片传的但后端把MultipartFile直接转成了字节数组再交给后续逻辑处理。表面看单次只有 5MB但纯并发加上其他业务对象积少成多就把内存打爆了。正确做法是全程流式处理从输入流读出缓冲后立刻写入目标文件或对象存储不要中间整体装配成 byte 数组。同时建议给上传接口单独设置一个更小的线程池限制并发上传的路数避免上传请求挤占核心业务接口的线程资源。6.3 分片合并时“缺块”负载均衡把请求打到了不同实例这个问题上文提过但值得展开讲一次完整排查过程。现象是前端上传 100 个分片全部成功合并接口却始终提示缺第 67 块和第 89 块。前端网络正常、重传也没用后端日志里每个分片写入都有记录。后来发现两个实例分别有自己的本地磁盘分片被负载均衡分散到了两台机器单看某一台机器都缺块。合并服务在实例 A 上运行它去本地目录找分片自然找不到属于实例 B 的那几块。修复方式就是把临时分片从本地磁盘迁移到共享存储或对象存储让所有实例读写同一份数据。这个坑在单实例开发时永远测不出来多实例部署才会暴露一定要提前按分布式思维设计。6.4 进度条“卡住”上传没停卡的是前端计算逻辑进度条卡住不一定代表上传失败。常见原因有两个。一个是前端用“已加载字节数 / 文件总大小”来计算进度但服务端做合并前还没有把总体字节数返回给前端比例看起来就停在 99% 不动。另一个是分片并发上传时前端只统计了最后发起的那个请求其他分片完成与否没有汇总。更稳的做法是让后端在查询接口里返回“已接收分片大小 / 文件总大小”前端定时轮询这个值刷新进度。合并阶段的进度可以用状态机来表示比如“上传完成服务端合并中”避免用户误以为卡死。6.5 对象存储直传的凭证过期问题如果走对象存储直传方案一个很容易被忽略的问题是临时凭证有效期。上传一个 3GB 文件可能需要十几分钟如果凭证有效期设置成常规的 5 分钟传一半就会收到权限错误。有些团队的解决方式是让前端在上传分片前请求一个新的临时凭证或者把凭证有效期设长再结合分片大小控制每个分片的耗时。另一个常见问题是大文件直传时对象存储服务要求分片大小有最小值限制。前端如果没有按文档约定设置分片大小上传会在某一片之后被拒绝。这类问题在接入前最好拿官方文档和真实大文件都验证一遍别等上线后由用户来发现。7. 结尾一点个人体会如果让我给一个可以直接照抄的选型结论文件稳定小于 500MB、内部系统、要求快可以先调参数扛一阵但只要存在 GB 级文件、弱网环境或多实例部署直接上分片上传并把临时分片放到共享存储这几乎是一条最优路径。我自己做过的方案里最终稳定运行的组合是前端按 5MB 分片、并发 3 路后端三个接口分别处理初始化、分片和合并秒传用“大小 指纹”双校验临时分片放在共享存储并定时清理。上线后最频繁的报警点反而是清理任务没跑起来分片目录胀满磁盘。另外提醒一句合并校验一定不能省它看起来多花了点时间但省掉它的代价是不知道哪一天交付给用户一个只有文件大小对、内容已经损坏的附件。