Node.js 流式文件上传:隔离存储、大小限制与失败清理

用原生 Node.js 和浏览器实现可运行的隔离上传,实测字节限额、断连清理与并发准入,拆解回执不确定性和生产安全边界。

很多上传接口的第一版只有三步:接收文件、写入目录、返回地址。等到文件变大、用户中途断网,或者磁盘上出现一批无法解释的半成品,问题才开始暴露。真正需要实现的功能,是把一条不可信的字节流,转换成一个可追踪、尚未获准使用的存储对象。接收完成和安全可用必须是两个不同状态。

本文实现一个浏览器到 Node.js 的隔离上传实验。它不依赖 Web 框架,不解析 multipart,也不接对象存储;重点是把大小限制、流式写盘、失败清理和回执语义放进同一个可以运行的例子。资料核对于 2026 年 11 月 8 日,代码实际运行环境为 Node.js v24.22.1。这里使用成熟接口,不把文章包装成某个刚发布的新特性。

一、先把接口承诺缩小

接口只接收单个原始文件体:POST /uploads,Content-Type 固定为 application/octet-stream。上限是 1 MiB,即 1048576 字节,不是十进制一百万字节。空文件被拒绝。每个 Node 进程最多同时处理四条已准入上传,接收管线设置十秒期限。这个定时器主要约束 pipeline,不能把后续 rename、rm 或底层文件系统操作强行变成十秒内必然结束的任务。

成功返回 201,并附带服务端生成的对象编号、实际字节数、SHA-256 和 quarantined 状态。这个状态只说明接收管线完成、文件已经改成完成态文件名。它没有承诺图片可解码、文档无病毒、文件归属已录入数据库,更没有公开下载地址。实验根本不提供下载路由,因此即便传入 HTML 或脚本,其内容也不会被这个服务作为网页执行。

这套契约适合讲清接收边界,不应直接照搬成互联网公开上传产品。真实头像业务需要格式白名单和解码验证;文档业务需要审核、权限和保留策略。客户端上报的类型不能证明文件内容安全,这一点在 OWASP 文件上传指南 中有明确提醒。本文中的类型检查只是协议检查,不是文件识别器。

为什么不用 multipart?一个请求只传一个文件时,原始请求体能去掉字段解析、边界匹配和临时文件管理这些额外变量。如果产品必须同时提交多个文件或复杂表单,应选择维护中的解析库,并逐项设置文件数量、字段长度、单文件大小和总大小限制。不能把下面的计数器理解为对任意 multipart 接口都已经完整防护。

二、可直接运行的服务端

新建一个独立目录,保存下面的 server.mjs 与后文的 index.html。示例只依赖 Node.js 内置模块,无需 npm install。建议在 Node.js 24 系列上复现,其他版本需要自行回归。存储目录应位于项目静态资源目录以外,运行账户独占写权限。

import http from 'node:http';
import { createWriteStream } from 'node:fs';
import { mkdir, mkdtemp, rename, rm, readFile } from 'node:fs/promises';
import { resolve, join, basename } from 'node:path';
import { createHash } from 'node:crypto';
import { Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';

const token = process.env.UPLOAD_TOKEN;
if (!token || token.length < 24) throw new Error('UPLOAD_TOKEN: at least 24 chars');
const root = resolve(process.env.UPLOAD_DIR || './quarantine');
const port = Number(process.env.PORT || 3000);
const limit = 1024 * 1024;
const maxActive = 4;
let active = 0;
await mkdir(root, { recursive: true, mode: 0o700 });
const page = await readFile(new URL('./index.html', import.meta.url));

function json(res, status, body) {
  if (res.destroyed || res.writableEnded) return;
  res.writeHead(status, {
    'Content-Type': 'application/json; charset=utf-8',
    'Cache-Control': 'no-store', Connection: 'close'
  });
  res.end(JSON.stringify(body));
}

async function handle(req, res) {
  if (req.method === 'GET' && req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8',
      'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
    return res.end(page);
  }
  if (req.method !== 'POST' || req.url !== '/uploads')
    return json(res, 404, { error: 'not_found' });
  if (req.headers.authorization !== `Bearer ${token}`)
    return json(res, 401, { error: 'unauthorized' });
  if (req.headers['content-type'] !== 'application/octet-stream' ||
      req.headers['content-encoding'])
    return json(res, 415, { error: 'raw_body_required' });
  const length = req.headers['content-length'];
  if (length !== undefined && (!/^\d+$/.test(length) || Number(length) > limit))
    return json(res, 413, { error: 'too_large' });
  if (active >= maxActive) return json(res, 503, { error: 'busy' });
  active++;
  let dir;
  let committed = false;
  let bytes = 0;
  const hash = createHash('sha256');
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 10_000);
  try {
    dir = await mkdtemp(join(root, 'u-'));
    const meter = new Transform({
      transform(chunk, encoding, done) {
        bytes += chunk.length;
        if (bytes > limit) return done(Object.assign(new Error('too_large'), { code: 'LIMIT' }));
        hash.update(chunk);
        done(null, chunk);
      }
    });
    await pipeline(req, meter,
      createWriteStream(join(dir, 'payload.part'), { flags: 'wx', mode: 0o600 }),
      { signal: controller.signal });
    if (!bytes) return json(res, 422, { error: 'empty_file' });
    await rename(join(dir, 'payload.part'), join(dir, 'payload.bin'));
    committed = true;
    json(res, 201, { id: basename(dir), status: 'quarantined', bytes,
      sha256: hash.digest('hex') });
  } catch (error) {
    console.error(JSON.stringify({ event: 'upload_failed', code: error.code || error.name, bytes }));
    json(res, error.code === 'LIMIT' ? 413 : 500, { error: 'upload_failed' });
  } finally {
    clearTimeout(timer);
    try {
      if (dir && !committed) await rm(dir, { recursive: true, force: true });
    } catch (error) {
      console.error(JSON.stringify({ event: 'cleanup_failed', code: error.code }));
    } finally { active--; }
  }
}
const server = http.createServer((req, res) => {
  handle(req, res).catch(error => {
    console.error(error.code || error.name);
    json(res, 500, { error: 'internal_error' });
  });
});
server.headersTimeout = 5_000;
server.requestTimeout = 15_000;
server.listen(port, '127.0.0.1', () => console.log(`http://127.0.0.1:${port}`));

这里有几个容易被“代码能跑”掩盖的设计点。首先,鉴权、媒体类型、声明长度和并发准入都在创建目录之前完成。被拒绝的请求不会预先分配文件。演示令牌仅用于本机实验,代码不把它嵌入网页,也不记录到日志;生产环境应使用已有的用户认证机制,绑定租户与上传额度,不应把一个共享令牌发给所有用户。

其次,Content-Length 只提供提前拒绝的机会。HTTP 请求可以使用分块传输而不提供这个头,应用必须对实际经过管线的字节继续计数。计数超过限制后,当前块不会继续写入目标文件,此前已经写出的部分则在 finally 中删除。整个应用层并未先把文件合并成一个大 Buffer,再检查大小。

第三,服务端完全不使用用户文件名拼接路径。mkdtemp 为本次接收创建独立目录,目录内只有固定名字的 payload.part 与 payload.bin。写入采用 wx,避免目标已经存在时静默覆盖。Node.js 文件系统文档 也建议直接执行打开操作并处理错误,而不是先检查存在性,再假定文件状态不会改变。mode 参数只在相应目录或文件新建时参与权限设置,已有根目录不会因为再次 mkdir 就自动收紧权限,部署时应另外检查所有者与实际权限。这里仍然要求存储根目录可信;如果别的账户能改写目录或替换符号链接,随机文件名不能消除所有本地文件系统攻击。

第四,committed 标志只有在 rename 成功后才变成 true。任何接收错误、空文件或写盘失败都会走清理分支;成功完成的隔离文件则保留。如果删除失败,会留下结构化告警,而不是让 finally 的异常绕过并发计数释放。这里的提交是本进程的业务命名,不能等同于数据库事务,也不代表断电持久性。

三、浏览器页面怎样表达结果

将下面页面保存为 index.html,与 server.mjs 放在同一目录。服务端只会通过根路由返回这一份页面,上传目录没有映射为静态文件目录。页面同源调用接口,不需要为演示开放任意来源的跨域权限。

<!doctype html><meta charset="utf-8"><title>隔离上传实验</title>
<label>实验令牌 <input id="token" type="password" autocomplete="off"></label>
<input id="file" type="file"><button id="send">上传</button>
<pre id="result"></pre>
<script type="module">
const token = document.querySelector('#token');
const file = document.querySelector('#file');
const send = document.querySelector('#send');
const result = document.querySelector('#result');
send.onclick = async () => {
  const selected = file.files[0];
  if (!selected || selected.size === 0 || selected.size > 1024 * 1024) {
    result.textContent = '请选择大于 0、不超过 1 MiB 的文件';
    return;
  }
  send.disabled = true;
  result.textContent = '接收中,尚未通过内容审核';
  try {
    const response = await fetch('/uploads', {
      method: 'POST', headers: {
        Authorization: `Bearer ${token.value}`,
        'Content-Type': 'application/octet-stream'
      }, body: selected
    });
    const data = await response.json();
    if (!response.ok) throw new Error(`${response.status}: ${data.error}`);
    result.textContent = JSON.stringify(data, null, 2);
  } catch (error) {
    result.textContent = `未取得成功回执:${error.message}。不要据此认定服务端没有保存。`;
  } finally { send.disabled = false; }
};
</script>

页面的大小检查帮助用户尽早发现选错文件,却无法替代服务端检查。用户可以修改脚本,也可以直接使用命令行构造请求。上传按钮在请求期间禁用,是避免普通用户重复点击的交互措施,不提供跨页面、跨设备或网络重试的业务幂等保证。

响应状态要显式检查。fetch 收到 HTTP 错误响应时,不会自动把所有非成功状态转成异常;只有网络层等特定失败才会直接拒绝 Promise。这是 MDN Fetch 使用说明 中的重要约定。页面先解析响应,再检查 response.ok,把接口拒绝和网络失败统一显示为“未取得成功回执”,避免错误地宣布服务端没有保存文件。

这句话并非保守措辞,而是一个真实竞态:服务端可能已经 rename,客户端却在收到 201 前断开。此时文件仍然保留,但浏览器不知道对象编号。当前实验没有解决这个问题,刷新后也无法查询先前上传。面向生产的下一步,应在发送字节之前创建绑定用户的上传会话,让客户端事先持有可查询的会话编号,再通过状态接口确认结果。不能简单把每一次 fetch 异常都解释成“请自动重传”。

页面没有显示虚假的百分比。标准 fetch 的这个调用方式没有在代码里实现可靠的上传进度统计。如果业务需要字节级进度,可另行评估 XMLHttpRequest 上传进度事件或专门的上传客户端,但仍要区分“客户端已发送”“服务器已接收”“审核已通过”三种进度,避免进度条到达百分之百就展示公开链接。

四、启动、调用与预期结果

在保存两个文件的目录执行以下命令。UPLOAD_DIR 要替换为你控制的专用目录;PORT 可以改成未占用端口,页面地址与后续 curl 地址同步修改。令牌通过本机随机生成,只适用于这个隔离实验,不要把真实生产令牌复制进文章、截图或提交到仓库。

node --version
export UPLOAD_TOKEN="$(node -e "console.log(require('node:crypto').randomBytes(24).toString('hex'))")"
export UPLOAD_DIR="$PWD/quarantine"
export PORT=3000
node server.mjs

进程应输出本机监听地址。打开 http://127.0.0.1:3000,在页面中输入本次实验令牌并选择小文件即可。令牌可在启动终端本地查看,不应通过聊天发送给别人。该页面没有把令牌写入 localStorage。不要把服务监听地址直接改成公网并视为上线完成。

也可以在拥有相同环境变量的另一个终端执行请求。如果新终端没有继承变量,应在本机安全地设置同一个实验令牌,不要重新生成另一份令牌后期待鉴权通过。

printf 'upload-safe-boundary' > sample.bin
curl -i http://127.0.0.1:3000/uploads \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @sample.bin

正常结果是 201 JSON,bytes 对应样本字节数,status 为 quarantined,id 每次不同。存储目录中出现以 u- 开头的子目录,里面只有 payload.bin。再次上传同一文件会生成另一个对象,摘要相同不代表系统自动去重。摘要提供内容比对能力,不提供内容审核、身份认证或所有权证明。

失败结果也应成为接口文档的一部分:令牌错误返回 401;发送 text/plain 或带 Content-Encoding 的请求返回 415;声明长度超过上限返回 413;空体返回 422;已有四个接收任务时,新请求返回 503。这些是本示例的设计值,不是行业统一标准。生产客户端应针对 busy 采用受控退避,并防止立即循环重试放大压力。

五、背压与错误响应之间的取舍

pipeline 把请求流、计数转换流和写盘流连接起来,避免手写 data 事件处理时无视写入端速度。磁盘变慢时,上游读取会受到背压约束,但这不等于进程内存只占一个固定小缓冲区。HTTP、转换流、文件流和内核都有各自缓冲,并发连接本身也占资源;highWaterMark 是流的缓冲阈值概念,不能直接拿来当整个服务的内存上限。

更重要的是,pipeline 出错可能销毁参与管线的流及底层连接。Node.js Stream 文档 专门提示了请求或响应参与管线时,预期错误响应可能无法送出的情况。因此代码里的 json 只是尽力响应,不能承诺所有运行中超限都能让浏览器收到整齐的 413 JSON。

本地本次分块超限测试收到了 413,但这只是该运行条件下的观察结果,不能外推为所有网络时序。若客户端持续发送、磁盘错误发生更早、代理采取不同的连接处理方式,客户端可能只看到连接失败。前端因此把未收到回执作为独立状态处理,服务端则用错误码日志和文件清理验证实际结果。

如果业务必须稳定返回可读错误,一种方向是把拒绝判定尽量前置到短请求的上传会话阶段,另一种方向是谨慎设计停止写盘后的请求体处理。继续排空一个无限制攻击流会消耗带宽和连接,直接关闭连接则牺牲错误展示的确定性。不能只为保住漂亮的 JSON 而无限读取剩余请求体。这个例子选择明确资源边界,并接受部分错误表现为网络失败。

六、实际执行的测试,不只看成功状态

我在 Node.js v24.22.1 上实际启动了这个服务,使用临时隔离目录和测试专用令牌运行了下面的验证程序。保存为 test.mjs 后执行 node test.mjs。它自行启动子进程,并使用 33181 端口;若端口已被占用,先停止冲突进程,或修改测试中的端口常量。测试结束会停止自己启动的子进程并删除自己的临时目录,不会删除正常实验的 quarantine 目录。

import assert from 'node:assert/strict';
import http from 'node:http';
import { spawn } from 'node:child_process';
import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { once } from 'node:events';
import { createHash } from 'node:crypto';
const root = await mkdtemp(join(tmpdir(), 'upload-test-'));
const token = 'local-test-token-1234567890';
const port = 33181;
const child = spawn(process.execPath, ['server.mjs'], {
 cwd: new URL('.', import.meta.url), env: {...process.env, UPLOAD_DIR:root, UPLOAD_TOKEN:token, PORT:String(port)}, stdio:['ignore','pipe','pipe']
});
let logs = ''; child.stderr.on('data', b => logs += b);
await once(child.stdout, 'data');
const headers = {Authorization:`Bearer ${token}`, 'Content-Type':'application/octet-stream'};
const post = (body, extra={}) => fetch(`http://127.0.0.1:${port}/uploads`, {method:'POST',headers:{...headers,...extra},body});
const wait = ms => new Promise(r=>setTimeout(r,ms));
try {
 const body=Buffer.from('upload-safe-boundary');
 let r=await post(body); assert.equal(r.status,201); const receipt=await r.json();
 assert.equal(receipt.sha256,createHash('sha256').update(body).digest('hex'));
 assert.deepEqual(await readFile(join(root,receipt.id,'payload.bin')),body);
 console.log('PASS success + hash + bytes on disk');
 assert.equal((await post(body,{Authorization:'Bearer wrong'})).status,401);
 assert.equal((await post(body,{'Content-Type':'text/plain'})).status,415);
 assert.equal((await post(body,{'Content-Encoding':'gzip'})).status,415);
 assert.equal((await post('')).status,422);
 assert.equal((await post(Buffer.alloc(1024*1024+1))).status,413);
 console.log('PASS auth / type / encoding / empty / declared limit');
 const outcome=await new Promise(resolve=>{
   const req=http.request({host:'127.0.0.1',port,path:'/uploads',method:'POST',headers},res=>{res.resume();resolve(res.statusCode)});
   req.on('error',e=>resolve(e.code));
   req.write(Buffer.alloc(600000)); req.end(Buffer.alloc(600000));
 });
 await wait(100); assert.equal((await readdir(root)).length,1); assert.match(logs,/LIMIT/);
 console.log('PASS chunked limit + cleanup: '+outcome);
 await new Promise(resolve=>{
  const req=http.request({host:'127.0.0.1',port,path:'/uploads',method:'POST',headers:{...headers,'Content-Length':'500000'}},res=>res.resume());
  req.on('error',()=>{}); req.write(Buffer.alloc(1000)); setTimeout(()=>{req.destroy();resolve()},100);
 });
 await wait(150); assert.equal((await readdir(root)).length,1);
 console.log('PASS interrupted upload cleanup');
 const held=[];
 for(let i=0;i<4;i++){
  const q=http.request({host:'127.0.0.1',port,path:'/uploads',method:'POST',headers:{...headers,'Content-Length':'500000'}},res=>res.resume());
  q.on('error',()=>{});q.write(Buffer.alloc(1));held.push(q);
 }
 await wait(150); assert.equal((await post(body)).status,503); held.forEach(q=>q.destroy());
 await wait(150); assert.equal((await readdir(root)).length,1);
 console.log('PASS concurrency gate + cleanup');
} finally {child.kill();await once(child,'exit');await rm(root,{recursive:true,force:true});}

本次运行输出如下,所有断言通过:

PASS success + hash + bytes on disk
PASS auth / type / encoding / empty / declared limit
PASS chunked limit + cleanup: 413
PASS interrupted upload cleanup
PASS concurrency gate + cleanup

第一组同时检查了成功状态、摘要和磁盘实际内容,没有把“返回 201”当作写盘正确的全部证据。第二组覆盖准入拒绝和空体;第三组没有提供 Content-Length,以验证真实字节计数而不是仅验证请求头判断。中断测试只发送部分内容后主动断开,随后确认目录中没有新增残留。并发测试占住四个未完成请求,验证第五个请求被拒绝,再断开占位连接并检查清理。

这些测试已经执行;浏览器人工操作、十秒期限触发、磁盘写满、删除失败、反向代理行为以及跨操作系统文件权限表现没有在本次执行中验证,不能称为全部通过。测试里的短暂等待是本机集成测试的简化,速度较慢的 CI 应改成有截止时间的条件轮询,避免把调度延迟误判为业务错误。

七、从实验到生产还缺哪些保护

最先需要补的是磁盘总量预算。单文件一兆、并发四个,只限制正在传输的工作,不限制一天累计成功的文件数量。攻击者或者普通业务流量仍然能通过持续小文件填满磁盘。实际系统应有按用户、租户和全局划分的额度,在接收前预留预算,成功后转为占用,失败后释放,并为清理延迟预留余量。

其次是崩溃恢复。finally 只在代码能够继续执行时起作用;进程被强制终止、机器掉电或文件系统不可用时,它不会替你清扫。生产清理程序应识别未完成对象,依据会话状态、租约和过期时间回收,不能简单删除所有“看起来很旧”的目录,否则可能删掉仍在上传的文件。当前完成态文件也没有自动过期策略,运行实验后需要自行管理。

再者是持久性定义。这里 rename 发生在同一子目录中,避免跨文件系统搬运,但没有执行文件与目录的持久化同步,也没有把对象记录与业务数据库一起提交。若产品要求“已经收到成功回执的数据即使突然断电也不能丢失”,必须按目标文件系统与部署环境设计并验证同步顺序。将本地 rename 直接等同于云对象存储完成请求,或者等同于数据库 commit,都会掩盖不同系统的失败窗口。

审核链路也需要独立身份。扫描程序应以受限权限读取隔离对象,避免自动执行上传内容;压缩包解包要限制文件数量、展开总量和路径,图片解码要考虑像素规模与解析器漏洞。通过审核之后才允许进入可下载区,下载时仍需校验归属、访问权限和响应头。若考虑外部扫描服务,还要先确认上传内容能否发送给第三方,不能因为它是“安全工具”就忽略隐私边界。

最后是部署拓扑。active 计数只在一个进程里有效,启动多个进程或多个容器后不会共享额度。反向代理可能先缓冲请求体,从而把磁盘和连接压力转移到代理层;也可能比应用先超时。上线前应分别验证入口大小限制、应用实际字节限制、代理临时目录、超时先后顺序和多实例配额,而不是只测本机直连。本文十秒、四并发、一兆都是便于复现的实验参数,不能直接当作容量规划结论。

结语

这个上传功能最有价值的部分,是把每一步的承诺写清楚:准入通过不等于内容可信,文件写完不等于业务可用,客户端断线不等于服务端回滚,单文件有限不等于总体资源有限。先用可执行的小闭环证明接收、计数、清理与回执正确,再接入数据库、审核和对象存储,才能知道新增的复杂度究竟改变了哪一条边界。

相关文章

评论

登录后即可参与讨论

暂无评论。