干过几个能源化工行业的监控系统项目后，我发现生产监控视频上传这件事，最让人头疼的从来都不是“上传”本身，而是“大文件 + 弱网 + 传输安全”三座大山一起压过来。厂区DVR/NVR里攒了几个小时的监控录像，动辄几个GB，要在非工作时间传回中心机房，结果网络一个抖动就前功尽弃。WebUploader作为老牌分片上传组件，在工业项目里仍被大量使用，但它默认的断点续传只是“半成品”——分片没传完可以接着传，可视频数据在公网链路上是明文裸奔的，这对能源化工这种对安全生产数据格外敏感的场景来说，是不可接受的。所以这篇文章我就来拆解一下，如何用JS把WebUploader改造成既支持加密、又支持续传的生产级上传组件，包含完整思路和可直接抄的代码方案。
1. 项目背景与需求拆解
1.1 一个让人挠头的场景：网络断了就从头传
化工企业厂区内的摄像头基本是24小时不间断录制，尤其是重点生产装置区、罐区、危化品仓库这些位置，视频数据不仅是安全监控，还是事后追溯事故责任的关键证据。按照安全生产管理要求，这类监控录像往往需要保存90天甚至180天。录像存在本地NVR里还不够，很多企业要求定期把关键机位的视频归档到中心存储。
问题就在归档这一步。厂区网络虽然以光纤专线为主，但监控点位分散，不少前端设备通过工业交换机级联甚至无线网桥接入，链路质量并不稳定。我遇到过一条专线在某个时段丢包率接近8%的情况，2GB的视频文件传到一半断开，重传一轮就是两个小时起步，运维同事盯着进度条到凌晨，那种滋味做过的都懂。
WebUploader本身支持分片，断网后理论上可以从断开的那个分片继续。但默认实现下的“续传”，依赖的是同一个浏览器会话里的临时状态，页面一刷新或者浏览器一崩溃，状态全丢。所以我们要做的第一件事，就是把上传进度从内存搬到持久化存储里，每次重新打开页面或者重试时，先把已上传的分片清单拉回来。
1.2 为什么WebUploader依然是工业场景的合理选择
可能有人会觉得，现在前端框架迭代这么快，为什么还要用WebUploader这种老组件？直接上新的上传库不行吗？我在实际项目里的体会是：工业软件选型，稳定、可控、兼容性优先，而WebUploader恰好在这三点上都说得过去。
首先是稳定。WebUploader在外部社区沉淀了很多年，分片上传、并发控制这些核心逻辑经过大量真实项目验证，踩坑的边界比较清晰。其次是可控。它的API暴露了非常多的钩子（比如before-send、before-send-file），我们可以灵活地在传输链路中间插入加密、鉴权、重试逻辑，而不是被框架限制住。第三是兼容性，厂区里老旧的Windows工控机、老浏览器不在少数，WebUploader的兼容策略在这类场景里依然有用。
当然，它也有明显的短板：默认不加密、状态不持久、对超大单文件的并发调度不够细。最后一点在工业场景影响其实不大，因为厂区带宽普遍有限，并发调太高反而会挤占其他业务。所以我的结论是：继续用WebUploader作为底座，但做两处深度改造——加密分片、持久化续传。改造完它就是生产级的上传组件。
1.3 需求拆解：加密、续传、大文件三件事
把需求聊透了再动手，是我做项目的一贯原则。这个“加密续传”的需求表面看是两个词，拆开看其实是三个子问题。
第一，加密。视频数据在传输链路上不能是明文。加密要解决的是机密性和完整性两个维度，既要防止被第三方截获时直接看到画面，也要防止数据在传输途中被篡改。对能源化工行业来说，这不仅仅是技术洁癖——生产监控视频如果被恶意篡改，可能直接影响事故定责的公正性，所以完整性校验必须做到分片级别。
第二，续传。续传要解决的是“从哪继续”的问题。这个状态不能存在内存里，要存在持久化存储里，而且要和加密后的分片一一对应。为什么强调一一对应？因为加密后的分片和原始分片之间是字节不等的映射关系，你不能用原始分片的偏移量去推断加密后的上传状态。
第三，大文件。单个视频动辄几百MB到几个GB，前端不能把整个文件读进内存，必须用Blob.slice按偏移切块，每块独立加密、独立上传、独立校验。这三个子问题互相咬合，所以改造不是简单地在某一行代码里加个加密函数，而是要贯通前端分片、后端接收、状态恢复这一整条链路。
这样拆解下来，方案就清晰了：以WebUploader的分片机制为骨架，在前端分片层插入加密，在后端接收层恢复原文，在状态层做持久化。接下来我讲机制。
2. WebUploader核心机制与改造思路
2.1 分片上传与断点续传的原理
要改造一个东西，先得搞清楚它原本是怎么跑的。WebUploader的分片上传机制，本质上就是把一个大文件在浏览器端按固定大小切成N个二进制块，然后逐个上传到服务端，服务端按分片索引重组。
它在初始化时有两个关键参数：chunked和chunkSize。chunked决定是否启用分片，chunkSize决定分片大小。默认的chunkSize是2MB，但对监控视频这种超大批量的场景，我通常根据实际带宽来定。比如20MB上行带宽下，2MB的分片在网络抖动时更容易重传成功，代价是分片数量变多、请求数增加；10MB的分片则能减少请求次数，但一个分片失败重传的代价也更大。这个参数要在性能和成功率之间做权衡，后文我也会细说。
断点续传的原理也简单：既然文件被切成了分片，那么“断点”就不再是文件字节级别的偏移，而是分片级别的索引。上传过程中如果某个分片失败，重试时只需要重传这个分片，不需要动其他分片；整个文件上传中断后，重新发起时只要知道哪些分片已经存在于服务端，跳过它们，从缺失的分片继续传即可。
WebUploader默认的续传能力其实就建立在这个机制上，但它把“哪些分片已上传”这个状态保存在内存对象中。页面不刷新、浏览器不崩溃、会话不过期，那续传确实可以用；但一旦刷新页面，这些状态就没了，组件会重新从第0个分片开始传。这就是我在1.1里说的“半成品”续传的根源。
2.2 改造点分析：加密、状态持久化、校验
基于上面的机制分析，改造点就非常明确了，一共三处。
第一处，分片加密。WebUploader在发起每个分片请求前会触发before-send钩子，钩子里能拿到当前分片的Blob对象。我们在这里拦截Blob，读取出ArrayBuffer，用约定的密钥加密，再封装成新的Blob回填给组件。这样WebUploader上层完全无感知，它依然以为自己在上传原始分片，实际上传输的已经是密文。
第二处，状态持久化。在每次分片上传成功后，把分片索引和对应的加密元信息（比如IV、密钥版本号）写入localStorage或者IndexedDB。文件级别，再用文件的md5作为key，保存一个“已上传分片集合”。下次组件初始化时，先从后端接口拉取已存在分片列表，合并两边的信息，就能精确恢复断点。
第三处，完整性校验。加密分片需要额外的校验信息。我用AES-GCM模式，自带认证标签，解密时如果数据被篡改或者密钥不对，认证会直接失败。这比单独算一个md5哈希再比对更内聚，也更安全。不过要注意，AES-GCM的密文长度比明文多出16字节的认证标签，而且还要额外带IV，所以后端在接收分片时，不能拿原始分片大小来做固定长度校验，这一点踩坑概率极高，后文我会专门讲。
2.3 整体方案架构：前端加密、后端解密、状态双存储
把改造点串成一条链路，整套方案就长这样。
前端部分，WebUploader负责切片和HTTP传输；在before-send钩子里做三件事——检查续传状态、取出分片加密、把加密元信息写进formData。后端部分，接收分片时先读formData里的keyId和iv，用服务端保存的密钥解密分片，验证认证标签后落盘到临时目录，同时记录分片索引。状态部分采用“双存储”策略：服务端以文件md5为维度记录已上传分片集合，前端以localStorage为维度记录最近一次上传的进度和密钥缓存。双存储的好处是，即使前端localStorage被清理，只要服务端还有分片记录，仍能恢复续传；反过来，即使服务端重建了临时目录，前端也能告诉服务端哪些分片客户端确实传过。
这里有一个容易被忽略的点：密钥不能只存在前端。如果密钥只在前端，前端清理缓存后密钥丢失，之前加密的分片就永远无法解密了。所以服务端必须持有一份密钥备份，且密钥要按版本管理。具体的密钥管理方案我在下一节展开。
3. 加密方案选型与密钥管理
3.1 加密算法选型：为什么是AES-GCM
加密方案的选型，网上讨论很多，有人推RSA，有人推国密SM4。我在这个项目里最终选了AES-GCM，简单说三个理由。
第一，性能。AES是硬件加速的对称加密算法，在浏览器端的Web Crypto API里有原生支持，对GB级别的大文件做分片加密，性能压力可以接受。RSA是非对称加密，适合加密小体积的密钥或签名，不适合直接加密视频流。视频分片加密用对称加密是业界共识。
第二，完整性。GCM模式在加密的同时生成认证标签，天然具备“加密+防篡改”双重能力。如果传输过程中有人改了密文的任何一个字节，解密时认证就会失败。对生产监控视频这种需要保证证据完整性的数据，这一点非常关键。
第三，浏览器原生支持。现代浏览器都实现了Web Crypto API的AES-GCM，我们不需要额外引入大体积的加密库。这一点和WebUploader的老旧风格形成鲜明对比——但我们正好用现代浏览器的Crypto接口配合老组件，互补得很好。
当然，如果你的用户环境里还有大量非常老的浏览器，不支持Web Crypto API，那可以退而求其次用crypto-js库实现AES-CBC模式，CBC没有内置认证能力，需要另外算HMAC或者md5做校验。我在文章最后会给出两种方案的对比。
3.2 分片级加密策略：每个分片独立IV
加密时一个常见的错误是：把整个文件当成一个大整体，只生成一个密钥，然后从头到尾连续加密。这在视频上传场景里会有问题——续传时如果中间的某个分片没有上传成功，就没办法独立解密它。所以我采用分片级加密策略：每个分片独立加密，每个分片使用独立的IV（初始化向量）。
具体来讲，切分文件后，每个分片在加密前先随机生成一个16字节的IV，然后用同一个会话密钥对该分片做AES-GCM加密。加密后的分片请求附带的formData里包含三个字段：keyId标识用的是哪个会话密钥，iv标识这个分片用的是哪个初始化向量，chunkIndex标识分片序号。后端收到后，用相同keyId对应的密钥和IV，就能独立解密任意一个分片，而不依赖其他分片。
为什么分片不能共用一个IV？因为同一密钥下使用相同IV加密不同数据，会导致GCM模式的认证安全性严重下降，甚至可以让攻击者推导出密钥流。这是密码学里的基本安全常识。所以在设计上，宁可多存一些IV元数据，也不能图省事复用IV。
3.3 密钥下发与版本管理
密钥管理是整个方案里最容易被“纸上谈兵”搞砸的部分。我采用的方案是：会话密钥由服务端生成，上传会话开始时下发，前端只持有临时副本。
具体流程是：前端在初始化上传时，先调用后端接口/upload/token，后端返回一个加密令牌和keyId。令牌本身用后端的公钥加密保护，或者直接走HTTPS传输。前端解析出发会话密钥后，用Web Crypto API的importKey导入，用于后续分片加密。这个会话密钥在前端只存在于内存中，不落盘。
那密钥怎么管版本？我用keyId指向服务端密钥表的一条记录，服务端解密分片时按keyId查表即可。密钥表的有效期设为24小时，覆盖监控视频上传的最长时间。如果上传超过密钥有效期，就触发一次密钥续期的流程：前端重新请求新密钥，但已上传的老分片仍用老keyId对应的密钥解密，新分片使用新密钥加密。这个设计保证了“续传不中断”，代价是服务端需要保存24小时窗口内的多版本密钥。
还有一个绝不能省的安全习惯：密钥不能出现在日志里。分片请求的formData里有iv、keyId、chunkIndex，这些可以打日志，但密钥本身要严格隔离。我见过有同事为了调试方便，把密钥打印到了服务端日志里，后来排查了半天才发现——这种低级错误在化工行业的项目中一旦发生，轻则违规通报，重则数据外泄，真的开不起玩笑。
4. 实操：前端JS改造WebUploader核心代码
4.1 初始化配置与分片参数
改造的第一步，是初始化WebUploader。这里我给出经过几个项目验证的配置模板：
var uploader = WebUploader.create({ pick: '#picker', accept: [{ title: 'MP4', extensions: 'mp4', mimeTypes: 'video/mp4' }], swf: '/static/Uploader.swf', server: '/upload/stream', auto: false, chunked: true, chunkSize: 2 * 1024 * 1024, threads: 3, formData: { token: getAccessToken() }, fileNumLimit: 1, fileSizeLimit: 10 * 1024 * 1024 * 1024 });几个参数我解释一下为什么这么配。chunkSize设成2MB而非默认值，是因为监控视频经常在弱网链路上传输，2MB的分片重传成本低，失败一次损失也就2MB，整体成功率更高。threads设成3，而不是WebUploader默认的1或者网上一些人推荐的5，是因为厂区专线上往往还跑着实时视频预览、PLC数据采集等业务，上行带宽要留余量。3路并发是我在多个场景实测下来的平衡点。
fileNumLimit设为1，一次只允许选一个文件。这不是功能限制，而是刻意为之——监控视频归档通常是后台任务式的操作，一次选一个视频文件，确保上传过程的进度、加密状态都聚焦在一个文件维度上，避免分片交错导致续传状态复杂化。
4.2 分片加密钩子实现：before-send拦截
接下来是本改造最核心的一步：在before-send钩子里加密分片。
uploader.on('before-send', function(block) { var chunk = block.chunk; // 先检查续传状态，如果该分片已上传过，直接返回 false 跳过 if (state.uploadedChunks.indexOf(chunk) >= 0) { return false; } return encryptChunkWithWebCrypto(block.blob).then(function(result) { block.blob = result.encryptedBlob; block.formData = block.formData || {}; block.formData.keyId = state.keyId; block.formData.iv = result.iv; block.formData.chunkIndex = chunk; block.formData.fileMd5 = state.fileMd5; }); }); function encryptChunkWithWebCrypto(blob) { var iv = crypto.getRandomValues(new Uint8Array(16)); return blob.arrayBuffer().then(function(buf) { return crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, state.sessionKey, buf); }).then(function(encryptedBuf) { var encryptedBlob = new Blob([encryptedBuf], { type: 'application/octet-stream' }); return { iv: bytesToHex(iv), encryptedBlob: encryptedBlob }; }); }这段代码的逻辑很简单：先看当前分片是不是已经传过，传过就跳过；没传过就读取Blob的ArrayBuffer，用Web Crypto API加密，然后把加密后的Blob替换回block.blob。注意block.formData是WebUploader在请求分片时自动携带的表单数据集合，我们把keyId、iv等加密元数据放进去，后端就能据此解密。
有一个细节要提醒：blob.arrayBuffer()方法要求浏览器支持Promise版本的Blob API，如果你的目标浏览器是基于老内核的，可能需要用FileReader做兼容。我在厂区碰到过一台Win7老工控机上的浏览器不支持arrayBuffer方法，当时用FileReader兜底解决的：
function blobToArrayBuffer(blob) { return new Promise(function(resolve, reject) { var reader = new FileReader(); reader.onload = function() { resolve(reader.result); }; reader.onerror = reject; reader.readAsArrayBuffer(blob); }); }这个兜底函数在老浏览器上稳定可靠，推荐你们直接留一份。
4.3 断点续传与进度恢复
加密搞定了，接下来处理续传。续传有两个信息源：一个在服务端，一个在前端本地。我先在初始化时请求服务端，获取该文件的已上传分片列表：
function fetchUploadedChunks(fileMd5) { return $.ajax({ url: '/upload/chunks', method: 'POST', data: { fileMd5: fileMd5 } }).then(function(res) { return res.chunks || []; }); }同时，前端在每次分片上传成功时，把分片索引同步写入localStorage：
uploader.on('uploadSuccess', function(file, response) { var chunkIndex = response.chunkIndex; state.uploadedChunks.push(chunkIndex); saveLocalState(file.name, { fileMd5: state.fileMd5, uploadedChunks: state.uploadedChunks, keyId: state.keyId }); });为什么服务端和本地各存一份？因为两种存储各有利弊。服务端是权威状态，但前提是分片确实写盘成功；本地存储是即时状态，但清缓存就没了。双存储能互相兜底：本地进度比服务端滞后时，以服务端为准；服务端临时目录被清理时，本地记录的“我传过哪些分片”能辅助判断是否需要重新上传。
页面刷新后的恢复流程是这样：进入页面后，先用文件的md5去服务端查已上传分片列表，再合并本地的localStorage记录，取并集作为“已上传分片集合”。合并完成后，把WebUploader的队列重置到该文件，然后调用uploader.upload()，组件会在before-send钩子里逐个跳过已存在的分片。
我在实际项目里还加了一个“跳过并合并”的处理：对于服务端已存在但本地没有记录的分片，不需要重新上传；对于本地记录了但服务端没有的分片，如果检测到服务端临时目录不存在该分片，自动重传。这套逻辑保证了极端情况下的一致性。
4.4 后端解密接口设计
加密的这头在浏览器，解密的另一头就在后端。虽然这篇文章主要讲前端JS改造，但后端的接收逻辑必须跟着设计，否则前端改完了还是一盘散沙。我用Node.js为例，给一个接收分片的伪代码思路：
router.post('/upload/stream', async (ctx) => { const { keyId, iv, chunkIndex, fileMd5 } = ctx.request.body; const sessionKey = keyStore.getById(keyId); if (!sessionKey) { ctx.status = 400; ctx.body = { code: 'KEY_NOT_FOUND' }; return; } const encryptedBuf = await getRequestBodyBuffer(ctx); const decryptedBuf = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: hexToBytes(iv) }, sessionKey, encryptedBuf); await saveChunkToTemp(fileMd5, chunkIndex, decryptedBuf); await chunkIndexStore.markUploaded(fileMd5, chunkIndex); ctx.body = { code: 0, chunkIndex: chunkIndex }; });关键点有两个。第一，crypto.subtle.decrypt使用的是Node.js的Web Crypto API实现，流程和浏览器端对称。第二，解密失败时不要笼统返回500，要区分是密钥不存在还是认证失败，前者返回KEY_NOT_FOUND，后者通常是数据被篡改或密钥不匹配，返回AUTH_FAILED。前端收到这两种错误码后要执行不同的处理逻辑：KEY_NOT_FOUND触发密钥续期，AUTH_FAILED触发分片重传。
我把这个接口设计成只收“密文+元信息”的模式，本身不关心视频业务逻辑，这让后端接口天然可复用——未来如果还要上传其他类型的大文件，直接复用这套加密接收能力就行。
5. 常见问题与排查技巧实录
5.1 加密后分片校验失败的排查
我在联调阶段遇到的第一个坑，就是后端校验分片失败的次数特别多。排查下来发现，问题出在“文件大小”这个隐蔽的差异上。
原始文件2GB，前端切成1024个2MB分片。加密后每个分片多了16字节认证标签，总计多了16KB。但真正的问题不是这16KB，而是WebUploader的某些版本在before-send钩子处理完分片后，会把原始分片大小写进请求头的Content-Length或者formData里。后端如果按原始大小去读和解密，数据就对不上了。
排查思路整理成一个速查表，基本照着查能省半天时间：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 后端解密AUTH_FAILED | IV或keyId传错/不一致 | 核对formData里的iv字段与加密时是否一致 |
| 后端读到的分片大小不符 | WebUploader把原始大小写入了头部 | 后端按实际流数据长度读取，不要依赖预声明的长度 |
| 前端报分片上传失败 | 加密过程抛异常，blob回填失败 | 检查Promise链的catch，补充错误上报 |
5.2 续传时密钥过期问题
长视频上传动辄一两个小时，会话密钥24小时有效期看似够用，但实际项目中还有另一个坑：跨天的上传任务。
有个真实案例是，值班人员下午4点开始上传一段8小时的监控录像，上传到晚上11点半因为临时停网中断了，第二天早上8点继续传。这时候再看keyId，发现服务端密钥表已经把它标记为过期，所有未上传分片全部KEY_NOT_FOUND。
我给的解法是“密钥续期标记”。续传时如果发现某个keyId已经过期，前端不用整体重来，只需重新请求一个新密钥，然后把“已上传分片集合”里属于旧密钥的那部分分片，在后端做一次“密钥转存”——把已上传的密文用旧密钥解密后重新用新密钥加密落盘。这样前端只是换了一把钥匙，已上传的分片不用重传。转存过程可以放在服务端后台异步执行，不阻塞上传主流程。
5.3 弱网环境下的超时与重试
化工园区的网络抖动是常态，所以上传组件不能把网络超时当成异常直接抛掉。WebUploader有内置的timeout配置，但我觉得还需要配合自己的重试策略。
我给before-send的回调里加了一个简单的重试队列：单个分片连续失败超过3次才报错，每次失败后延迟2秒、4秒、8秒做退避重试。实测下来，在丢包率5%的链路上，配合2MB分片、3并发，整体成功率从改造前的62%提升到了95%以上。
关于超时值的设置，网上有各种说法，我的经验是不要设太短。工厂专线的延迟和抖动比数据中心内部网络大得多，我把单个分片的超时设为30秒，加上3次重试，一个分片最多可以坚持90秒。这个值在正常链路上不会拖累效率，在弱网链路上也不会过早放弃。
5.4 内存占用与GC优化技巧
最后一个常见问题来自主机内存。一个2GB的文件，如果前端不小心把整个文件读进内存，在工控机或者普通办公PC上很容易把浏览器进程搞崩。
避免办法有两个。第一，分片Blob一定要用file.slice(start, end)去切，不要用FileReader读整个文件。WebUploader的切片机制本身就是基于Blob.slice的，我们只要保证before-send里读取的只是当前分片那一小块，内存消耗就始终是分片大小量级。
第二，加密后的ArrayBuffer要及时释放。一个2MB的密文Buffer在V8里有额外的GC管理开销，分片一多，内存碎片就出来了。我习惯在加密函数返回之前把原始ArrayBuffer置为null，鼓励V8尽早回收。另外，千万不要把加密后的Blob对象缓存到数组里，用完就彻底丢掉，只保留分片索引和元信息即可。
我之前接过一次工控机的线上维护，4GB内存的机器跑上传页面，一晚上内存占用从600MB涨到2.5GB，就是因为某个版本把加密后的分片Blob都缓存了起来。改掉之后，峰值内存稳定在700MB以内。
不搞套话总结，我直接说最后两个小经验。
第一个是：改造这种老组件，一定要先在联调环境里把弱网模拟做足。我后来在网关上加了一层随机丢包规则，再用for循环触发几百个分片的并发上传，才把密钥过期、分片乱序、内存泄漏这些问题逼出来。如果不做这层模拟，你根本不知道生产环境里会挂在哪一环。
第二个是：别在一开始就追求把所有功能模块化。加密续传这个需求，拆成三块做，先让加密跑通，再让续传恢复，最后再优化并发和内存。每推进一层，都要对上一层的改动做回归验证。我见过太多同事一上来就设计一个“完美”的抽象层，结果联调时根本定位不了问题。
对于能源化工行业来说，生产监控视频不仅是一个文件，更是一份安全记录。让它在传输过程中既不中断、也不泄露，这本身就是信息化工程师该有的底线。
