Danh mục và registry
Chương này định nghĩa cách nền tảng mở rộng quy mô trên toàn doanh nghiệp thông qua Danh mục Open Container Initiative (OCI): danh mục được bố trí ra sao, một tham chiếu được phân giải thế nào, một thực thể được xuất bản và ghim ra sao, và các dạng tên mà thực thể danh mục tuân theo.
Danh mục Aggrega: phân loại và phân giải registry
Trình biên dịch Aggrega dựa vào một registry có kiểu nghiêm ngặt, lấy cảm hứng từ OAM, để phân giải ý định trừu tượng của nhà phát triển (Miền 1) thành thực tế Ops cụ thể (Miền 3). Để hỗ trợ một hệ sinh thái mở, phân tán trong khi vẫn duy trì trải nghiệm nhà phát triển liền mạch, mọi schema, liên kết hạ tầng, chính sách có thể lập trình và plugin bộ điều hợp đều tuân theo một hệ phân loại URI Open Container Initiative (OCI) được chuẩn hóa. Vì mọi thực thể danh mục đều có thể định địa chỉ bằng URI, aggrega pull tải những thực thể mà một Release cần vào bộ nhớ đệm và ghim chúng trong lockfile của nó, và một bản dựng đọc chúng từ đó. Workspace cục bộ của nhà phát triển chỉ chứa các tệp Aggregate và Release của họ, không phải một bản sao của danh mục.
1. Cấu trúc thư mục lõi (danh mục)
Thư mục aggrega-catalog của thư viện chuẩn (và mọi danh mục bên thứ ba tuân thủ) được tổ chức để thực thi về mặt vật lý việc phân tách trách nhiệm. Cấu trúc này tách biệt tường minh các giao diện trừu tượng khỏi các triển khai hạ tầng cụ thể của chúng.
Đối với các Components và Features, các phân đoạn URI ánh xạ 1:1 tới các phân đoạn đường dẫn hệ thống tệp. Các Components dùng URI ba phân đoạn ({publisher}/{category}/{name}), trong đó phân đoạn hạng mục mang một trong một tập đóng các hạng mục nhận thức — cùng từ với nhãn component.aggrega.ai/category của thành phần (bản phản chiếu 1:1 của thư mục, được kiểm tra bởi quy tắc category-matches-directory của linter xuất bản). Các Features vẫn phẳng ({publisher}/{name}) — một tập nhỏ, tăng chậm. Phân loại bản thể học vận hành (stateful-server, server, v.v.) nằm trong nhãn component.aggrega.ai/type, không bao giờ trong cấu trúc thư mục; các nhãn năng lực nhận thức (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) phủ thêm các tập con hành vi lên trên. Giao diện web của hub dùng nhãn để lọc và tìm kiếm; các hạng mục phục vụ cả việc điều hướng hệ thống tệp lẫn trục duyệt của danh mục.
Cây dưới đây mang tính minh họa về nội dung và chính xác về hình dạng. Ở nơi một thực thể được vẽ đầy đủ, nó đi xuống tận tệp lá của mình, nên có thể đọc ra cả một đường dẫn thực từ sơ đồ: cấp thư mục nào mang phân đoạn URI nào, phân đoạn phiên bản bắt buộc nằm ở đâu, và mỗi loại thực thể dùng tên tệp nào ở lá. Cây chỉ hiển thị một vài mục ở mỗi cấp thay vì toàn bộ nội dung danh mục — ... đánh dấu một phần lược bỏ, và các tên được viết bên cạnh là những mục khác ở cùng cấp đó.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformCác hạng mục thành phần là một tập đóng, và chính tập đó — không phải hệ thống tệp — là nguồn thẩm quyền về hạng mục. Một giá trị hạng mục chưa có thực thể nào là từ vựng dành riêng: trục duyệt vẫn ổn định và tác giả biết một thành phần trong tương lai sẽ nằm ở đâu, nên một kệ trống là đúng chứ không phải một chỗ khuyết đang chờ người lấp vào. Vì danh mục không chứa tệp giữ chỗ, thư mục cho một giá trị như vậy được tạo khi thực thể đầu tiên của nó xuất hiện.
Danh sách có thẩm quyền — mọi hạng mục, nội dung của nó, các giá trị type vận hành mà thực thể của nó thường mang, và những thư mục nào đang tồn tại — là mục Hạng mục Component của hướng dẫn quy ước danh mục, được xuất bản cùng danh mục thư viện chuẩn mà nó chi phối.
Trục type chỉ mang các nguyên hàm vận hành — từ vựng nhận thức không bao giờ xuất hiện trên đó, và schema Component đã xuất bản liệt kê các giá trị mà khóa dành riêng chấp nhận, nên một từ nhận thức được viết ở đó sẽ bị từ chối khi tài liệu được tải. Cách chia ba trục: type vận hành (cách hạ tầng đối xử với thành phần), category nhận thức (thành phần là gì, được phản chiếu bởi thư mục) và các nhãn năng lực theo vai trò (các tập con hành vi — một thực thể là category: datastore cộng với bất kỳ giá trị datastore.aggrega.ai/engine nào mà danh tính sản phẩm của chính nó mang, nên core/datastore/qdrant mang vector và core/datastore/redis mang kv, và cả hai trục đều có thể truy vấn). Một năng lực mà tính đúng đắn của nó phụ thuộc vào những gì tác giả cấu hình hoàn toàn không được lưu trong danh mục: nó được chèn vào lúc biên dịch bởi vai trò label-transform của socket quản trị, vốn đọc các values mà nhà phát triển đã khai báo. Các hạng mục thuần AI mang tiền tố ai-; các hạng mục lưỡng dụng xuất hiện không có tiền tố, với sắc thái AI được biểu đạt bằng nhãn năng lực. Hạng mục được chọn theo cách người dùng điều hướng và duyệt, không theo cách trình biên dịch phân loại — từ vựng hạng mục và các nhãn năng lực là những thuật ngữ mà trình biên dịch dùng để so khớp bộ chọn và không gán cho chúng ý nghĩa nào. Tên của một thành phần không lặp lại hạng mục của nó: mô hình OpenAI của thư viện chuẩn là core/ai-model/openai, không phải core/ai-model/openai-model.
2. Lược đồ tách đôi và pipeline tổng hợp cầu nối
Để loại bỏ mã lặp khuôn mẫu theo từng Component xung quanh các khai báo socket topo, Aggrega chia việc xác thực thành hai phần và kiểm soát mỗi phần tại nơi đối tượng của nó nằm:
usesSchema(YAML khai báo). Khai báo các socket topo mà một thực thể catalog cung cấp, và gán cho mỗi socket một hợp đồng. CLI Go đọc nó một cách gốc để trích xuất các chuỗiselector:phục vụ việc so khớp nhãn trong quá trình phân tích tĩnh và để xác thực các cơ chếinjectđược phép. Mỗi mục socket hỗ trợ một trường tùy chọnrequired: true(mặc địnhfalse) — khi được đặt, trình biên dịch phát ra lỗi xác thực nếu không có phụ thuộc nào được khai báo trong socket đó. Đây là bản tương ứng dành cho socket của ngữ nghĩarequired: truetrên các mụcfeaturesSchema: cả hai đều dừng bản dựng. Khai báo socket ở đây là điều mà catalog thư viện chuẩn làm và vẫn là con đường tốt hơn — nhưng đó không phải là cách duy nhất để nhà phát triển vẽ một cạnh. Tác giả của một Aggregate có thể đặt tên trên chính component của mình một socket màusesSchemanày không khai báo, kể cả trên một thực thể hoàn toàn không khai báousesSchema; một socket ad hoc như vậy không mang selector, không mang danh sách cho phépinjectvà không mang lược đồ theo từng cạnh, chính vì ở đây không có mục nào để mang chúng.usescủa một phần gắn Feature vàusestheo từng cạnh của một Release không mở theo cách đó — cả hai chỉ có thể đặt tên một socket đã được khai báo. Xem dependency-resolution §“Miền 2: Lược đồ tách đôi” để biết hợp đồng đầy đủ và những gì một socket ad hoc phải từ bỏ.- Khử cú pháp rút gọn. Nếu nhà phát triển dùng dạng viết tắt mảng YAML (
uses: databases: ["db1"]), CLI sẽ chuẩn hóa nó thành một map ({"db1": {"target": "db1"}}). - Tổng hợp cầu nối. Trình biên dịch chiếu bảng slot
featuresSchema:thành một đoạn JSON Schema 2020-12 — mỗi slot gắn một thuộc tính, mô tả hình dạng của phần điền có thể ràng buộc slot đó, với từ khóa mở rộngx-aggrega-inject:trên slot khai báo danh sách cho phépinject. Việc xác thực JSON Schema bỏ qua các từ khóa mở rộng trong quá trình xác thực cấu trúc, và không có gì đọc lại từ khóa đó từ đoạn: một kiểm tra cần danh sách cho phép của một slot sẽ đọc chính slot đó. Bảng socketusesSchema:không được chiếu thành đoạn nào.selector:vàinject:của một socket vẫn nằm trong YAML có kiểu mà kiến trúc sư đã viết và được đọc từ đó, cònvalueSchema:/infraSchema:theo từng cạnh của một socket được bọc và biên dịch riêng, không có ràng buộc nào được bịa ra xung quanh nó. - Kết hợp. Kiến trúc sư nền tảng viết một khai báo
schema:chặt chẽ (dạng gọn hoặc JSON Schema 2020-12 đầy đủ) định nghĩavalues,infravàprovides. Khai báo đó là hợp đồng riêng của thực thể và được biên dịch riêng: cả đoạn slot lẫn bảng socket đều không được gộp vào nó. Mỗi bề mặt được kiểm tra tại nơi đối tượng của nó nằm, nên lỗi socket được báo cáo trên mục socket mà kiến trúc sư đã viết thay vì tại một đường dẫn bên trong khốischema:— và kiến trúc sư vẫn không phải viết mã lặp khuôn mẫuusesnào.
Ví dụ — một khai báo socket và những gì trình biên dịch làm với nó: YAML của kiến trúc sư nền tảng
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}Những gì trình biên dịch làm với nó Bảng socket được đọc đúng như YAML có kiểu mà nó là: chuỗi selector: được chuyển tới công cụ so khớp nhãn gốc, và danh sách inject: giới hạn những cơ chế phân phối mà một cạnh đi qua socket đó có thể đặt tên. Khối schema: được biên dịch riêng, như hợp đồng values / infra / provides riêng của thực thể. Bộ phân tích tĩnh đọc chuỗi selector: từ mục socket mà kiến trúc sư đã viết — cùng với appliesTo / appliesToAnyOf từ các thực thể Feature — và đánh giá việc so khớp nhãn dựa trên metadata.labels của mỗi đích để xác thực an toàn kiểu giữa các nút.
Selector kiểu Kubernetes trong usesSchema
Công cụ so khớp nhãn gốc của trình biên dịch Go đánh giá các chuỗi selector bằng ngữ nghĩa chọn lọc chuẩn kiểu Kubernetes (AND qua dấu phẩy, OR qua in(), NOT qua !=/notin()). Cũng chính công cụ này — và cùng ngữ pháp chuỗi selector — còn đánh giá các selector gắn Feature (appliesTo, và từng mục của appliesToAnyOf). Lớp selector hoàn toàn chỉ là cổng topo — các khai báo schema: theo từng trụ cột xác thực nội dung values, infra và provides một cách độc lập. Sau khi trình biên dịch Go vẽ các cạnh topo trong quá trình xây dựng topo, bộ phân tích tĩnh đọc các chuỗi selector từ các mục socket mà kiến trúc sư đã viết và đánh giá chúng dựa trên labels catalog của nút đích để xác thực an toàn kiểu giữa các nút.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Một selector mà công cụ không thể đọc thành một trong sáu dạng yêu cầu của nó — một yêu cầu rỗng, một khóa chứa khoảng trắng hoặc một trong các ký tự =, !, (, ) và dấu phẩy, một tập hợp chưa đóng — sẽ dừng bản build trên mọi cạnh mà nó bảo vệ thay vì bị đọc thành một selector khác. Ngữ pháp selector liệt kê các dạng và mọi trường hợp từ chối.
3. Định dạng và kết hợp lược đồ
Để cung cấp cả xác thực chặt chẽ lẫn siêu dữ liệu catalog chuẩn (tác giả, phiên bản, mô tả), các định nghĩa của Miền 2 (Giao diện) và Miền 3 (Triển khai) được viết dưới dạng phong bì YAML. Miền 2 sử dụng các khai báo schema: nhúng, được biểu diễn ở dạng gọn (mặc định; ~15 từ khóa, được chuyển đổi cơ học sang JSON Schema 2020-12) hoặc bằng YAML JSON Schema đầy đủ.
Vì sao mọi YAML catalog đều lặp lại phong bì. Phong bì (khối apiVersion, kind, metadata) xuất hiện ở đầu mọi tệp catalog — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — bất kể phần thân ngắn đến đâu. Sự lặp lại là có chủ ý: mỗi tệp được thiết kế để có thể phân tích cú pháp, xác thực, lint và kiểm tra như một tạo phẩm độc lập. Một tệp đơn lẻ được kéo từ registry OCI, thả vào sandbox CI hoặc mở trong trình soạn thảo bên thứ ba phải mang đủ thông tin tự mô tả để công cụ phía sau có thể xác định nó biểu diễn loại thực thể nào và phiên bản lược đồ nào được áp dụng. Vị trí thư mục không bao giờ thay thế cho phong bì: mọi trình phân tích, trình xác thực và linter đều đọc loại thực thể và phiên bản lược đồ từ phong bì. Cái giá là mã lặp khuôn mẫu cơ học cho mỗi tệp; lợi ích là bảo đảm về công cụ độc lập được duy trì trên bề mặt phân phối OCI, hệ thống tệp cục bộ và các bề mặt IDE / CI / inspect. Tác giả sao chép phong bì từ các tệp hiện có khi viết nội dung catalog mới, hoặc bắt đầu từ aggrega scaffold <kind>, lệnh này in ra một tài liệu khởi đầu cho loại đó với apiVersion và kind đã được điền sẵn.
Để duy trì nguyên tắc DRY (Don’t Repeat Yourself, “đừng lặp lại chính mình”), catalog sử dụng hai cơ chế kết hợp riêng biệt:
- Các mục SchemaLibrary dùng chung (
$ref:liên tài liệu): Các định nghĩa JSON Schema có thể tái sử dụng được lưu trong các thực thể catalog SchemaLibrary (Tier 3). Chúng được tham chiếu theo danh tính qua$ref:liên tài liệu (<library>#/schemas/<entry>, không có host — phiên bản đến từ lockfile) từ bất kỳ lược đồ Component hoặc Feature tiêu thụ nào. Chuỗi được duyệt tại thời điểm biên dịch. Xem entities/schemalibrary để biết hình dạng soạn thảo của thực thể thư viện và vocabulary/cross-document-ref để biết ngữ nghĩa phân giải. - Kế thừa đơn (
extends): Đối với các đường cơ sở thành phần hoàn chỉnh, các thực thể có thể dùng thuộc tínhextends: "URI". Trình biên dịch Go đọc chuỗi cha một cách đệ quy và hợp nhất sâu siêu dữ liệu YAML (ghi đè nhãn khi xung đột và nối thêm các mảng). Sau đó, hai loại catalog đi theo hai hướng khác nhau ở các trụ dữ liệu.schema:của một Feature được kết hợp với phần tương ứng của thực thể cơ sở theo cơ chế kết hợp của JSON Schema 2020-12. Một Component mở rộng hoàn toàn không viết nội dung trụ nào: nó viết dấu đánh dấu nguyên vănschema: inheritedvà nhận khốischema:của thực thể cơ sở đúng như thực thể cơ sở đã viết, ở mọi độ sâu của chuỗi. Thay vào đó, thứ mà một Component như vậy kết hợp là cấu trúc — các khe gắn (featuresSchema), các socket topo (usesSchema), danh sách cho phép tự tiêm (inject) và cácassertionsđược đặt tên đều được hợp nhất dọc theo chuỗi. Xem entities/component để biết các ví dụ mở rộng thành phần cơ sở và thành phần con + governance-and-compliance §“Kế thừa và kỷ luật xuất bản” để biết kế thừa giải quyết những gì ngay từ cấu trúc và những gì vẫn là một quy tắc kỷ luật xuất bản.
Xem entities/component để biết các ví dụ mở rộng component cơ sở và con, và entities/recipe để biết cách soạn thảo Recipe với con trỏ và bộ ánh xạ kèm các ví dụ đầy đủ.
4. Cấu hình workspace (.aggrega-config.yaml)
Tệp .aggrega-config.yaml ở gốc workspace là cấu hình workspace của dự án — khai báo riêng của workspace, phù hợp để quản lý mã nguồn giống như go.mod hoặc package.json. Theo quy ước, thư mục .aggrega/ được giữ ngoài hệ thống quản lý mã nguồn — hãy liệt kê nó trong .gitignore, như bạn vẫn làm với node_modules/ hoặc .terraform/.
Phần workspace là dấu hiệu gốc: sự hiện diện của nó đánh dấu gốc workspace, và nó chỉ mang các thư mục catalog xác định gốc — catalog_dirs, và map releases cung cấp cho một Release các thư mục catalog riêng. Mọi thiết lập khác nằm ở cấp cao nhất. Nhiều thiết lập là giá trị đơn; số khác là các phần gom các thiết lập của một mối quan tâm dưới một khóa duy nhất. Mọi trường đều tùy chọn với giá trị mặc định được ghi lại. Tập hợp đầy đủ, hiện hành các khóa cấp cao nhất, mỗi khóa kèm kiểu, giá trị mặc định và ý nghĩa, được sinh ra từ lược đồ tại schema/other/aggrega-config; ví dụ dưới đây cho thấy dấu hiệu gốc cùng với một vài thiết lập giá trị đơn:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootMột khối signing: mang các giá trị mặc định ký tạo phẩm được aggrega push --sign và aggrega sign sử dụng, ở cả cấp cao nhất (toàn cục) lẫn theo từng registry:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemThứ tự ưu tiên theo từng trường là cờ CLI > signing theo registry > signing toàn cục > mặc định public-good. Fulcio và Rekor mặc định dùng các phiên bản public-good của Sigstore, nên chúng là tùy chọn; timestamp_url không có mặc định — dấu thời gian tin cậy không cần khóa đến từ việc được đưa vào nhật ký minh bạch của Rekor, và một cơ quan cấp dấu thời gian RFC3161 là tùy chọn bật (đặt timestamp_url, hoặc --timestamp-url, với một endpoint đầy đủ để bật). Bảo mật: khối signing: không mang tài liệu bí mật nào — token định danh OIDC không bao giờ là một trường cấu hình (đó là một bí mật có thời hạn ngắn, được cung cấp tại thời điểm ký: lấy qua luồng trình duyệt ở terminal tương tác hoặc từ workflow trên GitHub Actions, còn lại thì được truyền bằng --identity-token hoặc xuất ra dưới dạng AGGREGA_IDENTITY_TOKEN hay SIGSTORE_ID_TOKEN), và khóa riêng không bao giờ được ghi trực tiếp; key_path là đường dẫn tới một tệp khóa. Đây là sự bất đối xứng có chủ ý so với phía xác minh, nơi ghim một khóa công khai trực tiếp, còn phía ký thì chỉ bao giờ có một đường dẫn khóa.
Đánh dấu một gốc không có catalog vendor bằng cách viết workspace: {}. Danh sách catalog_dirs hỗ trợ các thiết lập monorepo trong đó một catalog dùng chung nằm trong một thư mục anh em. Trình biên dịch kiểm tra từng thư mục theo thứ tự. Cờ offline: true ngăn mọi truy cập mạng — trình biên dịch chỉ dùng các đường dẫn cục bộ và bộ nhớ đệm, và dừng lại nếu không tìm thấy một thực thể ở cục bộ. Mỗi thiết lập theo phần gom một mối quan tâm. Trong số đó: các nút vặn độ nghiêm ngặt lúc build và các gợi ý soạn thảo; các socket gắn Wasm cấp workspace (governance, linter, importer, providers, cli), mỗi socket nhận một danh sách tham chiếu plugin; độ nghiêm ngặt lint theo từng quy tắc, bao gồm các công tắc chính sách kỷ luật xuất bản; tinh chỉnh bộ nhớ đệm phân tích cú pháp của daemon và kích thước pool worker điều phối yêu cầu của nó; và giới hạn kích thước của kho mô-đun đã biên dịch dùng chung cho cả máy. Số khác nữa mang các giá trị mặc định về ký và tin cậy chữ ký cùng hành vi riêng của daemon. Mọi khóa cấp cao nhất đều được ghi lại đầy đủ tại schema/other/aggrega-config.
Có ba bộ nhớ đệm riêng biệt có thể cấu hình, và đáng dành chút thời gian để phân biệt chúng vì tên của chúng giống nhau còn phạm vi thì không. artifact_cache_dir đặt tên cho bộ nhớ đệm nội dung trên đĩa theo từng workspace được mô tả bên dưới. parse_cache giới hạn bộ nhớ đệm phân tích cú pháp trong bộ nhớ của daemon, vốn chỉ tồn tại chừng nào daemon còn tồn tại. compiled_module_cache giới hạn kho trên đĩa chứa mã máy của plugin đã biên dịch — một trong các bộ nhớ đệm được mọi workspace trên máy dùng chung, vì dạng đã biên dịch của một plugin phụ thuộc vào plugin chứ không phụ thuộc vào dự án sử dụng nó:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capTrong số các bộ nhớ đệm mà mọi dự án trên máy dùng chung, đây là bộ nhớ đệm có thể chiếm phần lớn dung lượng bộ nhớ đệm trên đĩa, vì mọi plugin mà máy chạy đều được biên dịch vào đó một lần và giữ lại, nên nó là bộ nhớ đệm duy nhất có giới hạn kích thước cố định. Mọi lần gọi mở kho đều áp dụng giới hạn trước khi biên dịch bất cứ thứ gì, xóa toàn bộ các mục, bắt đầu từ mục được biên dịch sớm nhất, cho đến khi phần còn lại vừa. (Một bản build chạy với --disable-plugin-cache thay vào đó biên dịch vào bộ nhớ, nên nó không làm kho phình ra cũng không cắt bớt kho.) Việc xóa một mục chỉ tốn một lần biên dịch lại về sau và không gì khác, đó là điều khiến việc hạ giới hạn và áp dụng nó an toàn trong khi các bản build khác đang chạy trên cùng máy. Hãy đặt giới hạn cao hơn lượng mà một bản build đơn lẻ biên dịch: vì giới hạn được áp dụng trước khi biên dịch, một giới hạn thấp hơn tập làm việc của chính một bản build sẽ khiến mọi bản build loại bỏ và biên dịch lại cùng các mô-đun, và cũng vì lý do đó kho có thể vượt giới hạn giữa các bản build và được cắt bớt lại khi bắt đầu bản build tiếp theo. aggrega cache status báo cáo kích thước của kho, và aggrega cache evict --max-size cắt bớt kho theo yêu cầu về một giới hạn được cho trên dòng lệnh.
Gốc artifact_cache_dir mang ba cây con song song mà một lần gọi aggrega pull điền đồng nhất, mỗi cây cho một loại phụ thuộc được ghim: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ cho các thực thể catalog (Components, Features, Recipes, FeatureRecipes, Aggregates, các thư viện, và Plugins cùng các tệp thực thi mà chúng xuất bản), trong đó loại là loại mà thực thể được xuất bản theo, nên hai thực thể thuộc các loại khác nhau có chung một tham chiếu và một phiên bản — một Component và một Recipe cùng tên — là hai slot; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ cho các tạo phẩm nguồn được kéo từ các trường spec.source của Recipe / FeatureRecipe (chart Helm, đoạn compose); và <artifact_cache_dir>/inputs/sha256/<hex-digest> cho các đầu vào bên ngoài — các tài liệu từ xa mà một provider yêu cầu host cung cấp trong khi render, chẳng hạn một $ref trong values.schema.json của một chart trỏ tới một URL. Mỗi slot bộ nhớ đệm của tạo phẩm nguồn mang kho lưu trữ .tgz có thẩm quyền, một thư mục dẫn xuất extracted/ được tạo lại ở mỗi lần build đọc, và một tệp metadata.yaml ghi lại danh tính {kind, url, version, digest, mediatype, pulled_at} của tạo phẩm. Mỗi slot bộ nhớ đệm của thực thể mang tạo phẩm đã xuất bản đúng như khi được tìm nạp và manifest OCI dùng để xác minh nó. Slot của mỗi loại mà tài liệu có thể đặt tên một tệp bên cạnh nó — một Recipe, một FeatureRecipe, một Component, một Feature — còn mang một thư mục dẫn xuất extracted/ chứa các tệp mà tạo phẩm đó mang theo, trong một thư mục được đặt tên theo digest nội dung của tạo phẩm: tài liệu và các tệp mà thực thể đã khai báo nếu nó được xuất bản dưới dạng kho lưu trữ, và chỉ tài liệu nếu nó được xuất bản dưới dạng tài liệu của nó (§6). Thư mục của thực thể được bày ra ở đó từ tạo phẩm đã xác minh ở mỗi lần đọc, giống như các tệp của một tạo phẩm nguồn: mọi tệp đều được kiểm tra đối chiếu với tạo phẩm, một tệp bị thay đổi hoặc thêm thủ công trong thư mục đó sẽ bị loại bỏ thay vì được đọc, không có gì khác dưới extracted/ được đọc, và một tạo phẩm không qua được xác minh sẽ bị từ chối trước khi bất cứ thứ gì được bày ra. Một lần đọc chỉ ghi lại những gì khác với tạo phẩm, nên các bản build đọc cùng một bộ nhớ đệm cùng lúc — các yêu cầu mà aggrega serve xử lý song song, hoặc hai lệnh trên cùng một workspace — đều tìm thấy nguyên vẹn các tệp đã được giao cho mình. Đoạn <digest-prefix> dài 12 ký tự tách cùng một {kind, url, version} được gắn thẻ lại ở các digest upstream khác nhau vào các slot riêng biệt. Một đầu vào bên ngoài không cần slot như vậy: nó được lưu dưới dạng một tệp đơn được đặt tên theo digest nội dung mà lockfile ghim nó vào, nên những gì một bản build sau đọc được định địa chỉ bởi phần ghim chứ không phải bởi URL mà các byte đến từ đó — đó là điều cho phép bản build ấy phục vụ đầu vào khi mạng bị chặn.
Ba thư mục khác có thể xuất hiện bên cạnh ba thư mục đó, và không thư mục nào chứa nội dung phụ thuộc được ghim: index/ mang các ảnh chụp có thể tìm kiếm theo từng registry mà aggrega registry update ghi ra (§8), signatures/ lưu đệm mỗi gói chữ ký đã xác minh dưới digest riêng của nó, để một lần đọc sau kiểm tra lại blob đã lưu đệm dựa trên digest mà nó được ghi nhận thay vì tìm nạp lại gói, và catalog-snapshots/ giữ mỗi ảnh chụp catalog đã công bố mà một lần nhập đã đọc (§8) — tệp lưu trữ và manifest của nó trong một ô được đặt tên theo digest của manifest, với cây catalog được bày ra từ tệp lưu trữ ở mỗi lần đọc, cùng một tệp current nêu tên ảnh chụp mà workspace đọc khi không có gì nêu tên một ảnh chụp khác.
Gói tài liệu không nằm trong số đó. Các byte của nó chỉ phụ thuộc vào registry nơi nó được xuất bản và phiên bản mà nó được xuất bản, nên nó được giữ một lần cho mỗi máy, bên cạnh kho mô-đun đã biên dịch dưới cùng gốc bộ nhớ đệm theo người dùng, tại docs-bundles/<encoded-reference>/<encoded-version>/ bên dưới gốc đó: gói, manifest dùng để xác minh nó, và các chữ ký mà các lần tìm nạp của nó đã xác minh. artifact_cache_dir không với tới nó. Trước khi một trang được đọc từ đó, các chữ ký ấy được xác minh lại theo cơ chế kiểm tra chữ ký riêng của workspace đang đọc đối với registry của gói, nên một bản sao được các thiết lập lỏng hơn của một workspace cho vào sẽ không được phục vụ cho một workspace mà cơ chế kiểm tra của nó từ chối bản sao đó — xem aggrega-explain và aggrega-cache.
artifact_cache_dir được viết tương đối với gốc workspace, và nó chỉ cùng một thư mục bất kể lệnh được gọi từ thư mục nào hay những thư mục catalog nào đang được quét. Một giá trị tuyệt đối bị từ chối khi cấu hình được tải, kèm một chẩn đoán nêu tên trường: mọi bên đọc thiết lập này đều phân giải nó dựa trên gốc workspace, nên một đường dẫn tuyệt đối sẽ chỉ tới một vị trí mà không bên nào với tới, và nếu không thì lỗi sẽ âm thầm — bộ nhớ đệm mà một lần pull ghi sẽ lặng lẽ không còn là bộ nhớ đệm mà một bản build đọc. Bộ nhớ đệm có thể nằm bên trong một thư mục catalog, và trong bố cục mặc định thì đúng là như vậy, vì thư mục catalog thường chính là gốc workspace. Điều nó không được làm là là một thư mục catalog: một lần quét catalog bỏ qua bộ nhớ đệm, nên một thư mục bộ nhớ đệm đồng thời là thư mục catalog sẽ đưa toàn bộ nội dung của thư mục đó ra khỏi mọi lần quét. artifact_cache_dir: . chỉ gốc workspace, mà trong bố cục mặc định chính là trường hợp đó, và nó bị từ chối khi cấu hình được tải kèm một chẩn đoán nêu tên trường — cũng như mọi cách viết khác quy về gốc workspace. Hai dạng đó, cùng với đường dẫn tuyệt đối ở trên, là những dạng mà phép kiểm tra cấu hình có thể tự nhận ra. Một giá trị chỉ tới một thư mục catalog khác — sub, trong một workspace có catalog_dirs liệt kê sub — được tải mà không có phàn nàn nào, và triệu chứng duy nhất là các thực thể bên dưới nó không còn được tìm thấy. Vì vậy, giữ bộ nhớ đệm nằm ngoài mọi thư mục được liệt kê trong workspace.catalog_dirs là một phần của việc viết cấu hình chứ không phải điều mà nó kiểm tra giúp bạn.
Việc bỏ qua bộ nhớ đệm là điều ngăn một tạo phẩm phân giải bị đọc như thể một tác giả đã viết nó. Một slot bộ nhớ đệm chứa các byte mà một lần tìm nạp từ registry đã đặt vào đó, được lưu dưới tọa độ nơi chúng được tìm nạp và được bảo chứng bởi một digest trong lockfile; một lần quét nhặt một slot như vậy làm nội dung catalog do tác giả viết sẽ tiếp nhận các byte chưa được gì xác minh, trên một đường dẫn mà tác giả không thể chỉnh sửa. Có một hệ quả đáng nói rõ: nếu bộ nhớ đệm chứa một thực thể không được lockfile nào ghim — bị bỏ lại do một lần pull bị gián đoạn, được sao chép thủ công, hoặc bị bỏ rơi khi một Release không còn tham chiếu tới nó — thì thực thể đó không hiển thị với một lần quét catalog, và một bản build hoặc lần xác thực phụ thuộc vào nó sẽ dừng lại với thông báo rằng không tìm thấy thực thể. Cách khắc phục là pull lại Release, để thực thể được phân giải thông qua lockfile và digest của nó được ghi lại; việc dừng lại nêu tên thực thể để có thể xác định phần ghim còn thiếu. Lựa chọn còn lại — vẫn cứ phân giải nó — chính là việc đọc không được xác minh mà việc bỏ qua bộ nhớ đệm tồn tại để ngăn chặn.
Lockfile được tạo riêng cho từng Release: việc phân giải release.yaml sẽ ghi release.lock bên cạnh nó (phần tên gốc của tệp Release cộng với .lock). aggrega pull phân giải các phụ thuộc và ghi lockfile; aggrega build đọc nó và dùng các phiên bản đã ghim bất kể trạng thái của registry tại thời điểm build. Các workspace commit lockfile khi khả năng tái lập build giữa các máy là quan trọng; sau khi một thực thể, một thư viện, một plugin hoặc chính Release thay đổi trong workspace, aggrega pull --release <release> làm mới nó, phân giải lại những gì đã thay đổi trong khi giữ nguyên mọi ghim khác, và aggrega pull --upgrade --release <release> là cách để chấp nhận một phiên bản mới hơn mà registry hiện cung cấp. Lockfile ghi lại mọi thực thể đã phân giải cùng với loại của nó, URI của nó như đã viết, phiên bản đã phân giải, digest nội dung và các vị trí tham chiếu đến nó. Loại và URI cùng nhau xác định một mục, nên một Release có Aggregate và Manifest trùng tên sẽ ghi một mục cho mỗi thực thể, và một chỉnh sửa ở bất kỳ thực thể nào trong hai sẽ dừng bản build tiếp theo cho đến khi một lần pull ghi lại nó:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Mỗi mục đã ghim mang loại + URI + phiên bản đã phân giải + digest định địa chỉ theo nội dung. Digest được xác minh ở mỗi lần tải; các byte không khớp với digest đã ghim sẽ dừng build với một lỗi toàn vẹn. Digest của một thực thể được tính trên những gì một lần xuất bản của nó mang theo — tài liệu của nó và mọi tệp mà nó khai báo bên cạnh, mỗi tệp theo đường dẫn và byte của nó — chứ không phải trên các byte mà nó được truyền đi, nên cùng một thực thể ghi lại cùng một digest dù được đọc từ một thư mục catalog hay được tải từ một registry, bất kể kho lưu trữ của nó được nén thế nào và bất kể một lần checkout đã gán cho các tệp của nó những bit quyền nào, kể cả bit thực thi. Một lần tải trước hết được kiểm tra đối chiếu với digest mà chính registry tính trên các byte đã xuất bản, thông qua manifest, mà digest của nó được một mục phân giải qua registry ghi lại bên cạnh digest của chính mục đó.
5. Mô hình phân giải thực thể ba tầng
Trình biên dịch phân giải mọi tham chiếu thực thể gặp phải trong quá trình biên dịch thông qua một quy trình tra cứu xếp tầng nghiêm ngặt. Ba tầng — đường dẫn cục bộ, workspace và bộ nhớ đệm, và registry — tương ứng với ba quy trình làm việc soạn thảo cùng tồn tại trong một dự án Aggrega lành mạnh: một Release nêu tên các tệp nằm cạnh nó, một nhóm sử dụng một catalog đã được commit cùng với bộ nhớ đệm đã kéo trước đó, và một lần pull truy cập registry để lấy một artifact chưa được tải. Tầng workspace và bộ nhớ đệm cùng tầng registry của cùng quy trình xếp tầng này đánh giá các trường type trong các Aggregates, các giá trị URI trong các ánh xạ của Manifest, các khai báo implements trên các Recipes và FeatureRecipes, và các tham chiếu plugin bên trong các pipeline của Recipe và FeatureRecipe; chỉ những tệp mà một Release và Manifest của nó nêu tên mới đến được tầng đường dẫn cục bộ.
Đường dẫn cục bộ. Một tham chiếu aggregate, manifest hoặc extends của một Release, hoặc extends của một Manifest, bắt đầu bằng ./ hoặc ../ (một tiền tố đường dẫn tương đối POSIX) được đọc trực tiếp từ đĩa, tương đối với Release. Không tra cứu catalog, không gọi registry. Tiền tố tường minh phân biệt ý định đường dẫn cục bộ với việc tra cứu theo tên ở cấp cú pháp: một Release viết aggregate: ./aggregate.yaml nêu tên một tệp; aggregate: checkout nêu tên một Aggregate theo metadata.name của nó. Trình phân giải không bao giờ dò nội dung chuỗi để quyết định tầng nào được áp dụng — tiền tố chính là yếu tố phân biệt. Mọi tham chiếu khác, kể cả type của một Component trong một Aggregate, đều được phân giải qua tầng workspace và bộ nhớ đệm và tầng registry: một thực thể được soạn cục bộ được đặt dưới catalog/ ở gốc workspace hoặc trong một thư mục mà workspace.catalog_dirs liệt kê, và một type được viết dưới dạng đường dẫn tệp tương đối sẽ dừng bản build như một thực thể không catalog nào chứa.
Workspace và bộ nhớ đệm. Một tham chiếu không có tiền tố đường dẫn cục bộ tường minh trước hết được tìm trong các thư mục liệt kê ở workspace.catalog_dirs (các cây catalog cục bộ của dự án được soạn trong kho mã hoặc sao chép vào đó — xem §4 để biết hình dạng cấu hình) — hoặc, đối với một Release mà cấu hình cấp cho các thư mục riêng dưới workspace.releases, trong các thư mục của Release đó — sau đó trong thư mục catalog/ của gốc workspace, rồi trong artifact_cache_dir (vị trí .aggrega/cache/ bị git bỏ qua, chứa các artifact được kéo về từ các lần phân giải qua registry trước đó, với các cây con được mô tả ở §4). Việc trúng bộ nhớ đệm từ lần build thứ hai trở đi là điều giữ cho vòng lặp bên trong không cần mạng ngay cả khi dự án phụ thuộc vào nội dung catalog từ xa.
Registry. Nếu tầng workspace và bộ nhớ đệm không trả về kết quả khớp nào, aggrega pull — hoặc một bản build chạy với --auto-pull hay với thiết lập auto_pull của workspace — thực hiện một lệnh pull OCI dựa trên ORAS tới default_registry (mặc định hub.aggrega.ai), giải nén artifact vào bộ nhớ đệm cho các lần build tiếp theo và tiếp tục với thực thể đã phân giải. Một bản build không có cả hai chỉ đọc những gì lockfile của nó ghim, và dừng lại, nêu tên aggrega pull, khi thiếu lockfile. Dạng URI OCI mà lời gọi registry xây dựng tuân theo phân loại theo kiểu thực thể được mô tả ở §6 (Đóng gói artifact & phân loại OCI). Các URI viết tắt trong các Aggregates và Manifests được mở rộng thành dạng OCI đầy đủ trước lời gọi registry; các quy tắc suy luận chi phối việc mở rộng đó nằm ở tài liệu tham chiếu URI viết tắt nhận biết ngữ cảnh của Manifest và ở §8 bên dưới.
Thứ tự ưu tiên và che khuất. Thứ tự ưu tiên phân giải nghiêm ngặt là đường dẫn cục bộ > workspace và bộ nhớ đệm > registry. Một thực thể trong một thư mục catalog cục bộ có cùng định danh với một thực thể trong registry sẽ che khuất thực thể registry đó — điều này là có chủ đích và cho phép các tác giả catalog thử nghiệm các sửa đổi trước khi xuất bản. Việc che khuất tương tự cũng áp dụng giữa catalog_dirs và bộ nhớ đệm: một thực thể có trong một thư mục catalog của workspace được ưu tiên hơn bản sao trong bộ nhớ đệm, đảm bảo các chỉnh sửa cục bộ đối với một catalog được sao chép vào kho mã có hiệu lực ngay lập tức.
Trong tầng workspace và bộ nhớ đệm, catalog_dirs là một ngăn xếp ưu tiên có thứ tự theo nguyên tắc cái đầu tiên thắng. Khi cùng một định danh thực thể xuất hiện trong nhiều thư mục catalog được liệt kê, thư mục được liệt kê trước sẽ thắng và lần xuất hiện sau bị che khuất — bị ghi đè, không được tải, và không phải là lỗi. Điều này cho phép một dự án đặt thư mục catalog của riêng mình trước một thư mục dùng chung hoặc được sao chép vào kho mã và ghi đè các thực thể được chọn theo định danh, trong khi phần còn lại rơi xuống thư mục dùng chung. Việc ghi đè có thể quan sát được: chi tiết phân giải cho biết thư mục nào thắng và thư mục nào bị che khuất, nên việc xếp lớp không bao giờ diễn ra âm thầm. Việc che khuất chỉ áp dụng giữa các thư mục; hai tệp trong cùng một thư mục cùng nhận một định danh là một lỗi soạn thảo và dừng quá trình tải. Một thư mục được nêu nhiều hơn một lần — bởi một cờ --catalog và trong catalog_dirs, hoặc hai lần trong danh sách — là một mục duy nhất của ngăn xếp, được tìm một lần tại vị trí nó được nêu đầu tiên, nên một lần che khuất luôn liên quan đến hai tệp khác nhau và không bao giờ là một thư mục được đọc đối chiếu với chính nó. Vì thứ tự ưu tiên tuân theo thứ tự thư mục do tác giả kiểm soát, tập hợp đã phân giải là tất định.
Thư mục catalog/ của gốc workspace tham gia ngăn xếp đó ở cuối, không phải ở đầu, và chỉ khi thư mục đó tồn tại — nên bất cứ thứ gì một dự án liệt kê đều thắng nó khi xung đột, và việc liệt kê một thư mục không liên quan không bao giờ âm thầm khiến nó ngừng được đọc. Nó bị bỏ qua khi một mục được liệt kê đã bao trùm nó, vì việc duyệt một thư mục được liệt kê là đệ quy và một ngăn xếp nêu gốc workspace đã đọc nó rồi. Bỏ qua catalog_dirs và viết nó là một danh sách rỗng là hai khai báo khác nhau: nếu bỏ qua, workspace vẫn đọc catalog/; nếu viết là [], workspace không đọc catalog cục bộ nào, và đó là cách một workspace khai báo rằng nó không có catalog nào.
Build cách ly mạng. Đặt offline: true (§4) sẽ bỏ qua hoàn toàn tầng registry. Một tham chiếu không phân giải được ở tầng đường dẫn cục bộ hoặc tầng workspace và bộ nhớ đệm sẽ phát sinh lỗi thiếu thực thể thay vì âm thầm thử một lời gọi mạng, điều này mang lại cho các pipeline CI không được phép truy cập mạng về mặt pháp lý một hợp đồng thất bại nhanh mang tính tất định.
Nơi quy trình xếp tầng hoạt động. Quy trình xếp tầng tải thực thể vào bộ nhớ; các cơ chế phân giải tiếp theo được xếp chồng lên trên — tra cứu hai tầng type so với name của Manifest, việc khớp phiên bản ba dạng của implements (chính xác / khoảng tương thích phiên bản chính / không phiên bản) tại vocabulary/inheritance-and-interface, và việc chọn Recipe theo từng trục dựa trên provider và thể hiện thành phần — hoạt động trên các thực thể mà trình phân giải đã kéo về qua quy trình xếp tầng này.
6. Đóng gói artifact & phân loại OCI (năng lực là phân đoạn dẫn đầu)
Aggrega xử lý logic hạ tầng giống như cách Docker xử lý image container, sử dụng các tiêu chuẩn Open Container Initiative (OCI) thông qua ORAS (OCI Registry As Storage). Người dùng có thể lưu trữ catalog Aggrega của mình trên bất kỳ registry tiêu chuẩn nào (GHCR, AWS ECR, Aggrega Hub).
Vì các Recipes tương ứng nghiêm ngặt 1:1 với một năng lực kết xuất — một Recipe nêu một năng lực trong spec.capability và không thể nhắm tới hai — cách gọn gàng nhất để tổ chức chúng trong một registry OCI là đặt năng lực vào phân đoạn repository dẫn đầu.
Phân loại OCI bao quát mọi kiểu thực thể. Tên repository là phân đoạn kind — kind của thực thể, viết thường — theo sau là định danh của thực thể, viết thường toàn bộ:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, nhà phát hànhcore, danh mụcdatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, nhà phát hànhcore, danh mụccomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, nhà phát hànhcore(phẳng, không có danh mục)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Mô-đun Aggregate có thể tái sử dụnghub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, năng lựchelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, năng lựchelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, năng lựccomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, năng lựchelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, các định nghĩa schema dùng chung;metadata.namedạng PascalCaseAIDatastoresđược viết thường trong tên repositoryhub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, các đoạn ánh xạ Go-template dùng chunghub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, kiểu socketprovider(phân đoạnmetadata.pluginType)
Các kind có thể xuất bản bao gồm các kind soạn thảo của catalog cùng với Aggregate, một mô-đun có thể tái sử dụng (có thể xuất bản dù sau này nó được tham chiếu làm spec.aggregate cấp cao nhất của một Release hay được lồng trong khối aggregates: của một Aggregate khác), và Plugin, một tham chiếu định địa chỉ theo nội dung tới một artifact WebAssembly mà trình biên dịch định tuyến và runtime thực thi. Plugin là một artifact có thể xuất bản mang tính cấu trúc chứ không phải một kind soạn thảo của catalog. Release và Manifest là các đầu vào phía triển khai nằm trong hệ thống quản lý mã nguồn và không bao giờ được push — aggrega push từ chối chúng — nên chúng không có mediatype xuất bản. aggrega push --list-kinds báo cáo tập hợp mà tệp nhị phân đã cài đặt xuất bản, mỗi dòng một kind. Mỗi kind có thể xuất bản có mediatype OCI riêng ở mỗi dạng trong hai dạng mà một lần xuất bản có thể mang:
| Kind thực thể | Xuất bản dưới dạng tài liệu của nó | Xuất bản cùng các tệp nó khai báo |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — không khai báo tệp nào |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — không khai báo tệp nào |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — không khai báo tệp nào |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — không khai báo tệp nào |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — không khai báo tệp nào |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — xuất bản qua manifest riêng của nó |
Những gì một lần xuất bản mang theo, và do đó hình dạng của nó, xuất phát từ những gì thực thể khai báo — không phải từ kind của nó, và không phải từ những gì nằm trong thư mục của nó. Một lần xuất bản mang tài liệu của thực thể và các tệp mà chính thực thể nêu bên cạnh: source: cục bộ của một Recipe hoặc FeatureRecipe — một thư mục được mang theo cùng mọi tệp bên dưới nó mà các quy tắc bỏ qua được ghi trong entity.lock của nó giữ lại — mọi tệp mà các mục valuesMapping:, workload: và artifacts: của nó nhập bằng $import:, và entity.lock mà bước ghim của nó đã ghi; cùng mọi tệp schema mà một Component hoặc Feature nhập, kể cả mọi tệp của một chuỗi nhập. Không có gì khác trong thư mục được mang theo: một ghi chú, một README hay đầu ra của một lần build nằm cạnh thực thể không thuộc về những gì nó xuất bản, dù được gọi là gì, và không thay đổi hình dạng mà nó được xuất bản. Một thực thể không nêu gì được xuất bản dưới dạng tài liệu đã viết của nó, từng byte một, dưới mediatype +yaml của kind; một thực thể nêu một tệp được xuất bản dưới dạng một tệp tar nén gzip gồm tài liệu và các tệp đó, dưới mediatype +tar+gz của kind. Một Aggregate, một Plugin và các kind thư viện không khai báo tệp nào bên cạnh tài liệu, nên chúng luôn được xuất bản dưới dạng tài liệu — kể cả một Aggregate ở gốc workspace, vì mọi đường dẫn nó khai báo đều nêu một thực thể khác chứ không phải một tệp nó mang theo; một Recipe có toàn bộ nội dung nội tuyến cũng vậy. Một nguồn từ xa là một tham chiếu chứ không phải một tệp, nên nó không mang gì, dù entity.lock ghi lại ghim của nó khiến một Recipe như vậy trở thành một kho lưu trữ. Phân đoạn phiên bản của mỗi mediatype là chung cho mọi kind có thể xuất bản, và phân đoạn mã hóa cho biết các byte thuộc dạng nào trong hai dạng. Công cụ hạ nguồn điều phối dựa trên toàn bộ chuỗi mediatype — kind, phiên bản và mã hóa cùng nhau.
Một hình dạng soạn thảo không nêu thư mục nào mà một lần xuất bản có thể biết: một nguồn cục bộ được viết dưới dạng template. Thư mục của nó chỉ được chọn khi một Release điền vào template, nên thực thể mang theo mọi tệp trong thư mục của chính nó mà các quy tắc bỏ qua đã ghi giữ lại, để bất kỳ thư mục nào một Release chọn cũng đã được mang theo; aggrega push sẽ thông báo điều đó khi nó xảy ra. Chỉ mang theo những gì được nêu có một cái giá, và cái giá đó rơi vào bên sử dụng: một tệp mà thực thể đọc nhưng không nêu ở đâu sẽ không được mang theo, và chính bản build của bên sử dụng — không phải lần push của nhà phát hành — gặp phải sự vắng mặt của nó, nêu đường dẫn bị thiếu bên trong khe bộ nhớ đệm của mình.
Những tệp nào của một thư mục nguồn thuộc về thực thể được quyết định một lần, khi thực thể được ghim, và được ghi lại. Plugin phục vụ năng lực của thực thể trong workspace của tác giả khai báo những gì hệ sinh thái của nó không bao giờ phân phối — các thư mục quản lý phiên bản của một plugin chart và việc nó tôn trọng .helmignore của một chart, .terraform/ của một plugin mô-đun — và .aggregaignore của tác giả bên cạnh thực thể có tiếng nói cuối cùng. Bước ghim ghi lại plugin đó và các quy tắc đã kết hợp trong entity.lock, và việc xuất bản, mọi phép so sánh các ghim của nguồn, dòng lockfile của thực thể và quá trình kết xuất đều áp dụng các quy tắc đã ghi thay vì hỏi lại một plugin, nên những gì được xuất bản chính là những gì bản build của chính tác giả kết xuất, và một binding đã thay đổi hay một tệp nhị phân mới hơn không làm dịch chuyển digest nào cho đến khi thực thể được ghim lại. Trình biên dịch không có quan điểm nào về bất kỳ hệ sinh thái nào: các quy tắc đến từ plugin và tác giả, và trình biên dịch chỉ đối khớp chúng. Một liên kết tượng trưng giữa các tệp của thực thể bị từ chối thay vì được đi theo, vì thứ nó trỏ tới sẽ được mang theo dưới tên của nó. aggrega pin trình bày đầy đủ các quy tắc.
Tên của một Recipe không mang tiền tố miền cũng không mang năng lực: thư mục kiểu thực thể và phân đoạn năng lực đã nói lên cả hai.
Quy ước đặt tên: các Components (Miền 2) dùng {publisher}/{category}/{name}, còn các Features (Miền 2) và các Aggregates tái sử dụng được (Miền 1) dùng {publisher}/{name}, trong đó phân đoạn publisher nêu nhà cung cấp/tác giả (core = thư viện chuẩn chính thức, acme = doanh nghiệp). Các thực thể Miền 3 (Recipe, FeatureRecipe) dùng {capability}/{name}, trong đó năng lực là provider mà thực thể khai báo trong spec.capability; một tham chiếu cũng có thể nêu thực thể ở dạng trần, chỉ bằng phần lá. Tên Recipe cũng KHÔNG bao gồm năng lực, vì nó đã là phân đoạn dẫn đầu của URI chuẩn tắc.
Các Recipes dùng từ khóa implements để gắn với giao diện mà chúng đáp ứng. Trường implements hỗ trợ khớp chính xác, khớp theo khoảng tương thích phiên bản chính, hoặc khớp không phiên bản (xem vocabulary/inheritance-and-interface về việc khớp phiên bản của implements). Recipe của một mục ánh xạ trong Manifest phải triển khai kiểu mà nó được ánh xạ cho, hoặc một kiểu cơ sở mà kiểu đó extends: khóa của mục, và kiểu của mỗi thể hiện thành phần mà khóa đạt tới ở một phiên bản mà khóa không nêu, theo phiên bản mà bản build biên dịch thể hiện đó — nên một khóa không thể gửi một thể hiện tới một Recipe được viết cho một phiên bản khác của kiểu của nó.
Khi một kỹ sư Ops chạy aggrega push, CLI xuất bản thực thể ở hình dạng đó, bất biến tại phiên bản của nó. Bên sử dụng tải nó về qua Mô hình phân giải ba tầng, lưu vào bộ nhớ đệm cục bộ trong .aggrega/cache/ và bày những gì nó mang theo vào khe bộ nhớ đệm của thực thể (§4) — các tệp của một kho lưu trữ, hoặc chỉ riêng tài liệu.
Một thực thể được pull về đọc các tệp mà nó mang theo đúng như cách nó đọc chúng khi nằm cạnh nó trong một thư mục catalog. Thực thể được đọc từ vị trí của nó trong cây đã được bày ra đó, vì vậy một source: hoặc $import: tương đối mà nó khai báo — được viết ra trực tiếp hoặc do một template tạo ra — được phân giải bên trong những gì đã được phát hành, và một đường dẫn đi ra khỏi thư mục riêng của thực thể bị từ chối ở đó giống hệt như trong một thư mục catalog. Không có gì bên ngoài cây được đọc thay thế: không phải thư mục mà một bản build chạy từ đó, và không phải một tệp được đặt vào slot bộ nhớ đệm. Một Component hoặc Feature có schema được import từ một tệp sẽ mang theo tệp đó, vì vậy một bản sao được pull về tải hợp đồng đã được phát hành và xác thực các giá trị được viết dựa trên nó đúng như một bản sao được đọc từ thư mục catalog.
Đọc lại thực thể từ một gói là bước ngược lại, và nó nhận diện thực thể theo việc tài liệu là gì chứ không theo tên gọi của nó: tài liệu ở cấp cao nhất của gói có kind: là một loại thực thể có thể phát hành. Tên tệp của thực thể là một quy ước của catalog chứ không phải một hợp đồng, vì vậy recipe.yaml là thứ mà catalog thư viện chuẩn viết ra chứ không phải thứ định dạng yêu cầu, và một tệp được mang theo bên cạnh thực thể — một template chart, một đoạn compose — không bị nhầm là thực thể đó. Quy tắc này không thể làm theo chiều ngược lại, tức là dựa trên loại mà bên sử dụng đang tìm: một loại được đọc từ thực thể, vốn nằm bên trong gói, nên vào thời điểm phải mở gói thì chưa có loại nào để dựa vào. Phía đọc dừng lại thay vì lựa chọn khi cấp cao nhất của một gói chứa hai tài liệu thực thể — gói mà một client khác tạo ra bằng cách đóng gói cả một thư mục chứa hai thực thể, gói này khi đó sẽ nằm dưới từng tọa độ đã phát hành của chúng như một artifact duy nhất. Việc phát hành của sản phẩm này không thể tạo ra gói như vậy, vì mỗi thực thể chỉ mang theo những gì nó khai báo, và ngoài ra phía phát hành cũng từ chối một thư mục như thế: mỗi loại có thư mục riêng, trừ Aggregate, Release và Manifest, và aggrega pin cùng aggrega push từ chối một thực thể thuộc bất kỳ loại nào khác có một thực thể khác nằm cạnh nó, trong khi việc tải catalog, lint và build để nguyên thư mục. Tên của một thư mục không được đánh giá ở phía nào cả: bố cục <name>/<version>/ là quy ước của catalog thư viện chuẩn.
Một thực thể đã phát hành được đọc qua cùng bước đó. Một tọa độ mang đúng một bản sao của thực thể của nó, ở hình dạng mà các khai báo của nó đã tạo ra, và một người xem nó bằng aggrega inspect oci://<registry>/<repository>:<tag> chứ không qua một bản sao dễ đọc được phát hành bên cạnh — vì vậy không có bản sao thứ hai nào có thể trở nên khác với bản mà một bản build phân giải. Lệnh này giải nén một archive theo quy tắc ở trên, đọc thực thể của một Plugin từ manifest của nó thay vì từ tệp thực thi được phát hành cùng nó, và hiển thị kết quả như cách một tệp thuộc loại đó được hiển thị; xem Đọc một thực thể đã phát hành.
Các annotation manifest có thể tìm kiếm. Mỗi lần phát hành đóng dấu một tập nhỏ các annotation có thể tìm kiếm lên manifest OCI của artifact, để một chỉ mục registry hoặc một trình duyệt catalog có thể lọc artifact theo siêu dữ liệu catalog của chúng mà không cần tải và phân tích nội dung của từng thực thể. Mỗi thực thể mang mô tả dễ đọc cho con người (annotation mô tả OCI chuẩn) cùng với danh mục catalog và loại của nó. Một Plugin còn mang thêm loại socket của nó và các capability mà nó phục vụ. Các annotation này là những gì aggrega registry update đọc lại vào chỉ mục tìm kiếm cục bộ (§8).
Mọi tệp được phát hành đều có tên. Mỗi tệp mà một lần phát hành mang theo được đặt tên trên manifest bằng annotation chuẩn org.opencontainers.image.title, đó là tên mà một client OCI thông thường dùng để ghi tệp đó khi pull artifact vào một thư mục. Tên cho biết tệp là gì, và phần mở rộng của nó tuân theo media type của tệp:
| Những gì được phát hành | Tệp mà một client OCI thông thường ghi ra |
|---|---|
| một thực thể được phát hành dưới dạng tài liệu của nó | entity.yaml |
| một thực thể được phát hành cùng các tệp mà nó khai báo | entity.tar.gz |
| một Plugin | entity.yaml, thực thể, bên cạnh entity.wasm, tệp thực thi của nó |
| một chữ ký được đính kèm vào một artifact | signature.json |
| một dấu hiệu ngừng hỗ trợ được đính kèm vào một artifact | deprecation.json |
một artifact dữ liệu được phát hành bằng aggrega push-artifact | tên được chỉ định bằng --name |
Vì vậy oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server để lại thực thể đã phát hành tại ./server/entity.yaml, đúng từng byte như khi được phát hành. oras bỏ qua một descriptor không mang tên và vẫn báo thành công, đó là lý do mọi descriptor mà một lần phát hành đóng gói đều mang một tên. Tên chỉ được suy ra từ media type, không bao giờ từ tên của tệp đã được phát hành, vì vậy cùng các byte được phát hành từ một tệp có tên khác sẽ tạo ra cùng một manifest. Một thực thể được phát hành cùng các tệp của nó đến dưới dạng gói của nó: entity.tar.gz đặt tên cho gói, và thực thể bên trong được tìm thấy theo quy tắc ở trên chứ không theo bất kỳ tên tệp nào. Bản thân cơ chế phân giải của Aggrega không bao giờ đọc các tên này — nó chọn từng tệp theo media type và tin cậy tệp đó theo digest — vì vậy chúng tồn tại để phục vụ mọi client khác.
7. Kiến trúc Recipe: con trỏ và mapper
Xem entities/recipe để biết toàn bộ bề mặt soạn thảo của Recipe — source: (con trỏ), valuesMapping: (mapper, với ba chế độ soạn thảo: block scalar nội tuyến, $import: từ tệp, $import: từ thư viện tới một mục của MappingLibrary), schema nguồn do Wasm điều khiển, hỗ trợ IaC gốc và các ví dụ hoàn chỉnh.
8. Registry mặc định và URI rút gọn nhận biết ngữ cảnh
Để loại bỏ sự phình to của YAML, trình biên dịch phân giải các URI rút gọn theo cách nhận biết ngữ cảnh dựa trên vị trí trong schema nơi chúng xuất hiện. Registry mặc định được cấu hình trong .aggrega-config.yaml (mặc định là hub.aggrega.ai).
Một host registry chỉ có một cách đọc. Mỗi registries[].host được viết dưới dạng chính host đó — một tên host chữ thường có chứa dấu chấm, localhost, một tên đơn theo sau là một cổng, một địa chỉ IPv4 hoặc một địa chỉ IPv6 trong ngoặc vuông, mỗi loại có thể kèm :port tùy chọn, và không có scheme, đường dẫn, thông tin xác thực hay chữ in hoa — vì cách viết đó là khóa để tìm mọi chính sách tin cậy theo từng registry, và yêu cầu chữ ký tích hợp của hub chính thức được gắn với hub.aggrega.ai. default_registry đặt tên một host theo cùng cách, và có thể theo sau bằng một đường dẫn repository, chẳng hạn ghcr.io/acme: khi đó mọi thứ được phát hành qua registry mặc định sẽ nằm dưới đường dẫn đó, và mọi tham chiếu ngắn được phân giải dưới nó, trong khi sự tin cậy vẫn chỉ do host quyết định. Thay vào đó, default_registry có thể được viết dưới dạng name: của một mục registries, và khi đó đại diện cho host của mục đó. Tên được đọc một lần, khi cấu hình được phân giải, dựa trên các mục có hiệu lực sau mọi tệp cấu hình và môi trường, vì vậy mọi bên đọc registry mặc định — việc phát hành, liên kết vị trí, xác minh chữ ký và mọi lần tra cứu tin cậy — đều đọc host của một mục duy nhất đó, và không bên nào tới được một host được viết giống như tên; một tên theo sau bởi một đường dẫn bị từ chối, vì một tên đại diện cho một mục chứ không phải một vị trí. Tên được so khớp trước cách viết host, và một tên mà hai mục cùng mang bị từ chối vì mơ hồ. Cùng cách đọc đó quyết định ba việc mà một lần pull thực hiện với host: vị trí registry mà một danh tính catalog không có host được gắn vào, liệu artifact được tải về có nêu tên một registry mà chữ ký của nó được kiểm tra hay không, và việc kiểm tra đó chạy theo chính sách tin cậy nào. Một cách viết có thể tới được một registry nhưng lại bỏ lỡ chính sách của nó — chữ in hoa, một cổng HTTPS mặc định được ghi rõ, một scheme, thông tin xác thực, một đường dẫn trên host của một mục registries — bị từ chối ngay tại nơi nó được cấu hình, kèm theo cách viết cần dùng, và một tên đơn không có cổng không nêu tên mục nào cũng vậy, vì đó là hình dạng của phân đoạn đầu tiên của một danh tính catalog chứ không phải của một host. Việc từ chối áp dụng ở mọi lớp có thể đặt giá trị: tệp cấu hình, nơi schema nêu cùng hình dạng đó dưới dạng pattern trên mỗi registries[].host; biến môi trường AGGREGA_DEFAULT_REGISTRY; và dòng lệnh. Vì vậy mọi host mà một cấu hình có thể nêu tên đều là host có artifact được xác minh theo chính sách được viết cho nó. Host chỉ được đánh giá theo cách viết của nó; việc tên có phân giải được hay không, hoặc có registry nào trả lời ở đó hay không, là trạng thái runtime mà trình biên dịch không bao giờ truy xuất. cấu hình trình bày chi tiết các dạng được chấp nhận kèm ví dụ.
URI rút gọn được phân giải theo cách nhận biết ngữ cảnh dựa trên Manifest; xem ../language-reference/entities/manifest.md §URI rút gọn nhận biết ngữ cảnh để biết các quy tắc suy luận cụ thể.
Quản lý registry
aggrega registry quản lý các registry mà workspace biết và chính sách tin cậy chữ ký của chúng. Danh tính của một registry là host của nó; các lệnh con dùng chung một mô hình định danh:
aggrega registry add <host>đăng ký một registry và ghim chính sách tin cậy của nó, tải chính sách mà registry công bố ở lần liên hệ đầu tiên, trừ khi các flag tin cậy cung cấp một chính sách theo cách thủ công. Một--name <alias>tùy chọn gắn một bí danh thân thiện vào cùng mục được khóa theo host — host vẫn là danh tính, và bí danh được phân giải về host đó ở bất cứ nơi nào một registry được nêu tên. Một bí danh là duy nhất trên toàn bộ các registry.aggrega registry listin ra mọi registry đã cấu hình — host, bí danh, bản tóm tắt ngắn về tư thế tin cậy và một dấu đánh dấu trên registry mặc định — theo thứ tự host tăng dần. Lệnh này đọc cấu hình đã phân giải và không liên hệ với mạng nào.aggrega registry remove <name|host>xóa mục chính sách tin cậy của một registry, được chỉ định bằng host hoặc bí danh của nó. Lệnh này chỉ xóa chính sách tin cậy: con trỏdefault_registryđược giữ nguyên và khả năng push lên host đó không bị ảnh hưởng, vì vậy host trở về mức tin cậy mặc định thay vì trở nên không thể truy cập. Mộtdefault_registryđược viết dưới dạng tên của mục đã bị xóa sẽ không còn nêu tên gì sau đó, và bị từ chối cho đến khi được viết lại.aggrega registry updatelàm mới chỉ mục tìm kiếm cục bộ, được mô tả bên dưới.
Ở bất cứ nơi nào một registry được nêu tên — một đối số của lệnh con registry hoặc flag --registry trên aggrega push và aggrega push-artifact — cùng một resolver sẽ diễn giải token: một bí danh đã cấu hình được phân giải về host của nó, và mọi token khác được đọc như host mà nó nêu tên, với scheme, đường dẫn và thông tin xác thực của một tham chiếu bị loại bỏ. Ở nơi host đó trở thành thứ mà một quyết định về chữ ký được đưa ra dựa trên nó — đích của aggrega push hoặc aggrega push-artifact, hoặc khóa mà aggrega registry add ghi một mục dưới đó — nó bị buộc tuân theo cách đọc duy nhất ở trên và bị từ chối, kèm theo cách viết cần dùng, khi nó không được viết theo cách đó. Một host chưa đăng ký nhưng được viết theo cách đó là một đích hợp lệ và được chấp nhận.
Chỉ mục tìm kiếm cục bộ
aggrega registry update [<name|host>] xây dựng một chỉ mục tìm kiếm cục bộ của các registry mà workspace biết. Lệnh này duyệt các repository của từng registry đã cấu hình, chọn phiên bản đã phát hành cao nhất của mỗi repository, đọc các annotation manifest có thể tìm kiếm của phiên bản đó (§6), và ghi một chỉ mục cho từng registry vào bộ nhớ đệm artifact. Khi không có đối số, nó lập chỉ mục mọi registry đã cấu hình; với một đối số registry duy nhất (một host hoặc một bí danh), nó chỉ lập chỉ mục registry đó.
Chỉ mục tuân theo mô hình làm mới tường minh quen thuộc từ các trình quản lý gói: registry update là lệnh liên hệ với các registry, và một lệnh aggrega search sau đó đọc chỉ mục đã ghi ở chế độ ngoại tuyến. Tệp bản ghi của một registry có tính tất định — hai lần cập nhật trên cùng trạng thái registry tạo ra các byte giống hệt nhau, và dấu thời gian độ mới nằm trong một tệp anh em để nó không bao giờ làm xáo trộn các bản ghi. Một repository không có phiên bản đã phát hành nào, hoặc không thể đọc được, sẽ bị bỏ qua để một repository không đọc được không bao giờ khiến toàn bộ chỉ mục bị hủy bỏ.
Ảnh chụp catalog được công bố
Mỗi lần công bố catalog thư viện chuẩn cũng công bố toàn bộ catalog: một artifact OCI, một tệp tar nén gzip chứa mọi tệp mà cây catalog có tại commit mà lần công bố đó đã công bố, tại catalog/snapshot bên dưới registry mà catalog được công bố lên — hub.aggrega.ai/catalog/snapshot đối với hub chính thức. Nó chỉ được đẩy lên sau khi mọi thực thể của lần công bố đó đã có trên registry, nên nó không nêu tên thực thể nào mà registry không chứa. Nó được gắn thẻ bằng commit mà nó được xây dựng từ đó và bằng latest, và được bên công bố ký không cần khóa, như mọi thực thể của lần công bố, nên danh tính của bên công bố xác minh nó theo chính sách tin cậy của registry; latest chỉ chuyển sang một ảnh chụp khi ảnh chụp đó đã được ký. Tệp lưu trữ được ghi theo một bố cục cố định duy nhất — các mục theo thứ tự tăng dần của tên, mỗi mục có cùng chế độ, chủ sở hữu và thời điểm sửa đổi — nên một commit luôn tạo ra cùng một tệp tar.
Bên đọc duy nhất của nó là một lần nhập mà workspace không nêu tên thư mục catalog nào: không có workspace.catalog_dirs, không có AGGREGA_CATALOG_DIRS và không có thư mục catalog/ ở gốc workspace. aggrega import, lần nhập của phiên trình soạn thảo và công cụ nhập của trợ lý chạy cùng một thao tác, nên mỗi bên đều lấy ảnh chụp theo cùng một cách. Lần nhập tải nó từ registry mặc định của workspace qua cùng cổng kiểm soát lưu lượng ra và cùng bước đăng nhập như một lần pull, xác minh chữ ký của nó theo chính sách tin cậy của registry đó trước khi giữ lại bất cứ thứ gì, giữ nó trong bộ nhớ đệm artifact của workspace và đọc nó ở đó như một thư mục catalog, ràng buộc với digest của nó — nhờ đó trình nhập được cung cấp các Components của catalog, và --target soạn nháp một Manifest từ các Recipes của nó, đi qua đúng con đường mà một thư mục catalog đi qua. Bản ghi mà lần nhập ghi bên cạnh các bản nháp của nó nêu tên ảnh chụp bằng digest manifest của nó, nên một lần nhập sau với cùng các bản nháp sẽ đọc cùng catalog mà không cần gửi yêu cầu, và aggrega import --upgrade tải ảnh chụp mới nhất và từ đó trở đi nhập dựa trên nó. Ở chế độ ngoại tuyến, một lần nhập lẽ ra phải tải ảnh chụp sẽ dừng lại, nêu rõ cần chạy gì. Một workspace nêu tên một thư mục catalog sẽ nhập dựa trên thư mục đó và không tải ảnh chụp nào. Không lệnh nào khác đọc ảnh chụp: pull, build và xác thực phân giải từng thực thể qua các tầng của §5 và ghim nó trong lockfile, và các bản nháp của một lần nhập tham chiếu các thực thể catalog theo tên, nên việc build chúng phân giải các thực thể đó theo cùng một cách.
9. Ghim bằng lockfile và tính bất biến của artifact
Nguyên tắc ghim bằng lockfile neo mọi phụ thuộc vào một artifact cụ thể có thể định địa chỉ theo nội dung. Ở lần phân giải lockfile đầu tiên (aggrega pull), resolver tham khảo registry, chọn một phiên bản theo ràng buộc ba dạng của URI (chính xác / khoảng / không phiên bản), và ghi phiên bản đã ghim + digest vào <release-stem>.lock của Release. Các lần gọi aggrega build tiếp theo sử dụng các giá trị đã ghim bất kể registry có thay đổi hay không; các phiên bản mới có thể được phát hành mà không ảnh hưởng đến lockfile hiện có.
Mô hình ghim mang theo một quy tắc then chốt: khi một name:version đã được phát hành lên registry và phân giải về digest D, ánh xạ đó là vĩnh viễn. Việc phát hành lại cùng một name:version với nội dung khác bị từ chối tại thời điểm push. Chính aggrega push thực thi điều này ở mỗi lần phát hành: nó phân giải artifact hiện có tại name:version trong registry đích; nếu artifact tồn tại và digest khớp với nội dung sắp được push, lần push không tải lên gì và chỉ đính kèm những gì lần phát hành đó còn thiếu — ngày phát hành, và chữ ký ở nơi lần push có ký; nếu artifact tồn tại và digest khác, lần push dừng lại với lỗi vi phạm tính bất biến nêu cả hai digest.
Tính bất biến quan trọng vì hai hệ quả:
- Các ghim trong lockfile là trung thực. Khi lockfile ghi
mariadb:1.0.0ở digestD, một bản build tải theo digest sẽ nhận được các byte củaD. Nếu không có tính bất biến, một thay đổi phía registry có thể thay thế các byte củaDngay bên dưới ghim của lockfile, làm suy yếu sự ổn định từ thời điểm khóa đến thời điểm build. Các bản build có thể tái tạo dựa trên sự bảo đảm này. - Thay đổi siêu dữ liệu sau khi phát hành có một lộ trình rõ ràng. Việc đánh dấu một phiên bản đã phát hành là ngừng hỗ trợ, xoay vòng khóa ký hoặc sửa đổi attestation không thể thực hiện bằng cách thay đổi artifact đã phát hành (quy tắc cấm điều đó). Việc này phải được thực hiện bằng cách phát hành một phiên bản patch mới hoặc một artifact sidecar ghi nhận riêng thay đổi siêu dữ liệu. Cả hai lộ trình đều có thể kiểm toán — một phiên bản mới hoặc sidecar xuất hiện như một mục registry riêng biệt — và không lộ trình nào thay đổi các byte của artifact gốc.
Quy tắc bất biến áp dụng thống nhất cho mọi artifact Aggrega được phát hành qua OCI (thực thể, SchemaLibrary, MappingLibrary, các plugin Wasm được tham chiếu bởi pipeline[].plugin: của Recipe / pipeline[].plugin: của FeatureRecipe / plugins.{governance,linter,importer}[]: của cấu hình workspace). Bất cứ thứ gì được ghim bằng name:version cộng với một digest nội dung trong lockfile đều chịu tính bất biến.
Tính bất biến là vô điều kiện, và không cấu hình nào nới lỏng nó. Không có flag nào và không có thiết lập cấu hình workspace nào cho phép ghi đè, vì registry không cung cấp lộ trình ghi đè nào để người vận hành chọn bật. Nội dung đã thay đổi được phát hành dưới một phiên bản mới, và aggrega lint --pre-publish xác minh rằng mức tăng phiên bản khớp với phân loại của thay đổi.
Việc phân giải lại sang một phiên bản mới hơn đòi hỏi hành động tường minh của người dùng: aggrega pull --upgrade --release <release> <uri> phân giải lại một phụ thuộc duy nhất trong khi giữ nguyên mọi ghim khác, và aggrega pull --upgrade --release <release> phân giải lại tất cả các phụ thuộc dựa trên trạng thái registry hiện tại. Các phụ thuộc dạng khoảng và dạng không phiên bản được phân giải lại về phiên bản khớp mới nhất; các ghim dạng chính xác không thay đổi trừ khi người dùng nâng cấp tường minh lên một phiên bản chính xác khác. Lockfile là nguồn sự thật cho các bản build; dạng do người dùng nhập thể hiện ràng buộc phiên bản tại thời điểm soạn thảo.
10. Thực thi hình dạng tên thực thể catalog
Tên thực thể catalog tuân theo các pattern theo từng loại thực thể — được liệt kê bên dưới và trình bày chi tiết theo từng loại trong Tổng quan tham chiếu thực thể. Chúng là một bề mặt khác với tên instance mà một nhà phát triển viết trong một Aggregate hoặc một Release, vốn dùng chung một pattern bất kể loại; pattern đó nằm ở ../language-reference/02-naming-conventions.md “Tên instance”. Trường metadata.name mà một YAML catalog khai báo không phải lúc nào cũng giống hệt URI tham chiếu chuẩn của thực thể: Component và Feature nhúng các phân đoạn nhà phát hành và nhóm trực tiếp vào metadata.name; Recipe và FeatureRecipe khai báo một metadata.name chỉ gồm lá, và URI chuẩn hai phân đoạn của chúng ghép lá đó với spec.capability mà thực thể khai báo; mọi loại thư viện khai báo một token PascalCase trong metadata.name.
Hình dạng theo từng loại thực thể:
- Component — ba phân đoạn kebab-case
{publisher}/{category}/{name}được khai báo trongmetadata.name. Ví dụ:core/datastore/postgres. - Feature — hai phân đoạn kebab-case
{publisher}/{name}được khai báo trongmetadata.name. Ví dụ:core/data-masking. - Recipe — một lá kebab-case duy nhất trong
metadata.name(ví dụ:postgres). URI tham chiếu chuẩn{capability}/{name}(theo §6 ở trên) ghépspec.capabilityđã khai báo của thực thể với lá đó; phân đoạn đầu được so khớp vớispec.capability, không phải với vị trí của thực thể trên đĩa, vì vậy việc di chuyển mộtrecipe.yamlkhông thay đổi cách nó được tham chiếu. Catalog thư viện chuẩn đặt thực thể tại<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlđể cây phản chiếu tọa độ, nhưng sự phản chiếu đó là một quy ước của catalog chứ không phải nguồn gốc của URI. Một tham chiếu cũng có thể nêu tên recipe ở dạng trơn — chỉ có lá, không có phân đoạn capability — đây là dạng phổ biến nhất trong thực tế và được phân giải bất cứ khi nào chỉ có một recipe trong catalog mang tên đó. Không có phân đoạn nhà phát hành nào xuất hiện trong URI của Recipe, và một tham chiếu mang phân đoạn thứ ba sẽ không khớp với recipe nào. - FeatureRecipe — một lá kebab-case duy nhất trong
metadata.name(ví dụ:k8s-secret-from-parameter), đối xứng với Recipe: URI chuẩn{capability}/{name}từspec.capabilityđã khai báo cộng với lá, lá trơn được chấp nhận theo cùng cách, và cây<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlphản chiếu tọa độ theo quy ước. - Các loại thư viện — SchemaLibrary, MappingLibrary, WorkloadLibrary và ArtifactLibrary — một token PascalCase duy nhất trong
metadata.namekhớp với^[A-Z][A-Za-z0-9]*$(ví dụ:BaseComponents,AIDatastores,BaseWorkloads). Hình dạng là như nhau trên mọi loại thư viện, vì vậy việc di chuyển một mục giữa các thư viện không bao giờ có nghĩa là phải đổi tên theo một quy ước khác. Phần bao JSON Schema của mỗi loại thư viện cũng khai báo pattern đó, bên cạnh việc kiểm tra được mô tả bên dưới.
Đối với Component, Feature, Recipe và FeatureRecipe, JSON Schema cho metadata.name chấp nhận bất kỳ chuỗi không rỗng nào, vì vậy không có gì về hình dạng mang tính cấu trúc đối với các loại đó. Mọi hình dạng được ghi trong tài liệu — kể cả các loại thư viện, vốn có phần bao cũng khai báo pattern của chúng — đều được kiểm tra bởi plugin kỷ luật phát hành, plugin này mang các pattern như một nguồn sự thật dạng regex được chia sẻ với bản phân phối của trình biên dịch. Không loại nào được gán ở đây một hình dạng mà plugin sau đó lại bỏ qua.
Việc kiểm tra là tùy chọn tham gia: một lệnh thực hiện nó, và lệnh đó chỉ chạy khi tác giả yêu cầu. Hai lệnh thường được cho là thực hiện việc kiểm tra này nhất thì lại không:
aggrega lintbáo cáo vi phạm hình dạng tên. Plugin so sánhmetadata.namecủa từng thực thể với pattern cho loại của nó. Việc kiểm tra chạy khi tác giả gọiaggrega lint— trên một thực thể, trên bao đóng phụ thuộc của một Release với--release, hoặc trên mọi thực thể catalog khi được gọi không có đối số — và cùng bộ quy tắc đó có thể truy cập từ bề mặt công cụ hướng tới trình soạn thảo mà CLI cung cấp. Các phát hiện mang tính khuyến nghị: chúng được báo cáo ở mức độ nghiêm trọngwarn, và không làm dừng.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)Phát hiện bắt đầu bằng mức độ nghiêm trọng và mã ngắn mà quy tắc của nó được đăng ký, mã này được aggrega explain E0278 diễn giải. Đường dẫn của tệp vi phạm được in phía trên phát hiện, và một lần chạy trên toàn bộ catalog kết thúc bằng số lượng thực thể đã kiểm tra và số phát hiện khuyến nghị đã nêu ra.
aggrega buildkhông kiểm tra hình dạng tên. Đầu ra được render không phụ thuộc vào tên thực thể Aggrega, vì vậy một bản build trên catalog có tên không tuân thủ sẽ không phát ra cảnh báo hay chẩn đoán nào, và thành công đúng như bình thường.aggrega pushcũng không kiểm tra hình dạng tên. Việc phát hành từ chối vì những lý do khác — đáng chú ý nhất là quy tắc bất biến ở trên, theo đó việc phát hành lại mộtname:versionđã có với nội dung khác sẽ dừng lại. Khi một lời từ chối nêu tênaggrega lint --pre-publish, nó đang cho tác giả biết cần chạy lệnh nào; lần push không chạy lệnh đó.
Vì cả việc build lẫn phát hành đều không kiểm tra hình dạng, một catalog muốn quy ước được tuân thủ sẽ chủ động chạy aggrega lint — trong một hook pre-commit hoặc như một bước của pipeline. Lưu ý rằng một phát hiện về hình dạng tên mang tính khuyến nghị: aggrega lint báo cáo nó và vẫn thoát thành công, vì vậy một pipeline muốn dùng quy ước làm điều kiện chặn sẽ đọc các phát hiện được báo cáo thay vì dựa vào trạng thái thoát.
Một chính sách theo từng workspace sẽ tắt quy tắc:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseKhi chính sách được đặt, quy tắc hình dạng tên không báo cáo gì cả. Nó cũng có thể được đặt cho một lần gọi duy nhất bằng aggrega lint --allow-nonstandard-names, hoặc buộc tắt lại bằng --no-allow-nonstandard-names. Các trường hợp sử dụng hợp lệ là những catalog sẽ không bao giờ được phát hành, các thử nghiệm nhiều nhà phát hành và các thực thể cho mục đích đặc biệt.
11. Mở rộng Feature dựa trên annotation
Khối mappings.features.annotations của Manifest khai báo các liên kết giữa khóa annotation và loại Feature, cùng với một bảng định tuyến được nhóm theo trụ cột (maps.infra, maps.values) nêu tên các thuộc tính schema của Feature mà mỗi annotation có thể điền. Giai đoạn con mở rộng annotation của quá trình phân giải duyệt các ranh giới Release từ ngoài vào trong và các hệ thống con Aggregate từ ngoài vào trong, tính toán các tập annotation hiệu dụng theo từng thành phần thông qua cascade và ghi đè với khả năng opt-out bằng null cho toàn bộ giá trị và theo từng khóa con, và chèn các gắn kết Feature tổng hợp mang origin: annotation trong nguồn gốc IR của chúng. Phần hướng dẫn đầy đủ về hình dạng liên kết và cách soạn thảo nằm ở language-reference/entities/manifest.md và language-reference/providers/well-known-annotations.md; phần này ghi lại các cơ chế tại thời điểm tải catalog và thời điểm inspect mà đường mở rộng dựa vào.
Bộ nhớ đệm biên dịch schema. spec.schema.{infra,values} của mỗi Feature được biên dịch một lần mỗi bản build và được tái sử dụng qua các lượt duyệt cascade. Việc xác thực kiểu lặp lại theo từng khóa con dựa trên cùng một schema Feature (một phạm vi cascade cho mỗi thành phần, với hàng trăm thành phần) đọc schema đã biên dịch thay vì biên dịch lại. Không có gì được giữ lại giữa các bản build, nên một schema Feature đã thay đổi sẽ được biên dịch mới ở bản build tiếp theo.
Xác thực đích liên kết (tải catalog). Khi tải catalog, trình biên dịch duyệt mọi liên kết features.annotations của Manifest và xác minh rằng mọi đường dẫn có dấu chấm được khai báo dưới maps.infra và maps.values tương ứng với một thuộc tính mà spec.schema.<pillar> của Feature được tham chiếu thực sự khai báo. Một liên kết định tuyến tới đường dẫn mà schema của Feature không liệt kê sẽ dừng việc tải catalog với một OPS_ERROR rõ ràng nêu tên khóa liên kết, đường dẫn bị thiếu, URI của Feature và vị trí trong mã nguồn.
Lint chồng chéo trụ cột schema (tải catalog). Một cảnh báo khuyến nghị được phát ra khi spec.schema của một Feature khai báo cùng một tên thuộc tính ở cả hai trụ cột infra và values. Sự chồng chéo hiếm khi có chủ đích — các thuộc tính cùng tên ở các trụ cột khác nhau làm rối ý định soạn thảo (trụ cột nào được kích hoạt khi một annotation nhắm tới tên dùng chung?) và làm phức tạp các thông báo chẩn đoán. Cảnh báo không chặn và không có cách opt-out: tác giả cố ý chồng chéo thì giữ nguyên cả chồng chéo lẫn cảnh báo, còn tác giả không cố ý thì đổi tên thuộc tính ở một trụ cột.
Lint chồng chéo map liên kết (phân giải). Một cảnh báo khuyến nghị được phát ra khi một đường dẫn khóa con xuất hiện dưới cả maps.infra và maps.values trong các liên kết của Manifest. Một đường dẫn xuất hiện trong cả hai danh sách trụ cột là không nhất quán — một khóa con annotation duy nhất không thể định tuyến tới cả hai trụ cột cùng lúc, và cơ chế phân xử tất định mà trình biên dịch áp dụng (đường dẫn xuất hiện trong cả hai danh sách được định tuyến tới infra; một annotation viết trong Aggregate chỉ có thể định tuyến qua values, nên annotation viết ở đó cho đường dẫn này bị từ chối) là một lưới an toàn, không phải một hình dạng soạn thảo có chủ đích. Cảnh báo không chặn; các tác giả chạy mà bỏ qua cảnh báo vẫn nhận được một bản build sạch, với cơ chế phân xử hiển thị trong nguồn gốc IR.
Hiển thị nguồn gốc trong aggrega inspect. Lệnh inspect hiển thị một cặp ngoặc cho mỗi gắn kết Feature, ghi lại nguồn của từng lá đã được điền:
[explicit]— Feature được gắn kết tường minh thông qua một khốifeatures:của Aggregate hoặc Release.[annotation: <key> from <source>]— mọi lá đã được điền đều đến từ cùng một khóa annotation. Cặp ngoặc nêu tên khóa và nơi annotation được khai báo: tệp, và đường dẫn khóa phân tách bằng dấu chấm bên trong tệp đó.- Ngoặc theo từng lá — kết hợp giữa các phía, trong đó mỗi lá đã được điền được hiển thị với ngoặc nguồn riêng của nó (một số
[explicit], một số[annotation: <key> from <source>]). Hình dạng này làm lộ ra phép hợp nhất trong đó giá trị tường minh thắng theo từng trường: khi một gắn kết tường minh và một đóng góp từ annotation cùng nhắm tới một instance Feature trên cùng một Component nhưng ghi các lá khác nhau, cả hai đóng góp đều được giữ trên các lá tương ứng của chúng và đầu ra inspect nêu tên nguồn của từng lá một cách riêng biệt.
Phần hiển thị inspect đọc các map theo trụ cột values_provenance và infra_provenance của IR — được điền trong quá trình mở rộng annotation cùng với việc chèn các gắn kết tổng hợp — và phát ra dạng ngoặc tóm tắt tốt nhất nguồn chung của các lá. Cơ chế inspect là bề mặt nội quan chuẩn để hiểu vì sao một gắn kết Feature nhất định lại nằm trên một Component nhất định và các giá trị của nó đến từ đâu.