如何在 tus.io 上传流程中实现串行化处理以避免并发冲突-js教程-PHP中文网

本文介绍在使用 tus.io 协议时，如何解决 onUploadCreate 回调并发执行导致的状态竞争问题；核心方案是剥离服务端串行控制逻辑，将上传准备步骤（如元数据校验、用户鉴权、数据库预创建）前置到上游服务或前端，使 tus 服务回归无状态、高并发的纯文件传输职责。

本文介绍在使用 tus.io 协议时，如何解决 `onuploadcreate` 回调并发执行导致的状态竞争问题；核心方案是剥离服务端串行控制逻辑，将上传准备步骤（如元数据校验、用户鉴权、数据库预创建）前置到上游服务或前端，使 tus 服务回归无状态、高并发的纯文件传输职责。

在基于 tus.io 构建的分片/断点续传上传系统中，onUploadCreate 是一个关键生命周期钩子——它在每次上传初始化时被触发。虽然该函数本身声明为 async，但 tus-node-server 并不会等待其 Promise 完成后再触发下一个上传的回调。换言之：多个文件同时发起上传请求时，多个 onUploadCreate 实例会并行执行，即使内部已正确 await 所有异步操作（如 Axios 请求、MongoDB 查询），也无法保证逻辑按“单文件—全流程—再下一文件”的顺序执行。

你观察到的日志交错现象（如连续两条 Metadata is ok! 后才出现用户鉴权日志）正是典型并发表现：Node.js 事件循环调度了多个异步任务，它们共享同一套数据库连接与业务逻辑上下文，但彼此不感知、不协调。

❌ 常见误区：试图在 onUploadCreate 内强制串行化

许多开发者尝试用以下方式“加锁”：

// ❌ 不推荐：全局队列易成为性能瓶颈且难以容错
let uploadQueue = Promise.resolve();

async onUploadCreate(req, res, upload) {
  uploadQueue = uploadQueue.then(() => this.processUpload(upload));
  return uploadQueue;
}

这种方式虽能实现串行，但存在严重缺陷：

所有上传被强制排队，丧失 tus 的高并发优势；
单一失败（如网络超时）会导致后续所有上传阻塞；
无法水平扩展（集群部署下队列失效）；
违反 tus 设计哲学——它本应专注传输，而非业务编排。

✅ 推荐方案：职责分离 + 上游预处理

根本解法是将状态管理与业务校验完全移出 tus 服务层，让 tus 仅承担“接收上传 ID → 分配存储位置 → 流式写入”的无状态职能。具体实施路径如下：

1. 前端或 API 网关完成三步预检

在发起 tus POST /files 请求前，客户端（或 BFF 层）需同步完成：

✅ 校验 Upload-Metadata 结构与语义（如 uploadId, userSession, fileName）；
✅ 调用鉴权服务验证 userSession 有效性（返回 userId, permissions）；

✅ 调用业务服务创建初始记录：

// 示例：上游服务创建 dataset & datafile，并返回 uploadId 和关联 ID
const { uploadId, datasetId, datafileId } = await api.createUploadSession({
  metadata: { userSession: 'xxx', fileName: 'report.pdf' },
});

2. tus 服务配置为纯转发模式

此时 onUploadCreate 只需做轻量级校验与透传：

async onUploadCreate(req, res, upload) {
  const { uploadId, datasetId, datafileId } = upload.metadata;

  // 快速校验 uploadId 是否由上游签发（如 JWT 解析或 Redis 存在性检查）
  if (!await redis.exists(`valid-upload:${uploadId}`)) {
    throw { status_code: 400, body: 'Invalid upload session' };
  }

  // 关联上游生成的业务 ID 到 tus 元数据（供后续 hooks 使用）
  upload.metadata.datasetId = datasetId;
  upload.metadata.datafileId = datafileId;

  logger.info(`Upload ${uploadId} accepted for dataset ${datasetId}`);
  return res;
}

3. 后续钩子复用预置 ID（可选）

例如在 onUploadFinish 中直接更新数据文件状态，无需再次查库：

async onUploadFinish(req, res, upload) {
  await catalogue.updateDatafileStatus(
    upload.metadata.datafileId,
    'uploaded',
    upload.size
  );
}