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.

aggrega config

Kiểm tra và quản lý cấu hình workspace

Cú pháp

aggrega config

Mô tả

Inspect and manage the configuration Aggrega reads.
Most projects need two files.
One .aggrega-config.yaml at your project root, carrying a "workspace:" block —
that block is what marks the root — holds how this project builds: its catalog
directories, its provider bindings, which lint rules it relaxes. It is
committed, so a teammate who clones the project builds it the same way.
One global file is shared across every workspace on this machine:
~/.config/aggrega/config.yaml, or on Windows aggrega\config.yaml inside the
directory the APPDATA environment variable names. It holds what belongs to the
machine rather than to any one project: the registries you pull from and the
signature trust policy for each, how large the compiled-module store may grow,
any command extension you have installed. It loads automatically when it is
there, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable wins
over both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity token
is never a field in either file; it is supplied by environment variable or flag
at the moment it is needed.
Because the effective configuration is assembled rather than written anywhere,
"aggrega config show" is how you see what actually applies, and --origin is how
you find out which layer each setting came from. "aggrega config init" seeds a
working configuration, and "aggrega config capture" freezes the effective
build-critical settings into this workspace so a build does not depend on a
global file that is not committed.
Larger projects have more to work with. None of it is needed to start, and each
piece exists for the shape it solves:
More than one file inside a project. Every .aggrega-config.yaml from the
project root down to the directory you run in contributes, a nearer file
overriding a farther one. Only a file carrying "workspace:" marks the root;
one without it contributes settings without anchoring anything.
Extending a list instead of replacing it. A nearer file's list replaces the
farther one's. The companions catalog_dirs_append, governance_append,
linter_append, importer_append and providers_append concatenate onto the
resolved list at each layer instead of shadowing it.
A file your pipeline owns. .aggrega-config-append-ci.yaml may sit beside the
hand-authored file in any of those directories, so automation can overwrite
it wholesale without touching what a person wrote. It is additive only: it
removes nothing and overrides no scalar, and a scalar key written in it is
ignored and named in a warning. It never marks a root.
A relative path anchors to the file that declared it. A catalog directory, a
local plugin path, or an entry under a plugin's with.sources resolves against
the directory of the config file it was written in — not the project root,
and not the directory you ran the command from. So the same "./catalog" names
a different directory depending on which file carries it. Two settings sit
outside this rule: artifact_cache_dir is interpreted relative to the project
root wherever you run from, and AGGREGA_CATALOG_DIRS has no declaring file at
all, so supply absolute paths in it.
The other root markers. A "workspace:" block wins outright at whatever depth
it sits. Failing one, the nearest .aggrega/ directory or aggregate*.yaml,
release*.yaml or manifest*.yaml file anchors the root, in that order within a
directory; failing everything, your working directory is used.
--workspace-root skips discovery entirely.
Naming the global file. --config <path> wins over the AGGREGA_CONFIG
environment variable, which wins over the default location. Both name a file
deliberately, so a path either gives that does not exist is a loud error
rather than a silent fallback. Whichever file resolves is also the one a
config-writing command writes when it writes globally.

Lệnh con

LệnhMô tả
aggrega config captureCố định cấu hình hiệu lực quan trọng cho bản dựng vào workspace này
aggrega config initKhởi tạo một cấu hình hoạt động được với một registry và chính sách tin cậy của nó
aggrega config showHiển thị cấu hình hiệu lực và nguồn gốc của từng thiết lập

Mô tả aggrega config capture

Write the effective build-critical configuration into this project's workspace
config file, so the workspace builds identically without relying on the
machine's global configuration.
The build-critical subset is the configuration a build participates in: a set of
plugin socket attachments and the catalog directories. By default the captured
sockets are only those that determine the
rendered output — the provider bindings and the transform-role governance attachments — since only those must
travel with the project for byte-identical output. Pass --all-plugins to also
freeze the verdict-role governance, linter, and importer sockets, which otherwise stay free to
vary by environment. Each field is written at its effective value — the value
that resolves right now with the global configuration and the workspace tree
merged together — so a binding that today comes only from the global config is
materialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are not
captured: they stay in the global config by their nature. Capture always writes
this project's workspace config file. Running it again on an unchanged
configuration rewrites the same file byte-for-byte. Run in a folder that is not
inside a workspace, with no --workspace-root naming one, it writes nothing and
exits with an error saying so.

Các cờ của aggrega config capture

CờMặc địnhMô tả
--all-pluginsfalseGhi lại tất cả các socket plugin, bao gồm các cổng governance vai trò verdict, linter và importer. Nếu không có cờ này, capture chỉ cố định các socket quyết định đầu ra được render (các liên kết provider và các gắn kết governance vai trò transform).

Mô tả aggrega config init

Seed a working configuration by registering a registry and its signature trust
policy, so a fresh machine can pull and verify signed artifacts without editing
YAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signatures
required and the official trusted identities. The registry's advertised trust
policy is fetched once from its own origin and pinned locally — trust-on-first-
use; when the hub is unreachable, advertises nothing, or the workspace is
offline, its built-in official baseline is written instead, so init still
produces a usable config offline. Pass --registry to seed a different registry
(for an air-gapped or private hub). Such a registry has no built-in baseline,
so seeding it while the workspace is offline is refused: init takes no
identities or key to pin by hand, so register it once while online, or add it
with "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace by
default; pass --workspace to write it to this project's workspace config
instead. If the target config file already exists, init refuses rather than
overwrite it — pass --force to write anyway (the registry entry is merged into
the existing file, other settings preserved).
Before anything else, init says where things are: the configuration file it
created — or, under --force, the one already there that it wrote into — and
the directory the machine-wide caches are kept in. On Windows that directory is
aggrega\cache inside the directory the LOCALAPPDATA environment variable names;
elsewhere it is a directory named aggrega under the per-user cache directory:
~/.cache/aggrega on Linux unless XDG_CACHE_HOME names another, and
~/Library/Caches/aggrega on macOS.
A seeded configuration is a document you own and go on editing, so --dry-run does
everything init does except write: it hands the content back, creating and
modifying nothing. The answer names the file the content is for — which matters
here, because the target is the global config unless --workspace selects this
project's own. A caller that keeps its own document model puts the content there,
where it is visible before it is saved and can be amended or undone. The registry
is still contacted for its advertised trust policy, because the policy in that
content is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing config
file exactly as a write refuses it, and for the same reason. So its exit code
predicts the write's: if the dry run refuses, init would have refused. Pass
--force alongside it to see the merge an overwriting write would produce.
Under --dry-run standard output carries that content and nothing else, so it stays
parseable. A registry seeded with no trust policy, because it advertises none,
still produces its notice, on standard error: read that stream too, or that
configuration arrives without the advice to pin identities by hand. A pinned
policy, whether advertised or the hub's built-in baseline, is in the content
itself and produces no notice.

Các cờ của aggrega config init

CờMặc địnhMô tả
--dry-runfalseLàm mọi thứ trừ việc ghi: trả lại cấu hình được khởi tạo dưới dạng nội dung, nêu tên tệp mà nó dành cho, và không tạo hay sửa đổi gì. Mọi hành vi khác đều giống như khi ghi, nên một tệp cấu hình đã tồn tại bị từ chối đúng như khi ghi từ chối nó — hãy truyền thêm —force để xem kết quả hợp nhất mà một lần ghi đè sẽ tạo ra.
--forcefalseGhi đè một tệp cấu hình đã tồn tại. Nếu không có cờ này, init từ chối khi tệp đích đã tồn tại.
--globalfalseGhi mục vào cấu hình toàn cục được dùng chung cho mọi workspace. Đây là mặc định.
--registryhub.aggrega.aiMáy chủ registry cần khởi tạo cùng chính sách tin cậy của nó. Mặc định là hub chính thức.
--workspacefalseGhi mục vào cấu hình workspace của dự án này thay vì cấu hình toàn cục.

Mô tả aggrega config show

Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overrides
that contributed, lowest precedence first, then prints the effective merged
configuration — the global config, the workspace-tree cascade, and any
environment override combined into what applies right now.
Pass --global or --workspace to print a single layer's own file bytes verbatim,
preserving its comments and formatting; when that layer's file does not exist it
says so rather than failing. The two are mutually exclusive.
Pass --origin to annotate each effective setting with the layer it came from —
a command-line flag, an environment variable, a config file, or the built-in
defaults, highest precedence first. A flag is named as the reader typed it, so
a setting a flag decided reports that flag as its source. A setting is
attributed to the highest-precedence layer that sets it, whatever value that
layer writes: a file restating the default is the file named, not the built-in
defaults. List and map settings are attributed as a whole. The signing
requirement is the one exception: any layer may turn it on and none can turn it
off, so it names the first layer that turns it on.

Các cờ của aggrega config show

CờMặc địnhMô tả
--globalfalseIn nguyên văn các byte của chính tệp cấu hình toàn cục, giữ nguyên chú thích và định dạng.
--originfalseChú thích mỗi thiết lập hiệu lực bằng lớp mà nó đến từ (một cờ dòng lệnh, một biến môi trường, một tệp cấu hình, hoặc các giá trị mặc định tích hợp sẵn).
--workspacefalseIn nguyên văn các byte của chính tệp cấu hình workspace của dự án này, giữ nguyên chú thích và định dạng.

Chức năng

Các lệnh con config khởi tạo, kiểm tra và đóng băng cấu hình chi phối một bản build. Để biết một thiết lập thuộc về tệp nào và các lớp kết hợp với nhau ra sao, xem Cấu hình — trang này bắt đầu với hai tệp mà hầu hết các dự án cần và để phần còn lại phía sau.

config init — khởi tạo một cấu hình hoạt động được

aggrega config init khởi tạo cấu hình trên một máy mới bằng cách đăng ký một registry và chính sách tin cậy chữ ký của nó, để các artifact đã ký được kéo về và xác minh mà không cần sửa YAML bằng tay. Theo mặc định, lệnh đăng ký hub chính thức (hub.aggrega.ai) với yêu cầu chữ ký và các danh tính tin cậy chính thức của nó. Chính sách tin cậy mà registry công bố được tải một lần từ chính nguồn gốc của nó và được ghim cục bộ (tin cậy ở lần dùng đầu tiên); khi không kết nối được tới hub, hub không công bố gì, hoặc workspace ở chế độ ngoại tuyến, đường cơ sở chính thức tích hợp sẵn của nó sẽ được ghi thay thế, nên init vẫn tạo ra một cấu hình dùng được khi ngoại tuyến.

Trước mọi việc khác, init cho biết mọi thứ nằm ở đâu. Khởi tạo trên một máy Linux mới sẽ mở đầu bằng:

Created the global configuration file at /home/you/.config/aggrega/config.yaml
Machine-wide caches are kept in /home/you/.cache/aggrega

và trên một máy Windows mới bằng:

Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yaml
Machine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache

Dòng đầu tiên nêu tên tệp cấu hình mà init đã ghi: Created khi tệp chưa tồn tại, và Using khi tệp đã có và --force cho phép init ghi vào đó; với --workspace, dòng này nêu tệp cấu hình workspace thay vì tệp toàn cục. Dòng thứ hai nêu thư mục chứa các bộ nhớ đệm dùng chung cho cả máy — các plugin đã biên dịch và mô tả của chúng — đây là nơi mỗi nền tảng lưu bộ nhớ đệm của người dùng; Bộ nhớ đệm nào thuộc về dự án này, và bộ nhớ đệm nào thuộc về máy đưa ra quy tắc cho từng nền tảng. Mỗi dòng kết thúc bằng đường dẫn của nó và không có gì phía sau, nên có thể sao chép đường dẫn nguyên trạng. Các dòng tiếp theo thuộc về chính việc đăng ký: việc tải chính sách tin cậy tìm thấy gì, và registry được đăng ký trong tệp nào. Một lần khởi tạo bị từ chối không in dòng nào trong hai dòng này, vì nó không tạo ra gì, và --dry-run cũng vậy, vì đầu ra chuẩn của nó chỉ chứa nội dung được trả về.

  • --registry <host> khởi tạo một registry khác — một hub cách ly mạng hoặc riêng tư — thay cho registry chính thức. Registry như vậy không có đường cơ sở tích hợp sẵn, nên khi nó không công bố gì, mục sẽ được ghi mà không có chính sách, và trong một workspace ngoại tuyến, việc khởi tạo nó bị từ chối (mã ngắn E0310): chính sách không thể tải về, và init không nhận --identity hay --key để ghim chính sách bằng tay. Hãy khởi tạo nó một lần khi trực tuyến, hoặc thêm nó bằng aggrega registry add cùng một chính sách do bạn cung cấp.
  • Nếu tệp đích đã tồn tại, init từ chối thay vì ghi đè; --force vẫn ghi, hợp nhất mục registry vào tệp hiện có và giữ nguyên các thiết lập khác.
  • --dry-run làm mọi việc init làm ngoại trừ ghi. Nó trả cấu hình đã khởi tạo về dưới dạng nội dung, không tạo hay sửa đổi gì, và câu trả lời nêu tên tệp mà nội dung dành cho — điều này quan trọng ở đây, vì đích là cấu hình toàn cục trừ khi --workspace chọn cấu hình riêng của dự án này. Một bên gọi có mô hình tài liệu riêng, chẳng hạn một trình soạn thảo, đặt nội dung vào đó, nơi nó hiển thị trước khi được lưu và có thể được chỉnh sửa hoặc hoàn tác.
  • Vì một lần chạy thử làm mọi việc khác mà init làm, mã thoát của nó dự báo mã thoát của lần ghi. Nó từ chối một tệp cấu hình hiện có đúng như một lần ghi từ chối, và vì cùng lý do, nên bạn có thể dùng nó để hỏi xem init có thành công hay không trước khi cam kết thay đổi. Để xem tài liệu mà một lần ghi đè sẽ tạo ra, hãy truyền --force cùng với nó: --force --dry-run báo cáo kết quả hợp nhất và vẫn không ghi gì.
  • Registry vẫn được liên hệ để lấy chính sách tin cậy nó công bố, vì chính sách trong nội dung được báo cáo là chính sách mà một lần ghi sẽ ghim. Một lần chạy thử thực hiện cùng một yêu cầu không xác thực duy nhất tới nguồn gốc của chính registry đó như một lần ghi.
  • Với --dry-run, đầu ra chuẩn chỉ chứa nội dung đó và không gì khác, nên vẫn phân tích được. Điều duy nhất nội dung không thể biểu đạt là sự vắng mặt: khi một registry không công bố chính sách tin cậy nào và được khởi tạo không có chính sách, thông báo nói điều đó — và bảo bạn ghim danh tính bằng --identity hoặc --key — được gửi tới đầu ra lỗi chuẩn. Một tài liệu cấu hình không có danh tính tin cậy nào trông giống nhau dù một chính sách đã được ghim và tình cờ rỗng hay hoàn toàn không có chính sách nào được công bố, vì vậy hãy đọc cả hai luồng; một chương trình bỏ qua đầu ra lỗi chuẩn sẽ không được biết gì về điều này. Khi registry có công bố chính sách, hoặc đường cơ sở tích hợp sẵn của hub chính thức được ghim thay thế, chính sách đã ghim nằm ngay trong nội dung được báo cáo và không có thông báo riêng nào được tạo ra.

Một cấu hình đã khởi tạo là tài liệu bạn sở hữu và tiếp tục chỉnh sửa, đó là lý do nó có thể được trả về thay vì được ghi. Việc đóng băng cấu hình hiệu lực, ở phần dưới, tạo ra một bản ghi về kết quả phân giải của cấu hình — trạng thái mà trình biên dịch lưu về chính nó chứ không phải nội dung do ai đó soạn — nên nó luôn ghi và không cung cấp --dry-run.

config show — kiểm tra những gì đang áp dụng

aggrega config show báo cáo cấu hình đang áp dụng ngay lúc này. Trong chế độ xem mặc định, lệnh mở đầu bằng chuỗi các tệp cấu hình và các ghi đè từ biến môi trường đã đóng góp, theo thứ tự ưu tiên thấp nhất trước, rồi in cấu hình hợp nhất hiệu lực — cấu hình toàn cục, chuỗi theo cây workspace và mọi lớp phủ môi trường được kết hợp thành một kết quả duy nhất. Chuỗi tệp đã nạp này là nơi bạn xác nhận những tệp và ghi đè môi trường nào đã định hình cấu hình hiện tại.

Hai chế độ xem tập trung thu hẹp đầu ra:

  • --global hoặc --workspace in nguyên văn các byte của tệp thuộc một lớp duy nhất, giữ nguyên chú thích và định dạng; khi tệp của lớp đó không tồn tại, lệnh nói như vậy thay vì thất bại. Hai cờ này loại trừ lẫn nhau.
  • --origin chú thích mỗi thiết lập hiệu lực với lớp mà nó đến từ — một cờ dòng lệnh, một biến môi trường, một tệp cấu hình, hoặc các giá trị mặc định tích hợp sẵn, theo thứ tự ưu tiên cao nhất trước. Một cờ được nêu tên đúng như bạn đã gõ, nên một thiết lập do --offline quyết định trong lần chạy này báo cáo --offline là nguồn của nó; một biến môi trường được nêu tên sau tiền tố env: và một tệp cấu hình theo đường dẫn tuyệt đối của nó.

Với --origin, một thiết lập được quy cho lớp có độ ưu tiên cao nhất đặt nó, bất kể lớp đó ghi giá trị gì. Vì vậy một tệp dự án ghi default_registry: hub.aggrega.ai được nêu tên cho thiết lập đó dù giá trị mặc định tích hợp sẵn là cùng registry đó, và một tệp dự án nhắc lại giá trị mà tệp toàn cục đã đặt được nêu tên thay vì tệp toàn cục: trong cả hai trường hợp, đó là tệp đang giữ giá trị tại chỗ, và là tệp mà việc xóa nó sẽ thay đổi câu trả lời vào ngày giá trị mặc định hoặc tệp bên dưới thay đổi. Một thiết lập không được lớp nào đặt sẽ báo cáo các giá trị mặc định tích hợp sẵn.

  • Thế nào được tính là đặt thiết lập. Một tệp cấu hình đặt một thiết lập khi nó chứa khóa của thiết lập đó, và với thiết lập dạng danh sách thì cả khi nó chứa khóa đi kèm _append của danh sách. Một biến môi trường đặt thiết lập của nó khi được export với giá trị không rỗng, và một cờ khi bạn gõ nó — --offline=false đặt trạng thái chắc chắn như --offline.
  • Một tệp cấu hình do pipeline của bạn sở hữu chỉ được nêu tên cho các khóa mà nó được đọc, tức là các phần bổ sung danh sách và chính sách ký. Một khóa mà nó bỏ qua, và cảnh báo về, không bao giờ được báo cáo là nguồn của một giá trị.
  • Các thiết lập dạng danh sách và map được quy trọn vẹn, cho lớp có độ ưu tiên cao nhất đặt chúng; lớp nào đóng góp mục nào của danh sách thì không được báo cáo.
  • Yêu cầu ký là ngoại lệ duy nhất. Bất kỳ lớp nào cũng có thể bật nó và không lớp nào có thể tắt nó, nên nó nêu tên lớp đầu tiên bật nó. Một lớp ghi required: false không bật gì cả, nên khi không lớp nào bật nó, thiết lập báo cáo các giá trị mặc định tích hợp sẵn.

config capture — cố định các thiết lập quan trọng cho bản dựng

aggrega config capture ghi cấu hình hiệu lực quan trọng cho bản dựng vào tệp cấu hình workspace của dự án này, để workspace dựng ra kết quả giống hệt nhau mà không phụ thuộc vào cấu hình toàn cục của máy. Các thiết lập công cụ áp dụng cho toàn máy, chẳng hạn chính sách tin cậy của một registry, không được ghi lại; về bản chất, chúng nằm trong cấu hình toàn cục. Chạy lại lệnh trên một cấu hình không đổi sẽ ghi lại đúng tệp đó, giống hệt từng byte.

Tập con được ghi lại gồm một tập các liên kết socket của plugin và các thư mục catalog:

  • Theo mặc định, capture chỉ cố định các socket quyết định đầu ra được kết xuất — các liên kết provider và các liên kết governance vai trò transform — vì chỉ những socket đó cần đi cùng dự án để có các bản dựng giống hệt từng byte. Các thư mục catalog luôn được ghi lại.
  • --all-plugins mở rộng các socket được ghi lại để bao gồm cả các socket governance vai trò verdict, linter và importer. Nếu không có cờ này, ba loại socket đó vẫn được tự do thay đổi theo môi trường.

Capture luôn ghi, và không có cách nào để nhận lại nội dung thay vì ghi. Thứ nó tạo ra là bản ghi về kết quả phân giải của cấu hình, không phải một tài liệu do ai đó soạn, nên không có gì để tác giả xem xét và sửa đổi — việc trả về nội dung sẽ khuyến khích chỉnh sửa một ảnh chụp của một kết quả phân giải.

Lệnh capture chỉ ghi vào bên trong một workspace. Khi chạy trong một thư mục không nằm trong workspace nào, mà không có --workspace-root hay AGGREGA_WORKSPACE_ROOT chỉ định một workspace, nó không ghi gì cả — một tệp cấu hình được ghi ở đó sẽ biến thư mục thành một workspace — và thoát với một lỗi cho biết điều đó. aggrega config init --workspace biến thư mục thành một workspace trước.

Xem thêm

  • configuration.md — một thiết lập thuộc về tệp nào, thang thứ tự ưu tiên, và các cơ chế mà một dự án lớn hơn sử dụng.
  • global-flags.md — các cờ --config và --workspace-root.
  • environment-variables.md — các biến AGGREGA_* ghi đè cấu hình khi chạy.
  • aggrega-registry.md — quản lý trực tiếp các registry và chính sách tin cậy của chúng.
  • aggrega-cache.md — thư mục mà artifact_cache_dir chỉ định thực sự chứa gì, và vì sao một thực thể nằm ở đó mà không lockfile nào ghim lại không được bản build tìm thấy.