Tengine 集成 TFS 分布式文件系统:ngx_http_tfs_module 模块配置与 RESTful API 实战指南
Tengine 集成 TFS 分布式文件系统:ngx_http_tfs_module 模块配置与 RESTful API 实战指南
导读
ngx_http_tfs_module(即 nginx-tfs)是 Tengine 中为淘宝开源分布式文件系统 TFS(Taobao File System) 提供的异步客户端模块,它以 Nginx HTTP 模块的形式为 TFS 暴露出一套完整、标准的 RESTful API,让业务方可以像访问普通 Web 服务一样对 TFS 完成文件的写入、读取、更新、删除与元信息查询。本文将以仓库内的模块中文文档为主体,结合 RESTful API 说明与模块源码,完整讲解该模块的编译安装、tfs_upstream/tfs_pass 等全部指令的配置方法、v1/v2 两代 RESTful API 的调用细节,并深入剖析连接池、BlockCache、RcServer 心跳等底层实现原理。读完本文,你将能够在 Tengine 上独立搭建一个面向 TFS 的文件存取网关。
模块概述:什么是 nginx-tfs
TFS 是一个面向海量小文件的分布式文件系统,其集群中通常包含 NameServer(负责管理 Block 与 DataServer 的映射关系)、DataServer(实际存储数据)、RcServer(管理应用注册与配置信息)等角色。ngx_http_tfs_module 则扮演了 TFS 客户端 + RESTful 网关 的双重角色:
- 在 Nginx 侧,它以异步非阻塞的方式连接 TFS 集群,不阻塞 worker 进程;
- 在客户端侧,它将 TFS 的私有协议封装为 HTTP REST 接口,业务方只需发送标准的 HTTP 请求即可读写文件。
从源码目录 modules/ngx_http_tfs_module/ 可以看到,该模块的源码体系相当完整:核心入口 ngx_http_tfs_module.c、RESTful URI 解析 ngx_http_tfs_restful.c、与 NameServer/DataServer/RootServer/MetaServer 的通信协议封装(ngx_http_tfs_name_server_message.c、ngx_http_tfs_data_server_message.c 等)、连接池 ngx_http_connection_pool.c、本地/远程 BlockCache(ngx_http_tfs_local_block_cache.c、ngx_http_tfs_remote_block_cache.c)、以及 JSON 序列化 ngx_http_tfs_json.c 等,是一个功能边界清晰、分层明确的完整业务模块。
编译安装
TFS 模块默认不随 Tengine 编译,需要通过 --add-module 显式挂载。安装步骤如下:
-
安装 yajl JSON 库:模块使用开源 JSON 库 yajl 处理 JSON 数据,请先安装 yajl-2.0.1。
-
准备源码:下载 nginx 或 tengine 源码(本文以当前 tengine 仓库为准)。
-
配置并添加模块:
./configure --add-module=/path/to/nginx-tfs其中
/path/to/nginx-tfs指向本仓库的modules/ngx_http_tfs_module目录。 -
编译安装:
make && make install
编译脚本对 yajl 的探测逻辑
从模块的 config 编译脚本 可以看到,它并非简单依赖系统默认路径,而是依次尝试多种方式定位 yajl:
- 优先使用显式指定的
LIBYAJL_INC(头文件路径)与LIBYAJL_LIB(库文件路径)环境变量,此时链接-lyajl; - 若未显式指定,则依次探测系统默认目录、
/usr/local/(FreeBSD/OpenBSD/Linux 常见安装位置)、/usr/pkg/(NetBSD)、/opt/local/(MacPorts); - 探测全部失败时会输出
error: the ngx_tfs addon requires the libyajl library.并以非零状态退出,避免带病编译。
因此,如果你的 yajl 安装在不常见的位置,编译前务必设置好 LIBYAJL_INC 和 LIBYAJL_LIB。
完整配置示例
配置的核心思路是:先用 tfs_upstream 声明后端 TFS 服务器(NameServer 或 RcServer),再用 tfs_pass 把指定 location 的请求转交给 TFS 模块处理。仓库文档给出的最小可运行示例(NS 模式)如下:
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:6100;
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_rc 块展示了启用 RcServer(type rcs)时的完整形态——相比 NS 模式,RCS 模式额外要求 rcs_zone、rcs_interface、rcs_heartbeat 三条指令(后面会解释为什么这是强制的)。两条 tfs_upstream 可以并存:同一配置里既可按需访问 NameServer,也可访问 RcServer。
指令详解
以下指令按文档顺序逐一说明语法、默认值、上下文(Context)与底层实现要点。指令的解析逻辑与默认值均可对照 ngx_http_tfs_module.c 中的指令表(ngx_http_tfs_commands,L76-L170)与主配置初始化函数 ngx_http_tfs_init_main_conf(L742-L776)验证。
server
- Syntax:
server address - Default:none
- Context:
tfs_upstream
指定后端 TFS 服务器的地址。当 type 为 rcs 时,该地址是 RcServer 的地址;当 type 为 ns 时,该地址是 NameServer 的地址。此指令必须配置,且一个 tfs_upstream 块内至少要有一条 server——源码在 tfs_upstream 解析结束时检查 tu->ups_addr,为空则报 no servers are inside tfs upstream 并拒绝加载配置。
server 10.0.0.1:8108;
地址可以指定为域名或 IP,由 ngx_parse_url 完成解析(见 ngx_http_tfs_module.c)。
type
- Syntax:
type [ns | rcs] - Default:
ns - Context:
tfs_upstream
设置 TFS 服务器的类型,取值只能是 ns(NameServer)或 rcs(RcServer)。源码中用字符串常量 NGX_HTTP_TFS_NAMESERVER_TYPE("ns") 与 NGX_HTTP_TFS_RCSERVER_TYPE("rcs") 精确匹配参数值,非法取值会报 invalid type(L473-L501)。
关键差异:如需使用自定义文件名(v2)功能,请将类型设置为 rcs。自定义文件名功能依赖 MetaServer 和 RootServer 提供名字空间支持,而应用在 RcServer 上的注册信息(appkey/appid 等)正是通过 RCS 模式获取的。这一点在请求处理代码中也有强制校验:当请求使用 v2 协议(r_ctx.version == 2)而 upstream 未开启 RCS 时,模块会直接返回 400 Bad Request 并记录 custom file requires tfs_enable_rcs on, and make sure you have MetaServer and RootServer!(L255-L260)。
rcs_zone
- Syntax:
rcs_zone name=n size=num - Default:none
- Context:
tfs_upstream
配置 TFS 应用在 RcServer 上的配置信息缓存区。若开启 RcServer(配置了 type rcs),则必须配置此指令。它会在共享内存(shm zone)中缓存 TFS 应用在 RcServer 的配置信息,并配合 rcs_heartbeat 与 RcServer 保持 keepalive,保证应用配置及时更新。
rcs_zone name=tfs1 size=128M;
参数含义:
name:共享内存 zone 的名称(对应一个 TFS 应用);size:共享内存大小。
实现细节(L913-L998):size 通过 ngx_parse_size 解析,且不得小于 8 个内存页(8 * ngx_pagesize),否则报 zone is too small;name 与 size 缺一不可。最终通过 ngx_shared_memory_add 注册 zone,并挂载 ngx_http_tfs_rc_server_init_zone 作为初始化回调。
rcs_heartbeat
- Syntax:
rcs_heartbeat lock_file=/path/to/file interval=time - Default:none
- Context:
tfs_upstream
配置 TFS 应用与 RcServer 之间的 keepalive(心跳),用于定期交互、及时更新应用配置。若开启 RcServer 功能,则必须配置此指令。
rcs_heartbeat lock_file=/path/to/nginx/logs/lk.file interval=10s;
参数含义:
lock_file:锁文件路径。用于创建互斥锁,保证同一时刻只有一个 Nginx worker 在执行心跳,避免多 worker 同时向 RcServer 发起请求;interval:心跳间隔。
实现细节(L585-L643):interval 用 ngx_parse_time 解析,若小于 NGX_HTTP_TFS_MIN_TIMER_DELAY(在 ngx_tfs_common.h 中定义为 1000 毫秒),会自动重置为 1000ms 并给出告警日志;lock_file 缺省时报错。心跳定时器在模块初始化阶段创建:ngx_http_tfs_module_init 中为每个启用的 RCS upstream 初始化锁文件(ngx_http_tfs_timers_init),随后在 ngx_http_tfs_check_init_worker(worker 进程启动时)调用 ngx_http_tfs_add_rcs_timers 挂载定时器(L1130-L1203)。
rcs_interface
- Syntax:
rcs_interface interface - Default:none
- Context:
tfs_upstream
配置 TFS 模块使用的网卡,用于获取本机 IP 地址(该地址会在与 RcServer 交互时上报)。若开启 RcServer 功能,则必须配置此指令。
rcs_interface eth0;
实现细节(L647-L670):模块通过 ngx_http_tfs_get_local_ip 从网卡名解析出本机地址,网卡无效时报 device is invalid;解析成功后将 IP 转为文本保存。若 type rcs 却未配置本指令,tfs_upstream 解析会直接报 type rcs_server must set rcs_interface directives in tfs_upstream block(L411-L432)。
tfs_upstream
- Syntax:
tfs_upstream name {...} - Default:none
- Context:
http
配置 TFS 模块的 upstream 信息块,块内可包含上述 server、type、rcs_zone、rcs_interface、rcs_heartbeat 指令。upstream 名称不能重复,源码中 ngx_http_tfs_upstream_add 会检查重名(duplicate tfs upstream)。
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;
}
值得注意的配置校验(L405-L432):块内至少有一个 server;若 type rcs,则 rcs_interface、rcs_heartbeat、rcs_zone 三者缺一不可,否则整个配置加载失败。这从源码层面印证了文档中"必须配置"的约束。
tfs_pass
- Syntax:
tfs_pass name - Default:none
- Context:
location
关键指令,决定请求是否由 TFS 模块处理,必须配置。需要注意:
- 这里不支持直接写 IP 地址或域名,只能引用
tfs_upstream name {...}配置的 upstream; - 参数必须以
tfs://开头,如tfs_pass tfs://tfs_ns;。
location / {
tfs_pass tfs://tfs_rc;
}
实现细节(L801-L880):tfs_pass 解析时先检查前缀是否为 tfs://(大小写不敏感,ngx_strncasecmp),否则报 invalid URL prefix in tfs_pass;随后在已注册的 upstream 中查找对应名称(找不到报 host not found in tfs upstream),并把当前 location 的 content handler 设置为 ngx_http_tfs_handler。若 location 名以 / 结尾,还会自动开启 auto_redirect(自动补尾斜杠重定向)。
tfs_keepalive
- Syntax:
tfs_keepalive max_cached=num bucket_count=num - Default:none
- Context:
http, server
配置 TFS 模块与后端 TFS 服务器之间的连接池大小,必须配置。该连接池缓存与后端的连接,可理解为由多个 hash 桶构成的哈希表:
bucket_count:桶的个数;max_cached:每个桶的容量。
tfs_keepalive max_cached=100 bucket_count=15;
注意:应根据机器内存情况合理设置,连接池整体规模约等于 max_cached × bucket_count。实现上(L523-L581)两个参数都必须为合法正整数(ngx_atoi 解析且不能为 0),随后调用 ngx_http_connection_pool_init 初始化哈希桶结构。
tfs_block_cache_zone
- Syntax:
tfs_block_cache_zone size=num - Default:none
- Context:
http
配置模块的本地 BlockCache:在共享内存中缓存 TFS 中 Block 与 DataServer 的映射关系,避免每次读写都向 NameServer 查询路由,显著降低访问延迟。应根据机器内存情况合理设置大小。
tfs_block_cache_zone size=256M;
实现细节(L1001-L1059):该 zone 使用固定名称 tfs_module_block_cache_zone(L16)注册,挂载 ngx_http_tfs_local_block_cache_init_zone 初始化回调。此外源码中还有配套的 tfs_enable_remote_block_cache on|off 指令(见指令表 L162-L167)与 tair_timeout,用于开启基于 Tair 的远程 BlockCache,形成"本地缓存 + 远程缓存"两级缓存(请求处理时通过 block_cache_ctx.use_cache 位标志组合启用,见 L236-L246)。
tfs_log
- Syntax:
tfs_log path - Default:none
- Context:
http, server
配置是否记录 TFS 访问日志。配置后会以固定格式将访问 TFS 的请求记录到指定日志中,便于分析(具体字段格式见模块源码)。
tfs_log "pipe:/usr/sbin/cronolog -p 30min /path/to/nginx/logs/cronolog/%Y/%m/%Y-%m-%d-%H-%M-tfs_access.log";
示例中的管道写法可以配合 cronolog 按时间切分日志。注意:cronolog 支持依赖于 tengine 提供的扩展日志模块(即 pipe: 管道日志机制)。实现上该指令复用 Nginx 标准的 ngx_log_set_log(L674-L683),且同一 server 内不允许重复配置。
tfs_body_buffer_size
- Syntax:
tfs_body_buffer_size size - Default:
2m - Context:
http, server, location
配置与后端 TFS 服务器交互时使用的 body 缓冲区大小。默认值为 2m,对应源码常量 NGX_HTTP_TFS_DEFAULT_BODY_BUFFER_SIZE(ngx_tfs_common.h 中定义为 2 * 1024 * 1024)。
tfs_body_buffer_size 2m;
tfs_connect_timeout / tfs_send_timeout / tfs_read_timeout
- Syntax:
tfs_connect_timeout time/tfs_send_timeout time/tfs_read_timeout time - Default:均为
3s - Context:
http, server, location
三个超时指令分别控制:
tfs_connect_timeout:连接后端 TFS 服务器的超时时间;tfs_send_timeout:向后端 TFS 服务器发送数据的超时时间;tfs_read_timeout:从后端 TFS 服务器接收数据的超时时间。
实现细节:三条指令在配置解析时均使用 ngx_conf_set_msec_slot(毫秒为单位),并在主配置初始化时统一将未配置值设为 3000ms(L747-L757)。此外源码还提供了未在文档中列出的同类指令:tair_timeout(默认 3000ms)和 tfs_send_lowat(默认 0,仅在 FreeBSD 等支持 SO_SNDLOWAT 的平台生效,其他平台会忽略并告警,见 L884-L909)。
其他限制
能支持上传的文件大小取决于 client_max_body_size 指令配置的大小。 也就是说,TFS 模块并不单独限制上传体积,业务方需要配合 Nginx 核心模块的 client_max_body_size 来控制请求体上限。另外,源码中还有一个内置分界:当 v1 请求体超过 NGX_HTTP_TFS_USE_LARGE_FILE_SIZE(ngx_tfs_common.h 中定义为 15MB)时,模块会自动按大文件(文件名以 L 开头)方式处理(L1091-L1111)。
RESTful API:v1 原生 TFS 与 v2 自定义文件名
模块通过 URI 首段区分协议版本:/v1/... 为原生 TFS(文件名为 TFS 自动生成),/v2/... 为自定义文件名(需 RCS 模式)。URI 解析逻辑集中在 ngx_http_tfs_restful.c 的 ngx_http_restful_parse_uri 与 ngx_http_restful_parse(L787-L803)中,按 version == 1 与 version == 2 分别走 parse_action_raw 与 parse_action 两条解析路径。下述 API 语法中粗体为保留关键字,斜体为用户输入部分。完整说明见 TFS RESTful API 中文文档。
v1:原生 TFS 文件操作
v1 协议中,appkey 是应用在 RcServer 数据库中配置的应用标识符;若未使用 RcServer,直接使用 tfs 作为 appkey 即可。
写文件(POST)——将请求体保存为 TFS 文件并以 JSON 返回文件名:
POST /v1/appkey HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: length
Date: date
请求参数:
| 参数名 | 描述 |
|---|---|
| suffix | 文件后缀 |
| simple_name | 是否要求必须带正确后缀才可访问存入的 TFS 文件;1:必须带后缀才可访问,0:不带后缀也可访问 |
| large_file | 是否存成大文件(文件名以 L 开头);1:存成大文件,0:不存成大文件 |
应答字段:TFS_FILE_NAME(返回的 TFS 文件名)。状态码:200 OK 成功;400 Bad Request 错误请求;500 Internal Server Error TFS 或 Nginx 内部错误。
示例——写一个不带后缀的 TFS 文件:
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"
}
示例——写一个带 .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]
应答中文件名带后缀:{"TFS_FILE_NAME": "T1FOZHB4ET1RCvBVdK.jpg"}。
更新文件(PUT)——更新已有 TFS 文件并返回文件名:
PUT /v1/appkey/TfsFileName HTTP/1.1
Host: 10.0.0.1:7500
Content-Length: length
Date: date
请求参数为 suffix 与 simple_name(含义同上),应答与状态码同写文件。
示例:
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]
读文件(GET)——读取文件数据:
GET /v1/appkey/TfsFileName HTTP/1.1
Host: 10.0.0.1:7500
Date: date
请求参数:
| 参数名 | 描述 |
|---|---|
| suffix | 文件后缀;注意:若指定了该参数,且 TfsFileName 中也带了后缀,两者不一致将无法访问 |
| offset | 要读取的数据在文件中的偏移 |
| size | 要读取的数据长度 |
应答为原始数据流(data)。状态码在写文件基础上增加 404 Not Found(文件不存在)。
删除文件(DELETE)——删除或隐藏文件:
DELETE /v1/appkey/TfsFileName HTTP/1.1
Host: 10.0.0.1:7500
Date: date
请求参数:
| 参数名 | 描述 |
|---|---|
| suffix | 文件后缀(不一致将无法访问,同上) |
| hide | 隐藏操作类型:1:隐藏,0:反隐藏 |
应答无内容。示例(隐藏文件):
DELETE /v1/tfs/T1FOZHB4ET1RCvBVdK.jpg?hide=1 HTTP/1.1
获取文件元信息(GET metadata)——以 JSON 返回文件元信息:
GET /v1/appkey/metadata/TfsFileName HTTP/1.1
请求参数:suffix(同上)、type(0:正常获取,文件被删除或隐藏则无法获取;1:强制获取,即使被删除或隐藏也可获取)。
应答字段:
| 名称 | 描述 |
|---|---|
| FILE_NAME | 文件名 |
| BLOCK_ID | 文件所在 block 的 id |
| FILE_ID | 文件的 file id |
| OFFSET | 文件在其所在 block 中的偏移 |
| SIZE | 文件大小 |
| OCCUPY_SIZE | 文件真正占用空间 |
| MODIFY_TIME | 文件最后修改时间 |
| CREATE_TIME | 文件创建时间 |
| STATUS | 文件状态:0 正常、1 删除、4 隐藏、5 隐藏且删除 |
| CRC | 文件的 CRC 校验码 |
示例应答:
{
"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
}
v2:自定义文件名(需 RCS 模式)
v2 协议面向"自定义文件名"场景,每个应用根据 appkey 获得唯一 appid(代表应用在 TFS 中的一个独立名字空间),appid 与 uid 的组合对应一个独立的名字空间(appid 名字空间下的子空间)。所有 v2 操作都需要 appid 与 uid 两个路径参数。
获取 APPID(GET appid)——查询应用 appid,这是所有自定义文件名操作必需的前置步骤:
GET /v2/appkey/appid HTTP/1.1
应答字段:APP_ID。500 状态码在内部错误之外还表示登录失败(未在 RcServer 数据库中配置应用)。示例:
GET /v2/tfs/appid HTTP/1.1
应答:{"APP_ID": "1"}。
创建目录(POST dir):
POST /v2/appkey/appid/uid/dir/dir_name HTTP/1.1
请求参数:recursive(1:递归创建父目录;0:不递归)。成功返回 201 Created;此外还有 400(目录名不合规范)、401(无权限,每个应用只对自己的 appid 空间有修改权限)、403(超过最大子目录数/子文件数/目录深度)、409(目录已存在)、500。
删除目录(DELETE dir):
DELETE /v2/appkey/appid/uid/dir/dir_name HTTP/1.1
无请求参数。成功返回 200 OK;403 表示目录非空;404 表示目录或父目录不存在。
移动/重命名目录(POST dir + x-ali-move-source):
POST /v2/appkey/appid/uid/dir/dest_dir_name HTTP/1.1
x-ali-move-source: /src_dir_name
此 API 需要特定 header x-ali-move-source 指定源目录路径。请求参数:recursive(1:递归创建目的目录的父目录)。403 表示移动到子目录中;404 表示源目录/父目录不存在、或目的目录已存在、或目的父目录不存在。
列目录(GET metadata dir)——返回目录下所有子目录和文件的 JSON 数组:
GET /v2/appkey/metadata/appid/uid/dir/dir_name HTTP/1.1
应答为数组,每项包含:NAME(文件/目录名)、PID(父目录 id)、ID(自身 id)、SIZE、IS_FILE(是否文件)、CREATE_TIME、MODIFY_TIME、VER_NO(版本号)。
查看目录是否存在(HEAD dir):
HEAD /v2/appkey/appid/uid/dir/dir_name HTTP/1.1
目录存在返回 200 OK,不存在返回 404。
创建文件(POST file):
POST /v2/appkey/appid/uid/file/file_name HTTP/1.1
请求参数:recursive。成功返回 201 Created;404 表示父目录不存在;409 表示文件已存在。
写文件(PUT file)——向文件写入数据。自定义文件名支持多次写入,支持 pwrite(通过 offset 指定偏移量写,支持文件空洞),默认为追加写;注意不支持更新已有数据:
PUT /v2/appkey/appid/uid/file/file_name HTTP/1.1
Content-Length: length
请求参数:offset(要写入的偏移)、size(要写入的数据长度)。状态码中 409 Conflict 表示写偏移处已存在数据。
读文件(GET file):
GET /v2/appkey/appid/uid/file/file_name HTTP/1.1
请求参数:offset、size。应答为原始数据。
删除文件(DELETE file):
DELETE /v2/appkey/appid/uid/file/file_name HTTP/1.1
移动/重命名文件(POST file + x-ali-move-source):
POST /v2/appkey/appid/uid/file/dest_file_name HTTP/1.1
x-ali-move-source: /src_file_name
请求参数:recursive(1:递归创建目的文件的父目录)。400 还表示源文件和目的文件相同;404 表示源文件不存在、或目的文件已存在、或目的文件父目录不存在。
列文件元信息(GET metadata file):
GET /v2/appkey/metadata/appid/uid/file/file_name HTTP/1.1
应答字段同"列目录"单元素:NAME(文件绝对路径)、PID、ID、SIZE、IS_FILE、CREATE_TIME、MODIFY_TIME、VER_NO。
查看文件是否存在(HEAD file):
HEAD /v2/appkey/appid/uid/file/file_name HTTP/1.1
请求处理链路:从 HTTP 到 TFS
理解模块的工作方式有助于正确调优。当请求命中配置了 tfs_pass 的 location 后,处理流程如下(见 ngx_http_tfs_module.c):
- 解析 URI:
ngx_http_tfs_handler调用ngx_http_restful_parse,根据/v1/或/v2/前缀确定版本与操作类型(写/读/删/列目录等); - 读取请求体:对于写类操作(
NGX_HTTP_TFS_ACTION_WRITE_FILE)调用ngx_http_read_client_request_body异步读取客户端请求体,其余操作通过ngx_http_discard_request_body丢弃请求体;v2 请求但未启用 RCS 时直接返回 400; - 初始化 TFS 请求:
ngx_http_tfs_read_body_handler判断是否大文件(v1 且超过 15MB),并调用ngx_http_tfs_init启动与 TFS 集群的交互; - 异步交互:后续流程在 ngx_http_tfs.c 中通过连接池复用与 DataServer 的连接,借助本地 BlockCache(共享内存)缓存 Block→DataServer 映射、必要时查询 NameServer 获取路由,最终完成文件读写并回写响应。
整个交互全程基于 Nginx 事件驱动模型,不阻塞 worker 进程,这也是该模块能够承载高并发文件存取的关键。
常见问题与注意事项
- 编译报缺 yajl 库:检查是否安装 yajl-2.0.1,若安装位置特殊,编译时通过
LIBYAJL_INC/LIBYAJL_LIB显式指定路径(见 config)。 tfs_pass配了 IP/域名:tfs_pass只接受tfs://前缀 +tfs_upstream名称,不能直接写地址。type rcs配置加载失败:确认rcs_zone、rcs_interface、rcs_heartbeat三条指令都已配置(源码会在缺任一项时拒绝加载,见 L411-L432)。- v2 自定义文件名返回 400:确认 upstream 已开启 RCS(
type rcs),且部署了 MetaServer 与 RootServer。 - 上传大文件失败/超时:先检查
client_max_body_size(上传上限由此决定),再评估tfs_body_buffer_size与三个超时指令(默认均为 3s)是否匹配业务场景。 - 连接池与缓存调优:
tfs_keepalive max_cached × bucket_count、tfs_block_cache_zone size均需依据机器内存合理设定,过小会降低连接复用与路由缓存命中率,过大则占用内存。
参考资料
- 模块中文文档:docs/modules/ngx_http_tfs_module_cn.md
- RESTful API 中文说明:docs/modules/TFS_RESTful_API_cn.md
- 模块源码目录:modules/ngx_http_tfs_module/(核心入口 ngx_http_tfs_module.c、URI 解析 ngx_http_tfs_restful.c、公共常量 ngx_tfs_common.h)