文件上传

是什么，为什么存在

文件上传（file upload）是客户端把一段字节及其描述信息交给服务端的过程。HTTP 只负责传输消息；应用还要决定谁能上传、允许什么内容、怎样保存、何时可读，以及失败后清理哪些中间状态。只要接口接收头像、附件、数据导入文件或媒体资源，就会遇到这些问题。

上传端点与普通 JSON 端点的差别在于，载荷可能很大，而且字节本身会进入解析器、转码器、病毒扫描器或浏览器。攻击者可以伪造扩展名和媒体类型，也可以利用路径、压缩率、解析器漏洞或存储配额。安全边界因此不能停在表单解析成功这一刻。

一个稳健的上传流程把「接收完成」与「文件可用」分成不同状态。新字节先进入 上传隔离区（upload quarantine） ；只有身份、大小、类型、内容和业务规则都通过后，数据库记录才变为 available。扫描超时或处理失败时，文件保持不可见，系统可以重试或清理，而不是把未知状态当作成功。

上传通常有两条数据路径。较小的表单文件可以经过应用服务器；大文件可以使用短期授权直接进入对象存储。两条路径必须共享同一套控制面：服务端创建上传意图、绑定所有者与限制、核对实际对象，然后决定是否发布。

工作原理

两种 multipart 不同义

multipart/form-data 是 HTTP 表单编码。请求头中的 boundary 把消息体分成多个 part，每个 part 通过 Content-Disposition 给出字段名，文件 part 通常还带有客户端文件名和 Content-Type。同一请求可以同时携带文本字段和一个或多个文件。

对象存储的 multipart upload 则把一个对象拆成可独立上传的分段，最后通过完成操作组装。它解决重试、并发传输和大对象恢复问题，不是 multipart/form-data 的另一种解析方式。设计接口时要写清楚指的是「表单 part」还是「对象 part」。

从意图到发布

控制面先认证调用者，检查资源级授权和配额，再创建 pending 上传记录。记录包含服务端生成的 对象键（object key） 、预期大小、允许类型、可选校验和、过期时间和所有者；原始文件名只作为经过长度限制的显示元数据保存。

数据面随后接收字节。应用服务器路径由 multipart 解析器产生文件流；直传路径由对象存储接收 PUT 或分段。两者都需要计算实际字节数并拒绝超限输入，不能只相信请求开始前声明的大小。

接收完成后，服务端从自己控制的临时文件或对象读取实际属性。它核对键、长度和校验和，执行类型识别以及该格式所需的解码或重写，并按风险策略扫描。只有这些步骤都成功，才把记录从 pending 改为 available。

状态转换应该由受信任的服务完成，而不是由客户端提交一个 status: "available"。对完成请求执行所有者检查，并以条件更新或事务保证只有预期的 pending 记录能发布。重复完成请求应返回已保存的结果或明确冲突，不能再次创建文件记录。

分层限制

最外层代理或网关应限制请求体大小和读取时间，应用解析器还要限制文件数量、字段数量、字段长度以及单个文件大小。存储层设置租户配额和生命周期规则，处理器则限制解压后大小、图像尺寸、页数或媒体时长。每一层保护的资源不同，不能用单个 Content-Length 检查替代。

Content-Length 可能缺失，也可能描述整个 multipart 消息而不是其中某个文件。即使声明值合规，实际读取仍要累计字节，并在超过限制时中止上游、关闭目标流、删除部分文件。对于压缩包，还要限制条目数、嵌套层级与解压后的总量。

名称、类型与内容

客户端文件名适合显示，不适合作为路径或对象键。服务端应生成不可预测且不复用的键，把所有者关系放在数据库或受保护的元数据中。下载时再通过安全的 Content-Disposition 生成显示名称，避免让原始名称参与路径解析。

客户端声明的 Content-Type 只能帮助快速拒绝明显误传。文件签名比扩展名更接近实际字节，但一个正确前缀仍不能证明整个文件结构有效或无害。业务允许 PNG 时，应让受维护的 PNG 解码器完整解析，并在需要时重编码；允许 PDF 或压缩包时，要使用针对该格式的验证与资源限制。

检测失败时应默认拒绝或保持隔离。把扫描服务不可用当作「干净」会把依赖故障变成安全绕过。具体产品可以选择同步拒绝、异步重试或人工审核，但状态和用户可见性必须明确。

流与背压

流式处理让应用不必把整个文件放进一个 Buffer。源流产生数据，计数与哈希转换流处理每个块，目标流写入隔离位置；pipeline() 负责传播错误并等待各段结束。内存使用仍取决于各级缓冲区和并发数，所以「使用流」不等于自动具备容量控制。

背压（backpressure） 让写入较慢时暂停读取。若代码监听 data 后把块放进无界数组，或忽略写入流返回的压力信号，就绕开了这条反馈链。并发上传数量也要单独限制，否则每条流的缓冲虽小，总内存和文件描述符仍可能耗尽。

直传对象存储

预签名 URL（presigned URL） 把有限时间内对特定方法和对象键的存储权限交给客户端。它减少应用服务器转发的字节，但没有把授权、配额、验证和发布责任交给存储服务。签发前仍要认证用户并生成只能写入隔离前缀的新键。

客户端报告「上传成功」后，应用不能直接相信它提交的大小、类型或校验和。完成端点应读取对象存储观察到的属性，并在策略要求时验证签名覆盖的校验和。预签名能力可能在过期前被重复使用；键复用还可能覆盖已有对象，因此对象键和状态转换都要防止重放。

示例

第一层字节检查

下面的纯 Node.js 示例把声明类型映射到预期签名，并同时执行空文件与大小检查。函数刻意把结果命名为 headerGate：通过这里只说明文件头与入口策略相符，不表示 PNG 已被完整解码或扫描。

两个样本都声称自己叫 avatar.png，而名称没有参与判定。第二个样本的字节不匹配 PNG 签名，因此在廉价入口检查处被拒绝。第一个样本仍然只是测试夹具；生产代码必须把它交给真正的 PNG 解码器后才能接受。

流式写入隔离区

下一个示例用 pipeline() 把两个输入块写入权限为 0600 的暂存文件。转换流同时累计实际大小和 SHA-256，超过 32 字节就报错；写入成功后才在同一目录内改名，失败路径会删除部分文件。

import { createHash } from 'node:crypto';
import { createWriteStream } from 'node:fs';
import { mkdir, rename, rm } from 'node:fs/promises';
import { Readable, Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';
class Meter extends Transform {
  constructor(limit) {
    super();
    this.limit = limit;
    this.bytes = 0;
    this.hash = createHash('sha256');
  }
  _transform(chunk, encoding, callback) {
    this.bytes += chunk.length;
    if (this.bytes > this.limit) return callback(new Error('upload too large'));
    this.hash.update(chunk);
    callback(null, chunk);
  }
}
async function store(source, root, objectId) {
  const staged = `${root}/${objectId}.part`;
  const finalPath = `${root}/${objectId}`;
  const meter = new Meter(32);
  try {
    await pipeline(source, meter, createWriteStream(staged, { flags: 'wx', mode: 0o600 }));
    await rename(staged, finalPath);
    return { finalPath, bytes: meter.bytes, sha256: meter.hash.digest('hex') };
  } catch (error) {
    await rm(staged, { force: true });
    throw error;
  }
}
const root = '/tmp/codewiki-upload-example';
await rm(root, { recursive: true, force: true });
await mkdir(root, { recursive: true });
const source = Readable.from([Buffer.from('order='), Buffer.from('CW-42\n')]);
const result = await store(source, root, 'upload-7f3a');
console.log(`stored=${result.finalPath} bytes=${result.bytes}`);
console.log(`sha256=${result.sha256}`);
await rm(root, { recursive: true, force: true });

stored=/tmp/codewiki-upload-example/upload-7f3a bytes=12
sha256=fe2c1abd0da3359bd47aa3d712d29f040a30252a8ce116879b035d47b639de47

示例中的固定目录和对象 ID 只为产生可复现输出。真实服务应为每次已授权上传生成新键，并把暂存目录放在不可公开访问的位置。rename() 只提交本地暂存文件；内容解析、恶意软件扫描和数据库发布仍是后续关卡。

核对直传结果

直传完成端点需要把创建上传意图时保存的约束，与存储层观察到的对象属性比较。下面的纯函数还检查调用者与状态；不匹配的对象进入 rejected，扫描未通过的对象保持 quarantined，只有全部符合才得到 available。

function finalizeUpload(record, observed, actorId) {
  if (record.ownerId !== actorId) throw new Error('forbidden');
  if (record.status !== 'pending') throw new Error('invalid upload state');

  const matches = observed.key === record.key
    && observed.size === record.expectedSize
    && observed.contentType === record.expectedType
    && observed.sha256 === record.expectedSha256;

  if (!matches) return { ...record, status: 'rejected' };
  if (observed.scanStatus !== 'clean') {
    return { ...record, status: 'quarantined' };
  }
  return { ...record, status: 'available' };
}

const pending = {
  id: 'up-42',
  ownerId: 'user-7',
  key: 'quarantine/user-7/up-42',
  expectedSize: 12,
  expectedType: 'image/png',
  expectedSha256: 'abc123',
  status: 'pending',
};
const uploaded = {
  key: 'quarantine/user-7/up-42',
  size: 12,
  contentType: 'image/png',
  sha256: 'abc123',
  scanStatus: 'clean',
};

console.log(finalizeUpload(pending, uploaded, 'user-7').status);
console.log(finalizeUpload(pending, { ...uploaded, size: 13 }, 'user-7').status);
console.log(finalizeUpload(pending, { ...uploaded, scanStatus: 'infected' }, 'user-7').status);

available
rejected
quarantined

纯函数展示的是发布判定，不是完整事务。真实实现应从可信存储 API 读取 observed，再用条件更新提交结果；扫描结论也应绑定同一对象版本或校验和，避免对象在扫描后被替换。

陷阱

修复方法： 先把扩展名和声明类型作为廉价筛选，再检查文件签名，并用受维护的格式解析器读取完整内容。对可重编码的图像生成新文件，不复用未经验证的原始字节；解析器失败、超时或超限都保持拒绝状态。

修复方法： 服务端生成与原名无关的新对象键，并通过数据库把它映射到所有者和显示名称。若必须解析路径，使用平台提供的规范化与 containment 检查；简单删除 ../ 不能覆盖绝对路径、分隔符变体和符号链接问题。

修复方法： 在代理、解析器、流式计数器、租户配额和处理器处分别设限，并保留端到端背压。测试缺失 Content-Length、读取中断、慢速接收方和多个并发上限附近的上传，确认失败时连接与部分文件都被释放。

修复方法： 使用 pending、quarantined、available、rejected 等显式状态，把下载和后续处理限制在 available。发布操作核对对象版本并条件更新记录；扫描服务故障按失败关闭，不自动把对象标为干净。

修复方法： 为上传会话定义所有者、到期时间、分段位置、校验和与允许的状态转换。相同分段重试要验证长度和摘要，完成操作要幂等；生命周期任务清理过期暂存文件和未完成的对象存储 multipart upload。

延伸阅读

• RFC 7578：multipart/form-data
• OWASP 文件上传安全清单
• Node.js 24 Stream 文档
• Amazon S3：使用预签名 URL 上传对象
• Amazon S3：multipart upload 概览