【翻译】tus----一个可续传文件上传的开放协议

最新推荐文章于 2025-07-24 16:32:34 发布

weixin_30701521

最新推荐文章于 2025-07-24 16:32:34 发布

阅读量1.8k

点赞数

CC 4.0 BY-SA版权

文章标签： javascript 前端 python ViewUI

原文链接：http://www.cnblogs.com/pangjianxin/p/11175355.html

tus是一个开放的文件上传协议，支持续传功能，适用于Http。本文主要介绍了tus协议的核心概念，包括状态、贡献、摘要、提示和核心协议。内容包括HEAD和PATCH请求、相关头部信息如Upload-Offset和Upload-Length等，还提到了扩展如Creation、Expiration和Checksum。tus协议允许客户端和服务器实现断点续传，确保文件上传的可靠性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

tus

tus是一个可续穿文件上传协议，它以Http协议为载体，统一了一个文件断点续传的标准。

这篇文章翻译自https://tus.io/

目前该协议版本信息如下：

Version: 1.0.0 (SemVer)
Date: 2016-03-25
Authors: Felix Geisendörfer, Kevin van Zonneveld, Tim Koschützki, Naren Venkataraman, Marius Kleidl
Collaborators: Bruno de Carvalho, James Butler, Øystein Steimler, Sam Rijs, Khang Toh, Jacques Boscq, Jérémy FRERE, Pieter Hintjens, Stephan Seidt, Aran Wilkinson, Svein Ove Aas, Oliver Anan, Tim, j4james, Julian Reschke, Evert Pot, Jochen Kupperschmidt, Andrew Fenn, Kevin Swiber, Jan Kohlhof, eno, Luke Arduini, Jim Schmid, Jeffrey ‘jf’ Lim, Daniel Lopretto, Mark Murphy, Peter Darrow, Gargaj, Tomasz Rydzyński, Tino de Bruijn, Jonas mg, Christian Ulbrich, Jon Gjengset, Michael Elovskikh, Rick Olson, J. Ryan Stinnett, Ifedapo Olarewaju Robert Nagy

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

第一部分：状态

在SemVer（https://semver.org/）之后，从1.0.0开始，tus就可以被广泛采用了。我们不期望做出破坏性的更改，但是如果我们这样做了，这些更改就必须在2.0.0中。引入一个新的扩展或任何向后兼容的更改，添加新的功能，都会导致一个意外的次要版本。

NOTES：SemVer就是Semantic Versioning 2.0.0是一个语义版本控制，Tus协议采用了这个协议，我也不知道这个协议到底他妈的是干啥的。可能是描述注入MUST、SHOULD、MAY等等这些词的语气的吧。比如MUST这个词你可能会在脑海中闪现出一副老板训人的那种语气，要求你必须完成某项工作的表情之类的吧。困惑中。

第二部分：贡献

这个协议由Tus社区创建，并归属于Tus社区，欢迎通过Github来提交协议的补丁和反馈意见，所有的作者和贡献者的名字都会在协议的开头列出。

如果你有开源的或者商业的任何关于该协议的实现想要列在我们的官方网站上（implementations），请一定让我们知道（let us know）。

第三部分：摘要

协议通过 HTTP/1.1 (RFC 7230) 和 HTTP/2 (RFC 7540)提供了支持文件断点恢复上传的机制和原理。

第四部分：提示

被方括号包起来的字符表示一个占位符（例如[size])。

术语空格、逗号和分号指的是它们的ASCII表示形式。

第五部分：核心协议

核心协议描述了如何恢复一个中断了的上传操作。它假设你已经有了一个上传的URL，这个URl通常是由Creation扩展来创建的。（Creation扩展会在下面介绍）

客户端协议和服务端协议必须（MUST)实现核心协议。

这个规范没有描述url的结构，因为这是留给特定实现来决定的。本文档中显示的所有url仅用于示例目的。

另外，认证和授权的部分也由服务端实现来决定。

例子

HEAD请求用于确定应该继续上传的偏移量。

下面的例子展示了100字节的内容在上传了70之后被中断然后续传的情形

请求:

HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Tus-Resumable: 1.0.0

响应:

HTTP/1.1 200 OK
Upload-Offset: 70
Tus-Resumable: 1.0.0

给定偏移量，客户端使用PATCH Method恢复上传:

请求:

PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1
Host: tus.example.org
Content-Type: application/offset+octet-stream
Content-Length: 30
Upload-Offset: 70
Tus-Resumable: 1.0.0

[remaining 30 bytes]

响应:

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 100

头部

Upload-Offset

通用头，可以用在请求和响应中，它必须（MUST）是一个非负的整数。它指示上传资源中的字节偏移量。

Upload-Length

通用头，可以用在请求或响应中，它必须（MUST）是一个非负整数，它指示所要上传的资源的大小。

Tus-Version

响应头，它必须是一个服务端支持的以逗号分隔的协议版本列表。这个列表必须（MUST）按照服务端推荐程序排序，其中，列表中所列出的第一项是最为推荐的协议版本。

Tus-Resumable

通用头，这个头是除了OPTION Method请求之外必须包含在每一个请求和响应中的头。它的值必须（MUST）是客户端和服务端都使用的一个版本号。

如果客户端中指定的版本号不被服务端支持，服务端必须（MUST）返回412 Precondition Failed状态码并且必须（MUST）包含Tus-Resumable头。此外，服务端必须不能（MUST NOT）处理请求。

Tus-Extension

响应头，这个头必须（MUST）是一个服务端支持的逗号分隔的可扩展功能的列表，如果服务端没有任何扩展功能支持，那么这个头必须（MUST）省略。

Tus-Max-Size

响应头，它必须是一个非负整数，以字节为单位指示整个上载的最大允许大小。如果存在已知的硬性限制，服务器应该（SHOULD）设置此头。

X-HTTP-Method-Override

请求头,如果该请求头出现了，它必须(MUST)是一个字符串，服务器必须(MUST)将其解释为请求的方法。而真正的请求方法必须被忽略。当客户端环境不允许使用PATCH 或 DELETE 等方法时，客户端应该（SHOULD）使用这个头。

请求

HEAD请求

对于HEAD请求，服务端相应必须（MUST）包含Upload-Offset头，甚至当Upload-Offset是0或者上传过程已结束的情况下也应该包含。在上传大小已知的情况下，服务端响应必须（MUST）包含Upload-Length头。如果资源未发现（意味着Upload-Offset无效），服务端响应应该（SHOULD）返回404 Not Found