Tengine TFS 模块 RESTful API 完全指南:Raw TFS 与 Custom TFS 文件操作详解
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,核心文件包括:
- ngx_http_tfs_restful.c:RESTful 请求的 URI 解析与动作分发(本文讲解的 API 语义均由此文件落地);
- ngx_http_tfs_module.c:模块配置指令与请求入口 handler;
- ngx_http_tfs.c:与 TFS 数据服务器、元数据服务器交互的主流程;
- ngx_http_tfs_module.md:模块的安装与配置说明。
需要注意的是,该模块默认不随 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 请求在模块内部经过如下链路:
- URI 版本解析:
ngx_http_restful_parse_uri()校验 URL 以v开头,版本号仅接受1/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的特殊形态); - 动作分发: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等)并校验各查询参数; - 入口执行: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 请求即可。
七、实战建议与注意事项
基于文档语义与源码行为,给出以下使用建议:
- 文件名长度:Raw TFS 与 Custom TFS 的文件名/路径最长 256 字节,超长请求会返回 400,生成文件名的业务方应做截断或校验。
- 后缀一致性:v1 READ / DELETE / STAT 中若 URL 路径与
suffix参数不一致,访问会失败(400)。带后缀访问是最常见的使用方式,写入时应通过suffix=.jpg&simple_name=1明确后缀与访问约束。 - 隐藏 vs 删除:v1 DELETE 不带参数是物理删除;
hide=1是隐藏(可通过 STAT force 模式或后续 reveal 恢复)。需要"软删除"能力的业务应优先使用隐藏。 - v2 写入模型:WRITE_FILE 默认追加写、不支持就地更新(偏移处已有数据返回 409)。适合日志、流水、只追加对象等场景;需要覆盖写的数据建议走 v1 WRITE。
- 命名空间隔离:v2 以 appid + uid 组合隔离命名空间,越权修改其他命名空间返回 401。应用侧应在 uid 维度做好数据隔离设计。
- HEAD 用于存在性探测:IS_DIR_EXIST / IS_FILE_EXIST 使用 HEAD,只返回 200/404,无响应体,是低成本探测接口。
- 错误码语义: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 的接口手册与排障参考。