Tengine 集成 TFS 分布式文件系统:ngx_http_tfs_module 模块配置与 RESTful API 实战指南

原创2026-09-21 23:35:101,714 阅读
文章标签:后端网络负载均衡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 显式挂载。安装步骤如下:

  1. 安装 yajl JSON 库:模块使用开源 JSON 库 yajl 处理 JSON 数据,请先安装 yajl-2.0.1。

  2. 准备源码:下载 nginx 或 tengine 源码(本文以当前 tengine 仓库为准)。

  3. 配置并添加模块:

    ./configure --add-module=/path/to/nginx-tfs
    

    其中 /path/to/nginx-tfs 指向本仓库的 modules/ngx_http_tfs_module 目录。

  4. 编译安装:

    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):

  1. 解析 URI:ngx_http_tfs_handler 调用 ngx_http_restful_parse,根据 /v1/ 或 /v2/ 前缀确定版本与操作类型(写/读/删/列目录等);
  2. 读取请求体:对于写类操作(NGX_HTTP_TFS_ACTION_WRITE_FILE)调用 ngx_http_read_client_request_body 异步读取客户端请求体,其余操作通过 ngx_http_discard_request_body 丢弃请求体;v2 请求但未启用 RCS 时直接返回 400;
  3. 初始化 TFS 请求:ngx_http_tfs_read_body_handler 判断是否大文件(v1 且超过 15MB),并调用 ngx_http_tfs_init 启动与 TFS 集群的交互;
  4. 异步交互:后续流程在 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 均需依据机器内存合理设定,过小会降低连接复用与路由缓存命中率,过大则占用内存。

参考资料

登录后查看全文
tengine