BuildBuddy故障排除手册：常见问题与解决方案大全-平芜编程栈

BuildBuddy故障排除手册：常见问题与解决方案大全

【免费下载链接】buildbuddyBuildBuddy is an open source Bazel build event viewer, result store, remote cache, and remote build execution platform.项目地址: https://gitcode.com/gh_mirrors/bu/buildbuddy

BuildBuddy是一个开源的Bazel构建事件查看器、结果存储、远程缓存和远程构建执行平台，在使用过程中可能会遇到各种问题。本手册汇总了BuildBuddy的常见故障及解决方案，帮助用户快速定位并解决问题，确保构建过程顺畅高效。

远程执行（RBE）故障排除

远程连接/协议失败：执行失败

此错误通常表示缓存写入超时。默认情况下，Bazel的remote_timeout标志将所有远程执行调用限制为60秒。

解决方案：建议使用以下标志增加远程超时时间：

--remote_timeout=10m

这些耗时的写入仅在工件最初写入缓存时发生一次，后续构建不应再出现。

远程连接/协议失败：执行失败 DEADLINE_EXCEEDED

这一错误同样是缓存写入超时的信号。Bazel默认的remote_timeout限制了远程执行调用时间。

解决方案：通过以下命令延长超时时间：

--remote_timeout=10m

exec user process caused "exec format error"

当构建配置为darwin（Mac OSX）CPU，但尝试在Linux执行器上运行时会出现此错误。BuildBuddy Cloud的免费层不包含Mac执行器。

解决方案：如果需要在BuildBuddy Cloud账户中添加Mac执行器，请联系销售团队。

rpc error: code = Unavailable desc = No registered executors.

此错误与上述"exec format error"原因相同，即构建配置为darwin CPU却在Linux执行器上运行。

解决方案：如需Mac执行器，请联系销售团队获取相关服务。

WARNING: Remote Cache: UNAVAILABLE: io exception

当Bazel无法与BuildBuddy维持长时间TCP连接时可能发生此错误。

排查与解决步骤：

运行bazel --remote_grpc_log=grpc.log捕获gRPC流量，使用BuildBuddy CLI的bb print --grpc_log=<path-to-file>/grpc.log将protobuf格式日志转换为JSON。
若日志中出现"Connection reset by peer"等网络错误，可能是中间代理或网关（如AWS NAT Gateway）过早终止空闲连接。
尝试调整Linux网络设置：

sudo sysctl -w net.ipv4.tcp_keepalive_time=180 sudo sysctl -w net.ipv4.tcp_keepalive_intvl=60 sudo sysctl -w net.ipv4.tcp_keepalive_probes=5

这些设置会使Linux内核更早、更频繁地发送保活探针，防止中间代理/网关断开空闲连接。

CacheNotFoundException: Missing digest

远程构建执行期间，Bazel可能会遇到CacheNotFoundException错误，提示“Missing digest”。

解决方案：

复制缺失blob的哈希，导航到调用URL -> Cache -> "Cache requests"，将哈希粘贴到过滤器输入框，查看Bazel是否尝试上传blob到BuildBuddy远程缓存。
若上传失败，可通过--remote_retries（默认5次）和--remote_retry_max_delay（默认5秒）配置重试次数和延迟。Bazel 8及以上版本可使用--experimental_collect_system_network_usage收集网络使用数据，该数据会显示在调用页面的“Timing”选项卡中。
若Bazel未尝试上传缺失的blob，可使用以下标志：

--experimental_remote_cache_lease_extension --experimental_remote_cache_ttl --experimental_remote_cache_eviction_retries=5

若上述方法无效，运行bazel clean --noasync手动清除本地状态，关闭Bazel JVM后重新构建。排查时建议使用--disk_cache=''禁用本地磁盘缓存，并避免使用任何远程缓存代理解决方案。

图：BuildBuddy缓存请求卡片界面，可用于查看缓存请求状态和相关信息

上传速度慢问题解决

构建事件协议（BEP）上传超时

此错误意味着bes_timeout标志设置的时间可能不足以让Bazel完成所有构建工件的上传。

解决方案：建议使用以下标志增加上传超时时间：

--bes_timeout=600s

这些缓慢的上传仅在工件最初写入缓存时发生一次，后续构建不应再出现。

等待构建事件上传

如果构建已完成，但经常需要等待构建事件上传，可能是在网络受限环境中上传大型构建工件（如docker镜像或大型二进制文件）。

解决方案：对于网络受限环境，建议使用以下标志运行：

--noremote_upload_local_results

这将上传构建、测试和分析日志，但不会上传可能需要更长时间上传的大型构建工件。

BuildBuddy缓存工作原理

理解BuildBuddy的缓存工作原理有助于更好地排查缓存相关问题。BuildBuddy的缓存读取和写入流程如下：

图：BuildBuddy缓存读取流程示意图，展示了Bazel与BuildBuddy App之间的交互及缓存读取过程

图：BuildBuddy缓存写入流程示意图，展示了Bazel向BuildBuddy App写入缓存的过程及数据验证机制

BuildBuddy故障排除手册：常见问题与解决方案大全