简介FastDFS基础依赖库libfastcommon的1.0.7稳定版源码包面向搭建或升级FastDFS 5.05的运维人员与存储开发者解决编译安装时底层通用组件缺失的问题。压缩包共54个文件大小仅94KB以24个.h头文件和22个.c源文件为主体搭配Shell编译脚本、Makefile.in配置模板、spec打包文件及README、HISTORY、INSTALL等说明文档结构清晰适合Linux环境下直接编译与二次移植。当前已有565人浏览学习。通过阅读源码可深入理解FastDFS的哈希算法、内存池、日志记录、网络通信、任务队列与配置解析等核心实现有助于日常排错、性能调优以及基于libfastcommon的二次开发也是研究分布式文件系统底层机制的实用参考资料。1. libfastcommon-1.0.7.tar.gz装FastDFS时会被它卡住的第一个前置依赖在Linux服务器上编译FastDFS最让人翻车的往往不是tracker或storage本身而是configure阶段突然报出一句“fastcommon/hash.h: No such file or directory”。这时候十有八九是libfastcommon没有装好。libfastcommon-1.0.7.tar.gz说的就是FastDFS家族里那个“公共基础库”字符串处理、哈希表、ini配置解析、日志、网络socket封装、线程和共享内存封装全部放在这一个包里。tracker、storage、client库在编译和运行时都依赖它所以它不是“可有可无的工具包”而是整个FastDFS能跑起来的地基。这篇笔记就围绕这个包讲清楚三件事它里面到底有什么、怎么把它装对、以及装的过程中那些让人头疼的路径和版本问题。2. libfastcommon到底封装了什么从FastDFS的依赖关系看它的六个高频模块2.1 为什么FastDFS要把代码抽成一个公共库FastDFS的进程模型是典型的“多组件协作”tracker负责调度storage负责存储client SDK负责接入。这三个组件如果各自拷贝一份网络收发、配置解析、日志输出的代码版本一多就会变成灾难tracker修了一个bugstorage还带着旧实现日志格式不统一排查问题得同时看三套代码。libfastcommon存在的意义就是把这些“每个进程都要用”的公共逻辑收拢到一个库里让所有组件在编译期链接同一个实现运行期加载同一个动态库。作者选择“公共基础库”而不是“直接把代码include进来”还有一个现实原因内存管理。FastDFS的storage对内存的申请、释放、缓存淘汰有非常严格的约束公共代码如果不统一每个模块各自管理内存池一旦出现泄漏或越界根本没办法定位是哪个组件写的。libfastcommon把内存池、哈希表的key/value存储、日志缓冲全部收敛到库内部对外只暴露操作接口这样FastDFS各组件在内存行为上就是一致的。这也是为什么装FastDFS时必须先把这个库装对——版本不对后面所有组件都白编。2.2 六个高频模块哈希表、ini配置、日志、网络、线程与共享内存拆开libfastcommon-1.0.7的源码目录头文件集中在include/fastcommon和include/sf两个目录下。对我日常开发最有用的模块有六个第一个是common_hash这是FastDFS里使用频率最高的数据结构。common_hash_create传入容量和是否加锁的布尔值创建一个哈希表common_hash_add和common_hash_find分别用来写入和查找key是char加长度value是void。Fdfs的store_path索引、连接池复用、扩展属性管理都挂在这个哈希表上。它和glib的GHashTable相比最大特点是不需要反复malloc key可以传栈上的buffer内存分配次数少适合高并发小对象缓存。第二个是ini_file_reader。FastDFS的tracker.conf、storage.conf、client.conf全部用这套接口解析包括节区、键值对、注释行。接口长这样iniLoadFromFile加载文件iniGetStrValue读取字符串值iniGetIntValue读取整型值。它比标准C的getenv风格配置更清晰也比手写fgets解析更省事——支持section、支持整行注释、支持key带空格。第三个是日志模块封装了log_init、log_destroy、logInfo、logError等函数。这套日志支持按天滚动、按大小滚动、同时输出到syslog和文件。FastDFS的storage.binlog就是靠它写的tracker的选举日志也是。日志级别的控制参数是log_level从DEBUG到ERROR一共五档生产环境通常调到INFO。第四个是sockopt网络封装。FastDFS的TCP通信全部走这套封装包括socket创建、超时控制、TCP_NODELAY设置、收发缓冲调整。直接用裸socket写业务一个read要处理EINTR、EWOULDBLOCK、半包粘包libfastcommon把“连接管理、超时、熔断”这些通用逻辑抽成函数业务代码只关心字节流。这对tracker和storage之间的心跳、文件传输来说是一层很必要的隔离。第五个是pthread相关封装主要处理线程属性初始化、互斥锁、条件变量。FastDFS的work thread pool用到了它修改线程栈大小、绑定CPU、设置调度策略都在这层做。第六个是共享内存和进程间同步。storage的多进程模型里binlog索引、trunk空间分配都依赖共享内存这层封装把mmap和信号量的差异隐藏掉上层代码不用关心是System V还是POSIX接口。2.3 静态库与动态库双输出以及sf库的协作libfastcommon安装完成后lib目录下会同时出现libfastcommon.a、libfastcommon.so以及libsf.a、libsf.so。这里的sf目录是server framework的缩写早期版本里这部分代码还没有完全独立所以安装时会看到两个库。FastDFS的tracker进程在链接时实际依赖的是libsf这个库——它打包了server端的线程池、io调度、配置生命周期管理。如果编译FastDFS时只写了-lfastcommon而漏掉-lsf链接阶段就会报出undefined reference指向iniLoadFromFile或log_init这类符号。这种“双输出”的设计在C项目里很常见。静态库保证编译期符号完整动态库保证运行期内存布局统一。但带来的副作用是同一个环境下如果存在多个版本的libfastcommon动态链接器会按文件路径先到先得很容易出现“编译时用1.0.7的头文件接口运行时加载高版本动态库”这种错位。这也是后面第4章里几个坑的共同根源。3. 编译安装libfastcommon-1.0.7的最小流程三条命令和三个验证3.1 编译前置检查gcc、make和sudo权限动手编译前先在服务器上确认三件事gcc、make、写权限。命令如下gcc --version make --version idgcc的输出和make的输出分别确认编译器跟构建工具的版本。1.0.7这个版本出来的时间比较早代码风格偏传统C只要是gcc 4.8以上都能编译不需要很新的特性。id命令看当前用户uid如果不是root后面install步骤就得加sudo。这里想提醒一个细节检查gcc时别只看有没有还要看有没有装完整。有些精简安装的容器镜像里gcc命令存在但缺少crt1.o、libc-dev这类基础文件运行./make.sh时会以“cannot find -lc”这种形式报错。遇到这种情况先补build-essential或等价的基础包再继续。3.2 解压、编译、安装与TARGET_PREFIX参数拿到libfastcommon-1.0.7.tar.gz后最直接的安装流程是tar xzf libfastcommon-1.0.7.tar.gz cd libfastcommon-1.0.7 ./make.sh sudo ./make.sh installmake.sh脚本会先调用configure生成Makefile然后执行make。install步骤会把头文件拷贝到include目录把动态库和静态库拷贝到lib目录。默认情况下64位系统上动态库会放进/usr/lib64头文件放进/usr/include/fastcommon和/usr/include/sf。如果希望把它统一装到/usr/local下用TARGET_PREFIX指定前缀TARGET_PREFIX/usr/local ./make.sh sudo TARGET_PREFIX/usr/local ./make.sh installTARGET_PREFIX这个环境变量就是这版编译脚本里最重要的参数。它控制头文件和库文件的最终路径却不会自动把路径写进动态链接器的搜索目录。很多人在这一步踩坑库装进了/usr/local/lib但ldconfig没管那儿导致编译FastDFS时头文件找得到、运行tracker时动态库找不到。安装完成后自己补一条/sbin/ldconfig更重要。3.3 安装后的三项验证头文件、动态库缓存、版本宏安装结束别急着去编译FastDFS先花十秒钟验证三点。验证命令如下ls /usr/include/fastcommon/hash.h ls -l /usr/lib64/libfastcommon.so* /sbin/ldconfig -p | grep fastcommon第一条检查头文件是否真的在预期位置hash.h是核心头文件如果它不在说明TARGET_PREFIX指定的路径和后续编译时的-I参数不匹配。第二条检查动态库文件和它的软链正常情况下应该有libfastcommon.so.1和它指向的实体文件libfastcommon.so是供编译链接用的软链。第三条是确认动态链接器已经缓存了这个库。ldconfig -p的输出里看到“libfastcommon.so.1 /usr/lib64/libfastcommon.so.1”说明运行期加载没问题。如果只看到libfastcommon.a而看不到.so或者grep结果为空就得回头检查安装路径是不是在ldconfig的搜索范围内。动态库路径感知是三行里最容易翻车的一环。4. 安装libfastcommon和FastDFS联调避坑六条翻车现场4.1 现象启动tracker报错“libfastcommon.so.1: cannot open shared object file”这是编译完FastDFS、第一次启动tracker时最经典的错误。原因很直接libfastcommon.so被装在了动态链接器没有搜索的目录里运行时找不到。很多教程为了让环境干净把库装到/usr/local/lib下但ldconfig的默认搜索路径里并不包含这个目录。权威的方式是在/etc/ld.so.conf.d下建一个fastcommon.conf写入/usr/local/lib然后执行/sbin/ldconfig。优先用这种方式而不是直接改LD_LIBRARY_PATH因为后者只对当前shell生效重启后又是老样子。4.2 现象编译FastDFS时头文件能找到链接时报找不到“-lfastcommon”这个和4.1相反属于编译期路径错位。如果你的libfastcommon装到了/usr/local/lib而FastDFS编译时只默认找/usr/lib64那么链接器就会在最后的collect2阶段报错。解决思路不是去复制库文件而是让两边的路径统一要么FastDFS和libfastcommon都用默认前缀/usr要么都在make.sh时指定TARGET_PREFIX/usr/local。我一般会在服务器上写一个环境变量文件把CFLAGS和LDFLAGS固定好确保两个项目的include和lib路径完全一致。4.3 现象编译FastDFS时出现大量“undefined reference toiniGetStrValue”这个符号是libfastcommon里ini解析模块的导出函数。出现undefined reference通常有三个原因。一是FastDFS版本和libfastcommon版本不匹配例如用FastDFS 6.x去配1.0.7老库里根本没有新版接口。二是链接顺序错了-lfastcommon和-lsf被放在了源文件前面链接器从左到右扫描时会忽略后面的库。三是只链了libfastcommon但漏掉libsf因为tracker实际依赖的是sf库对ini模块的组合。排查时先用nm -D /usr/lib64/libfastcommon.so | grep iniGetStrValue看看符号到底在不在。4.4 现象头文件明明存在编译还是报“No such file or directory”这是include路径问题。libfastcommon安装后头文件放在/usr/include/fastcommon目录下所以业务代码里写的是#include fastcommon/hash.h而不是#include hash.h。如果你的编译选项里用了-I/usr/local/include又写了-I/usr/include要注意顺序编译器会按顺序查找。很多时候问题是自己写了-I/usr/include/fastcommon然后又用#include hash.h这样重复前缀导致路径变成/usr/include/fastcommon/hash.h反而找不到。经验做法是编译选项里只加-I/usr/include或-I/usr/local/include代码里统一带fastcommon/前缀。4.5 现象系统中同时存在多个版本的libfastcommonFastDFS版本升级后libfastcommon也会跟着升级。最典型的翻车场景服务器上原本有1.0.7的rpm包后来又手动编译安装了高版本动态链接器缓存的还是老版本路径运行时加载了旧库导致新接口调用直接段错误。排查时先用ldconfig -p | grep fastcommon把当前缓存列出来再用ls -l /usr/lib64/libfastcommon.so*看看软链指向哪里。如果版本混乱建议先把rpm或deb包卸载干净再统一用手动编译的方式安装一个版本不要混用。4.6 现象按老教程写的代码调用哈希表接口时编译不过这个问题很典型网上大量FastDFS二次开发文章是照着1.0.x的老接口写的比如common_hash_create的调用方式后来有调整。你拿1.0.7的头文件去编译但教程里的参数个数对不上。解决办法是以当前头文件为准打开include/fastcommon/hash.h看函数原型。libfastcommon的接口设计保持了很强的向后兼容性大部分函数只是增加参数而不是删除旧符号但老教程不一定说的是你这版最可靠的都是源码里那份头文件。5. 在自己的C程序里用它common_hash与ini_file_reader的读写例子5.1 用common_hash建立节点状态表libfastcommon的价值不只在FastDFS里它也可以拿出来直接用在其他C项目里。下面这个例子演示用common_hash维护一组节点状态#include fastcommon/hash.h #include stdio.h #include string.h int main() { common_hash_t hash; int ret common_hash_create(hash, 128, false); if (ret ! 0) { fprintf(stderr, common_hash_create failed, ret%d\n, ret); return 1; } const char *key node_1; long value 200; ret common_hash_add(hash, key, strlen(key), value); if (ret ! 0) { fprintf(stderr, common_hash_add failed, ret%d\n, ret); return 1; } void *result NULL; ret common_hash_find(hash, key, strlen(key), result); if (ret 0 result ! NULL) { printf(key%s, value%ld\n, key, *(long *)result); } common_hash_destroy(hash); return 0; }编译命令是gcc -o hash_demo hash_demo.c -I/usr/include -L/usr/lib64 -lfastcommon这段代码里common_hash_create的第三个参数是false表示这个哈希表不启用内部锁适合单线程场景。如果你的程序是多线程同时读写改成true更安全。common_hash_add的value是void*意味着你可以塞任何结构而不只是long但你要自己保证value的生命周期至少和哈希表一样长。common_hash_find返回的是void*的地址取出来之后要自己转回原类型。5.2 把配置文件解析结果放进哈希表第二个例子是把ini配置读进来然后转存到哈希表里。这在写FastDFS的脚本工具时很常见启动时解析配置后续频繁查询某个值每次都走iniGetStrValue效率低不如一次性放进哈希表。#include fastcommon/hash.h #include fastcommon/ini_file_reader.h #include stdio.h #include string.h int main() { IniContext ctx; int ret iniLoadFromFile(demo.conf, ctx); if (ret ! 0) { fprintf(stderr, iniLoadFromFile failed\n); return 1; } common_hash_t hash; common_hash_create(hash, 64, false); const char *ip iniGetStrValue(server, ip, ctx); const char *port iniGetStrValue(server, port, ctx); if (ip ! NULL port ! NULL) { common_hash_add(hash, ip, strlen(ip), (void*)ip); common_hash_add(hash, port, strlen(port), (void*)port); } void *out_ip NULL; common_hash_find(hash, ip, strlen(ip), out_ip); if (out_ip ! NULL) { printf(server ip is %s\n, (char *)out_ip); } common_hash_destroy(hash); iniFreeContext(ctx); return 0; }注意这里common_hash_add的value直接放了iniGetStrValue返回的指针这个指针的内存在iniFreeContext之后就会失效所以上面的代码顺序是先查完再释放context。这也反映出一个实际经验哈希表保存的value最好是拷贝出来的独立内存或者明确知道生命周期。如果你要长期持有配置值建议用strdup拷贝一份然后在清理哈希表时统一释放。5.3 编译参数与库链接顺序链接libfastcommon时有个容易忽略的规则-lfastcommon一定要写在源文件或目标文件之后。比如下面这条命令gcc -o conf_demo conf_demo.c -I/usr/include -L/usr/lib64 -lfastcommon如果写成gcc -o conf_demo -lfastcommon conf_demo.c在遇到undefined reference时也是同样的问题。因为GNU ld是从左到右解析符号的库放在前面时后面的目标文件里没有解析的符号再也找不到提供者。背后的原理是链接器只从库里提取“当前还未解析的符号”一旦库被扫过后续新出现的未定义符号不会回头再看这个库。6. 版本边界1.0.7和高版本怎么选动态库版本怎么验证libfastcommon-1.0.7不是越老越稳也谈不上越新越好关键看配套的FastDFS版本和操作系统。1.0.7常见于FastDFS 5.05到5.08时代如果你还在维护老项目版本锁死是明智的。真要升级建议同时升级FastDFS和libfastcommon并且把两个版本的匹配关系写进部署文档。用在高版本FastDFS上去配1.0.7运行时出现诡异段错误的概率非常高因为tracker调用了老库根本不存在的接口。运行时到底加载的是哪个版本可以用strings直接看strings /usr/lib64/libfastcommon.so.1 | grep -E 1\.0\.[0-9]这条命令会输出动态库文件里残留的版本字符串能和安装的版本对应上。比看文件修改时间更可靠因为rpm或deb包升级时会替换软链但文件内容骗不了人。也可以对比ldconfig -p的输出确认实际加载路径和当前安装路径一致。我的习惯是在每台服务器上留一个install_libfastcommon.sh解压目录名带上版本号例如libfastcommon-1.0.7-build这样即使过半年再回来ls也能看到机器上到底装的是哪版。这条经验救过我不少次希望帮到你。本文还有配套的精品资源点击获取