本页面介绍了如何远程缓存、设置服务器以托管缓存,以及如何使用远程缓存运行构建。
开发者团队和/或持续集成 (CI) 系统使用远程缓存来共享构建输出。如果您的构建可以重现,则一台机器的输出可以安全地在另一台机器上重复使用,从而显著加快构建速度。
概览
Bazel 将构建拆分为离散步骤,这些步骤称为操作。每项操作都有输入、输出名称、命令行和环境变量。系统会为每个操作明确声明必需的输入和预期输出。
您可以将服务器设置为构建输出(即这些操作输出)的远程缓存。这些输出由一个输出文件名列表及其内容的哈希值组成。借助远程缓存,您可以重复使用其他用户的构建中的构建输出,而不必在本地构建每个新的输出。
如需使用远程缓存,请执行以下操作:
- 将服务器设置为缓存的后端
- 配置 Bazel 构建以使用远程缓存
- 使用 Bazel 0.10.0 或更高版本
远程缓存会存储两种类型的数据:
- 操作缓存,是操作哈希到操作结果元数据的映射。
- 输出文件的内容可寻址存储区 (CAS)。
请注意,远程缓存还会为每个操作额外存储 stdout 和 stderr。因此,检查 Bazel 的 stdout/stderr 不是估算缓存命中的理想信号。
构建如何使用远程缓存
将服务器设置为远程缓存后,您可以通过多种方式使用缓存:
- 对远程缓存执行读写操作
- 读取和/或写入远程缓存(特定目标除外)
- 仅从远程缓存读取
- 完全不使用远程缓存
当您运行可以对远程缓存执行读写操作的 Bazel 构建时,构建会执行以下步骤:
- Bazel 会创建需要构建的目标的图,然后创建必需的操作列表。每项操作都声明了输入和输出文件名。
- Bazel 会检查本地机器中是否存在现有的构建输出,并重复使用找到的所有输出。
- Bazel 会检查缓存中是否存在现有构建输出。如果找到输出,则 Bazel 会检索相应输出。这是缓存命中。
- 对于未找到输出的必需操作,Bazel 会在本地执行操作并创建所需的构建输出。
- 新构建输出会上传到远程缓存。
将服务器设置为缓存的后端
您需要设置一台服务器来充当缓存的后端。HTTP/1.1 服务器可以将 Bazel 的数据视为不透明字节,因此许多现有服务器可以用作远程缓存后端。Bazel 的 HTTP 缓存协议支持远程缓存。
您负责选择、设置和维护将存储缓存输出的后端服务器。选择服务器时,请考虑以下因素:
- 网速。例如,如果您的团队位于同一办公室,您可能需要运行自己的本地服务器。
- 安全性。远程缓存将包含您的二进制文件,因此必须确保安全。
- 便于管理。例如,Google Cloud Storage 是一项全代管式服务。
有许多后端可用于远程缓存。选项包括:
nginx
nginx 是一种开源网络服务器借助 [WebDAV 模块],它可以用作 Bazel 的远程缓存。在 Debian 和 Ubuntu 上,您可以安装 nginx-extras
软件包。在 macOS 上,nginx 可通过 HomeBrer 获取:
brew tap denji/nginx
brew install nginx-full --with-webdav
以下是 nginx 的配置示例。请注意,您需要将 /path/to/cache/dir
更改为 nginx 在其中具有读写权限的有效目录。如果您的输出文件较大,则可能需要将 client_max_body_size
选项更改为较大的值。服务器将需要其他配置,例如身份验证。
nginx.conf
中 server
部分的配置示例:
location /cache/ {
# The path to the directory where nginx should store the cache contents.
root /path/to/cache/dir;
# Allow PUT
dav_methods PUT;
# Allow nginx to create the /ac and /cas subdirectories.
create_full_put_path on;
# The maximum size of a single file.
client_max_body_size 1G;
allow all;
}
bazel-remote
bazel-remote 是一个开源远程构建缓存,您可以在自己的基础架构上使用。自 2018 年初以来,它已在多家公司成功用于生产环境。请注意,Bazel 项目不提供 bazel-remote 技术支持。
此缓存会将内容存储在磁盘上,并提供垃圾回收来强制执行存储空间上限并清理未使用的工件。该缓存以 [Docker 映像] 形式提供,其代码可在 GitHub 上获取。REST 和 gRPC 远程缓存 API 均受支持。
如需了解如何使用,请参阅 GitHub 页面。
Google Cloud Storage
[Google Cloud Storage] 是一种全代管式对象存储,提供与 Bazel 的远程缓存协议兼容的 HTTP API。您必须拥有已启用结算功能的 Google Cloud 帐号。
如需将 Cloud Storage 用作缓存,请执行以下操作:
创建存储分区。 由于网络带宽对远程缓存非常重要,因此请确保选择离您最近的存储分区位置。
为 Bazel 创建一个服务帐号,以便向 Cloud Storage 进行身份验证。请参阅创建服务帐号。
生成 JSON 密钥,然后将其传递给 Bazel 进行身份验证。请妥善存储密钥,因为任何拥有密钥的人都可以在您的 GCS 存储分区中读取和写入任意数据。
通过将以下标志添加到 Bazel 命令来连接到 Cloud Storage:
- 使用
--remote_cache=https://storage.googleapis.com/bucket-name
标志将以下网址传递给 Bazel:其中bucket-name
是您的存储分区的名称。 - 使用标记
--google_credentials=/path/to/your/secret-key.json
传递身份验证密钥,或者使用--google_default_credentials
标记以使用应用身份验证。
- 使用
您可以将 Cloud Storage 配置为自动删除旧文件。为此,请参阅管理对象生命周期。
其他服务器
您可以将任何支持 PUT 和 GET 的 HTTP/1.1 服务器设置为缓存的后端。用户曾报告在缓存后端(例如 Hazelcast、Apache httpd 和 AWS S3)方面取得了成功。
身份验证
从 0.11.0 版开始,Bazel 已添加对 HTTP 基本身份验证的支持。您可以通过远程缓存网址将用户名和密码传递给 Bazel。语法为 https://username:password@hostname.com:port/path
。请注意,HTTP 基本身份验证通过网络以明文形式传输用户名和密码,因此请务必始终将其与 HTTPS 搭配使用。
HTTP 缓存协议
Bazel 支持通过 HTTP/1.1 进行远程缓存。该协议在概念上很简单:二进制数据 (BLOB) 通过 PUT 请求上传,并通过 GET 请求下载。操作结果元数据存储在路径 /ac/
下,输出文件存储在路径 /cas/
下。
例如,假设某个在 http://localhost:8080/cache
下运行的远程缓存。对于具有 SHA256 哈希 01ba4719...
的操作,请求下载操作结果元数据的 Bazel 请求如下所示:
GET /cache/ac/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b HTTP/1.1
Host: localhost:8080
Accept: */*
Connection: Keep-Alive
将包含 SHA256 哈希 15e2b0d3...
的输出文件上传到 CAS 的 Bazel 请求将如下所示:
PUT /cache/cas/15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225 HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Length: 9
Connection: Keep-Alive
0x310x320x330x340x350x360x370x380x39
使用远程缓存运行 Bazel
将服务器设置为远程缓存后,要使用远程缓存,您需要向 Bazel 命令添加标志。请参阅下面的配置及其标志列表。
您可能还需要配置身份验证,这取决于您的所选服务器。
您可能需要将这些标志添加到 .bazelrc
文件中,这样就无需在每次运行 Bazel 时都指定它们。根据您的项目和团队动态,您可以向符合以下要求的 .bazelrc
文件添加标志:
- 在本地机器上
- 在项目的工作区中,已与团队共享
- 在 CI 系统上
对远程缓存执行读写操作
注意谁可以向远程缓存写入数据。您可能只想让 CI 系统能够向远程缓存写入数据。
使用以下标志对远程缓存执行读写操作:
build --remote_cache=http://your.host:port
除 HTTP
之外,还支持以下协议:HTTPS
、grpc
、grpcs
。
除上述标志外,请使用以下标志,仅从远程缓存中读取数据:
build --remote_upload_local_results=false
从远程缓存中排除特定目标
如需使用远程缓存排除特定目标,请使用 no-remote-cache
标记该目标。例如:
java_library(
name = "target",
tags = ["no-remote-cache"],
)
从远程缓存中删除内容
从远程缓存中删除内容是服务器管理工作的一部分。如何从远程缓存中删除内容取决于您设置为缓存的服务器。删除输出时,请删除整个缓存或删除旧输出。
缓存的输出结果以一组名称和哈希值的形式存储。删除内容时,无法区分哪些输出属于特定 build。
您可能需要从缓存中删除内容,以便:
- 在缓存中毒后创建干净缓存
- 通过删除旧输出来减少占用的存储空间
Unix 套接字
远程 HTTP 缓存支持通过 unix 网域套接字进行连接。此行为类似于 curl 的 --unix-socket
标志。使用以下代码配置 unix 网域套接字:
build --remote_cache=http://your.host:port
build --remote_proxy=unix:/path/to/socket
Windows 不支持此功能。
磁盘缓存
Bazel 可以将文件系统上的目录用作远程缓存。在切换分支和/或处理同一项目的多个工作区(例如多个检出)时,这对于共享构建工件非常有用。由于 Bazel 不会对目录进行垃圾回收,因此您可能需要定期清理此目录。按如下方式启用磁盘缓存:
build --disk_cache=path/to/build/cache
您可以使用 ~
别名将特定于用户的路径传递给 --disk_cache
标志(Bazel 将替换当前用户的主目录)。通过在 .bazelrc
文件中签入的项目为项目的所有开发者启用磁盘缓存时,这种方法非常有用。
已知问题
构建期间修改输入文件
在构建期间修改输入文件时,Bazel 可能会将无效结果上传到远程缓存。您可以使用 --experimental_guard_against_concurrent_changes
标志启用更改检测。此功能还没有已知问题,在未来的版本中将默认处于启用状态。
如需了解最新动态,请参阅 [问题 #3360]。通常,请避免在构建期间修改源文件。
环境变量泄露到操作中
操作定义包含环境变量。这可能会成为跨机器共享远程缓存命中的问题。例如,具有不同 $PATH
变量的环境不会共享缓存命中。操作定义中仅包含通过 --action_env
明确列入白名单的环境变量。Bazel 的 Debian/Ubuntu 软件包,用于安装 /etc/bazel.bazelrc
,其中包含环境变量(包括 $PATH
)的白名单。如果缓存命中次数低于预期,请检查您的环境中是否没有旧的 /etc/bazel.bazelrc
文件。
Bazel 不会跟踪工作区之外的工具
Bazel 目前不会在工作区之外跟踪工具。例如,如果某个操作使用 /usr/bin/
中的编译器,这可能会带来问题。然后,安装了不同编译器的两个用户会错误地共享缓存命中,因为输出不同,但他们具有相同的操作哈希值。如需了解最新动态,请参阅问题 4558。
在 Docker 容器内运行构建时,增量内存中状态会丢失 Bazel 会使用服务器/客户端架构(即使在单个 Docker 容器中运行时)。在服务器端,Bazel 会保持内存中状态,从而加快构建速度。在 Docker 容器内(例如在 CI 中)运行构建时,内存中状态会丢失,Bazel 必须先重新构建此状态,然后才能使用远程缓存。