Tengine TFS 模块(ngx_http_tfs_module)实战指南:基于 RESTful API 接入淘宝分布式文件系统
Tengine TFS 模块(ngx_http_tfs_module)实战指南:基于 RESTful API 接入淘宝分布式文件系统
TFS(Taobao File System)是淘宝内部大规模使用的分布式文件系统,本指南讲解 Tengine 中 ngx_http_tfs_module 模块的完整使用方法:它是一个基于 Nginx 事件驱动模型实现的 TFS 异步客户端,对外提供 RESTful API,可将 Tengine 无缝变身为 TFS 的文件读写网关。读完本文,你将掌握该模块的编译启用、tfs_upstream/tfs_pass 等全部指令的配置方法、RcServer/NameServer 两种上游模式的选型,以及 Raw TFS 与 Custom TFS 两套 RESTful 接口的实际调用方式。
模块简介与定位
ngx_http_tfs_module 是 Tengine 中与淘宝 TFS 深度集成的一个 HTTP 模块,其核心定位是:
- 异步 TFS 客户端:所有与 TFS 服务器(NameServer / RcServer / DataServer)之间的网络交互都基于 Nginx 的事件驱动机制,不阻塞 worker 进程,与 Nginx 全异步模型保持一致;
- RESTful 网关:模块内部完成 URI 解析、动作映射、TFS 协议编解码,对上层业务只暴露标准的 HTTP 接口(GET/POST/PUT/DELETE);
- 原生 Tengine 模块:模块在 modules/ngx_http_tfs_module 目录下完整实现,官方文档位于 docs/modules/ngx_http_tfs_module.md,配套的接口协议文档为 docs/modules/TFS_RESTful_API.md。
从 模块入口实现 可以看到,每个请求到达后先分配 ngx_http_tfs_t 请求上下文,通过 ngx_http_restful_parse() 解析 RESTful URI,再按动作分发到 ngx_http_tfs_read_body_handler() 进行后续异步处理,整体架构与标准 upstream 模块类似但完全独立实现。
编译启用与依赖
该模块默认不参与编译,需要在 configure 阶段显式开启:
./configure --with-http_tfs_module
make && make install
需要注意一个硬性依赖:从 模块编译配置 可以看到,编译时强依赖 libyajl(Yet Another JSON Library),configure 会依次在系统默认路径、/usr/local/、/usr/pkg/ 等位置自动探测,也可通过 LIBYAJL_INC 和 LIBYAJL_LIB 环境变量显式指定头文件与库路径;如果找不到 libyajl,configure 会直接报错退出:
./configure --with-http_tfs_module LIBYAJL_INC=/opt/yajl/include LIBYAJL_LIB=/opt/yajl/lib
libyajl 之所以必需,是因为模块在 ngx_http_tfs_json.c 中依赖它完成 TFS 元数据与 RESTful 响应的 JSON 编解码。
启用后,模块会把 ngx_http_tfs_module 注入 HTTP 模块链,并将 ngx_http_tfs.c、ngx_http_tfs_restful.c、ngx_http_connection_pool.c、ngx_http_tfs_block_cache.c、ngx_http_tfs_timers.c 等约 20 个源文件一并编译进去。
最小可用配置示例
以下配置来自官方文档,它同时示范了两种上游模式:RcServer 模式(注释部分)与 NameServer 模式(启用部分):
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;
}
}
}
配置要点:
tfs_upstream在http块内定义 TFS 上游;tfs_pass在location中绑定 URI 前缀,协议前缀必须是tfs://(见下文);- 端口
7500只是示例监听端口,RESTful 请求通过该端口进入; tfs_log使用 cronolog 按 30 分钟切割访问日志,示例中的%Y/%m/%Y-%m-%d-%H-%M是 cronolog 的时间格式占位符。
指令详解
tfs_upstream
语法:tfs_upstream name {...} 默认值:无 上下文:http
定义一组 TFS 上游服务器信息,块内可包含 server、type、rcs_zone、rcs_heartbeat、rcs_interface 等子指令。从源码看,tfs_upstream 指令处理函数(ngx_http_tfs_upstream)会把 name 注册进模块的主配置 upstreams 数组,并在块解析结束后做合法性校验:若类型为 rcs,则 必须 同时配置 rcs_interface、rcs_heartbeat、rcs_zone 三个子指令,否则启动报错。
server
语法:server address 默认值:无 上下文:tfs_upstream
指定上游 TFS 服务器的地址,支持域名或 IP 形式:
server 10.0.0.1:8108;
type
语法:type [ns | rcs] 默认值:ns 上下文:tfs_upstream
指定上游类型:
ns:NameServer,TFS 元数据定位服务器,仅需一个server地址即可工作;rcs:RcServer,资源/应用配置服务器,需要配合rcs_zone、rcs_heartbeat、rcs_interface使用。
源码中该指令只接受 ns 与 rcs 两个取值(对应 ngx_http_tfs_module.c 中的 NGX_HTTP_TFS_NAMESERVER_TYPE / NGX_HTTP_TFS_RCSERVER_TYPE 常量),其他取值会导致配置加载失败。
rcs_zone
语法:rcs_zone name=n size=num 默认值:无 上下文:tfs_upstream
定义一块共享内存区,用于存放从 RcServer 注册中心拉取到的应用配置信息(appkey、集群路由等)。当上游类型为 rcs 时该指令必填,配置信息可通过 rcs_heartbeat 心跳定时刷新。
rcs_zone name=tfs1 size=128M;
从 rcs_zone 实现 看,size 必须大于等于 8 * ngx_pagesize(即至少 8 个内存页,通常为 32KB 级别),过小会直接报 "zone is too small";共享内存初始化时绑定 ngx_http_tfs_rc_server_init_zone 回调。
rcs_heartbeat
语法:rcs_heartbeat lock_file=/path/to/file interval=time 默认值:无 上下文:tfs_upstream
开启与 RcServer 的心跳,使应用配置信息能够及时更新。上游类型为 rcs 时必填。参数说明:
lock_file=/path/to/file:通过文件锁实现互斥,保证同一时刻只有一个 Nginx worker 进程执行心跳,避免多个 worker 同时向 RcServer 拉取配置造成压力;interval=time:心跳间隔,如10s。
rcs_heartbeat lock_file=/path/to/nginx/logs/lk.file interval=10s;
源码细节:interval 通过 ngx_parse_time 解析,若小于最小阈值 NGX_HTTP_TFS_MIN_TIMER_DELAY 会被自动重置为 1000ms 并打出 warn 日志(见 rcs_heartbeat 实现);lock_file 会被转换为绝对路径。心跳定时器在模块初始化阶段(ngx_http_tfs_module_init)注册,且只在满足 enable_rcs && lock_file && used 三个条件时才生效。
rcs_interface
语法:rcs_interface interface 默认值:无 上下文:tfs_upstream
指定 TFS 模块使用的网卡接口名,用于获取本机 IP 地址。仅当上游为 RcServer 时必填。模块在配置解析阶段就通过 ngx_http_tfs_get_local_ip() 根据接口名解析出本机地址(见 rcs_interface 实现),该地址用于向 RcServer 注册/定位本机所属集群,接口名无效会报 "device is invalid" 错误。
rcs_interface eth0;
tfs_pass
语法:tfs_pass name 默认值:无 上下文:location
将当前 location 的请求转发到指定的 TFS 上游。协议前缀必须写成 tfs://,模块会校验该前缀(ngx_http_tfs_pass),否则报 "invalid URL prefix in tfs_pass":
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;
}
location / {
tfs_pass tfs://tfs_rc;
}
配置 tfs_pass 后,模块会把当前 location 的 handler 替换为 ngx_http_tfs_handler;若 location 名以 / 结尾还会开启 auto_redirect(自动补斜杠重定向)。另外,当上游是 rcs 类型时,此处会校验 rcs_interface 与 rcs_zone 是否已配置并注册共享内存;若配置了 tfs_block_cache_zone,也会在此绑定 BlockCache 共享内存。
tfs_keepalive
语法:tfs_keepalive max_cached=num bucket_count=num 默认值:无 上下文:http, server
定义 TFS 模块的连接池,用于缓存到上游的连接,避免每次请求都新建 TCP 连接。参数说明:
max_cached=num:单个 hash 桶的容量上限;bucket_count=num:hash 桶的数量。
tfs_keepalive max_cached=100 bucket_count=15;
从实现看(ngx_http_tfs_keepalive),连接池按"桶数 × 每桶容量"的哈希结构组织,两个参数都必须是非零整数,最终调用 ngx_http_connection_pool_init() 完成初始化,连接池实例保存在主配置 conn_pool 中,所有 worker 共享使用。
tfs_block_cache_zone
语法:tfs_block_cache_zone size=num 默认值:无 上下文:http
定义用于 BlockCache 的共享内存区。BlockCache 缓存"文件 → 数据块所在 DataServer"的块定位信息,可显著减少 NameServer 查询压力:
tfs_block_cache_zone size=256M;
该指令内部固定使用名为 tfs_module_block_cache_zone 的共享内存(常量 NGX_HTTP_TFS_BLOCK_CACHE_ZONE_NAME),size 解析失败或缺失会报错(见 ngx_http_tfs_block_cache_zone)。请求处理时,若存在本地 BlockCache 上下文,会启用 NGX_HTTP_TFS_LOCAL_BLOCK_CACHE;模块还支持 tfs_enable_remote_block_cache on|off 指令开启基于 Tair 的远程块缓存(对应 NGX_HTTP_TFS_REMOTE_BLOCK_CACHE,代码见 ngx_http_tfs_module.c 与 ngx_http_tfs.h)。
tfs_log
语法:tfs_log path 默认值:无 上下文:http, server
设置 TFS 访问日志路径。同一条配置中重复出现会报 "is duplicate"。支持 Nginx 的 pipe: 语法交给外部程序(如 cronolog)做日志切割:
tfs_log "pipe:/usr/sbin/cronolog -p 30min /path/to/nginx/logs/cronolog/%Y/%m/%Y-%m-%d-%H-%M-tfs_access.log";
tfs_body_buffer_size
语法:tfs_body_buffer_size size 默认值:2m 上下文:http, server, location
设置读取上游(TFS 服务器)响应时的缓冲区大小,默认 2m:
tfs_body_buffer_size 2m;
超时指令组
以下三个超时指令均支持 http / server / location 三级上下文,默认值均为 3s,与源码中 ngx_http_tfs_init_main_conf() 设置的 3000ms 一致:
| 指令 | 语法 | 默认值 | 作用 |
|---|---|---|---|
tfs_connect_timeout |
tfs_connect_timeout time |
3s |
与上游 TFS 服务器建立连接的超时 |
tfs_send_timeout |
tfs_send_timeout time |
3s |
向上游 TFS 服务器发送数据的超时 |
tfs_read_timeout |
tfs_read_timeout time |
3s |
从上游 TFS 服务器读取数据的超时 |
对应的配置槽位定义在 ngx_http_tfs_module.c 中(tfs_connect_timeout / tfs_send_timeout / tfs_read_timeout,均使用 ngx_conf_set_msec_slot 解析毫秒值)。
其他参数
- 上传文件大小上限:取决于 Nginx 核心指令
client_max_body_size。TFS 模块在写入大文件时(请求体超过NGX_HTTP_TFS_USE_LARGE_FILE_SIZE阈值或 URI 显式声明large_file=1)会走大文件写入路径(见 ngx_http_tfs_read_body_handler),因此若要支持大文件上传,需要同步调大client_max_body_size; - 源码中还支持
tfs_buffer_size(默认ngx_pagesize / 2)、tfs_send_lowat(仅在 FreeBSD 等支持SO_SNDLOWAT的平台生效,其他平台会忽略并告警)、tair_timeout(默认 3s,Tair 去重/远程缓存场景使用)等指令,可自行按需配置。
上游模式与工作原理
NameServer 模式(type ns)
适用于不依赖 RcServer 应用注册的简单场景。Nginx 直接向 NameServer 查询文件所在数据块的位置,再转发到对应的 DataServer 读写。官方示例中使用 tfs 作为默认 appkey 即可完成 Raw TFS 的读写操作。配置最简:
tfs_upstream tfs_ns {
server 127.0.0.1:8108;
type ns;
}
RcServer 模式(type rcs)
适用于生产环境。RcServer 中注册了各应用(appkey)的集群路由与配置,Nginx 通过 rcs_heartbeat 定期拉取并缓存到 rcs_zone 共享内存中。模块会为每个启用的 rcs 上游在 worker 启动阶段注册心跳定时器(ngx_http_tfs_check_init_worker),且借助 lock_file 保证多 worker 中仅一个执行心跳,其余 worker 通过共享内存读取最新配置。Custom TFS(v2 接口,即带目录/命名空间的文件系统)必须依赖 RcServer 模式——ngx_http_tfs_handler 中明确检查:当 URI 版本为 2 而上游未启用 rcs 时直接返回 400。
RESTful API 使用示例
模块对外暴露两类 RESTful 接口(完整协议见 docs/modules/TFS_RESTful_API.md):
Raw TFS(v1 接口)
URI 形式为 /v1/{appkey}[/{TfsFileName}],appkey 是应用 ID;未使用 RcServer 时固定用 tfs 作为 appkey。
写入文件(返回 JSON 形式的文件名):
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]
响应(TFS_FILE_NAME 即 TFS 文件名,可用于后续访问):
{
"TFS_FILE_NAME": "T1FOZHB4ET1RCvBVdK"
}
带后缀写入(通过 suffix=.jpg&simple_name=1 指定,并要求访问时必须携带正确后缀):
POST /v1/tfs?suffix=.jpg&simple_name=1 HTTP/1.1
更新文件:
PUT /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
读取文件(支持 offset / size 范围读取,响应体即文件数据):
GET /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
删除或隐藏文件(hide=1 为隐藏,hide=0 为取消隐藏):
DELETE /v1/tfs/T1FOZHB4ET1RCvBVdK HTTP/1.1
DELETE /v1/tfs/T1FOZHB4ET1RCvBVdK.jpg?hide=1 HTTP/1.1
查看文件元数据:
GET /v1/tfs/metadata/T1FOZHB4ET1RCvBVdK HTTP/1.1
STAT 响应为 JSON,包含 FILE_NAME、BLOCK_ID、FILE_ID、OFFSET、SIZE、OCCUPY_SIZE、MODIFY_TIME、CREATE_TIME、STATUS(0 正常 / 1 已删除 / 4 已隐藏 / 5 隐藏且删除)、CRC 等字段。
Custom TFS(v2 接口,需 RcServer)
提供带命名空间的目录文件系统:GET_APPID 获取应用 ID,然后以 appid + uid 作为唯一命名空间执行目录/文件操作。典型调用:
获取 appid:
GET /v2/tfs/appid HTTP/1.1
创建目录(recursive=1 可递归创建父目录,成功返回 201):
POST /v2/tfs/1/1234/dir/dir_1 HTTP/1.1
删除目录:
DELETE /v2/tfs/1/1234/dir/dir_1 HTTP/1.1
移动/重命名目录(通过自定义请求头 x-ali-move-source 指定源目录):
POST /v2/tfs/1/1234/dir/dir_dest HTTP/1.1
x-ali-move-source: /dir_src
列出目录内容:
GET /v2/tfs/metadata/1/1234/dir/dir_1 HTTP/1.1
v2 接口对应的动作在 ngx_http_tfs_protocol.h 中枚举定义,包括 CREATE_DIR、REMOVE_DIR、MOVE_DIR、LS_DIR、READ_FILE、WRITE_FILE、STAT_FILE、GET_APPID 等 16 种动作,URI 解析后即映射到这些动作码执行。
源码结构速览
该模块代码完整位于 modules/ngx_http_tfs_module 目录,核心文件与职责对应关系如下:
| 文件 | 职责 |
|---|---|
| ngx_http_tfs_module.c | 模块入口、全部指令解析与请求分发 |
| ngx_http_tfs.c | 请求状态机、与 NameServer/DataServer 的交互流程 |
| ngx_http_tfs_restful.c | RESTful URI 解析与动作映射 |
| ngx_http_tfs_rc_server_info.c | RcServer 应用配置管理与共享内存 |
| ngx_http_connection_pool.c | 上游连接池(tfs_keepalive) |
| ngx_http_tfs_block_cache.c | 块定位缓存(本地 + 远程 Tair) |
| ngx_http_tfs_timers.c | RcServer 心跳定时器与文件锁 |
| ngx_http_tfs_json.c | 基于 libyajl 的 JSON 编解码 |
| ngx_http_tfs_protocol.h | TFS 协议常量与动作枚举 |
注意事项与限制
- 必须显式开启:
--with-http_tfs_module不会随默认配置编译,且依赖 libyajl; - RcServer 三件套:
type rcs时必须同时提供rcs_zone、rcs_heartbeat、rcs_interface,缺失任一指令都会导致启动失败; - 协议前缀:
tfs_pass必须使用tfs://前缀,这是模块识别 TFS 上游的唯一方式; - 上传大小:大文件上传需配合调整
client_max_body_size,否则请求体会被 Nginx 拒绝; - Custom TFS 依赖 RcServer:v2 接口(目录、命名空间)要求上游为 rcs 类型,否则返回 400;
- 心跳互斥:心跳通过 lock_file 实现单 worker 执行,请确保 lock_file 路径可写且各 worker 可见。