以 Tus 上传固件文件#

验证状态：已源码核验、未联调；适用基线：源码归纳 @ 2026-09-14

用途与 App 场景#

把 .bin 或 .img 固件写入临时 Tus 存储，取得后续固件保存/更新要提交的上传 URL。本页是 http-tus-firmware-upload 的唯一正本；上传完成不等于固件元数据已保存，更不等于设备已升级。

Web 使用位置#

协议身份#

前置条件与权限#

需要有效登录态。浏览器先把文件名转小写检查 .img/.bin，但这只是交互预检；固件保存/更新入口会再次检查服务端记录的文件名扩展名。Controller 调用不带 ownerKey 的 process(request,response)，因此 Tus 存储层没有按用户/租户隔离；任何已认证调用方若获知上传 URL，均可能查询、续传、下载或终止它。认证与空间见认证与空间。

输入#

输出、应答或事件#

完成判据#

客户端 onSuccess 只表示上传字节达到总长并取得 upload.url。原始固件表单还在浏览器计算整文件 MD5；必须等 MD5 就绪后再调用固件保存。最终持久化由创建固件包或创建 SpiritCam 固件完成。

示例#

按当前 Web 构造的创建请求头（JSON 仅用于表达 header 值）：

1{
2  "Tus-Resumable": "1.0.0",
3  "Upload-Length": "4096",
4  "Upload-Metadata": "filename ZmlybXdhcmUuYmlu,filetype YXBwbGljYXRpb24vb2N0ZXQtc3RyZWFt",
5  "Authorization": "Bearer <token>"
6}

按协议构造的创建成功响应头：

1{
2  "Location": "/main-service/system-api/upload/upload-01",
3  "Tus-Resumable": "1.0.0"
4}

按协议构造的续传状态响应头：

1{
2  "Upload-Offset": "4096",
3  "Upload-Length": "4096",
4  "Tus-Resumable": "1.0.0"
5}

错误与边界#

Tus 错误是 HTTP/协议响应，不保证 ApiResult JSON：资源 URL 不存在时 HEAD/PATCH/GET/DELETE 为 404；未完成上传的 GET 为 422；PATCH 偏移不匹配为 409、Content-Type 错误为 415；超限为 413。参见HTTP 约定。

Web 重试间隔为 0、3、5、10、20 秒，tus-js-client 会先按资源偏移恢复；不要用新的 POST 盲目重试，否则可能产生孤立上传。PATCH 只有在服务端确认的 offset 上才可续传。DELETE 第一次成功为 204，再次调用同一 URL 为 404；若调用方把 204/404 都解释为“临时资源已不存在”，资源状态层面可安全收敛。GET 遇到 422 应先完成上传，不应原样重试。

服务没有调用 withMaxUploadSize，1.0.0-3.0 磁盘实现因而以 Long.MAX_VALUE 为内部上限；但本票核验的部署 Nginx 对每个 /main-service 请求限制 10G、读取超时 300 秒。当前客户端不分块，所以该部署的单文件实际入口上限是 10G；开发 Vite 代理超时为 90 秒。其他部署必须重新核验。

调用关系与资源清理#

服务使用 tus-storage-path 保存临时上传，启用磁盘存储、线程本地缓存和临时下载扩展。定时任务每天调用 cleanup()，但应用没有设置上传过期周期，因此不能把它理解为“所有遗留上传一天后删除”。固件保存成功会复制文件并调用 deleteUpload 删除临时项。不要把临时 Location 当长期下载地址。

已知缺口#

已闭合锁定依赖实现、协议响应和当前部署的 10G/300 秒限制；磁盘配额、其他部署代理限制及无 owner 隔离风险尚未联调。接入方上线前必须验证容量与访问隔离。

验证状态与依据#