FastDFS通信协议详解_fastdfs协议

FastDFS通信协议详解

本篇文章转载于 FastDFS 作者 余庆 大佬的 FastDFS分享与交流 公众号。

FastDFS 采用二进制 TCP 通信协议。一个数据包由 包头（header）和包体（body）组成。包头只有 10 个字节，格式如下：

	@ pkg_len：8字节整数，body长度，不包含header，只是body的长度
    
	@ cmd：1字节整数，命令码

	@ status：1字节整数，状态码，0表示成功，非0失败（UNIX错误码）
1
2
3
4
5

数据包中的类型说明：

• 整数类型采用网络字节序（Big-Endian），包括 4 字节整数和 8 字节整数；

• 1 字节整数不存在字节序问题，在 Java 中直接映射为 byte 类型，C/C++ 中为 char 类型；

• 固定长度的字符串类型以 ASCII 码 0 结尾，对于 Java 等语言需要调用 trim 处理返回的字符串。变长字符串的长度可以直接拿到或者根据包长度计算出来，不以 ASCII 0 结尾。

下面将列举 client 发送给 FastDFS server 的命令码及其 body（包体）结构。

一、公共命令码

1.1 FDFS_PROTO_CMD_ACTIVE_TEST

激活测试，通常用于检测连接是否有效。客户端使用连接池的情况下，建立连接后发送一次 active test 即可和 server 端保持长连接。

• 请求body：无
• 响应body：无

二、发送给 tracker server 的命令码

2.1 TRACKER_PROTO_CMD_SERVER_LIST_ONE_GROUP

查看一个 group 状态

• 请求body：

	@group_name：16字节字符串，组名
1

• 响应body：

	@group_name：17字节字符串

    @total_mb：8字节整数，磁盘空间总量，单位MB

    @free_mb：8字节整数 ，磁盘剩余空间，单位MB

    @trunk_free_mb：8字节整数，trunk文件剩余空间，单位MB（合并存储开启时有效）

    @server_count：8字节整数，storage server数量

    @storage_port：8字节整数，storage server端口号

    @storage_http_port：8字节整数，storage server上的HTTP端口号

    @active_count：8字节整数，当前活着的storage server数量

    @current_write_server：8字节整数，当前写入的storage server顺序号

    @store_path_count：8字节整数，storage server存储路径数

    @subdir_count_per_path：8字节整数，存储路径下的子目录数（FastDFS采用两级子目录），如 256

    @current_trunk_file_id：8字节整数，当前使用的trunk文件ID（合并存储开启时有效）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

2.2 TRACKER_PROTO_CMD_SERVER_LIST_ALL_GROUPS

列举所有 group

• 请求body：无
• 响应body：n 个 group 实体信息，n >= 0。每个 group 的数据结构参见上面的2.1。

2.3 TRACKER_PROTO_CMD_SERVER_LIST_STORAGE

列举一个 group 下的 storage server

• 请求body：

	@group_name：16字节字符串，组名

	@server_id：不定长，最大长度为15字节，storage server id，可选参数
1
2
3

• 响应body： n 个 storage server实体信息，n >= 0。 每个storage实体结构如下：

[   //列表开始

    @status：1字节整数，storage server状态

    @id：16字节字符串，server ID

    @ip_addr：16字节字符串，IP地址

    @domain_name：128字节字符串，域名

    @src_storage_id：16字节字符串，同步源storage的server ID

    @version：6字节字符串，运行的FastDFS版本号，例如6.04

    @join_time: 8字节整数，加入集群时间

    @up_time: 8字节整数，fdfs_storaged启动时间

    @total_mb: 8字节整数，磁盘空间总量，单位MB

    @free_mb: 8字节整数，磁盘剩余空间，单位MB

    @upload_priority: 8字节整数，上传文件优先级

    @store_path_count: 8字节整数，存储路径数

    @subdir_count_per_path: 8字节整数，存储路径下的子目录数（FastDFS采用两级子目录），如 256

    @current_write_path: 8字节整数，当前写入的存储路径（顺序号）

    @storage_port: 8字节整数，storage server服务端口号

    @storage_http_port: 8字节整数，HTTP服务端口号

    @alloc_count：4字节整数，已分配的连接buffer数目

    @current_count：4字节整数，当前连接数

    @max_count：4字节整数，曾经达到过的最大连接数

    @total_upload_count：8字节整数，上传文件总数

    @success_upload_count：8字节整数，成功上传文件数

    @total_append_count：8字节整数，调用append总次数

    @success_append_count：8字节整数，成功调用append次数

    @total_modify_count：8字节整数，调用modify总次数

    @success_modify_count：8字节整数，成功调用modify次数

    @total_truncate_count：8字节整数，调用truncate总次数

    @success_truncate_count：8字节整数，成功调用truncate次数

    @total_set_meta_count：8字节整数，设置文件附加属性（meta data）总次数

    @success_set_meta_count：8字节整数，成功设置文件附加属性（meta data）次数

    @total_delete_count：8字节整数，删除文件总数

    @success_delete_count：8字节整数，成功删除文件数

    @total_download_count：8字节整数，下载文件总数

    @success_download_count：8字节整数，成功下载文件数

    @total_get_meta_count：8字节整数，获取文件附加属性（meta data）总次数

    @success_get_meta_count：8字节整数，成功获取文件附加属性（meta data）次数

    @total_create_link_count：8字节整数，创建文件符号链接总数

    @success_create_link_count：8字节整数，成功创建文件符号链接数

    @total_delete_link_count：8字节整数，删除文件符号链接总数

    @success_delete_link_count：8字节整数，成功删除文件符号链接数

    @total_upload_bytes：8字节整数，上传文件总字节数

    @success_upload_bytes：8字节整数，成功上传文件字节数

    @total_append_bytes：8字节整数，append总字节数

    @success_append_bytes：8字节整数，成功append字节数

    @total_modify_bytes：8字节整数，modify总字节数

    @success_modify_bytes：8字节整数，成功modify字节数

    @total_download_bytes：8字节整数，下载总字节数

    @success_download_bytes：8字节整数，成功下载字节数

    @total_sync_in_bytes：8字节整数，文件同步流入总字节数

    @success_sync_in_bytes：8字节整数，文件同步成功流入字节数

    @total_sync_out_bytes：8字节整数，文件同步流出总字节数

    @success_sync_out_bytes：8字节整数，文件同步成功流出字节数

    @total_file_open_count：8字节整数，文件打开总次数

    @success_file_open_count：8字节整数，文件成功打开次数

    @total_file_read_count：8字节整数，文件读总次数

    @success_file_read_count：8字节整数，文件成功读次数

    @total_file_write_count：8字节整数，文件写总次数

    @success_file_write_count：8字节整数，文件成功写次数

    @last_source_update：8字节整数，最近一次源头更新时间

    @last_sync_update：8字节整数，最近一次同步更新时间

    @last_synced_timestamp：8字节整数，最近一次被同步到的时间戳

    @last_heart_beat_time：8字节整数，最近一次心跳时间

]  //列表结束
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

2.4 TRACKER_PROTO_CMD_SERVICE_QUERY_STORE_WITHOUT_GROUP_ONE

获取一个 storage server 用来存储文件（不指定 group name）

• 请求body：无
• 响应body：

	@group_name：16字节字符串，组名
	
	@ip_addr：15字节字符串， storage server IP地址

	@port：8字节整数，storage server端口号

	@store_path_index：1字节整数，基于0的存储路径顺序号
1
2
3
4
5
6
7

2.5 TRACKER_PROTO_CMD_SERVICE_QUERY_STORE_WITH_GROUP_ONE

获取一个 storage server 用来存储文件（指定组名）

• 请求body：

	@group_name：16字节字符串，组名
1

• 响应body：

	@ip_addr：15字节字符串， storage server IP地址

	@port：8字节整数，storage server端口号

    @store_path_index：1字节整数，基于0的存储路径顺序号 
1
2
3
4
5

2.6 TRACKER_PROTO_CMD_SERVICE_QUERY_STORE_WITHOUT_GROUP_ALL

获取 storage server 列表用来存储文件（不指定组名）

• 请求body：无

• 响应body：

	@group_name：16字节字符串，组名

 	[   //列表开始

	@ip_addr：15字节字符串， storage server IP地址

	@port：8字节整数，storage server端口号

	]  //列表结束

	@store_path_index：1字节整数，基于0的存储路径顺序号 
1
2
3
4
5
6
7
8
9
10
11

2.7 TRACKER_PROTO_CMD_SERVICE_QUERY_STORE_WITH_GROUP_ALL

获取 storage server 列表用来存储文件（指定组名）

• 请求body：

	@group_name：16字节字符串，组名
1

• 响应body：

    @group_name：16字节字符串，组名

    [   //列表开始

    @ip_addr：15字节字符串， storage server IP地址

    @port：8字节整数，storage server端口号

    ]  //列表结束

    @store_path_index：1字节整数，基于0的存储路径顺序号 
1
2
3
4
5
6
7
8
9
10
11

2.8 TRACKER_PROTO_CMD_SERVICE_QUERY_FETCH_ONE

获取一个 storage server 用来下载文件

2.9 TRACKER_PROTO_CMD_SERVICE_QUERY_UPDATE

获取 storage server 列表用来修改文件或文件附加信息

• 请求body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

• 响应body：

    @group_name：16字节字符串，组名

    @ip_addr：15字节字符串， storage server IP地址

    @port：8字节整数，storage server端口号
1
2
3
4
5

2.10 TRACKER_PROTO_CMD_SERVICE_QUERY_FETCH_ALL

获取 storage server 列表用来下载文件

• 请求body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

• 响应body：

    @group_name：16字节字符串，组名

    @ip_addr：15字节字符串， 第一个storage server IP地址

    @port：8字节整数，storage server端口号

    [   //列表开始

    @ip_addr：15字节字符串，其他storage server IP地址

    ]  //列表结束
1
2
3
4
5
6
7
8
9
10
11

三、发送给storage server的命令码

3.1 STORAGE_PROTO_CMD_UPLOAD_FILE

上传普通文件

3.2 STORAGE_PROTO_CMD_UPLOAD_APPENDER_FILE

上传 appender 类型文件

• 请求body：

	@store_path_index：1字节整数，基于0的存储路径顺序号 

	@meta_data_length：8字节整数，meta data（文件附加属性）长度，可以为0

	@file_size：8字节整数，文件大小

	@file_ext_name：6字节字符串，不包括小数点的文件扩展名，例如 jpeg、tar.gz

	@meta_data： meta_data_length字节字符串，文件附加属性，每个属性用字符 \x01分隔，名称key和取值value之间用字符 \x02分隔

	@file content：file_size字节二进制内容，文件内容 
1
2
3
4
5
6
7
8
9
10
11

• 响应body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

3.3 STORAGE_PROTO_CMD_UPLOAD_SLAVE_FILE

上传 slave 文件

• 请求body：

	@master_filename_length：8字节整数，主文件名长度 

	@meta_data_length：8字节整数，meta data（文件附加属性）长度，可以为0

	@file_size：8字节整数，文件大小

	@filename_prefix：16字节字符串， 从文件前缀名

	@file_ext_name：6字节字符串，不包括小数点的文件扩展名，例如 jpeg、tar.gz

	@master_filename：master_filename_length字节字符串，主文件名

	@meta_data：meta_data_length字节字符串，文件附加属性，每个属性记录用字符 \x01分隔，名称key和取值value之间用字符 \x02分隔

	@file content：file_size字节二进制内容，文件内容
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

• 响应body：

    @group_name：16字节字符串，组名
    
    @filename：不定长字符串，文件名
1
2
3

3.4 STORAGE_PROTO_CMD_DELETE_FILE

删除文件

• 请求body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

• 响应body：无

3.5 STORAGE_PROTO_CMD_SET_METADATA

设置 meta data（文件附加属性）

• 请求body：

	@filename_length：8字节整数，文件名长度

	@meta_data_length：8字节整数，meta data（文件附加属性）长度，可以为0   

	@op_flag：1字节字符，操作标记，取值说明如下：
	   'O' - 覆盖方式，覆盖原有meta data
	   'M' - merge方式，和原有meta data合并到一起，已存在的属性将被覆盖
	   
	@group_name：16字节字符串，组名 

	@filename：filename_length字节的字符串，文件名

	@meta_data：meta_data_length字节字符串，文件附加属性，每个属性记录用字符 \x01分隔，名称key和取值value之间用字符 \x02分隔
1
2
3
4
5
6
7
8
9
10
11
12
13

• 响应body：无

3.6 STORAGE_PROTO_CMD_DOWNLOAD_FILE

下载文件

• 请求body：

	@file_offset：8字节整数，文件偏移量

	@download_bytes：8字节整数，下载字节数

	@group name：16字节字符串，组名

	@filename：不定长字符串，文件名
1
2
3
4
5
6
7

• 响应body：

	@file_content：不定长二进制内容，文件内容   
1

3.7 STORAGE_PROTO_CMD_GET_METADATA

获取meta data（文件附加属性）

• 请求body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

• 响应body：

    @meta_data：不定长字符串，文件附加属性，每个属性记录用字符 \x01分隔，名称key和取值value之间用字符 \x02分隔
1

3.8 STORAGE_PROTO_CMD_QUERY_FILE_INFO

获取文件信息

• 请求body：

    @group_name：16字节字符串，组名

    @filename：不定长字符串，文件名
1
2
3

• 响应body：

    @file_size：8字节整数，文件大小

    @create_timestamp：8字节整数，文件创建时间（Unix时间戳）

    @crc32：8字节整数，文件内容CRC32校验码

	@source_ip_addr：16字节字符串，源storage server IP地址
1
2
3
4
5
6
7

3.9 STORAGE_PROTO_CMD_APPEND_FILE

追加文件内容

• 请求body：

    @appender_filename_length：8字节整数，appender文件名长度

    @file_size：8字节整数，文件大小

    @appender_filename：appender_filename_length字节数字符串，appender文件名

    @file_content：file_size字节数的二进制内容，追加的文件内容 
1
2
3
4
5
6
7

• 响应body：无

3.10 STORAGE_PROTO_CMD_MODIFY_FILE

修改文件内容

• 请求body：

	@appender_filename_length：8字节整数，appender文件名长度

	@file_offset：8字节整数，文件偏移量

	@file_size：8字节整数，文件大小

	@appender_filename：appender_filename_length字节数字符串，appender文件名

	@file_content：file_size字节数的二进制内容，新（目标）文件内容 
1
2
3
4
5
6
7
8
9

• 响应body：无

3.11 STORAGE_PROTO_CMD_TRUNCATE_FILE

改变文件大小

• 请求body：

	@appender_filename_length：8字节整数，appender文件名长度

	@truncated_file_size：8字节整数，truncate后的文件大小

	@appender_filename：appender_filename_length字节数字符串，appender文件名
1
2
3
4
5

• 响应body：无

3.12 STORAGE_PROTO_CMD_REGENERATE_APPENDER_FILENAME

appender类型文件改名为普通文件

• 请求body：

	@appender_filename：不定长字符串，appender文件名
1

• 响应body：

	@group name：16字节字符串，组名 
	@filename：不定长字符串，重新生成的文件名（普通类型）
1
2

四、命令码列表 （代号及取值）