Lưu vào bộ nhớ đệm từ xa

Báo cáo vấn đề Xem nguồn Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Trang này trình bày về tính năng lưu vào bộ nhớ đệm từ xa, cách thiết lập một máy chủ để lưu trữ bộ nhớ đệm và cách chạy các bản dựng bằng bộ nhớ đệm từ xa.

Bộ nhớ đệm từ xa được một nhóm nhà phát triển và/hoặc hệ thống tích hợp liên tục (CI) sử dụng để chia sẻ các kết quả bản dựng. Nếu bản dựng của bạn có thể tái tạo, thì các đầu ra từ một máy có thể được sử dụng lại một cách an toàn trên một máy khác, điều này có thể giúp bản dựng nhanh hơn đáng kể.

Tổng quan

Bazel chia bản dựng thành các bước riêng biệt, được gọi là hành động. Mỗi thao tác đều có đầu vào, tên đầu ra, dòng lệnh và biến môi trường. Đầu vào bắt buộc và đầu ra dự kiến được khai báo rõ ràng cho từng hành động.

Bạn có thể thiết lập một máy chủ làm bộ nhớ đệm từ xa cho các đầu ra bản dựng, đây là những đầu ra hành động này. Các đầu ra này bao gồm một danh sách tên tệp đầu ra và hàm băm nội dung của các tệp đó. Với bộ nhớ đệm từ xa, bạn có thể sử dụng lại các kết quả của bản dựng từ bản dựng của một người dùng khác thay vì tạo từng kết quả mới cục bộ.

Cách sử dụng tính năng lưu vào bộ nhớ đệm từ xa:

  • Thiết lập một máy chủ làm phần phụ trợ của bộ nhớ đệm
  • Định cấu hình bản dựng Bazel để sử dụng bộ nhớ đệm từ xa
  • Sử dụng Bazel phiên bản 0.10.0 trở lên

Bộ nhớ đệm từ xa lưu trữ 2 loại dữ liệu:

  • Bộ nhớ đệm của thao tác, là một bản đồ gồm các hàm băm thao tác với siêu dữ liệu kết quả thao tác.
  • Một kho lưu trữ có thể định địa chỉ nội dung (CAS) của các tệp đầu ra.

Xin lưu ý rằng bộ nhớ đệm từ xa cũng lưu trữ stdout và stderr cho mọi thao tác. Do đó, việc kiểm tra stdout/stderr của Bazel không phải là một tín hiệu tốt để ước tính số lượt truy cập vào bộ nhớ đệm.

Cách bản dựng sử dụng tính năng lưu vào bộ nhớ đệm từ xa

Sau khi thiết lập một máy chủ làm bộ nhớ đệm từ xa, bạn có thể sử dụng bộ nhớ đệm theo nhiều cách:

  • Đọc và ghi vào bộ nhớ đệm từ xa
  • Đọc và/hoặc ghi vào bộ nhớ đệm từ xa, ngoại trừ các mục tiêu cụ thể
  • Chỉ đọc từ bộ nhớ đệm từ xa
  • Không sử dụng bộ nhớ đệm từ xa

Khi bạn chạy một bản dựng Bazel có thể đọc và ghi vào bộ nhớ đệm từ xa, bản dựng sẽ làm theo các bước sau:

  1. Bazel tạo biểu đồ gồm các mục tiêu cần được tạo, sau đó tạo danh sách các thao tác bắt buộc. Mỗi thao tác này đều có các tên tệp đầu vào và đầu ra đã khai báo.
  2. Bazel kiểm tra máy cục bộ của bạn để tìm các đầu ra bản dựng hiện có và sử dụng lại mọi đầu ra mà nó tìm thấy.
  3. Bazel kiểm tra bộ nhớ đệm để tìm các kết quả đầu ra của bản dựng hiện có. Nếu tìm thấy đầu ra, Bazel sẽ truy xuất đầu ra. Đây là một kết quả tìm kiếm trong bộ nhớ đệm.
  4. Đối với các thao tác bắt buộc mà không tìm thấy đầu ra, Bazel sẽ thực thi các thao tác cục bộ và tạo đầu ra bản dựng bắt buộc.
  5. Đầu ra của bản dựng mới được tải lên bộ nhớ đệm từ xa.

Thiết lập máy chủ làm phần phụ trợ của bộ nhớ đệm

Bạn cần thiết lập một máy chủ để đóng vai trò là phần phụ trợ của bộ nhớ đệm. Máy chủ HTTP/1.1 có thể coi dữ liệu của Bazel là các byte không rõ ràng, do đó, nhiều máy chủ hiện có có thể được dùng làm một chương trình phụ trợ lưu vào bộ nhớ đệm từ xa. Giao thức lưu vào bộ nhớ đệm HTTP của Bazel là giao thức hỗ trợ tính năng lưu vào bộ nhớ đệm từ xa.

Bạn chịu trách nhiệm chọn, thiết lập và duy trì máy chủ phụ trợ sẽ lưu trữ các đầu ra được lưu vào bộ nhớ đệm. Khi chọn máy chủ, hãy cân nhắc:

  • Tốc độ kết nối mạng. Ví dụ: nếu nhóm của bạn ở cùng một văn phòng, bạn có thể muốn chạy máy chủ cục bộ của riêng mình.
  • Bảo mật. Bộ nhớ đệm từ xa sẽ có các tệp nhị phân của bạn và cần được bảo mật.
  • Dễ quản lý. Ví dụ: Google Cloud Storage là một dịch vụ được quản lý toàn diện.

Có nhiều phần phụ trợ có thể dùng cho bộ nhớ đệm từ xa. Một số lựa chọn bao gồm:

nginx

nginx là một máy chủ web nguồn mở. Với [mô-đun WebDAV], bạn có thể dùng nó làm bộ nhớ đệm từ xa cho Bazel. Trên Debian và Ubuntu, bạn có thể cài đặt gói nginx-extras. Trên macOS, nginx có sẵn thông qua Homebrew:

brew tap denji/nginx
brew install nginx-full --with-webdav

Dưới đây là một ví dụ về cấu hình cho nginx. Xin lưu ý rằng bạn sẽ cần thay đổi /path/to/cache/dir thành một thư mục hợp lệ mà nginx có quyền ghi và đọc. Bạn có thể cần thay đổi lựa chọn client_max_body_size thành một giá trị lớn hơn nếu có các tệp đầu ra lớn hơn. Máy chủ sẽ yêu cầu cấu hình khác, chẳng hạn như xác thực.

Ví dụ về cấu hình cho phần server trong nginx.conf:

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 là một bộ nhớ đệm bản dựng từ xa nguồn mở mà bạn có thể sử dụng trên cơ sở hạ tầng của mình. Công cụ này đã được sử dụng thành công trong quá trình sản xuất tại một số công ty kể từ đầu năm 2018. Xin lưu ý rằng dự án Bazel không cung cấp dịch vụ hỗ trợ kỹ thuật cho bazel-remote.

Bộ nhớ đệm này lưu trữ nội dung trên đĩa, đồng thời cung cấp tính năng thu gom rác để thực thi giới hạn lưu trữ trên và dọn dẹp các cấu phần phần mềm không dùng đến. Bộ nhớ đệm có sẵn dưới dạng [hình ảnh docker] và mã của bộ nhớ đệm có trên GitHub. Cả API bộ nhớ đệm từ xa REST và gRPC đều được hỗ trợ.

Hãy tham khảo trang GitHub để biết hướng dẫn về cách sử dụng.

Google Cloud Storage

[Google Cloud Storage] là một kho lưu trữ đối tượng được quản lý hoàn toàn, cung cấp một API HTTP tương thích với giao thức lưu vào bộ nhớ đệm từ xa của Bazel. Bạn phải có tài khoản Google Cloud đã bật tính năng thanh toán.

Cách sử dụng Cloud Storage làm bộ nhớ đệm:

  1. Tạo một vùng lưu trữ. Đảm bảo bạn chọn vị trí nhóm gần bạn nhất, vì băng thông mạng rất quan trọng đối với bộ nhớ đệm từ xa.

  2. Tạo một tài khoản dịch vụ cho Bazel để xác thực với Cloud Storage. Xem phần Tạo tài khoản dịch vụ.

  3. Tạo một khoá JSON bí mật rồi truyền khoá đó đến Bazel để xác thực. Lưu trữ khoá một cách an toàn, vì bất kỳ ai có khoá đều có thể đọc và ghi dữ liệu tuỳ ý vào/từ vùng lưu trữ GCS của bạn.

  4. Kết nối với Cloud Storage bằng cách thêm các cờ sau vào lệnh Bazel:

    • Truyền URL sau đến Bazel bằng cách sử dụng cờ: --remote_cache=https://storage.googleapis.com/bucket-name, trong đó bucket-name là tên của nhóm lưu trữ.
    • Truyền khoá xác thực bằng cờ: --google_credentials=/path/to/your/secret-key.json hoặc --google_default_credentials để sử dụng Xác thực ứng dụng.

  5. Bạn có thể định cấu hình Cloud Storage để tự động xoá các tệp cũ. Để thực hiện việc này, hãy xem phần Quản lý vòng đời của đối tượng.

Các máy chủ khác

Bạn có thể thiết lập bất kỳ máy chủ HTTP/1.1 nào hỗ trợ PUT và GET làm phần phụ trợ của bộ nhớ đệm. Người dùng đã báo cáo thành công khi sử dụng các phần phụ trợ lưu vào bộ nhớ đệm như Hazelcast, Apache httpd và AWS S3.

Xác thực

Kể từ phiên bản 0.11.0, Bazel đã hỗ trợ Phương thức xác thực cơ bản HTTP. Bạn có thể truyền tên người dùng và mật khẩu đến Bazel thông qua URL bộ nhớ đệm từ xa. Cú pháp là https://username:password@hostname.com:port/path. Xin lưu ý rằng phương thức Xác thực cơ bản qua HTTP truyền tên người dùng và mật khẩu dưới dạng văn bản thuần tuý qua mạng. Do đó, bạn phải luôn sử dụng phương thức này với HTTPS.

Giao thức lưu vào bộ nhớ đệm HTTP

Bazel hỗ trợ lưu vào bộ nhớ đệm từ xa thông qua HTTP/1.1. Về cơ bản, giao thức này rất đơn giản: Dữ liệu nhị phân (BLOB) được tải lên thông qua các yêu cầu PUT và tải xuống thông qua các yêu cầu GET. Siêu dữ liệu kết quả của thao tác được lưu trữ theo đường dẫn /ac/ và các tệp đầu ra được lưu trữ theo đường dẫn /cas/.

Ví dụ: hãy xem xét một bộ nhớ đệm từ xa chạy trong http://localhost:8080/cache. Yêu cầu Bazel tải siêu dữ liệu kết quả của thao tác xuống cho một thao tác có hàm băm SHA256 01ba4719... sẽ có dạng như sau:

GET /cache/ac/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b HTTP/1.1
Host: localhost:8080
Accept: */*
Connection: Keep-Alive

Yêu cầu Bazel tải một tệp đầu ra có hàm băm SHA256 15e2b0d3... lên CAS sẽ có dạng như sau:

PUT /cache/cas/15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225 HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Length: 9
Connection: Keep-Alive

0x310x320x330x340x350x360x370x380x39

Chạy Bazel bằng bộ nhớ đệm từ xa

Sau khi thiết lập một máy chủ làm bộ nhớ đệm từ xa, để sử dụng bộ nhớ đệm từ xa, bạn cần thêm cờ vào lệnh Bazel. Xem danh sách các cấu hình và cờ của chúng bên dưới.

Bạn cũng có thể cần định cấu hình quy trình xác thực, quy trình này dành riêng cho máy chủ bạn chọn.

Bạn có thể muốn thêm các cờ này vào tệp .bazelrc để không cần chỉ định chúng mỗi khi chạy Bazel. Tuỳ thuộc vào dự án và động lực của nhóm, bạn có thể thêm cờ vào tệp .bazelrc:

  • Trên máy cục bộ
  • Trong không gian làm việc của dự án, được chia sẻ với nhóm
  • Trên hệ thống CI

Đọc và ghi vào bộ nhớ đệm từ xa

Hãy cẩn thận khi cấp quyền ghi vào bộ nhớ đệm từ xa cho người dùng. Bạn có thể chỉ muốn hệ thống CI của mình có thể ghi vào bộ nhớ đệm từ xa.

Hãy dùng cờ sau để đọc và ghi vào bộ nhớ đệm từ xa:

build --remote_cache=http://your.host:port

Ngoài HTTP, các giao thức sau cũng được hỗ trợ: HTTPS, grpc, grpcs.

Ngoài cờ ở trên, hãy dùng cờ sau để chỉ đọc từ bộ nhớ đệm từ xa:

build --remote_upload_local_results=false

Loại trừ một số mục tiêu cụ thể khỏi việc sử dụng bộ nhớ đệm từ xa

Để loại trừ một số mục tiêu cụ thể khỏi việc sử dụng bộ nhớ đệm từ xa, hãy gắn thẻ mục tiêu bằng no-remote-cache. Ví dụ:

java_library(
    name = "target",
    tags = ["no-remote-cache"],
)

Xoá nội dung khỏi bộ nhớ đệm từ xa

Xoá nội dung khỏi bộ nhớ đệm từ xa là một phần trong quy trình quản lý máy chủ. Cách bạn xoá nội dung khỏi bộ nhớ đệm từ xa phụ thuộc vào máy chủ mà bạn đã thiết lập làm bộ nhớ đệm. Khi xoá dữ liệu đầu ra, hãy xoá toàn bộ bộ nhớ đệm hoặc xoá dữ liệu đầu ra cũ.

Đầu ra được lưu vào bộ nhớ đệm được lưu trữ dưới dạng một tập hợp tên và hàm băm. Khi xoá nội dung, bạn không thể phân biệt đầu ra nào thuộc về một bản dựng cụ thể.

Bạn có thể muốn xoá nội dung khỏi bộ nhớ đệm để:

  • Tạo bộ nhớ đệm sạch sau khi bộ nhớ đệm bị hỏng
  • Giảm mức sử dụng bộ nhớ bằng cách xoá các đầu ra cũ

Cổng Unix

Bộ nhớ đệm HTTP từ xa hỗ trợ kết nối qua các ổ cắm miền Unix. Hành vi này tương tự như cờ --unix-socket của curl. Sử dụng nội dung sau để định cấu hình socket miền unix:

   build --remote_cache=http://your.host:port
   build --remote_cache_proxy=unix:/path/to/socket

Tính năng này không được hỗ trợ trên Windows.

Bộ nhớ đệm trên ổ đĩa

Bazel có thể sử dụng một thư mục trên hệ thống tệp làm bộ nhớ đệm từ xa. Điều này hữu ích khi chia sẻ cấu phần phần mềm bản dựng khi chuyển đổi nhánh và/hoặc làm việc trên nhiều không gian làm việc của cùng một dự án, chẳng hạn như nhiều lần thanh toán. Bật bộ nhớ đệm trên ổ đĩa như sau:

build --disk_cache=path/to/build/cache

Bạn có thể truyền một đường dẫn dành riêng cho người dùng đến cờ --disk_cache bằng cách sử dụng bí danh ~ (Bazel sẽ thay thế thư mục gốc của người dùng hiện tại). Điều này rất hữu ích khi bạn bật bộ nhớ đệm trên ổ đĩa cho tất cả nhà phát triển của một dự án thông qua tệp .bazelrc đã kiểm tra của dự án.

Thu gom rác

Bắt đầu từ Bazel 7.4, bạn có thể sử dụng --experimental_disk_cache_gc_max_size và --experimental_disk_cache_gc_max_age để đặt kích thước tối đa cho bộ nhớ đệm trên ổ đĩa hoặc cho độ tuổi của từng mục trong bộ nhớ đệm. Bazel sẽ tự động thu thập rác bộ nhớ đệm trên đĩa khi không hoạt động giữa các bản dựng; bạn có thể đặt bộ hẹn giờ không hoạt động bằng --experimental_disk_cache_gc_idle_delay (mặc định là 5 phút).

Ngoài tính năng tự động thu thập rác, chúng tôi cũng cung cấp một công cụ để chạy tính năng thu thập rác theo yêu cầu.

Vấn đề đã biết

Sửa đổi tệp đầu vào trong quá trình tạo bản dựng

Khi một tệp đầu vào được sửa đổi trong quá trình tạo bản dựng, Bazel có thể tải kết quả không hợp lệ lên bộ nhớ đệm từ xa. Bạn có thể bật tính năng phát hiện thay đổi bằng cờ --experimental_guard_against_concurrent_changes. Không có vấn đề nào đã biết và tính năng này sẽ được bật theo mặc định trong bản phát hành sau này. Hãy xem [vấn đề #3360] để biết thông tin cập nhật. Nói chung, hãy tránh sửa đổi các tệp nguồn trong quá trình tạo.

Các biến môi trường rò rỉ vào một thao tác

Định nghĩa hành động chứa các biến môi trường. Đây có thể là vấn đề khi chia sẻ lượt truy cập bộ nhớ đệm từ xa trên nhiều máy. Ví dụ: các môi trường có các biến $PATH khác nhau sẽ không dùng chung các lượt truy cập vào bộ nhớ đệm. Chỉ những biến môi trường được đưa vào danh sách cho phép một cách rõ ràng thông qua --action_env mới được đưa vào định nghĩa hành động. Gói Debian/Ubuntu của Bazel dùng để cài đặt /etc/bazel.bazelrc với danh sách cho phép các biến môi trường, bao gồm cả $PATH. Nếu bạn nhận được ít lượt truy cập vào bộ nhớ đệm hơn dự kiến, hãy kiểm tra để đảm bảo môi trường của bạn không có tệp /etc/bazel.bazelrc cũ.

Bazel không theo dõi các công cụ bên ngoài không gian làm việc

Bazel hiện không theo dõi các công cụ bên ngoài không gian làm việc. Điều này có thể gây ra vấn đề nếu, chẳng hạn, một thao tác sử dụng trình biên dịch từ /usr/bin/. Sau đó, hai người dùng đã cài đặt các trình biên dịch khác nhau sẽ chia sẻ sai lượt truy cập bộ nhớ đệm vì đầu ra khác nhau nhưng có cùng hàm băm hành động. Hãy xem vấn đề #4558 để biết thông tin cập nhật.

Trạng thái gia tăng trong bộ nhớ sẽ bị mất khi chạy các bản dựng bên trong vùng chứa Docker Bazel sử dụng cấu trúc máy chủ/máy khách ngay cả khi chạy trong một vùng chứa Docker. Về phía máy chủ, Bazel duy trì trạng thái trong bộ nhớ giúp tăng tốc quá trình tạo. Khi chạy các bản dựng bên trong vùng chứa docker (chẳng hạn như trong CI), trạng thái trong bộ nhớ sẽ bị mất và Bazel phải tạo lại trạng thái đó trước khi sử dụng bộ nhớ đệm từ xa.