用户传了个两百兆的扫描件进来，上传这条链路比解析还难

用户传了个两百兆的扫描件进来，上传这条链路比解析还难

功能需求一句话，让用户上传文档然后提问。开发时拿一个两兆的 PDF 测通了，上线第一天有人传了两百兆的扫描件，接口超时，进程内存打满，整个服务跟着挂了十分钟。

上传这件事看起来是最简单的部分，实际是整条链路里最容易出事的地方。文件大小、网络抖动、重复上传、恶意文件，每一个都能让服务躺下。

先分片

超过一定大小的文件必须分片上传。切成固定大小的一块，通常是二到五兆，前端并发传几块，服务端按序号合并。

分片解决三个问题。第一是大文件不占满内存，服务端每次只处理一片。第二是失败可续，某一片失败只重传那一片，不用整个重来。第三是并发上传，带宽利用得更好。

服务端要有分片记录，用文件标识加片序号作为键，记录哪些片已收到。合并前校验片数完整、序号连续，缺片就报错让客户端补。

秒传靠内容哈希

客户端算整个文件的哈希，传之前先问服务端有没有这个文件。有就直接返回已有的标识，叫秒传。

这个设计在团队内部场景特别有效，同一份合同被十个人各传一遍的情况很常见。

哈希要算整个文件，不能只算第一片。算整个文件在前端有点耗时，两三百兆要几秒，可以显示进度，用户能接受。

断点续传的状态

上传中断之后，用户重新打开页面，希望从断点继续。

做法是前端先请求这个文件的已上传分片列表，拿到之后只传缺的那些。服务端的记录要带过期时间，比如二十四小时，过期的记录清理掉，避免存储里堆满废弃分片。

过期清理要真的跑起来。很多团队写了清理逻辑但没调度，半年后发现存储里全是不完整的文件。

解析前必须校验

这一节比上传本身重要。文件进了系统不代表能解析，解析不了的要在入口拦住，别让它排队到后台再失败。

第一件事是校验真实类型。不能只看扩展名，要把文件头的魔数读出来对。一个改了后缀的可执行文件不应该被当成 PDF。

第二件事是页数和大小上限。一份八百页的扫描件，解析成本可能是几块钱，时间几十分钟。这类文件应该提示用户拆分，或者走单独的高成本通道。

第三件事是加密检测。加密的 PDF 打不开，解析会直接失败，在入口就告诉用户需要先解密。

第四件事是损坏检测。传输中断或者本身就是坏文件，解析到一半才失败，浪费算力。

第五件事是图像尺寸检查。纯图片的 PDF 里可能有超大尺寸的页面，渲染成位图时把内存吃光。解析之前先读页面的尺寸信息，超限的降采样。

压缩炸弹这个坑

这是最容易被忽略的一种攻击。一个两兆的压缩包解压出来是二十个 G，或者一个 PDF 里嵌着几百张超高分辨率图片。

上传时看起来人畜无害，解析时内存被吃光。

防御要在解析之前，设置解压后的总量上限、单页像素上限、图层数量上限。超限的文件直接拒绝，或者转入受限的沙箱解析。

让它异步

上传和解析必须分开。

上传接口只负责接收并落盘，落盘之后立刻返回一个文档标识，然后投一个解析任务到队列。用户看到的是正在解析的进度，而不是一个转了三分钟的圈。

这套结构在异步长任务那篇讲过，三个接口，提交、查询、取结果。文档上传正是一个典型例子，因为它天然满足耗时不可控这个条件。

存储放在哪

文件本体不要放数据库。放对象存储，数据库里只存元信息，路径、大小、哈希、页数、状态。

临时分片也要有目录规范，按日期和文件标识分目录，合并成功后清掉分片。合并本身最好是流式拼接，别把整个文件读进内存再写出去。

如果对象存储支持前端直传，尽量让前端直接传到存储，服务端只签发凭证。这样能省掉中间一层带宽，也避免大文件穿过你的应用。

配额要算清楚

一份文档占的不只是存储。解析要算力，向量化要调用，存向量要空间，之后的检索要资源。

所以按用户或按租户设三档限制，单文件大小、每日解析页数、总存储量。超限时明确提示，而不是静默失败。

这些配额的记账可以复用配额那篇的思路，把解析页数当成一个计量单位。

验收清单

上线之前过一遍这几个场景。

传一个刚好超过上限的文件，看提示是否清晰。上传到一半断网，重新打开看是否续传。同一个文件传两次，看是否秒传。传一个改过后缀的图片，看是否被拦。传一个加密 PDF，看是否在入口报错而不是排队失败。传一个一百页的扫描件，看是否异步返回并最终完成。

这七个场景过了，这条链路基本能扛住真实用户。

结合系列

异步长任务那篇讲的是任务三段式，文档解析是它最典型的使用者。扫描件解析那篇讲的是解析本身怎么做，这一篇讲的是文件怎么安全地进来。代码沙箱那篇的隔离思路，对压缩炸弹这类输入同样适用，环境要能扛住异常输入。配额那篇的计量，在这里变成按页算的解析额度。数据脱敏篇的出口控制，要求上传时就识别哪些文档含敏感信息。