Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Biến môi trường

CLI aggrega đọc một tập cố định các biến môi trường có tiền tố AGGREGA_. Mỗi biến ghi đè thiết lập tương ứng trong .aggrega-config.yaml khi chạy — tầng mà một job CI hoặc một trình điều phối chèn bí mật kiểm soát mà không cần sửa các tệp được theo dõi — trong khi một cờ dòng lệnh vẫn được ưu tiên hơn tất cả.

Thứ tự ưu tiên

Một biến môi trường nằm trên các tệp cấu hình đã commit — một lớp ghi đè lúc chạy mà pipeline hoặc bộ điều phối tiêm secret áp dụng mà không cần sửa tệp được theo dõi — và dưới một cờ dòng lệnh, nên một giá trị tường minh gõ trên dòng lệnh không bao giờ bị môi trường xung quanh âm thầm ghi đè. Cấu hình trình bày đầy đủ thang ưu tiên và cách xếp lớp của các tệp bên dưới.

Một biến chưa được đặt (hoặc rỗng) sẽ rơi xuống lớp bên dưới — nó không bao giờ ghi đè một giá trị đã cấu hình bằng một giá trị trống. Để xem cấu hình đang áp dụng ngay lúc này và lớp nào đã quyết định từng thiết lập, hãy chạy aggrega config show --origin.

Cách đặt tên

Tên biến là AGGREGA_ theo sau là đường dẫn cấu hình của nó viết dạng chữ hoa nối bằng gạch dưới (dấu chấm trở thành dấu gạch dưới): signing.fulcio_url trở thành AGGREGA_SIGNING_FULCIO_URL. Có một tên được rút gọn cho tiện dùng — workspace.catalog_dirs gắn với AGGREGA_CATALOG_DIRS, tương tự như PATH.

Các thiết lập theo từng registry (registries[].*) không có biến môi trường: một danh sách các khối chính sách theo từng host không thể biểu diễn bằng một biến duy nhất, và chính sách tin cậy và ký của một registry là cấu hình được commit, không phải một giá trị ghi đè từ môi trường. Các flag mang tính tình huống, dùng một lần và theo vị trí (--dry-run, --trace, --detail, --output, --skip-verify, --release, --entity và họ lint --allow-*/--no-allow-*) cũng không có biến môi trường — chúng là các quyết định cho từng lần chạy.

Các thiết lập dựa trên cấu hình

BiếnĐường dẫn cấu hìnhGhi chú
AGGREGA_DEFAULT_REGISTRYdefault_registryMáy chủ đích/registry (mặc định là hub.aggrega.ai). Được viết theo cách default_registry được viết trong tệp — xem cách viết một máy chủ registry — và một giá trị không viết như vậy sẽ bị từ chối khi cấu hình được phân giải, kèm tên biến này.
AGGREGA_OFFLINEofflineBoolean. Cấm mọi lưu lượng mạng đi ra: mọi lệnh sẽ fetch, pull, acquire, push, sign hoặc liên hệ một registry đều từ chối một cách rõ ràng thay vì kết nối, và một bản build chỉ dùng những gì máy đã có — lockfile, cache và các thư mục catalog cục bộ của nó, từ đó --auto-pull điền các thực thể catalog của lockfile mà không cần truy cập registry (một Recipe có chart được tải từ nguồn từ xa vẫn dừng khi offline). Khi đó việc khám phá đọc chỉ mục cục bộ — thông báo ngừng hỗ trợ được lấy từ chỉ mục đã build thay vì thăm dò trực tiếp, và tầng phân giải catalog từ registry từ xa bị bỏ qua; gợi ý plugin mà một lệnh không được nhận diện in ra chỉ đọc chỉ mục cục bộ, bất kể thiết lập này là gì. Việc xác minh tài liệu đã được cache hoặc ghim vẫn chạy — offline cấm việc tải, không cấm kiểm tra cục bộ. --offline là cờ ở trên nó, theo cả hai chiều: nó đặt chế độ cho một lần chạy, và --offline=false cho phép mạng trong một lần chạy khi biến này hoặc một tệp cấu hình đã bật chế độ đó.
AGGREGA_AUTO_PULLauto_pullBoolean. Tự động tải các phụ thuộc còn thiếu khi build.
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dirThư mục cache nội dung trên đĩa, viết tương đối so với gốc workspace để nó chỉ cùng một thư mục dù lệnh chạy ở đâu. Giá trị tuyệt đối bị từ chối, giá trị chỉ chính gốc workspace cũng vậy — hãy cho cache một thư mục con riêng.
AGGREGA_CATALOG_DIRSworkspace.catalog_dirsPhân tách theo dấu phân cách danh sách đường dẫn của hệ điều hành (: trên Unix). Cung cấp đường dẫn tuyệt đối. Thay thế danh sách đã cấu hình; một Release được cấp danh sách riêng dưới workspace.releases giữ danh sách đó.
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_urlURL của CA Fulcio cho ký không khóa.
AGGREGA_SIGNING_REKOR_URLsigning.rekor_urlURL nhật ký minh bạch Rekor cho ký không khóa.
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_urlURL cơ quan cấp dấu thời gian RFC3161 cho ký không khóa.
AGGREGA_SIGNING_KEY_PATHsigning.key_pathĐường dẫn tới tệp PEM khóa ECDSA P-256 được giữ để ký có khóa. Chỉ là con trỏ đường dẫn — không bao giờ là dữ liệu khóa.
AGGREGA_SIGNING_REQUIREDsigning.requiredBoolean. Yêu cầu chữ ký để phát hành và sử dụng các loại mà signing.kinds bao phủ. Nó chỉ bật yêu cầu và không bao giờ tắt: một tệp cấu hình đặt nó sẽ giữ nó ở trạng thái bật.
AGGREGA_SIGNING_KINDSsigning.kindsPhân tách bằng ký tự phân cách danh sách đường dẫn của hệ điều hành (: trên Unix), mỗi mục là một loại được viết như kind: của nó, hoặc all. Nó mở rộng các loại mà yêu cầu bao phủ và không bao giờ thu hẹp chúng; một giá trị không phải là loại có thể ký sẽ bị từ chối, kèm tên biến này.
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verificationBoolean. Tắt xác minh chữ ký trên toàn cục — một cách rõ ràng: mỗi lần pull đều ghi một cảnh báo.
AGGREGA_WORKSPACE_ROOT(đi cùng --workspace-root)Gốc workspace tuyệt đối, bỏ qua việc khám phá — trên mọi lệnh, và cho mọi yêu cầu tới aggrega mcp không nêu workspace riêng. Không phải trường cấu hình; cờ thắng khi được đặt. Khi đặt rỗng, nó được coi là chưa đặt — trừ với aggrega mcp qua đầu vào và đầu ra chuẩn mang AGGREGA_BUNDLE_VERSION và không có --workspace-root, tức lần khởi chạy của gói desktop với thiết lập Workspace folder để trống, khi đó mọi lệnh gọi không nêu workspace riêng đều được trả lời bằng một lời từ chối nêu tên thiết lập đó. Khi nó không chỉ tới thư mục nào tồn tại, mọi lệnh đọc workspace của nó đều từ chối trước khi làm bất cứ việc gì khác, aggrega serve và một listener aggrega mcp từ chối khởi động, còn aggrega mcp qua đầu vào và đầu ra chuẩn vẫn khởi động và trả lời mọi lệnh gọi hoạt động trong workspace đó bằng lời từ chối — mỗi lời từ chối nêu tên biến này cùng thiết lập Workspace folder của ứng dụng desktop đặt nó, và trích dẫn giá trị như đã cho.
AGGREGA_BUNDLE_VERSION(do gói desktop đặt)Phiên bản của gói desktop đã khởi chạy aggrega mcp, được gói đặt vào môi trường của máy chủ. Không phải trường cấu hình. Máy chủ đọc nó một lần khi khởi động và báo cáo nó cạnh phiên bản của chính mình trên describe-capabilities khi gọi không có đối số, cho biết khi hai phiên bản đến từ các bản phát hành khác nhau; không có gì từ chối khi chúng khác nhau. Sự hiện diện của nó cũng đánh dấu lần khởi chạy của gói, nên một AGGREGA_WORKSPACE_ROOT rỗng bên cạnh nó bị từ chối thay vì được coi là chưa đặt, như hàng phía trên mô tả. Khi đặt rỗng, nó được coi là chưa đặt.

AGGREGA_CONFIG chỉ tới một tệp cấu hình toàn cục cụ thể để nạp bên dưới các tệp riêng của dự án; nó chọn tệp nào được áp dụng thay vì ghi đè một thiết lập đơn lẻ. Khi chưa đặt, lớp đó tự động nạp từ vị trí mặc định của nền tảng — trên Windows là aggrega\config.yaml trong thư mục mà biến môi trường APPDATA chỉ định, còn ở nơi khác là aggrega/config.yaml trong thư mục XDG_CONFIG_HOME chỉ định, nếu không có thì dùng ~/.config/aggrega/config.yaml. Xem Cấu hình.

Vị trí các tệp riêng của máy

Tệp cấu hình toàn cục và các cache toàn máy nằm ở nơi mỗi nền tảng lưu tệp riêng của người dùng, vì vậy aggrega cũng đọc các biến chỉ định những vị trí đó. Không biến nào trong số đó là biến AGGREGA_ và không biến nào ghi đè một thiết lập: mỗi biến cho biết nơi tìm một tệp khi không có gì chỉ định nó.

BiếnĐược đọc trênNó định vị gì
APPDATAWindowsTệp cấu hình toàn cục, tại aggrega\config.yaml trong thư mục mà APPDATA chỉ định.
LOCALAPPDATAWindowsCác cache toàn máy, dưới aggrega\cache trong thư mục mà LOCALAPPDATA chỉ định.
XDG_CONFIG_HOME, sau đó HOMELinux, macOS và các hệ Unix khácTệp cấu hình toàn cục, tại aggrega/config.yaml trong thư mục mà XDG_CONFIG_HOME chỉ định, hoặc tại ~/.config/aggrega/config.yaml khi XDG_CONFIG_HOME chưa đặt.
XDG_CACHE_HOME, sau đó HOMELinux và các hệ Unix khácCác cache toàn máy, dưới một thư mục aggrega trong thư mục mà XDG_CACHE_HOME chỉ định, hoặc dưới ~/.cache/aggrega khi XDG_CACHE_HOME chưa đặt. Một XDG_CACHE_HOME không phải đường dẫn tuyệt đối sẽ không định vị cache nào, và khi đó các plugin đã biên dịch chỉ được giữ trong lần chạy.
HOMEmacOSCác cache toàn máy, dưới ~/Library/Caches/aggrega.

AGGREGA_CONFIG, hoặc --config, chỉ định trực tiếp tệp toàn cục trên mọi nền tảng và thắng các biến này. Các cache riêng của một dự án không do biến nào trong số đó định vị: chúng nằm trong dự án, dưới artifact_cache_dir. aggrega config init cho biết cả tệp toàn cục lẫn các cache toàn máy nằm ở đâu trên máy mà nó chạy.

Boolean

Một biến boolean chấp nhận true, false, 1 hoặc 0 (không phân biệt hoa thường). Mọi giá trị không rỗng khác là một lỗi rõ ràng thay vì một phỏng đoán ngầm — khác với YAML, yes/no/on/off không được chấp nhận.

Bí mật

Bí mật được cung cấp qua biến môi trường hoặc cờ và không bao giờ là trường cấu hình.

BiếnMục đíchThứ tự ưu tiên
AGGREGA_IDENTITY_TOKENToken định danh OIDC cho ký không khóa (keyless).Cờ --identity-token > AGGREGA_IDENTITY_TOKEN > OIDC sẵn có của GitHub Actions > SIGSTORE_ID_TOKEN.
AGGREGA_REGISTRY_PASSWORDMật khẩu registry cho aggrega login không tương tác.--password-stdin > AGGREGA_REGISTRY_PASSWORD > lời nhắc tương tác.

SIGSTORE_ID_TOKEN được chấp nhận như một bí danh tương thích với hệ sinh thái sigstore cho token định danh, xếp dưới AGGREGA_IDENTITY_TOKEN và endpoint sẵn có của GitHub Actions. Đây là biến mà các công cụ sigstore rộng hơn vốn đã đặt.

Cùng một cơ chế phân giải định danh phục vụ cả ba lệnh ký — aggrega push --sign, aggrega sign và aggrega deprecate. Tại một terminal tương tác, mỗi lệnh lấy một token ngắn hạn qua luồng trình duyệt mà không cần cờ nào. Trên GitHub Actions, mỗi lệnh tự động tạo một token OIDC workflow mới từ endpoint sẵn có của runner, nên không cần xuất token. Mọi lần chạy không tương tác khác không có terminal và không có endpoint sẵn có, nên phải cung cấp token một cách tường minh (xuất AGGREGA_IDENTITY_TOKEN, hoặc truyền --identity-token). Khi không có token được cung cấp, không có endpoint sẵn có và không có terminal, việc ký không khóa bị từ chối thay vì bị treo.

Hướng dẫn CI (GitHub Actions)

Trên GitHub Actions, CLI phát hiện endpoint OIDC sẵn có của runner và tự động tạo một token workflow mới cho mỗi chữ ký. Hãy cấp cho job quyền tạo token và ký mà không cần xuất token:

permissions:
id-token: write # allow the job to mint a workflow OIDC token
# ...
- run: aggrega push <entity> --sign

Điều tương tự áp dụng cho aggrega sign và aggrega deprecate. Để cố định một định danh cụ thể thay vì định danh được tạo tự động, hãy xuất AGGREGA_IDENTITY_TOKEN một cách tường minh; một token tường minh (hoặc --identity-token) luôn được ưu tiên hơn endpoint sẵn có:

- run: |
AGGREGA_IDENTITY_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r .value)
export AGGREGA_IDENTITY_TOKEN
aggrega push <entity> --sign

CI không phải GitHub Actions không có endpoint sẵn có: hãy xuất AGGREGA_IDENTITY_TOKEN từ cơ chế OIDC của nhà cung cấp đó, hoặc truyền --identity-token.

Với một lô tương tác, cách tương ứng là aggrega auth token, lệnh chạy luồng OIDC trên trình duyệt một lần và in token định danh ra stdout để có thể xuất theo cùng cách:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

Xem aggrega-auth.md. Cả hai cách đều cho phép một lô lệnh aggrega sign dùng lại một định danh mà không cần một lượt qua trình duyệt cho mỗi artifact.

Nên dùng --password-stdin thay vì AGGREGA_REGISTRY_PASSWORD. Một biến môi trường có thể bị các tiến trình con đọc và có thể tồn tại lâu trong shell; stdin là cách an toàn hơn để truyền mật khẩu. Biến môi trường này tồn tại như một tiện ích cho CI.

Xem thêm