Tengine TFS 模块 RESTful API 完全指南:Raw TFS 与 Custom TFS 文件操作详解

原创2026-09-21 19:28:581,732 阅读
文章标签:后端网络负载均衡API网关云原生网络安全

Tengine TFS 模块 RESTful API 完全指南:Raw TFS 与 Custom TFS 文件操作详解

本文是 Tengine 仓库中 TFS(Taobao File System)模块 RESTful API 的完整技术指南,基于 TFS_RESTful_API.md 展开,并结合 ngx_http_tfs_restful.c 等源码逐条印证。通过阅读本文,你将掌握在 Tengine 上通过标准 HTTP 方法(POST/PUT/GET/DELETE/HEAD)读写 TFS 分布式文件系统的全部接口,包括 v1 Raw TFS 的文件写入、更新、读取、删除、元数据查询,以及 v2 Custom TFS 的目录与文件全生命周期管理,并了解这些接口在模块源码中的实现路径与参数校验规则,可直接据此开发应用或调试线上问题。

一、背景:TFS 模块与 RESTful API 的定位

TFS 是淘宝开源的分布式文件系统。Tengine 通过 ngx_http_tfs_module 实现了 TFS 的异步客户端,对外提供 RESTful API,使任意 HTTP 客户端都可以把 Tengine 当作 TFS 的接入层来存取文件。该模块的实现主体位于 modules/ngx_http_tfs_module,核心文件包括:

需要注意的是,该模块默认不随 Tengine 编译,需在 configure 时显式启用:

./configure --with-http_tfs_module

同时,TFS 模块依赖 RcServer(应用注册中心)与 MetaServer/RootServer 才能提供完整能力(详见后文 Custom TFS 部分的说明)。

二、通用约定:版本前缀、appkey 与固定/可变字段

整套 RESTful API 存在两条主线:

  • Raw TFS(v1 版本):面向传统 TFS 文件(文件名由 TFS 系统自动生成,如 T1FOZHB4ET1RCvBVdK),提供 WRITE / UPDATE / READ / DELETE / STAT 五种操作;
  • Custom TFS(v2 版本):面向带命名空间(appid + uid)和目录结构的用户自定义文件系统,提供目录与文件两类共 13 种操作。

所有请求都遵循如下约定(文档原文 NOTE):

粗体(bold)词汇为 API 固定保留字;斜体(italics)词汇为调用方输入参数。

即 URL 中的 v1、v2、metadata、dir、file、appid 等是固定字面量,而 appkey、TfsFileName、appid 数值、uid、dir_name、file_name 等由调用方提供。

2.1 appkey 的含义

appkey 是在 RcServer 数据库中注册的应用程序 ID。文档对 appkey 的说明在各 API 中保持一致:

appkey is an id of an application configured in RcServer database. If you are not using RcServer, use tfs as appkey.

翻译过来即:appkey 是配置在 RcServer 数据库中的应用标识;如果没有使用 RcServer,则统一使用固定值 tfs 作为 appkey。这也是本文所有示例请求都使用 /v1/tfs/... 或 /v2/tfs/... 的原因。

2.2 URL 版本解析在源码中的实现

从源码看,模块在 ngx_http_restful_parse_uri 中首先校验 URL 必须以 v 开头且版本号只能是 1 或 2,随后分别进入两套解析器:

  • 版本为 1:调用 ngx_http_restful_parse_raw() 解析 Raw TFS 路径;
  • 版本为 2:调用 ngx_http_restful_parse_custom_name() 解析 Custom TFS 路径。

由此可知,API 的版本前缀不只是文档惯例,而是模块请求入口的强约束——不符合 v1/v2 前缀格式的请求会直接返回 400。

三、Raw TFS(v1)API 详解

Raw TFS 是 TFS 最原始的使用方式:写入时由 TFS 集群返回一个系统生成的文件名,后续所有读取、更新、删除、查询操作都以该文件名为依据。文档为每个操作给出了语法、请求参数、响应、状态码与完整示例,以下逐一展开。

3.1 WRITE:写入文件

功能描述:WRITE 操作将数据以 TFS 文件形式存储,文件名以 JSON 格式返回。

语法:

POST /v1/<appkey> HTTP/1.1
Host: <10.0.0.1:7500>
Content-Length: <length>
Date: <date>

请求参数:

参数 说明
suffix 文件后缀
simple_name 是否要求使用正确后缀访问文件:1 表示必须带正确后缀才能访问;0 表示无此限制
large_file 是否保存为大文件(大文件文件名以 L 开头):1 保存为大文件;0 不作为大文件保存

响应字段:

名称 说明
TFS_FILE_NAME 返回的 TFS 文件名

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 请求错误
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例 1:无后缀写入(以 tfs 作为 appkey 写入一个无后缀文件):

POST /v1/tfs HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: 22
Date: Fri, 30 Nov 2012 03:05:00 GMT

[data]

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
	"TFS_FILE_NAME": "T1FOZHB4ET1RCvBVdK"
}

示例 2:带后缀写入(以 tfs 作为 appkey 写入一个后缀为 .jpg 的文件,并要求访问时必须带该后缀):

POST /v1/tfs?suffix=.jpg&simple_name=1 HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: 22
Date: Fri, 30 Nov 2012 03:05:00 GMT

[data]

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
	"TFS_FILE_NAME": "T1FOZHB4ET1RCvBVdK.jpg"
}

从源码看,v1 的 POST 请求在 ngx_http_restful_parse_action_raw 中被映射为 NGX_HTTP_TFS_ACTION_WRITE_FILE,并对 suffix、simple_name、large_file 三个参数逐一做长度必须为 1 且取值只能是 0/1 的校验;此外源码还额外支持 meta_segment(是否分段写元数据)与 no_dedup(是否关闭去重)两个隐藏参数,参数不合法同样返回 400。

3.2 UPDATE:更新文件

功能描述:UPDATE 操作更新一个已存在的 TFS 文件,更新后同样以 JSON 返回文件名。

语法:

PUT /v1/<appkey>/<TfsFileName> HTTP/1.1
Host: <10.0.0.1:7500>
Content-Length: <length>
Date: <date>

请求参数:

参数 说明
suffix 文件后缀
simple_name 是否要求使用正确后缀访问文件:1 必须带正确后缀;0 无限制

响应字段:

名称 说明
TFS_FILE_NAME 返回的 TFS 文件名

状态码:与 WRITE 一致(200 OK / 400 Bad Request / 500 Internal Server Error)。

示例:以 tfs 为 appkey 更新文件 T1FOZHB4ET1RCvBVdK:

PUT /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: 22
Date: Fri, 30 Nov 2012 03:05:00 GMT

[data]

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
	"TFS_FILE_NAME": "T1FOZHB4ET1RCvBVdK"
}

源码限制提示:虽然文档未在参数表中列出,但结合 ngx_http_restful_parse_action_raw 的实现可以看到,v1 的 PUT 更新路径有两个额外约束:

  • 请求中不允许携带 large_file 参数(大文件不支持原址更新,携带即返回 400);
  • 更新目标文件名解析后若属于大文件类型(NGX_HTTP_TFS_LARGE_FILE_TYPE)也会直接拒绝。

这些约束源于 TFS 底层对大文件(文件名以 L 开头)不支持就地覆盖写。

3.3 READ:读取文件

功能描述:READ 操作从 TFS 文件中读取数据。

语法:

GET /v1/<appkey>/<TfsFileName> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:

参数 说明
suffix 文件后缀。注意:若给出了该参数,而 TfsFileName 中带有另一个不同的后缀,则访问会失败
offset 文件内的读取偏移量
size 读取的数据大小

响应字段:

名称 说明
data 读取到的数据

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 请求错误
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例 1:读取无后缀文件:

GET /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Last-Modified: Thu, 29 Nov 2012 03:05:00 GMT
Transfer-Encoding: chunked
Connection: keep-alive

[data]

示例 2:读取带后缀文件:

GET /v1/tfs/T1FOZHB4ET1RCvBVdK.jpg HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应与示例 1 相同(200 OK,Last-Modified,chunked 传输数据)。

源码补充:v1 的 GET 读取在源码中支持 offset、size 两个参数(size 不能为 0),未显式给出 size 时默认按 NGX_HTTP_TFS_MAX_SIZE(定义为 ULLONG_MAX - 1,见 ngx_tfs_common.h)读取整个文件。文件名后缀不匹配时,底层文件名解析函数 ngx_http_tfs_raw_fsname_parse() 会返回错误并导致 400,这与文档中"后缀不一致则访问失败"的说明一致。

3.4 DELETE:删除或隐藏文件

功能描述:DELETE 操作删除(unlink)或隐藏(conceal)一个 TFS 文件。

语法:

DELETE /v1/<appkey>/<TfsFileName> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:

参数 说明
suffix 文件后缀。注意:若给出了该参数,而 TfsFileName 中带有另一个不同的后缀,则访问会失败
hide 指定隐藏操作:1 隐藏(conceal);0 解除隐藏(reveal)

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 请求错误
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例 1:删除文件:

DELETE /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Length: 0
Connection: keep-alive

示例 2:隐藏文件(hide=1 表示仅隐藏、不物理删除):

DELETE /v1/tfs/T1FOZHB4ET1RCvBVdK.jpg?hide=1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应(与删除相同,200 OK、Content-Length: 0):

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Length: 0
Connection: keep-alive

源码补充:v1 DELETE 在 ngx_http_restful_parse_action_raw 中支持两种参数风格:

  • 面向外部用户的 hide 参数:1 会被转换为 NGX_HTTP_TFS_UNLINK_CONCEAL(隐藏),0 转换为 NGX_HTTP_TFS_UNLINK_REVEAL(解除隐藏);
  • 面向内部/高级用户的 type 参数:可直接指定 del(0) / undel(2) / hide(4) / reveal(6) 四种操作。

另外源码规定:大文件不支持 UNDELETE(恢复删除)操作,若目标文件名是大文件类型且指定了 UNDELETE,返回 400。隐藏与删除的区别在于:隐藏后文件仍可通过 STAT(force 模式)或后续 reveal 操作恢复可见,而删除是真正的释放。

3.5 STAT:查询文件元数据

功能描述:STAT 操作获取一个 TFS 文件的元数据,结果以 JSON 格式返回。

语法:

GET /v1/<appkey>/metadata/<TfsFileName> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

注意这里的 metadata 是固定保留字,用于与普通的 READ(GET /v1/<appkey>/<TfsFileName>)区分。从 ngx_http_restful_parse_raw 可以看到,解析器在 appkey 之后如果遇到以 metadata 开头的路径段,就会置位 ctx->meta,后续动作分发时据此选择 NGX_HTTP_TFS_ACTION_STAT_FILE 而不是 READ。

请求参数:

参数 说明
suffix 文件后缀。注意:若给出了该参数,而 TfsFileName 中带有另一个不同的后缀,则访问会失败
type 获取类型:0 普通模式(normal),文件被删除或隐藏时操作失败;1 强制模式(force),即使文件被删除或隐藏也能成功

响应字段:

名称 说明
FILE_NAME 文件名
BLOCK_ID 包含该文件的块 ID
FILE_ID 文件 ID
OFFSET 文件在块内的偏移
SIZE 文件大小
OCCUPY_SIZE 文件占用大小
MODIFY_TIME 修改时间
CREATE_TIME 创建时间
STATUS 文件状态:0 正常;1 已删除;4 已隐藏;5 已隐藏且已删除
CRC 文件数据的 CRC 校验值

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 请求错误
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey 查询文件 T1FOZHB4ET1RCvBVdK 的元数据:

GET /v1/tfs/metadata/T1FOZHB4ET1RCvBVdK HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Fri, 30 Nov 2012 03:05:00 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
    "FILE_NAME": "T1FOZHB4ET1RCvBVdK",
    "BLOCK_ID": 101,
    "FILE_ID": 9223190836479524436,
    "OFFSET": 69563585,
    "SIZE": 103578,
    "OCCUPY_SIZE": 103614,
    "MODIFY_TIME": "Fri, 09 Mar 2012 13:40:32 UTC+0800",
    "CREATE_TIME": "Fri, 09 Mar 2012 13:40:32 UTC+0800",
    "STATUS": 0,
    "CRC": 3208008078
}

源码补充:v1 的 GET 与 HEAD 均可触发 STAT:GET 带 metadata 前缀时执行 STAT_FILE,HEAD 请求则统一执行 NGX_HTTP_TFS_ACTION_STAT_FILE 并置位 chk_exist(仅检查文件是否存在),这正是文档中"文件不存在返回 404"的实现路径。type 参数在源码中被限定为 NGX_HTTP_TFS_READ_STAT_NORMAL(0) 与 NGX_HTTP_TFS_READ_STAT_FORCE(1) 两种取值,非法取值返回 400。

四、Custom TFS(v2)API 详解

Custom TFS 在 TFS 之上引入了命名空间与目录树概念,适合需要按用户/应用组织文件、并支持目录级操作的场景。其路径格式为:

/v2/<appkey>/<appid>/<uid>/<dir|file>/<name>

4.1 前置概念:appid、uid 与命名空间

文档对三个关键标识的说明如下:

  • appkey:配置在 RcServer 数据库中的应用 ID;
  • appid:通过下述 GET_APPID 接口获取,每个应用可获取与其 appkey 唯一对应的 appid,这是 Custom TFS 每个操作的必填参数,可将其视为 TFS 中的一个命名空间(namespace);
  • uid:user id 的缩写,每个 appid 与 uid 组合构成 TFS 中的一个唯一命名空间。

同时文档强调:每个应用只允许修改自己 appid 下的命名空间,越权访问会返回 401 Unauthorized。

重要前提:Custom TFS 依赖 RcServer。在 ngx_http_tfs_module.c 的请求入口可以看到,当 tfs_upstream 未开启 RCS(enable_rcs 为否)而请求版本为 v2 时,模块会直接记录错误日志并返回 400:

"custom file requires tfs_enable_rcs on, and make sure you have MetaServer and RootServer!"

也就是说,使用 v2 API 必须保证:RcServer 已配置、模块已通过 rcs_zone / rcs_heartbeat 等指令接入 RcServer,并且集群中存在 MetaServer 与 RootServer。

4.2 GET_APPID:获取应用 appid

功能描述:获取指定 TFS 应用的 appid,以 JSON 格式返回。每个应用对应其 appkey 的唯一 appid,是后续所有 Custom TFS 操作的必填参数,可视为该应用在 TFS 中的命名空间。

语法:

GET /v2/<appkey>/appid HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应字段:

名称 说明
APP_ID 应用的 appid

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 请求错误
500 Internal Server Error 登录失败(可能该 appkey 未在 RcServer 数据库中配置)或 TFS/nginx 服务器内部错误

示例:查询 appkey tfs 的 appid:

GET /v2/tfs/appid HTTP/1.1
Host: 10.0.0.1:7500
Date: Thu, 28 Jun 2012 08:00:26 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Thu, 28 Jun 2012 08:00:26 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
    "APP_ID": "1"
}

源码补充:在 ngx_http_restful_parse_custom_name 中,解析器对 GET /v2/<appkey>/appid 这种特殊形态做了单独识别:当第二个路径段以字母 a 开头且 GET 方法下内容为 appid 时,置位 get_appid,随后在动作解析阶段映射为 NGX_HTTP_TFS_ACTION_GET_APPID。这也是 appid 既是接口名、又是后续路径中数字参数的原因——模块通过路径段的首字符(a 或 m)来区分三种形态。

4.3 目录操作

4.3.1 CREATE_DIR:创建目录

功能描述:创建一个目录。

语法:

POST /v2/<appkey>/<appid>/<uid>/dir/<dir_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:

参数 说明
recursive 1 递归创建父目录;0 不递归创建父目录

响应:无。

状态码:

HTTP 状态码 说明
201 Created 操作成功
400 Bad Request 目录名非法
401 Unauthorized 无权限(每个应用只允许修改自己 appid 下的命名空间)
403 Forbidden 子目录数/子文件数/目录深度超过限制
409 Conflict 目录已存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,在 appid 1、uid 1234 的命名空间下创建 /dir_1:

POST /v2/tfs/1/1234/dir/dir_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应:

HTTP/1.1 201 Created
Server: Tengine/1.3.0
Date: Wed, 27 Jun 2012 14:59:27 GMT
Content-Length: 0
Connection: keep-alive

源码补充:v2 POST 的动作解析见 ngx_http_restful_parse_action。创建类操作会额外校验 recursive 参数(只能为 0/1),并且禁止创建根目录(路径长度为 1 时返回 400)。需要留意:解析器校验 appid 与 uid 必须为大于 0 的数字(ngx_http_tfs_atoull 解析且不能为 0),非法时同样返回 400。

4.3.2 RM_DIR:删除目录

功能描述:移除一个目录。

语法:

DELETE /v2/<appkey>/<appid>/<uid>/dir/<dir_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 目录名非法
401 Unauthorized 无权限
403 Forbidden 目录非空
404 Not Found 目录或父目录不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,删除 appid 1、uid 1234 命名空间下的 /dir_1:

DELETE /v2/tfs/1/1234/dir/dir_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Thu, 28 Jun 2012 08:12:13 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Thu, 28 Jun 2012 08:12:13 GMT
Content-Length: 0
Connection: keep-alive

源码补充:删除目录时,源码同样禁止删除根目录(/)。目录非空(403)与目录/父目录不存在(404)等语义由 TFS 元数据服务器返回后透传。

4.3.3 MV_DIR:移动/重命名目录

功能描述:移动或重命名一个目录。源目录通过自定义 HTTP 请求头指定。

语法:

POST /v2/<appkey>/<appid>/<uid>/dir/<dest_dir_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>
x-ali-move-source: /<src_dir_name>

请求参数:

参数 说明
recursive 1 递归创建目标目录的父目录;0 不递归创建

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 目录名非法
401 Unauthorized 无权限
403 Forbidden 移动到了子目录
404 Not Found 源目录或父目录不存在,或目标目录已存在,或目标目录的父目录不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,在 appid 1、uid 1234 命名空间下将 /dir_src 重命名为 /dir_dest:

POST /v2/tfs/1/1234/dir/dir_dest HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:33:05 GMT
x-ali-move-source: /dir_src

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:33:05 GMT
Content-Length: 0
Connection: keep-alive

源码补充:x-ali-move-source 是模块固定的自定义请求头(定义见 ngx_http_tfs_restful.c)。POST 请求若携带该头,模块会判定为 MOVE 操作:源路径取自请求头、目标路径取自 URL,并进行源==目标即 400、源路径长度非法即 400 的校验,随后映射为 MOVE_DIR 或 MOVE_FILE。

4.3.4 LS_DIR:列出目录内容

功能描述:列出指定目录下的所有子目录与子文件,结果以 JSON 数组返回。

语法:

GET /v2/<appkey>/metadata/<appid>/<uid>/dir/<dir_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应字段(数组中的每个元素):

名称 说明
NAME 文件/目录名
PID 文件/目录的父目录 ID
ID 文件/目录的 ID
SIZE 文件大小
IS_FILE 是否为文件
CREATE_TIME 创建时间
MODIFY_TIME 修改时间
VER_NO 文件/目录的版本号

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 目录名非法
404 Not Found 目录或父目录不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,列出 appid 1、uid 1234 命名空间下根目录 / 的所有子目录与子文件:

GET /v2/tfs/metadata/1/1234/dir/ HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:42:25 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:42:25 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

[
    {
        "NAME": "d_0",
        "PID": 635213,
        "ID": 635218,
        "SIZE": 0,
        "IS_FILE": false,
        "CREATE_TIME": "Wed, 27 Jun 2012 10:32:04 UTC+0800",
        "MODIFY_TIME": "Wed, 27 Jun 2012 11:29:30 UTC+0800",
        "VER_NO": 0
    },
    {
        "NAME": "d_3",
        "PID": 635213,
        "ID": 635219,
        "SIZE": 0,
        "IS_FILE": false,
        "CREATE_TIME": "Wed, 27 Jun 2012 10:36:17 UTC+0800",
        "MODIFY_TIME": "Sat, 30 Jun 2012 13:32:53 UTC+0800",
        "VER_NO": 0
    },
    {
        "NAME": "file_1",
        "PID": -9223372036854140595,
        "ID": 0,
        "SIZE": 222,
        "IS_FILE": true,
        "CREATE_TIME": "Wed, 27 Jun 2012 17:13:23 UTC+0800",
        "MODIFY_TIME": "Wed, 27 Jun 2012 17:25:03 UTC+0800",
        "VER_NO": 1
    }
]

源码补充:从 ngx_http_restful_parse_custom_name 可以看到,URL 中 metadata 路径段会被解析为 ctx->meta 标记;随后 GET + dir 类型 + meta 标记组合为 NGX_HTTP_TFS_ACTION_LS_DIR。注意示例中目录 PID 可能为负数、IS_FILE 为布尔值,说明 TFS 内部对目录与文件采用了不同的 ID 空间编码,客户端解析 JSON 时应按字段类型而非硬编码假设处理。

4.3.5 IS_DIR_EXIST:判断目录是否存在

功能描述:检查指定目录是否存在。

语法:

HEAD /v2/<appkey>/<appid>/<uid>/dir/<dir_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应:无。

状态码:

HTTP 状态码 说明
200 OK 目录存在
400 Bad Request 目录名非法
404 Not Found 目录不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,检查 appid 1、uid 1234 命名空间下 /dir_1 是否存在:

HEAD /v2/tfs/1/1234/dir/dir_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:42:25 GMT

目录存在时响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:42:25 GMT
Content-Length: 0
Connection: keep-alive

源码补充:HEAD 请求在 ngx_http_restful_parse_action 中被统一映射为 LS 类动作并置位 chk_exist,即复用元数据查询流程但只关心是否存在——目录用 LS_DIR、文件用 LS_FILE 完成存在性检查,这与"HEAD 只返回状态码、不返回响应体"的语义相符。

4.4 文件操作

4.4.1 CREATE_FILE:创建文件

功能描述:创建一个文件(此时不写数据,只建立文件条目)。

语法:

POST /v2/<appkey>/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:

参数 说明
recursive 1 递归创建父目录;0 不递归创建父目录

响应:无。

状态码:

HTTP 状态码 说明
201 Created 操作成功
400 Bad Request 文件名非法
401 Unauthorized 无权限
403 Forbidden 子目录数/子文件数/目录深度超过限制
404 Not Found 父目录不存在
409 Conflict 文件已存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,在 appid 1、uid 1234 命名空间下创建 /file_1:

POST /v2/tfs/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Fri, 30 Nov 2012 03:05:00 GMT

对应响应:

HTTP/1.1 201 Created
Server: Tengine/1.3.0
Date: Wed, 27 Jun 2012 14:59:27 GMT
Content-Length: 0
Connection: keep-alive

源码补充:与 CREATE_DIR 相比,CREATE_FILE 的路径解析会额外执行一条校验——不允许对文件类型执行根路径操作(file 类型且路径长度为 1 时直接返回 400,见 ngx_http_restful_parse_custom_name),即文件必须位于某个目录之下。

4.4.2 WRITE_FILE:写入文件数据

功能描述:向文件写入数据。支持 PWRITE(按偏移写),支持文件空洞(file hole),默认采用追加(Append)模式。注意:不支持就地更新(in-place update)。

语法:

PUT /v2/<appkey>/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Content-Length: <length>
Date: <date>

请求参数:

参数 说明
offset 写入偏移量
size 要写入的数据大小

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 文件名或参数非法
401 Unauthorized 无权限
404 Not Found 文件不存在
409 Conflict 写入偏移处已存在数据(即就地更新)
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,向 appid 1、uid 1234 命名空间下的 /file_1 写入数据:

PUT /v2/tfs/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: 222
Date: Wed, 27 Jun 2012 14:59:27 GMT

[Data]

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Wed, 27 Jun 2012 14:59:27 GMT
Content-Length: 0
Connection: keep-alive

源码补充:v2 PUT 在 ngx_http_restful_parse_action 中只允许作用于 file 类型(对 dir 执行 PUT 返回错误)。未指定 offset 参数时,模块会将其设置为 NGX_HTTP_TFS_APPEND_OFFSET(值为 -1,见 ngx_tfs_common.h),即默认追加写;而"就地更新不被支持"在底层也有呼应:数据服务器消息处理中,v2 写操作若带非追加偏移会被拒绝(见 ngx_http_tfs_data_server_message.c 附近对 v2 偏移的判断逻辑),409 Conflict 即对应"偏移处已有数据"的冲突语义。该特性与 v1 WRITE 的随机写能力形成对比:v2 面向追加型日志/流水数据,v1 面向可覆盖的对象数据。

4.4.3 READ_FILE:读取文件数据

功能描述:从文件读取数据。

语法:

GET /v2/<appkey>/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:

参数 说明
offset 读取偏移量
size 要读取的数据大小

响应字段:

名称 说明
data 读取到的数据

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 文件名或参数非法
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,读取 appid 1、uid 1234 命名空间下 /file_1 的完整内容:

GET /v2/tfs/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Wed, 27 Jun 2012 14:59:27 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Wed, 27 Jun 2012 14:59:27 GMT
Content-Length: 222
Connection: keep-alive

[data]

源码补充:v2 GET 在 ngx_http_restful_parse_action 中,若请求头带 Range 会直接返回 400(v2 文件读取不支持 HTTP Range 分片);size 参数必须大于 0,未指定时默认读取整个文件。此外源码还支持一个文档未提及的参数 check_hole(取值 0/1),用于在读取时检查文件空洞。

4.4.4 RM_FILE:删除文件

功能描述:移除一个文件。

语法:

DELETE /v2/<appkey>/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 文件名非法
401 Unauthorized 无权限
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,移除 appid 1、uid 1234 命名空间下的 /file_1:

DELETE /v2/tfs/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Thu, 28 Jun 2012 08:12:13 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Thu, 28 Jun 2012 08:12:13 GMT
Content-Length: 0
Connection: keep-alive

源码补充:删除文件时,源码会预设 ctx->size = NGX_HTTP_TFS_MAX_SIZE(见 ngx_http_restful_parse_action),供底层 t->file.left_length 使用,这是删除文件时向数据服务器发送删除消息的内部约定。

4.4.5 MV_FILE:移动/重命名文件

功能描述:移动或重命名一个文件。源文件通过自定义请求头指定。

语法:

POST /v2/<appkey>/<appid>/<uid>/file/<dest_file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>
x-ali-move-source: /<src_file_name>

请求参数:

参数 说明
recursive 1 递归创建目标文件的父目录;0 不递归创建

响应:无。

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 文件名非法,或源文件与目标文件为同一文件
401 Unauthorized 无权限
404 Not Found 源文件不存在,或目标文件已存在,或目标文件的父目录不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,在 appid 1、uid 1234 命名空间下将 /file_src 重命名为 /file_dest:

POST /v2/tfs/1/1234/file/file_dest HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:33:05 GMT
x-ali-move-source: /file_src

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:33:05 GMT
Content-Length: 0
Connection: keep-alive

源码补充:MV_FILE 与 MV_DIR 共用同一套 POST + x-ali-move-source 分发逻辑(见 ngx_http_restful_parse_action),仅通过 file_type 区分动作码 MOVE_FILE / MOVE_DIR。校验规则包括:源路径长度必须在 1~256 之间、目标路径不能是根路径、源与目标不能完全相同。

4.4.6 LS_FILE:查询文件元数据

功能描述:获取文件的元数据。

语法:

GET /v2/<appkey>/metadata/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应字段:

名称 说明
NAME 文件名(绝对路径)
PID 文件父目录的 ID
ID 文件的 ID
SIZE 文件大小
IS_FILE 是否为文件
CREATE_TIME 创建时间
MODIFY_TIME 修改时间
VER_NO 文件的版本号

状态码:

HTTP 状态码 说明
200 OK 操作成功
400 Bad Request 文件名非法
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,查询 appid 1、uid 1234 命名空间下 /file_1 的元数据:

GET /v2/tfs/metadata/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:42:25 GMT

对应响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:42:25 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{
    "NAME": "/file_1",
    "PID": 635213,
    "ID": 0,
    "SIZE": 298481,
    "IS_FILE": true,
    "CREATE_TIME": "Fri, 15 Jun 2012 09:37:39 UTC+0800",
    "MODIFY_TIME": "Sat, 30 Jun 2012 23:57:38 UTC+0800",
    "VER_NO": 0
}

与 v1 的 STAT 相比,v2 的 LS_FILE 返回的元数据面向目录树结构(NAME 为绝对路径、PID 为父目录 ID、含 VER_NO 版本号),而 v1 STAT 返回的是块存储维度的元数据(BLOCK_ID、OFFSET、OCCUPY_SIZE、CRC、STATUS),两者服务的数据模型不同。

4.4.7 IS_FILE_EXIST:判断文件是否存在

功能描述:检查文件是否存在。

语法:

HEAD /v2/<appkey>/<appid>/<uid>/file/<file_name> HTTP/1.1
Host: <10.0.0.1:7500>
Date: <date>

请求参数:无。

响应:无。

状态码:

HTTP 状态码 说明
200 OK 文件存在
400 Bad Request 文件名非法
404 Not Found 文件不存在
500 Internal Server Error TFS 或 nginx 服务器内部错误

示例:以 tfs 为 appkey,检查 appid 1、uid 1234 命名空间下 /file_1 是否存在:

HEAD /v2/tfs/1/1234/file/file_1 HTTP/1.1
Host: 10.0.0.1:7500
Date: Sat, 30 Jun 2012 05:42:25 GMT

文件存在时响应:

HTTP/1.1 200 OK
Server: Tengine/1.3.0
Date: Sat, 30 Jun 2012 05:42:25 GMT
Content-Length: 0
Connection: keep-alive

五、从源码看 API 的整体处理链路

综合 ngx_http_tfs_restful.c 的实现,一次 RESTful 请求在模块内部经过如下链路:

  1. URI 版本解析:ngx_http_restful_parse_uri() 校验 URL 以 v 开头,版本号仅接受 1/2;
  2. 路径解析:v1 走 ngx_http_restful_parse_raw()(提取 appkey、可选 metadata 标记、文件名);v2 走 ngx_http_restful_parse_custom_name()(提取 appkey、appid、uid、file/dir 类型、路径名,并识别 GET /v2/<appkey>/appid 的特殊形态);
  3. 动作分发:v1 走 ngx_http_restful_parse_action_raw()、v2 走 ngx_http_restful_parse_action(),根据 HTTP 方法与路径形态确定 ctx->action.code(如 WRITE_FILE、STAT_FILE、CREATE_DIR、MOVE_FILE 等)并校验各查询参数;
  4. 入口执行:ngx_http_tfs_module.c 中的 ngx_http_tfs_handler() 调用 ngx_http_restful_parse(),随后按动作码分发到 TFS 异步处理流程,与 NameServer、数据服务器(v1)或 RcServer、MetaServer、RootServer(v2)交互。

关键常量定义在 ngx_tfs_common.h:

  • NGX_HTTP_TFS_MAX_FILE_NAME_LEN = 256:文件名/路径最大长度,超长请求返回 400;
  • NGX_HTTP_TFS_MAX_SIZE = ULLONG_MAX - 1:未指定 size 时读取/删除的默认长度;
  • NGX_HTTP_TFS_APPEND_OFFSET = -1:v2 写操作未指定 offset 时的追加写标记。

文档中所有"参数非法返回 400"、"后缀不匹配访问失败"等描述,都能在这套解析与校验逻辑中找到对应实现,这也意味着 API 行为与源码是严格一致的,可作为开发与排障的双重依据。

六、部署配置:让 RESTful API 跑起来

RESTful API 依赖 ngx_http_tfs_module 正常工作,其配置方法记录在 ngx_http_tfs_module.md。模块提供以下指令:

指令 上下文 说明
tfs_upstream name {...} http 定义上游 TFS 服务器组
server address tfs_upstream 上游 TFS 服务器地址(域名或 IP),如 server 10.0.0.1:8108;
type [ns | rcs] tfs_upstream 上游类型:ns(NameServer,默认)或 rcs(RcServer)
rcs_zone name=n size=num tfs_upstream 用于缓存 RcServer 应用配置的共享内存区,type 为 rcs 时必填,如 rcs_zone name=tfs1 size=128M;
rcs_heartbeat lock_file=... interval=... tfs_upstream 与 RcServer 的心跳配置,用于更新应用配置
rcs_interface eth0 tfs_upstream RCS 对外网卡接口
tfs_pass tfs://name location 将 location 的请求转发给 TFS upstream
tfs_keepalive max_cached=n bucket_count=n http/server 连接池配置
tfs_log ... http/server 自定义访问日志
tfs_connect_timeout / tfs_send_timeout / tfs_read_timeout http/server/location 与 TFS 交互的超时时间(毫秒)
tfs_buffer_size / tfs_body_buffer_size http/server/location 缓冲区大小
tfs_block_cache_zone / tfs_enable_remote_block_cache http 块缓存配置(本地/远端,远端依赖 Tair)

一个完整的配置示例(摘自 ngx_http_tfs_module.md):

http {
    #tfs_upstream tfs_rc {
    #    server 127.0.0.1:6100;
    #    type rcs;
    #    rcs_zone name=tfs1 size=128M;
    #    rcs_interface eth0;
    #    rcs_heartbeat lock_file=/logs/lk.file interval=10s;
    #}

    tfs_upstream tfs_ns {
        server 127.0.0.1:8108;
        type ns;
    }

    server {
          listen       7500;
          server_name  localhost;

          tfs_keepalive max_cached=100 bucket_count=10;
          tfs_log "pipe:/usr/sbin/cronolog -p 30min /path/to/nginx/logs/cronolog/%Y/%m/%Y-%m-%d-%H-%M-tfs_access.log";

          location / {
              tfs_pass tfs://tfs_ns;
          }
    }
}

部署要点:

  • v1(Raw TFS):最小配置只需 NameServer(type ns),即可对外提供 /v1/tfs/... 全部接口;
  • v2(Custom TFS):必须使用 RcServer(type rcs,并配置 rcs_zone、rcs_heartbeat、rcs_interface),同时集群需要部署 MetaServer 与 RootServer;否则 v2 请求会被模块直接以 400 拒绝(日志提示 "custom file requires tfs_enable_rcs on");
  • 配置完成后,用 nginx -t 校验语法,然后按上文各接口的语法格式发起 HTTP 请求即可。

七、实战建议与注意事项

基于文档语义与源码行为,给出以下使用建议:

  1. 文件名长度:Raw TFS 与 Custom TFS 的文件名/路径最长 256 字节,超长请求会返回 400,生成文件名的业务方应做截断或校验。
  2. 后缀一致性:v1 READ / DELETE / STAT 中若 URL 路径与 suffix 参数不一致,访问会失败(400)。带后缀访问是最常见的使用方式,写入时应通过 suffix=.jpg&simple_name=1 明确后缀与访问约束。
  3. 隐藏 vs 删除:v1 DELETE 不带参数是物理删除;hide=1 是隐藏(可通过 STAT force 模式或后续 reveal 恢复)。需要"软删除"能力的业务应优先使用隐藏。
  4. v2 写入模型:WRITE_FILE 默认追加写、不支持就地更新(偏移处已有数据返回 409)。适合日志、流水、只追加对象等场景;需要覆盖写的数据建议走 v1 WRITE。
  5. 命名空间隔离:v2 以 appid + uid 组合隔离命名空间,越权修改其他命名空间返回 401。应用侧应在 uid 维度做好数据隔离设计。
  6. HEAD 用于存在性探测:IS_DIR_EXIST / IS_FILE_EXIST 使用 HEAD,只返回 200/404,无响应体,是低成本探测接口。
  7. 错误码语义:v1 与 v2 的状态码语义略有差异——v1 WRITE/UPDATE 失败只区分 400/500(没有 404/409),而 v2 文件操作细化了 404(文件/父目录不存在)、409(已存在或偏移冲突)、403(数量/深度超限、目录非空)等语义,客户端应按版本分别处理错误。

以上内容完整覆盖了 TFS_RESTful_API.md 中 Raw TFS 与 Custom TFS 的全部 18 个接口(v1 的 WRITE / UPDATE / READ / DELETE / STAT,v2 的 GET_APPID 与目录、文件两大类操作),并补充了来自 ngx_http_tfs_restful.c、ngx_http_tfs_module.c、ngx_tfs_common.h 与 ngx_http_tfs_module.md 的源码级细节,可作为基于 Tengine 接入 TFS 的接口手册与排障参考。

登录后查看全文
tengine