brpc 从零到一的构建与部署实战指南源码编译、依赖管理、测试与实例追踪【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/gh_mirrors/brpc6/brpc本文以 Apache brpc 官方文档 docs/cn/getting_started.md 为核心骨架结合当前仓库内的config_brpc.sh、CMakeLists.txt、example/echo_c 示例与 Dockerfile 等源码佐证系统讲解 brpc 在 Ubuntu、CentOS、macOS、Docker 等环境下的依赖准备、config_brpc.sh与 CMake 两条编译路线、样例运行与单元测试方法以及 tcmalloc、glog、thrift 等可选组件的链接注意事项。读完本文你将从零完成 brpc 的编译安装跑通第一个 echo 服务并具备按需定制构建选项、排查链接异常的能力。1. 构建总览为什么 brpc 鼓励静态链接brpc 的构建设计有一个核心理念鼓励静态链接依赖。这样做的直接收益是运行 brpc 服务的每台机器不再需要单独安装 gflags、protobuf、leveldb 等依赖库二进制自带全部依赖部署与迁移成本大幅降低。brpc 的三项基础依赖及其用途如下依赖用途gflags广泛用于定义全局选项如端口、超时、负载均衡算法等protobuf消息序列化与 RPC 服务接口定义leveldb 记录 RPC 调用用于链路追踪其中 leveldb 与 rpcz 的绑定关系可以在文档与源码中得到印证rpcz 是 brpc 自带的 RPC 追踪模块通过内置服务查看最近一段时间的 RPC 调用记录其落盘存储依赖 leveldb。从 CMakeLists.txt 可以看到无论使用 CMake 还是config_brpc.sh最终链接库集合都包含gflags、protobuf、leveldb、protoc、ssl、crypto、dl、z这一套基础依赖这正对应了文档中声明的依赖清单。2. 支持的环境总览brpc 官方支持以下五类编译环境本文后续小节将逐一给出完整步骤Ubuntu / LinuxMint / WSL第 3 节Fedora / CentOS第 4 节自己构建依赖的 Linux第 5 节macOS第 6 节Docker第 7 节需要特别说明的是macOS 版本在相同硬件条件下性能可能明显低于 Linux 版本。如果你的服务对性能敏感请勿将 macOS 作为生产环境。3. Ubuntu/LinuxMint/WSL 编译指南3.1 依赖准备Debian 系发行版Ubuntu、LinuxMint、WSL使用 apt 安装全部基础依赖sudo apt-get install -y git g make libssl-dev libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev可选依赖按需安装静态链接 leveldb 需要 snappysudo apt-get install -y libsnappy-dev通过源码编译生成 leveldb 静态库当发行版不自带静态库时使用git clone --recurse-submodules https://github.com/google/leveldb.git mkdir -p build cd build cmake -DCMAKE_BUILD_TYPERelease -DCMAKE_POSITION_INDEPENDENT_CODEON .. cmake --build . sudo cp -r ../include/leveldb /usr/include/ sudo cp libleveldb.a /usr/lib/注意-DCMAKE_POSITION_INDEPENDENT_CODEON很关键它让 leveldb 以 PIC位置无关代码方式编译否则后续静态链接进 brpc 共享库或可执行文件时会报重定位错误。在样例中启用 cpu/heap profilersudo apt-get install -y libgoogle-perftools-dev运行单元测试需要 gtestDebian 系默认不编译 gtest需手动编译sudo apt-get install -y cmake libgtest-dev cd /usr/src/gtest sudo cmake . sudo make sudo mv lib/libgtest* /usr/lib/ cd -如果/usr/src/gtest不存在请尝试/usr/src/googletest/googletest不同 Ubuntu 版本源码目录位置有差异。3.2 使用 config_brpc.sh 编译 brpc克隆 brpc 仓库并进入项目目录后执行$ sh config_brpc.sh --headers/usr/include --libs/usr/lib $ make脚本工作原理可以从 config_brpc.sh 的源码看出端倪它用getopt解析参数将--headers/--libs提供的路径转换成绝对路径readlink -f/realpath随后在指定路径中递归查找libgflags、libprotobuf、libleveldb、libssl等库文件并自动探测 protobuf 版本、gflags 命名空间最终生成config.mk与src/butil/config.h两个构建配置文件make依据它们完成编译。值得一提的是脚本会在--with-glog时向src/butil/config.h写入BRPC_WITH_GLOG宏这一机制决定了 brpc 内部日志实现与 glog 的切换。常用配置选项选项作用--headersPATH指定头文件搜索路径可传多个空格分隔--libsPATH指定库文件搜索路径可传多个空格分隔--ccclang --cxxclang切换编译器为 clang--nodebugsymbols不链接调试符号生成更轻量的二进制--with-glog使用 glog 版日志--with-thrift启用 thrift 支持注意从 config_brpc.sh 可以看到--cc和--cxx必须同时设置或同时不设置在 Darwin 平台脚本默认使用 clang其他平台默认使用 gcc/g。运行样例$ cd example/echo_c $ make $ ./echo_server $ ./echo_client默认情况下样例链接 brpc 的静态库。如果你想链接 brpc 的共享库请依次执行make clean和LINK_SO1 make。这一机制在 example/echo_c/Makefile 中有明确实现Linux 下默认用-Wl,-Bstatic $(STATIC_LINKINGS) -Wl,-Bdynamic静态链接 brpc 与依赖当LINK_SO非空时改用-lbrpc动态链接。运行测试$ cd test $ make $ sh run_tests.sh3.3 使用 cmake 编译 brpcmkdir build cd build cmake .. cmake --build . -j6对于 cmake 3.13也可以使用如下更简洁的命令cmake -B build cmake --build build -j6CMake 路线的关键选项均定义在 CMakeLists.txt 顶部CMake 选项默认值作用-DWITH_GLOGONOFF使用 glog 日志-DWITH_THRIFTONOFF启用 thrift framed 协议-DWITH_DEBUG_SYMBOLSOFFON关闭调试符号-DWITH_RDMAONOFF启用 RDMA 支持-DWITH_MESALINKONOFF使用 MesaLinkOpenSSL 替代实现-DWITH_BORINGSSLONOFF使用 BoringSSL-DWITH_SNAPPYONOFF链接 snappy-DBUILD_UNIT_TESTSONOFF构建单元测试-DBUILD_BRPC_TOOLSOFFON构建 brpc 工具集其他实用技巧要帮助 VSCode 或 EmacsLSP正确理解代码添加-DCMAKE_EXPORT_COMPILE_COMMANDSON生成compile_commands.json。要修改编译器为 clang修改环境变量CC和CXX为clang和clang。不想链接调试符号先移除build/CMakeCache.txt再用-DWITH_DEBUG_SYMBOLSOFF重新执行 cmake。想让 brpc 使用 glog用-DWITH_GLOGON执行 cmake。要启用 thrift 支持先安装 thrift再用-DWITH_THRIFTON执行 cmake。用 cmake 运行样例$ cd example/echo_c $ cmake -B build cmake --build build -j4 $ ./echo_server $ ./echo_client上述操作默认链接 brpc 的静态库。若想链接共享库先移除CMakeCache.txt再用-DLINK_SOON重新执行 cmake该选项定义于 example/echo_c/CMakeLists.txt。运行测试$ mkdir build cd build cmake -DBUILD_UNIT_TESTSON .. make make test3.4 编译完成后的验证echo 样例源码导读config_brpc.sh与 CMake 两种路线殊途同归最终产物落在output/lib与output/include目录。为了让你对构建成功有一个可验证的感性认识这里简要解读 example/echo_c 的样例结构echo.proto定义EchoRequest/EchoResponse消息与EchoService.Echo方法server.cpp实现EchoServiceImpl通过brpc::Server::AddService注册服务server.Start启动监听默认端口 8000可用--port修改RunUntilAskedToQuit等待 Ctrl-Cclient.cpp创建brpc::Channelchannel.Init指向0.0.0.0:8000构建EchoService_Stub后每 1 秒发送一次hello world请求并打印响应与延迟。运行./echo_server 后再运行./echo_client客户端会输出类似Received response from ...: hello world ... latency...us的日志同时服务端打印收到请求的来源地址与内容这就是构建成功最直接的验证。4. Fedora/CentOS 编译指南4.1 依赖准备CentOS 一般需要先安装 EPEL 仓库否则很多包默认不可用sudo yum install epel-release安装依赖sudo yum install git gcc-c make openssl-devel gflags-devel protobuf-devel protobuf-compiler leveldb-devel可选依赖样例中启用 cpu/heap profilersudo yum install gperftools-devel运行测试sudo yum install gtest-devel4.2 使用 config_brpc.sh 编译 brpc$ sh config_brpc.sh --headers/usr/include --libs/usr/lib64 /usr/bin $ make与 Ubuntu 的差异在于--libs需要同时包含/usr/lib6464 位库目录与/usr/bin用于定位 protoc 等可执行文件见 config_brpc.sh 中find_bin的逻辑。其余选项与 Ubuntu 完全一致--cxxclang --ccclang切换 clang--nodebugsymbols去掉调试符号--with-glog启用 glog--with-thrift启用 thrift 支持。运行样例$ cd example/echo_c $ make $ ./echo_server $ ./echo_client动态链接方式同样为make clean后执行LINK_SO1 make。运行测试$ cd test $ make $ sh run_tests.sh4.3 使用 cmake 编译 brpcFedora/CentOS 上的 CMake 路线与 Ubuntu 完全相同直接参考第 3.3 节即可此处不再赘述。4.4 使用 vcpkg 编译 brpcvcpkg 是一个全平台支持的 C 包管理器也可以用它一键编译 brpc$ git clone https://github.com/microsoft/vcpkg.git $ ./bootstrap-vcpkg.bat # 使用 powershell $ ./bootstrap-vcpkg.sh # 使用 bash $ ./vcpkg install brpcvcpkg 会自动处理 brpc 及其依赖的获取与构建适合希望省去手工装依赖的开发者。5. 自己构建依赖的 Linux当发行版仓库中的依赖版本过旧或需要自定义依赖如自行编译 protobuf/leveldb时可以采用这种方式。5.1 依赖准备brpc 默认会构建出静态库和共享库两个版本因此其依赖也需要同时具备静态库与共享库两种形态。以 gflags 为例它默认不构建共享库需要给 cmake 指定选项改变这一行为$ cmake . -DBUILD_SHARED_LIBS1 -DBUILD_STATIC_LIBS1 $ make5.2 编译 brpc假设 gflags 被克隆在../gflags_dev进入 brpc 项目目录后运行$ sh config_brpc.sh --headers../gflags_dev /usr/include --libs../gflags_dev /usr/lib64 $ make这里给--headers和--libs传递了多个路径脚本会在这些位置递归检索依赖。你还可以把所有依赖连同 brpc 一起打包到一个目录中然后把该目录传给--headers/--libs脚本会递归搜索所有子目录直到找到必须的文件。这一点可以在 config_brpc.sh 的find_dir_of_lib、find_dir_of_header等函数中看到实现——它们使用find -L ${LIBS_IN} -name lib${1}.a ...这样的递归查找方式。官方给出的目录化组织示例$ ls my_dev gflags_dev protobuf_dev leveldb_dev brpc_dev $ cd brpc_dev $ sh config_brpc.sh --headers.. --libs.. $ make其余开关--cxxclang --ccclang、--nodebugsymbols、--with-glog、--with-thrift与前述一致。CMake 路线同样参考第 3.3 节。6. macOS 编译指南6.1 平台注意事项性能提示在相同硬件条件下macOS 版 brpc 的性能可能明显差于 Linux 版。如果你的服务是性能敏感的请不要使用 macOS 作为生产环境。Apple Siliconmaster HEAD 已支持 M1 系列芯片M2 未测试过欢迎通过 issues 报告遗留的 warning/error。6.2 依赖准备brew install ./homebrew-formula/protobuf.rb brew install openssl git gnu-getopt coreutils gflags leveldb注意这里特别安装了gnu-getopt和coreutils——因为 config_brpc.sh 在 Darwin 平台会检查getopt -V是否为 gnu-getopt 的实现输出为 --同时需要 GNU 版realpath缺少它们脚本会直接退出。可选依赖样例中启用 cpu/heap profilerbrew install gperftools运行测试需要 gtest。先运行brew install googletest看看 homebrew 是否支持老版本没有不支持则手动编译git clone https://github.com/google/googletest -b release-1.10.0 cd googletest/googletest mkdir build cd build cmake -DCMAKE_CXX_FLAGS-stdc11 .. make编译完成后将include/和lib/目录复制到/usr/local/include和/usr/local/lib以便所有应用都能使用 gtest。6.3 OpenSSL 路径问题Monterey 中 openssl 的安装位置可能不再位于/usr/local/opt/openssl而可能在/opt/homebrew/Cellar目录下。如果编译时报告找不到 openssl先运行brew link openssl --force看看/usr/local/opt/openssl是否出现没有的话自行设置软链sudo ln -s /opt/homebrew/Cellar/openssl3/3.0.3 /usr/local/opt/openssl。注意该命令中 openssl 的目录可能随环境变化可通过brew info openssl查看实际路径。实际上config_brpc.sh 在 Darwin 平台会自动探测/usr/local/opt/openssl与/opt/homebrew/Cellar两个位置并把它们加入头文件与库搜索路径这为上述两种安装布局都提供了兜底。6.4 使用 config_brpc.sh 编译 brpc$ sh config_brpc.sh --headers/usr/local/include --libs/usr/local/lib --ccclang --cxxclang $ makeMacOS Monterey 下 brew 安装路径可能改变如有路径相关错误可尝试$ sh config_brpc.sh --headers/opt/homebrew/include --libs/opt/homebrew/lib --ccclang --cxxclang $ make其余选项--nodebugsymbols、--with-glog、--with-thrift与前述一致。运行样例$ cd example/echo_c $ make $ ./echo_server $ ./echo_client动态链接同样用make cleanLINK_SO1 make。注意 Darwin 平台下静态库.a必须在链接命令中显式给出这一逻辑在 example/echo_c/Makefile 中已有注释说明。运行测试$ cd test $ make $ sh run_tests.sh6.5 使用 cmake 编译 brpc参考第 3.3 节。CMake 在 Darwin 平台会自动把 OpenSSL 根目录指向/usr/local/opt/openssl见 CMakeLists.txt并链接 CoreFoundation、CoreGraphics 等系统框架见 CMakeLists.txt。7. Docker 编译指南使用 Docker 编译 brpc 可以完全隔离宿主环境差异$ mkdir -p ~/brpc $ cd ~/brpc $ git clone https://github.com/apache/brpc.git $ cd brpc $ docker build -t brpc:master . $ docker images $ docker run -it brpc:master /bin/bash仓库根目录的 Dockerfile 给出了镜像内的构建过程佐证它基于ubuntu:20.04通过 apt 安装git g make libssl-dev libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev libsnappy-dev等依赖随后执行RUN cd brpc sh config_brpc.sh --headers/usr/include --libs/usr/lib \ make -j $(nproc)也就是说进入容器后 brpc 已完成编译可以直接进入example/echo_c运行样例或继续执行测试。8. 支持的依赖版本范围brpc 对各依赖有明确的版本兼容区间选择合适的版本能避免大量编译与运行期问题依赖支持版本备注GCC4.8 - 11.2C11 默认启用以去除 boost 依赖如 atomicGCC7 中 over-aligned 问题暂时被禁止Clang3.5 - 4.0无已知问题glibc2.12 - 2.25无已知问题protobuf3.0 - 3.251.8.0 版本引入部分 proto3 语法后不再兼容 pb 2.xpb 3.x 的 Arena 至今未被支持gflags2.0 - 2.2.1无已知问题openssl0.97 - 1.1被 https 功能需要tcmalloc1.7 - 2.5brpc 默认不链接 tcmalloc用户按需链接glog3.3与 brpc 默认日志实现冲突二选一valgrind3.8brpc 自动检测 valgrind 并注册 bthread 栈thrift0.9.3 - 0.11.0无已知问题几个需要重点展开的版本注意事项8.1 GCC 版本细节C11 默认启用因此编译器最低要求为支持 C11 的版本config_brpc.sh 与 CMakeLists.txt 都会在 GCC 低于 4.8 时直接报错退出。请在 makefile 的 cxxflags 中增加-D__const____unused__选项以避免 gcc4 中的 errno 问题。这一宏实际上已被 config_brpc.sh 与 CMakeLists.txt 自动加入 CPPFLAGS源码注释明确说明这是为了避免 GCC4.8 对 TLS 变量的过度优化对应上游 issue #1693。使用其他版本的 gcc 可能会产生编译警告可联系社区修复。8.2 protobuf 版本边界1.8.0 版本中相关 PR 引入了部分 proto3 语法因此目前 brpc 不再兼容 pb 2.x 版本如果你希望使用 pb 2.x需要使用 1.8.0 之前的 brpc 版本。另外从 config_brpc.sh 的源码可以看到当探测到 protobuf 版本 4.22GOOGLE_PROTOBUF_VERSION 4022000时脚本会自动要求并链接一长串absl_*目标库absl_strings、absl_sync 等同时把标准切换到 C17否则使用-stdc0x。这一自适应逻辑在 CMakeLists.txt 中也有对应实现。这意味着高版本 protobuf4.21会引入 abseil 依赖你需要同时安装 abseil 库。8.3 tcmalloc 的使用陷阱brpc 默认不链接 tcmalloc用户按需自行链接。tcmalloc 与 glibc 内置 ptmalloc 相比通常能提升性能但不同版本的 tcmalloc 表现可能迥异例如 tcmalloc 2.1 与 1.7、2.5 相比可能让 brpc 多线程样例性能显著恶化由 tcmalloc 中的一个自旋锁导致甚至小版本号之间表现也不同。当程序表现不符合预期时移除 tcmalloc 再尝试其他版本。用 gcc 4.8.2 编译然后链接更早版本 GCC 编译的 tcmalloc可能会让程序在main()函数之前挂掉或死锁遇到此类问题时请用同一个 GCC 重新编译 tcmalloc。另一个常见问题是tcmalloc 不会像 ptmalloc 一样及时把内存归还给系统。因此当发生无效内存访问时程序可能不会直接挂掉而是可能在不相关的位置挂掉甚至一直不挂。当程序出现怪异的内存问题时优先尝试移除 tcmalloc。如果要使用 cpu profiler 或 heap profiler需要链接libtcmalloc_and_profiler.a——这两个 profiler 都基于 tcmalloc 实现而 contention profiler 不需要 tcmalloc。移除 tcmalloc 时不仅要移除 tcmalloc 的链接也要移除宏-DBRPC_ENABLE_CPU_PROFILER。8.4 glog 与默认日志的取舍brpc 实现了一个默认的日志功能源码位于 src/butil/logging.h它与 glog 冲突。要替换成 glog可以给config_brpc.sh增加--with-glog选项或给 cmake 增加-DWITH_GLOGON选项。切换后src/butil/config.h中的BRPC_WITH_GLOG宏会被置为 1brpc 的日志调用会改走 glog 实现。8.5 其他依赖openssl被 https 功能需要版本范围 0.97 - 1.1更现代的版本亦可以实际编译结果为准。valgrindbrpc 会自动检测 valgrind随后注册 bthread 栈不支持老版本如 3.2。thrift支持 0.9.3 - 0.11.0。从 config_brpc.sh 可以看到启用--with-thrift后会追加-DENABLE_THRIFT_FRAMED_PROTOCOL宏并链接libthriftnb必要时附带-levent -lthrift还会根据 thrift 版本判断是否定义_THRIFT_VERSION_LOWER_THAN_0_11_0_以适配 API 差异。9. 实例追踪trackme_server在构建与部署之外brpc 还提供了一个实例追踪工具帮助你在生产环境中定位和监控所有 brpc 实例。使用方法很简单在某处运行 tools/trackme_server启动需要被追踪的 brpc 实例时加上-trackme_serverSERVER参数trackme_server 会周期性地从各实例收到 ping 消息并打印日志你可以从日志中聚合出所有实例的地址再调用实例的内置服务如 /status、/vars、/connections 等参见 builtin_service获取更多运行信息。这一机制适用于服务实例数量较多、需要统一盘点与健康巡检的部署场景配合 brpc 自带的监控体系可以快速建立实例清单。10. 快速排查清单把前面各节的易错点汇总为一份自查清单便于编译失败时快速定位依赖不齐确认 gflags、protobuf含 protoc、leveldb 均已安装高版本 protobuf 需额外安装 abseil。--cc/--cxx必须成对出现只设置其中一个config_brpc.sh 会直接报错退出。macOS 缺少 gnu-getopt/coreutilsconfig_brpc.sh在 Darwin 平台强制要求它们否则脚本报错。openssl 找不到macOS 下优先brew link openssl --force失败则手动软链到/usr/local/opt/openssl。leveldb 静态链接失败通过源码编译 leveldb 时务必加-DCMAKE_POSITION_INDEPENDENT_CODEON并安装 snappy。编译选项改动后缓存残留切换 CMake 选项如LINK_SO、WITH_DEBUG_SYMBOLS前先删除build/CMakeCache.txt切换样例链接方式前先make clean。程序在 main 之前挂掉/死锁大概率是 tcmalloc 与 GCC 版本不匹配用同一 GCC 重编 tcmalloc或直接移除 tcmalloc。性能异常先检查是否链接了表现不佳的 tcmalloc 版本如 2.1替换或移除后对比。生产环境性能敏感避免在 macOS 上部署 brpc 服务。通过以上九个检查点配合 config_brpc.sh 生成的config.mk与src/butil/config.h进行核对绝大多数构建问题都能在几分钟内定位解决。【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/gh_mirrors/brpc6/brpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考