本文介绍在使用 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
);
}⚠️ 注意事项与最佳实践
- 幂等性设计：上游服务创建 uploadSession 接口必须幂等（相同 uploadId 多次调用返回相同结果），防止重复提交引发脏数据；
- 过期机制：为 uploadId 设置 TTL（如 24 小时），避免长期占用资源；
- 错误回滚：若 tus 上传中途失败，上游服务应提供 abortUploadSession(uploadId) 接口清理临时数据；
- 监控告警：对上游预处理耗时、tus 接收成功率、元数据校验失败率等指标埋点，及时发现链路瓶颈。
通过此架构，你既规避了服务端串行化陷阱，又保障了业务一致性——所有状态决策发生在可控、可测试、可扩展的上游服务中，而 tus 作为基础设施专注做好一件事：可靠、高效、标准的文件传输。
