大文件上传和加密存储这两个词放在一起难度不是相加而是相乘。我之前接手一个文档归档项目客户端传上来的单文件普遍几个GB起初觉得SpringMVC里做加密存储就是拿到 MultipartFile 后 new 一个 AES写进磁盘完事。真做完一轮压测和故障演练才发现上传链路没稳、加密模式选错、临时文件残留任何一个坑都能让“加密存储”变成一句空话。这篇文章把我实际趟过的路子整理出来从 SpringMVC 的 multipart 配置讲起到 AES-GCM 选型的原因再到上传即加密的落地代码、下载解密的细节以及上线后随机读取、密钥轮换这些绕不开的运维问题尽量做到让团队可以直接抄作业。适合正在用 SpringMVC 承接文件上传业务、并且对落盘安全性有硬性要求的开发者参考。1. 大文件上传链路先稳住加密才有附着点很多人把注意力全放在加密算法本身结果加密代码写得挺漂亮上传环节却连几个 GB 的文件都接不住。加密是叠加在上传链路上的上传链路不稳定加密做得再好也是白搭。所以我先讲讲 SpringMVC 里大文件上传必须注意的几个底层问题。1.1 multipart 配置里最容易被忽视的阈值参数SpringMVC 解析 multipart 请求有两种常见方式一种是基于 Servlet 3.0 的StandardServletMultipartResolver另一种是基于 Apache Commons FileUpload 的CommonsMultipartResolver。新项目我建议优先用前者配置更简单容器自己处理临时文件不用额外引入依赖。注册方式大概是这样的Bean public MultipartResolver multipartResolver() { return new StandardServletMultipartResolver(); }但真正决定大文件能不能接住的地方不在MultipartResolver而在 Servlet 容器的MultipartConfigElement配置。很多人只在 application.properties 里写了文件大小上限就以为完事了。实际上有三个参数需要一起确认参数作用大文件场景建议值maxFileSize单个文件允许的最大字节数根据业务上限比如 10GBmaxRequestSize整个请求含表单字段、多个文件的最大字节数建议略大于 maxFileSize比如 10GB 2MBfileSizeThreshold超过该大小后文件内容写入临时文件否则留在内存保持默认 0让所有 part 都落盘第三个参数容易被忽略。Servlet 规范里fileSizeThreshold的默认值是 0意思是所有上传内容直接进磁盘临时文件而不是进内存。这个默认行为对大文件是友好的因为几个 GB 的内容塞进 JVM 堆GC 直接给你颜色看。所以除非有明确的小文件高频场景否则别手贱去调大这个阈值。在 Spring Boot 里对应的配置是spring.servlet.multipart.max-file-size10GB spring.servlet.multipart.max-request-size10GB spring.servlet.multipart.file-size-threshold0如果是传统 SpringMVC 外置 Tomcat 的方式需要在 web.xml 或 Servlet 注册代码里给 DispatcherServlet 加MultipartConfigElement。我当时是在初始化 Servlet 时设置的ServletRegistration.Dynamic registration servletContext.addServlet(dispatcher, dispatcherServlet); registration.setMultipartConfig(new MultipartConfigElement( tempDir, // 临时目录 10L * 1024 * 1024 * 1024, // maxFileSize10GB 10L * 1024 * 1024 * 1024, // maxRequestSize10GB 0 // fileSizeThreshold ));这里有个实操细节临时目录一定要单独划一个分区并且和最终存储目录在同一个挂载点。为什么后面讲落盘流程时你会看到上传完成后我们要做一次原子移动跨文件系统的 rename 会退化成“复制删除”一旦中央目标盘满了移动失败文件就丢了。1.2 从 Part 流式读取而不是一次性拿进内存Controller 里拿到MultipartFile后新手最容易踩的坑是file.getBytes()或file.transferTo()一把梭。getBytes()会把整个文件读进字节数组几个 GB 的文件这么搞内存直接爆掉这属于事故级写法。transferTo()虽然内部是流式复制但它的目标直接就是明文文件我们后面要插入加密环节所以也用不上。加密场景下的正确姿势是拿输入流一边读一边加密一边写try (InputStream in file.getInputStream()) { // 这里接加密输出流后面详写 }这里我多说一句MultipartFile.getInputStream()返回的就是临时文件的流大文件场景下读的是磁盘不是内存所以性能瓶颈主要在磁盘 IO 和后续的加密写入上。如果发现上传接口很慢先看磁盘别急着怪加密。缓冲区大小也值得留意。我见过用 4KB 缓冲区的代码加密大文件时每 4KB 就要做一次底层 IO 调用性能惨不忍睹。实际测试下来缓冲区设置在 64KB 到 1MB 之间比较合理IO 次数少内存占用也可控。我通常用 256KB。1.3 大文件上传超时与临时目录生命周期文件大了以后上传时间必然长。这时候第一个要防的是代理层和容器层的超时。Nginx 默认的client_max_body_size是 1MB不调的话上传 2MB 就直接 413。连接超时和读取超时要分开设置读取超时建议给到 30 分钟以上因为大文件传输中可能长时间没有数据流动连接超时设短了会被误杀。这属于部署层面的问题但线上出问题十有八九出在这里不能忽视。临时文件的清理机制也值得提前摸清楚。StandardServletMultipartResolver底层依赖容器的 multipart 处理逻辑part 对应的临时文件会在请求处理完毕后由容器清理。这个“请求处理完毕”指的是 DispatcherServlet 处理完整个请求链也就是 Controller 方法返回之后。听起来很完美但有个隐患如果你在业务代码里把MultipartFile的流交给另一个线程异步处理Controller 先返回了那么临时文件可能已经被清理异步线程再读就是空的。所以大文件的加密落盘必须在请求线程内同步完成不要异步化。这不是技术限制而是生命周期设计问题想清楚了能省掉很多莫名其妙的 bug。2. 加密方案选型AES-GCM 胜出的逻辑加密算法选型看着是个选择题实际上是安全底线和工程复杂度之间的权衡。我在这个项目里最终选了 AES-GCM下面说说理由。2.1 为什么 ECB 和 CBC 都不适合文件存储先排除最不该用的 ECB 模式。ECB 有个致命缺陷相同的明文块会产生相同的密文块文件的结构信息会直接映射到密文上。典型例子是图片加密后虽然打不开但你用十六进制工具看图像的轮廓和色块分布仍然清晰可见等于白加密。这种模式只适合加密小于一个分组的短数据文件场景绝对不能用。CBC 模式比 ECB 好一些每个密文块都依赖前一个密文块相同明文块在不同位置产生的密文不同解决了模式泄露问题。但 CBC 有另外两个问题。第一它不提供完整性保护密文被篡改后解密端毫无感知存储场景下文件损坏或被人恶意替换是很危险的。第二CBC 在解密时需要填充操作配合错误的 padding 处理机制可能引发 padding oracle 攻击。虽然现代库的默认实现已经规避了大部分攻击路径但既然有更合适的模式没必要冒着被人审出问题的风险去用 CBC。2.2 GCM 的认证加密到底解决了什么问题GCM 模式全称 Galois/Counter Mode底层用 CTR 模式的计数器方式生成密钥流来加密数据同时用 GHASH 函数对密文计算认证标签。一句话概括它在加密的同时给整个密文算了一个 128 位的签名任何一位密文被改动解密端读到最后一个分组时都会直接抛认证失败用户拿到的不是损坏的文件而是明确的错误提示。这一点对存储场景极其重要。我们加密文件是为了防泄露但防篡改同样重要——一份被恶意替换过的合同文件比丢失更可怕。GCM 把这两件事一次做完了这是它胜出的根本原因。GCM 的密文长度是可控的加密后的数据长度等于明文长度额外附加一个 16 字节的认证标签。后面算 Content-Length 时要用到这个性质。2.3 GCM 在大文件场景的两个硬约束选 GCM 之前有两个硬约束必须搞清楚否则实现到一半会翻车。第一个约束和加密量有关。NIST SP 800-38D 规定在同一个密钥和 IV 组合下GCM 加密的数据量不能超过 2^39 - 256 bits大约 64GB。超过这个量GHASH 内部的计算碰撞概率会上升到不可接受的水平。对我们这个单文件最大 10GB 的场景来说是够用的。如果你的业务会出现单个文件超过 64GB 的情况就得考虑分片加密每个分片用独立的 IV再给每个分片单独存认证标签。那套复杂度会明显上升所以先确认业务边界再选方案。第二个约束是 IV 的唯一性。这是 CTR 类模式的天条同一个密钥下IV 绝对不能重复。一旦两次加密用了相同的 IV两个密文异或就能得到两个明文的异或再结合已知明文攻击密文会被直接剥离。很多实现翻车都是因为 IV 生成方式不对——用时间戳、用 UUID、用自增 ID这些都是错的。正确的做法是用SecureRandom生成 12 字节的随机数每次加密前新生成一个并存储下来供解密使用。JDK 里使用 GCM 的方式很直接Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(secretKey, AES); byte[] iv new byte[12]; SecureRandom secureRandom new SecureRandom(); secureRandom.nextBytes(iv); GCMParameterSpec gcmSpec new GCMParameterSpec(128, iv); cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmSpec);注意NoPadding不是“不加密明文”而是 GCM 是 CTR 流密码模式不需要填充明文长度就是密文长度。很多第一次用的人看到 NoPadding 会疑惑这里解释一下。2.4 密钥从哪来环境变量与密钥版本化加密方案定了密钥管理必须跟上。最简单的做法是环境变量把 Base64 编码后的 256 位密钥放在环境变量或外置配置文件里应用启动时读取代码里不出现任何明文密钥。比如String keyBase64 System.getenv(FILE_ENC_KEY); byte[] keyBytes Base64.getDecoder().decode(keyBase64);这就避免了“密钥硬编码在代码里”的低级事故。生产环境如果预算允许可以上真正的密钥管理服务但第一版用环境变量是完全能接受的前提是你把密钥文件权限收紧并且定期轮换。密文文件一旦用旧密钥加密完毕轮换密钥就成了一个头疼问题——重加密所有历史文件非常耗时不轮换又不符合安全规范。折中方案是引入密钥版本号每个密钥分配一个 ID写文件时在文件头记录keyId。轮换密钥时新文件全部用新密钥旧文件保持旧密钥不动通过 keyId 找到对应的解密密钥。这样可以先把密钥换掉历史文件后续再分批重加密。这也是文件头设计里必须预留 keyId 字段的原因。3. 上传即加密落盘流程的完整实现选型讨论完了下面是真正动手的部分。我按“文件头设计 → 控制器落盘 → 临时文件清理 → 元数据”四个小节展开。3.1 加密文件格式设计一个只有 18 字节的文件头加密后的文件必须是自包含的也就是拿到这个文件本身就能知道它用什么 IV、哪个密钥版本加密的而不是去数据库里查。为什么因为数据库和文件系统是两个存储存在数据不一致的可能——文件拷贝走了、数据库记录丢了文件就再也解不开。自包含格式更稳妥。我设计的文件头只有 18 字节字段长度说明magic4 字节固定值比如0x46454E43FENC用于识别合法加密文件version1 字节文件格式版本当前为 1keyId1 字节加密该文件所用的密钥版本号iv12 字节加密时生成的随机 IV头之后紧跟 GCM 加密数据。这个格式简单到用ByteBuffer就能读写不依赖任何框架任何语言都能解析很实用。magic 字段尤其重要它能让解密程序在打开非预期文件时快速失败而不是把随机字节当成密文去解密抛出一堆不知所云的异常。3.2 控制器里的落盘代码CipherOutputStream 的正确用法核心流程是这样的从 MultipartFile 取输入流 → 生成 IV → 初始化加密 Cipher → 用 CipherOutputStream 包住最终文件的输出流 → 边读边写 → 关闭输出流这一步会触发 GCM tag 的写入→ 原子移动到最终位置。代码骨架public FileEncryptResult encryptUpload(MultipartFile file, String destDir, byte[] secretKey, byte keyId) throws Exception { // 1. 生成 IV byte[] iv new byte[12]; SecureRandom secureRandom new SecureRandom(); secureRandom.nextBytes(iv); // 2. 初始化加密 Cipher Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(secretKey, AES); GCMParameterSpec gcmSpec new GCMParameterSpec(128, iv); cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmSpec); // 3. 生成目标文件名UUID避免重名 String storedName UUID.randomUUID().toString().replace(-, ) .enc; Path tmpPath Paths.get(destDir /tmp/, storedName .tmp); Path finalPath Paths.get(destDir, storedName); // 4. 写入文件头 try (FileOutputStream fos new FileOutputStream(tmpPath.toFile())) { fos.write(new byte[]{F, E, N, C}); // magic fos.write(1); // version fos.write(keyId); // keyId fos.write(iv); // IV // 5. 加密写入 try (CipherOutputStream cos new CipherOutputStream(fos, cipher); InputStream in file.getInputStream()) { byte[] buf new byte[256 * 1024]; int len; while ((len in.read(buf)) ! -1) { cos.write(buf, 0, len); } } } // 6. 原子移动 Files.move(tmpPath, finalPath, StandardCopyOption.ATOMIC_MOVE); return new FileEncryptResult(storedName, finalPath.toFile().length()); }这里有个必须牢记的坑CipherOutputStream 的 GCM tag 写在 close 的时候。cos.write()只负责生成密文流等关闭流时CipherOutputStream 内部会调用cipher.doFinal()把最后一段密文和 16 字节的认证标签写入底层流。所以代码里不要提前调用cipher.doFinal()更不要在 close 前又手动 flush 一次 Cipher否则可能出现重复写入或空输出。我见过不止一个人在这里翻车加密出来的文件要么少 16 字节要么直接抛IllegalStateException: cipher object is not initialized。正确做法是一个流程里只创建一次 Cipher只关闭一次 CipherOutputStream。3.3 临时文件与明文残留的清理策略落盘路径上有一个很多人没意识到的风险multipart 临时文件和加密过程中产生的临时文件都是明文状态。先说 MultipartFile 本身的临时文件。StandardServletMultipartResolver 会在请求结束由容器清理这个没问题。容易出问题的是业务代码自己手贱保留的副本比如为了写缩略图或校验在本地又存了一份明文。这个副本不会自动清理项目上线跑一段时间后明文文件散落在磁盘各处加密就成了摆设。我的原则是业务代码里绝不允许把 MultipartFile 另存为明文副本所有处理都在输入流上进行加密完成后只保留密文。再说加密过程中的临时文件。上面代码里加密数据先写destDir/tmp/xxx.tmp完成后再原子移动到最终位置。为什么多这一步因为要避免半截文件被下载出去——如果写入过程在 80% 时失败目标路径上留着一个不完整的加密文件下载模块不知道它坏了用户拉下来的就是损坏数据。先写临时文件整个写入成功后再 rename保证目标路径上只有完整文件。跨文件系统的 rename 问题前面提过这里再强调一次Files.move的ATOMIC_MOVE只有在同一个文件系统内才真正原子。如果你把临时目录和最终存储目录放在不同盘上这个操作可能直接抛异常或者退化成非原子操作。所以临时目录和最终目录一定要规划在同一个挂载点下。明文临时文件的残留问题还可以从系统层面加固临时目录挂 tmpfs 或用加密磁盘重启即清空。生产环境我建议至少在启动脚本里加一个清理步骤把固定的临时目录挨个扫一遍防止上次崩溃留下的残留。3.4 元数据处理与重名策略加密文件最终落盘用 UUID 命名原始文件名、大小、keyId、上传时间这些信息需要存数据库。我建的表结构大致是这样字段类型说明file_idvarchar(64)业务侧访问文件使用的 ID可以用数字或短 IDstored_namevarchar(128)磁盘上的 UUID 文件名original_namevarchar(512)用户上传时的原始文件名下载时用enc_sizebigint加密后文件大小含文件头和 GCM tagplain_sizebigint明文文件大小key_idtinyint解密所需密钥版本created_atdatetime上传时间plain_size看起来是冗余字段但下载时计算 Content-Length 很需要它省得每次去推算。上传接口如果要支持去重可以在加密之前先对流计算 SHA-256再把哈希存到数据库做唯一索引同一文件重复上传时直接复用已有密文节省存储。注意计算哈希要在流上做不能把文件再读一遍内存。4. 解密读取与上线后绕不开的问题文件加密落盘只是第一步真正麻烦的是业务要用起来下载、随机读取、密钥轮换。这一节把上线后会遇到的问题集中说一下。4.1 下载解密Content-Length 怎么算下载接口的逻辑是读文件头拿 IV初始化解密 Cipher用 CipherInputStream 包住文件流直接写给 HTTP Response。代码骨架public void decryptDownload(String storedName, HttpServletResponse response, byte[] secretKey) throws Exception { Path filePath Paths.get(storageDir, storedName); try (FileInputStream fis new FileInputStream(filePath.toFile())) { // 1. 读文件头 byte[] header new byte[18]; fis.read(header); ByteBuffer buf ByteBuffer.wrap(header); byte[] magic new byte[4]; buf.get(magic); if (magic[0] ! F || magic[1] ! E || magic[2] ! N || magic[3] ! C) { throw new IllegalStateException(not an encrypted file); } int version buf.get(); int keyId buf.get(); byte[] iv new byte[12]; buf.get(iv); // 2. 根据 keyId 取密钥 byte[] key keyResolver.getKeyById(keyId); // 3. 初始化解密 Cipher Cipher cipher Cipher.getInstance(AES/GCM/NoPadding); SecretKeySpec keySpec new SecretKeySpec(key, AES); GCMParameterSpec gcmSpec new GCMParameterSpec(128, iv); cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec); // 4. 精确计算 Content-Length long encSize Files.size(filePath); long plainSize encSize - 18 - 16; // 去掉文件头和 GCM tag response.setContentLengthLong(plainSize); // 5. 解密流式输出 try (CipherInputStream cis new CipherInputStream(fis, cipher); OutputStream out response.getOutputStream()) { byte[] buf2 new byte[256 * 1024]; int len; while ((len cis.read(buf2)) ! -1) { out.write(buf2, 0, len); } } } }这里有个容易忽略的细节GCM 认证发生在数据全部读完之后。在CipherInputStream读取最后一个分组时如果 GCM tag 校验失败它会抛AEADBadTagException。这意味着下载接口在文件损坏时不能给用户发一个“读了一半的文件”而是应该捕获异常返回 500 或明确的错误码。我建议在调用的地方包一层 try/catch明确区分“文件不存在”、“密钥错误”、“文件损坏”三种错误信息否则排障时面对一堆通用异常头会很痛。4.2 GCM 不是为随机读设计的范围请求的取舍文件服务经常遇到范围请求Range Request比如视频拖动、PDF 分页读取。GCM 模式下这个需求很尴尬认证标签是整个密文的认证你必须从头读到尾验证通过才能确定第 N 块密文是可信的。想直接从某个偏移量解密某一段在标准 GCM 语义下做不到。实际业务中一般有三种取舍方案优点缺点适用场景全量解密流式输出实现最简单内存可控不支持跳过客户端还是要等全量数据下载、导出等完整读取场景分片加密每片独立 IV支持精准范围读取文件格式和密钥派生逻辑复杂每个分片都要存 IV 和偏移表视频点播、大文件在线预览额外维护一份明文副本随机读取无障碍存储成本翻倍明文的暴露面扩大高并发读取的热数据我们最终选择了第一种业务上主要是合同和归档文件的下载没有在线预览的强需求。如果将来要支持视频播放我倾向于分片加密而不是明文副本——存储成本和安全隐患比那点开发复杂度要命得多。分片加密大概思路是固定每 16MB 一个分片给每个分片生成独立 IV、独立 GCM 加密每个分片头部存自己的 IV元数据里再存各分片的偏移量。这能让加密后的文件支持精确定位解密但文件头和格式设计会复杂很多。做之前先问清楚业务是否真的需要。4.3 密钥轮换与批量重加密密钥不能一辈子不换。前面文件头的 keyId 此时发挥作用。轮换流程可以这样设计生成新密钥分配新的 keyId更新环境变量或密钥管理服务。代码里保留旧密钥一段时间的“宽限期”新上传文件全部用新密钥旧文件继续用旧密钥解密。后台起一个批量任务遍历存储目录遇到 keyId 是旧版本的文件逐文件解密再重新加密然后更新数据库里的 keyId。批量重加密的耗时要提前评估。我们当时实测机械盘上约 1GB 文件“解密 重加密 写盘”大概 20 到 40 秒但改用 SSD 后能压缩到 5 秒内。这个数字很受磁盘随机写能力影响压测的时候最好用真实盘来测。重加密期间旧文件要保留到新文件完全写入成功后才能删。我习惯的做法是加密临时文件写完后 rename 成最终文件等 rename 成功、数据库 keyId 更新完毕再删旧文件。如果中途崩溃重新扫描一遍数据库和目录对账把 keyId 不一致的再处理一轮。不用搞很复杂的事务对账任务就能兜底。4.4 性能观察与调优最后聊聊上线后的性能观察。我刚开始担心几千行代码里最耗时的会是 CPU 加密但实际压测下来瓶颈几乎都出在 IO 上。写入缓冲区从 8KB 调到 256KB加密耗时直接下降了一半以上把临时目录从普通机械盘换到 SSD 或 tmpfs整个上传时长又有肉眼可见的改善。AES-NI 硬件指令在服务器上基本是标配GCM 加解密速度能到几百 MB/s 到 GB/s 量级真正的大文件处理几乎都是等磁盘而不是等 CPU。还有一点和加密无关但直接影响用户体感的上传接口要预留足够的读取超时。默认的 30 秒对于几 GB 的文件来说远远不够我一般设到 30 分钟以上配合前端显示上传进度和分片重试体验才算基本及格。写到这里加密存储这件事的完整链路基本讲清了。最后再分享一个小经验如果你和我一样用 CipherInputStream 做下载解密千万别在流上做任何 seek 操作GCM 的内部状态不会因为你 seek 就自动同步结果不是乱码就是认证失败。文件解密要么完整读要么走分片方案没有中间路线。想清楚这一点很多后面会遇到的问题都能提前绕开。