Cấu hình
Nơi aggrega đọc các thiết lập của nó, và nên đặt một thiết lập vào tệp nào.
Trường hợp đơn giản
Hai tệp, và hầu hết các dự án không cần gì thêm.
Một tệp trong dự án của bạn, tên là .aggrega-config.yaml, nằm ở thư mục gốc của dự án. Tệp này chứa
cách dự án này được build: thư mục nào chứa nội dung catalog được vendor, plugin nào render
mục tiêu nào, quy tắc lint nào được nới lỏng, bộ nhớ đệm cục bộ đặt ở đâu. Tệp này được commit, nên một
đồng đội clone dự án sẽ build nó theo cùng một cách.
Khối workspace: của tệp là thứ đánh dấu thư mục đó là thư mục gốc của dự án:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueKhối này chỉ chứa các thư mục catalog xác định thư mục gốc; mọi thiết lập khác nằm ở cấp cao nhất
bên cạnh nó. Một dự án không vendor nội dung catalog nào vẫn viết khối này, để trống —
workspace: {} — vì chính sự hiện diện của khối là dấu hiệu đánh dấu.
Một tệp toàn cục trên máy của bạn, tại ~/.config/aggrega/config.yaml — trên Windows, tại
aggrega\config.yaml bên trong thư mục mà biến môi trường APPDATA chỉ định. Mọi workspace
trên máy đó đều được phân giải qua tệp này, và nó chứa
các thiết lập thuộc về máy chứ không thuộc về một
dự án nào — các registry bạn pull về và chính sách tin cậy chữ ký cho từng registry, kho module
đã biên dịch được phép lớn đến mức nào, và mọi plugin mở rộng lệnh bạn đã cài. Những thiết lập đó
giống nhau ở bất cứ đâu bạn làm việc, nên mục đích là khai báo chúng một lần. Tệp được tải tự động khi
có mặt, và không có gì hỏng khi nó vắng mặt.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init viết tệp toàn cục đó cho bạn, đăng ký một registry cùng với
chính sách tin cậy chữ ký mà registry đó công bố, và cho biết tệp nằm ở đâu trên máy bạn và các
bộ nhớ đệm toàn máy được lưu ở đâu. aggrega config show in ra những gì đang áp dụng lúc này, và
aggrega config show --origin cho biết tệp nào — hoặc biến môi trường nào — đã quyết định từng
thiết lập.
Bí mật không phải là cấu hình. Mật khẩu registry và token định danh ký không bao giờ là trường trong tệp nào; chúng được cung cấp qua biến môi trường hoặc flag vào lúc cần đến. Xem environment-variables.md.
Các entity cục bộ được đọc từ đâu
Một dự án giữ nội dung catalog của riêng mình — một Component, một Feature, một Recipe, một trong các loại thư viện — có hai cách để cho biết nội dung đó nằm ở đâu, và cách thứ nhất hoàn toàn không cần cấu hình.
Thư mục catalog ở gốc dự án được đọc dù có gì chỉ định nó hay không. Đặt một
entity dưới <project>/catalog/ và mọi lệnh tải catalog đều đọc nó, kể cả trong một
dự án có khối workspace: trống. Thư mục catalog được đọc đệ quy, nên cách bạn
sắp xếp các thư mục con bên trong là tùy bạn.
Các thư mục liệt kê dưới workspace.catalog_dirs cũng được đọc, và được đọc trước.
Danh sách là một ngăn xếp tìm kiếm có thứ tự: thư mục đầu tiên khai báo một định danh sẽ sở hữu nó, và
cùng định danh đó trong một thư mục sau bị che khuất. catalog được đọc sau mọi thứ được liệt kê — trừ khi
một thư mục được liệt kê đã chứa nó, khi đó nó được đọc như một phần của thư mục đó — nên
việc liệt kê một thư mục bổ sung vào những gì bạn đã có chứ không thay thế nó. Tùy chọn lặp lại được --catalog <dir>
trên dòng lệnh được đọc trước cả hai, và đường dẫn tương đối đưa ra ở đó được phân giải theo
thư mục bạn chạy lệnh, vì không có tệp cấu hình nào khai báo nó. Một thư mục được chỉ định nhiều
hơn một lần — trên dòng lệnh và trong danh sách, hoặc hai lần trong danh sách — được đọc một lần, tại vị trí nó
được chỉ định đầu tiên, nên không có gì trong nó bị báo là bị che khuất bởi chính nó: sự che khuất luôn là hai
tệp khác nhau khai báo cùng một định danh. Hai cách viết của cùng một thư mục, một đường dẫn tới nó qua liên kết, và — trên
hệ thống tệp không phân biệt chữ hoa chữ thường — một cách viết khác chữ hoa chữ thường đều chỉ cùng một thư mục đó. Một thư mục
nằm bên trong một thư mục được liệt kê khác vẫn được đọc như một mục riêng. Một dự án giữ một
biến thể catalog cho mỗi Release có thể thay vào đó cho mỗi Release một danh sách riêng — xem
Cho một Release các thư mục catalog riêng.
Liệt kê một thư mục là cách một dự án đọc các entity được giữ bên ngoài nó. Một thư mục được liệt kê có thể nằm ở bất cứ đâu — một bản checkout cùng cấp, một thư mục dùng chung với các dự án khác — và được đọc tại chỗ, kể cả khi bản thân nó là một liên kết tượng trưng. Không có gì khác vươn xa đến thế: một liên kết bên trong dự án dẫn ra nơi khác không được đọc xuyên qua, và một tài liệu chỉ định một tệp bên ngoài dự án bằng đường dẫn bị từ chối, nên một entity giữ ở nơi khác được tiếp cận bằng cách liệt kê thư mục chứa nó và gọi entity bằng tên của nó. Một thư mục được liệt kê bên ngoài dự án là một gốc riêng, nên một liên kết bên dưới nó dẫn ra ngoài nó cũng không được đọc. Ranh giới workspace trình bày toàn bộ quy tắc.
Một thư mục được liệt kê phải là một thư mục. Một đường dẫn được liệt kê nơi không có gì tồn tại, hoặc nơi có một tệp hay một liên kết không dẫn đến đâu, bị từ chối trước khi bất kỳ thứ gì được đọc hoặc ghi bởi mọi lệnh đọc danh mục — một lần pull, một lần build, một lần kiểm tra hợp lệ, một lần inspect, một lần lint, và các thao tác tương tự được thực hiện từ trình soạn thảo qua aggrega serve hoặc từ trợ lý qua aggrega mcp — nên một lần build không bao giờ chạy với ít danh mục hơn số bạn đã liệt kê. Lời từ chối nêu tên mục như đã viết, đường dẫn mà nó được phân giải tới, tệp cấu hình và dòng liệt kê nó, và danh sách chứa nó:
<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalidHãy tạo thư mục, hoặc xóa mục đó: một bản sao của dự án được lấy mà không kèm bản checkout cùng cấp mà dự án liệt kê sẽ xóa mục đó, và phân giải từ registry những gì bản checkout lẽ ra cung cấp. Điều tương tự áp dụng cho thư mục mà mục riêng của một Release liệt kê, cho thư mục mà một tệp cấu hình thuộc pipeline của bạn hoặc tệp toàn cục thêm vào, và cho thư mục mà AGGREGA_CATALOG_DIRS mang theo, biến mà lời từ chối nêu tên thay cho một tệp. Bản thân cấu hình vẫn được nạp, nên một lệnh không đọc danh mục nào vẫn chạy. Một thư mục --catalog không tồn tại đã được gõ cho một lệnh, và aggrega build từ chối nó, nêu tên thư mục. Một thư mục được liệt kê tồn tại nhưng không thể đọc bị từ chối bởi các lệnh nạp toàn bộ danh mục, kèm tên của nó.
Viết danh sách trống nghĩa là dự án này hoàn toàn không có catalog cục bộ, và đó là cách
viết duy nhất khiến catalog cũng không được đọc:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Bỏ qua khóa là một tuyên bố khác: danh sách bị bỏ qua là trường hợp thông thường, và catalog
vẫn được đọc.
Một lần build, pull, kiểm tra hợp lệ hoặc aggrega inspect không tìm thấy entity nào dưới một tên bạn đã dùng sẽ cho biết dự án này đọc các entity cục bộ từ đâu và cần thay đổi gì để entity bạn chỉ định được đọc. Nó không nói gì như vậy khi bạn đã viết danh sách trống — không đọc catalog cục bộ nào là điều bạn đã khai báo ở đó, và một gợi ý thay đổi điều đó sẽ là tranh cãi với bạn. Nó cũng không nói vậy khi tài liệu khai báo tên đó đã được đọc và bị từ chối: tài liệu đó đã nằm ở nơi catalog đọc, nên báo cáo thay vào đó nêu điều tài liệu vi phạm, dòng và ràng buộc, và việc di chuyển nó sẽ không sửa được gì. Một tài liệu hỏng đến mức tên mà nó khai báo hoàn toàn không đọc được thì không thể khớp với tên bạn đã dùng, nên lời giải thích vẫn được đưa ra — và khi tài liệu đó khai báo một apiVersion của Aggrega, một lần build, pull hoặc kiểm tra hợp lệ một Release sẽ nêu tên nó bên cạnh lời giải thích, kèm lý do của chính bộ phân tích cú pháp, vì đó có thể là tệp cần mở. Một lỗi đã tìm thấy entity nhưng không thể chấp nhận nó — một registry nay phục vụ các byte khác dưới một phiên bản mà lockfile của bạn ghim, một tệp mà entity mang theo không đọc được — cũng không phải là entity bị thiếu, và nó chỉ báo cách khắc phục riêng của nó.
Một lần pull hay push có ghim một entity hay không
Một Recipe hoặc FeatureRecipe mang các ghim cho những đầu vào nó đọc — một source: từ xa được viết
đầy đủ, một tệp mà một mục artifacts nhập vào, các tệp của một source: bên cạnh nó — trong entity.lock bên cạnh nó, và việc ghi lại chúng là
bước của tác giả entity, aggrega pin. Theo mặc định cả pull lẫn push
đều không chạy bước đó: một lần pull dừng lại ở entity mà lock của nó không ghim, và một lần push từ chối công bố nó.
Hai khóa, mỗi lệnh một khóa, biến việc chạy bước đó thành mặc định của lệnh tương ứng:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueMỗi khóa chỉ điều khiển lệnh của riêng nó và không gì khác, và --pin-sources của mỗi lệnh ghi đè
khóa của chính nó theo cả hai chiều — --pin-sources=false tắt bước này cho một lần chạy trong một dự án
được cấu hình để ghim. Một lần build tự điền lockfile của nó là một lần pull và tuân theo
pin_sources_at_pull. Chúng thuộc về tệp dự án chứ không phải tệp toàn cục: việc các lần pull của một
dự án có ghi lại ghim hay không là chính sách của dự án đó, và một đồng đội clone nó nên nhận được
cùng câu trả lời. pin_sources_at_pull cũng là cách một dự án sử dụng catalog chưa được ghim của người khác
ghi lại các ghim đó một lần thay vì dừng lại ở mỗi lần pull.
Plugin nào kết xuất một capability
Một Recipe nêu tên capability mà nó kết xuất thông qua — capability: helm — và một plugin phục vụ capability đó sẽ kết xuất nó. Khi có đúng một plugin phục vụ một capability thì không cần cấu hình gì. Khi có nhiều hơn một, một mục plugins.providers cho biết plugin nào, theo định danh của plugin:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmMột lần pull phân giải mục đó và ghi plugin nó đã chọn vào lockfile của Release, và một lần build kết xuất thông qua những gì lockfile ghi lại, nên một chỉnh sửa ở đây có hiệu lực ở lần pull kế tiếp.
uri nêu plugin theo định danh của nó, provider/<name>, không bao giờ theo nơi nó được phát hành. aggrega plugin add provider <query> --capability <capability> ghi mục theo dạng đó, không kèm phiên bản: mục chọn plugin nào phục vụ capability, phiên bản là phiên bản mà Recipe ghim hoặc nếu không thì là phiên bản cao nhất hiện có, và lockfile ghi lại phiên bản mà lần pull đã chọn. Một plugin mà trình biên dịch mang sẵn bên trong được phục vụ ở chính phiên bản của trình biên dịch, nên một phiên bản được viết trên mục cho một plugin như vậy chỉ được phân giải khi đúng là phiên bản đó. Một mục có uri là một vị trí registry — oci://hub.aggrega.ai/plugin/provider/helm — không nêu định danh của plugin nào, và bị từ chối khi tệp được nạp, kèm theo tên mục và dạng cần viết.
Các mục được viết một lần cho toàn bộ dự án, còn một lần build là của một Release, nên một mục cho capability mà Release này không bao giờ yêu cầu vẫn hợp lệ — một Release khác trong dự án đọc nó — và không bị báo cáo gì. Điều mà mỗi lần build và mỗi aggrega validate --release thực sự kiểm tra là mọi mục, dù có Recipe nào yêu cầu capability của nó hay không, theo những gì mục đó nêu tên:
- Một mục nêu tên một plugin mà plugin đó không phục vụ capability của mục sẽ dừng build và làm validation thất bại. Một lần pull phân giải mọi mục có nêu tên plugin, và từ chối mục nó không phân giải được, nên khi một mục đã qua một lần pull thì build nắm giữ plugin của nó và biết plugin đó phục vụ gì; một mục nêu tên plugin mà build chưa nắm giữ sẽ được đánh giá khi một lần pull đã tải nó về. Thông báo nêu tên mục, plugin,
những gì plugin đó thực sự phục vụ, và một cách viết cách một lần chỉnh sửa nếu có — dạng mà một lỗi gõ
như
hlemthay chohelmcó. - Một mục chỉ nêu tên một capability mà không plugin nào build đọc phục vụ là một cảnh báo, và build tiếp tục. Plugin phục vụ nó có thể là plugin chỉ một Release khác đọc, mà build này không thấy được, và một mục không nêu tên plugin nào chẳng chọn gì mà việc phân giải capability sẽ không chọn khi không có nó.
Một capability ở đây không bao giờ chứa dấu hai chấm, và capability nào chứa sẽ bị từ chối khi tệp được nạp. capability: của một Recipe được đọc là capability cho đến dấu hai chấm cuối cùng và một phiên bản ghim sau đó, nên một mục có khóa helm:1.0.0 sẽ không bao giờ được tra cứu. Thay vào đó, hãy ghim phiên bản trên plugin — uri: provider/helm:1.0.0 — hoặc trong Recipe.
Importer nào biến một nguồn thành bản nháp
aggrega import chuyển một nguồn cho importer công bố định dạng của nguồn đó — một importer trong catalog của bạn hoặc một trong các importer lõi của trình biên dịch, import:langflow cho một flow Langflow. Khi có đúng một importer công bố định dạng đó thì không cần cấu hình gì. Một mục plugins.importer gắn một importer bằng cách nêu tên nó trong uri, theo định danh và phiên bản, và chuyển cho nó những gì mục mang dưới with:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer viết uri theo đúng dạng đó. Phiên bản là chính xác — :1.2.0 — hoặc một khoảng — :^1.2.0 cho phiên bản cao nhất bằng hoặc trên nó trong cùng phiên bản major. Hãy viết dạng này hoặc dạng kia: trong danh sách này, một uri không có dấu hai chấm được đọc là đường dẫn hệ thống tệp, như
Đường dẫn tương đối trỏ đến đâu mô tả, và không nêu tên importer nào.
Một mục làm gì tùy thuộc vào việc importer mà nó nêu tên có công bố định dạng mà một lần import yêu cầu hay không:
- Có: importer đó là importer được chạy, ở phiên bản mà
urinêu, bất kể có bao nhiêu importer khác trong catalog cũng công bố định dạng đó, và nó được chuyểnwith.sourcesvàwith.settingscủa mục. Một mục là cách một workspace có catalog liên kết importer của hai nhà phát hành cho cùng một định dạng cho biết nó dùng importer nào. - Không — nó nêu tên importer của định dạng khác, plugin thuộc loại khác, hoặc thứ mà catalog của bạn
không chứa và trình biên dịch không mang: mục đó không tham gia vào lần import đó. Nó không chọn gì, và
withcủa nó không được chuyển cho importer nào. Thiết lập của một mục chỉ đến được importer mà nó nêu tên, nên một workspace gắn một importer cho mỗi định dạng sẽ cấu hình từng importer mà thiết lập của cái này không đến được cái kia.
Khi nhiều hơn một importer công bố định dạng và không có importer duy nhất nào trong số đó được gắn — không cái nào được gắn, hoặc các mục nêu tên hai trong số đó — lần import bị từ chối, nêu tên các importer mà nó không thể chọn giữa. Một mục nêu tên importer công bố định dạng đó, ở một phiên bản mà không phiên bản nào của nó trong catalog thỏa mãn — một phiên bản chính xác mà catalog không chứa, hoặc một khoảng mà không phiên bản nào rơi vào — cũng bị từ chối, nêu tên phiên bản, thay vì chạy một phiên bản khác thế chỗ; một phiên bản hoàn toàn không phải phiên bản, như :latest, bị từ chối vì sai định dạng. Một thực thể Plugin của một trong các core importer của trình biên dịch mà không có module nào bên cạnh trong thư mục catalog của nó thì không phải là ứng viên: ở chính phiên bản của trình biên dịch, core importer chạy thế chỗ nó, còn ở bất kỳ phiên bản nào khác, thực thể chỉ còn là ứng viên khi một mục nêu tên chính xác phiên bản đó hoặc khi không có importer nào cùng tên có thể chạy công bố định dạng đó, như Importer nào chạy bên cạnh các importer của riêng bạn mô tả.
Mỗi importer được gắn bởi một mục. Hai mục nêu tên cùng một importer — cùng định danh, ở một phiên bản hay hai — bị từ chối khi cấu hình được nạp, bất kể lệnh nào đọc nó, nêu tên cả hai mục và các tệp chứa chúng. Quy tắc bao trùm mọi tệp góp vào danh sách: một mục trong tệp toàn cục, một mục trong tệp của dự án, một mục dưới importer_append, và một mục trong .aggrega-config-append-ci.yaml của pipeline đều được tính, nên chuyển một importer sang phiên bản mới nghĩa là thay đổi phiên bản trên mục duy nhất của nó. aggrega plugin add importer làm đúng như vậy khi danh sách plugins.importer của tệp nó ghi đã nêu tên importer: nó chuyển mục đó sang phiên bản nó phân giải được, giữ nguyên vị trí của mục và with của mục, thay vì thêm mục thứ hai. Nó không đọc danh sách nào khác, nên một importer được gắn dưới importer_append, hoặc trong .aggrega-config-append-ci.yaml của pipeline, sẽ bị lệnh gắn lần thứ hai và cặp đó bị từ chối khi cấu hình được nạp; hãy thay đổi phiên bản trên mục như vậy tại nơi nó được viết.
Một mục có uri là đường dẫn hệ thống tệp không nêu tên importer nào và không được so sánh, và các danh sách
plugins.governance và plugins.linter không chịu quy tắc này: một plugin có thể được gắn vào chúng nhiều lần, mỗi lần với with riêng.
Các parser mà một lần import đọc thông qua không cần mục nào. Một importer đọc nguồn của nó — và một lần import không nêu tên định dạng sẽ nhận diện nguồn — thông qua một parser cho cú pháp của nguồn: parser mà catalog của bạn phục vụ cho cú pháp đó, và, với cú pháp mà catalog của bạn không phục vụ parser nào, parser mà chính trình biên dịch mang theo, trong đó có JSON. Vì vậy một workspace có catalog không chứa parser nào vẫn import được một flow Langflow hoặc Flowise mà không cần cấu hình gì. Không danh sách nào gắn parser: parser mà catalog của bạn phục vụ cho một cú pháp là parser được dùng, và hai parser khác tên cùng phục vụ một cú pháp sẽ bị từ chối, như A parse or import format is advertised by more than one plugin (Một định dạng parse hoặc import được công bố bởi nhiều hơn một plugin) mô tả.
Bắt đầu từ con số không
Một aggrega vừa cài đặt không có tệp nào, và đó là trạng thái hoạt động được chứ không phải hỏng: mọi thiết lập trở về giá trị mặc định tích hợp và các lệnh vẫn chạy. Điều còn thiếu là một registry để pull nội dung catalog, cùng với chính sách tin cậy cho biết chữ ký nào được chấp nhận — đó chính là những gì aggrega config init ghi.
Bạn không cần biết điều đó trước. Một lệnh đọc cấu hình và không tìm thấy tệp nào ở đâu cả sẽ báo như vậy một lần, trên standard error, và nêu aggrega config init là cách tạo tệp. Đó là lời khuyên chứ không phải lỗi: standard output không bị ảnh hưởng, bạn không bị hỏi gì, và mã thoát là bất cứ gì lệnh vốn sẽ báo. Nó chỉ được ghi khi standard error là một terminal, nên nó đến với bạn tại bàn phím và không bao giờ tích tụ trong log của pipeline. Khi một trong hai tệp tồn tại — tệp của dự án bạn hoặc tệp toàn cục — nó không còn xuất hiện.
Để khởi tạo tệp toàn cục với hub chính thức và chính sách tin cậy mà hub đó công bố:
aggrega config initTruyền --registry <host> để khởi tạo một registry khác, --workspace để ghi mục vào tệp của dự án này thay vì tệp toàn cục, và --dry-run để xem nội dung sẽ được ghi mà không tạo gì. aggrega-config.md trình bày đầy đủ về lệnh này.
Cách viết một host registry
Mỗi registries[].host nêu tên một host registry. default_registry cũng vậy — có thể kèm theo một đường dẫn repository — trừ khi nó nêu tên một trong các mục đó (xem bên dưới). Một host được viết đúng là chính host đó, theo cách viết duy nhất mà chính sách tin cậy của registry được lưu theo:
- một tên host viết thường có chứa dấu chấm, chẳng hạn
registry.example.com; localhost, hoặc một tên đơn theo sau là một cổng, chẳng hạnregistry:5000;- một địa chỉ IPv4 như
127.0.0.1, hoặc một địa chỉ IPv6 trong ngoặc vuông như[::1];
mỗi loại có thể kèm :port, và không gì khác — không scheme, không đường dẫn, không thông tin xác thực, không khoảng trắng
và không chữ hoa. Một tên đơn không có cổng không phải là host registry, vì đó là hình dạng
của phân đoạn đầu tiên trong tên một thực thể catalog — core trong core/web-api — và hai thứ này không bao giờ
được đọc nhầm thành nhau.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueCách viết là một phần của chính sách. Một mục registries áp dụng cho host mà host: của nó nêu tên,
và yêu cầu chữ ký có sẵn của hub chính thức áp dụng cho hub.aggrega.ai, nên một host viết
theo bất kỳ cách nào khác sẽ đến đúng registry nhưng bỏ lỡ chính sách viết cho nó. Thay vào đó, nó bị từ chối khi
cấu hình được tải, và thông báo từ chối nêu cách viết cần dùng: HUB.AGGREGA.AI và
https://registry.example.com bị từ chối kèm tên hub.aggrega.ai và registry.example.com, và
registry.example.com/charts cũng vậy khi là một registries[].host, vốn không mang đường dẫn. Cổng 443 là
cổng mặc định của một host truy cập qua HTTPS, nên hub.aggrega.ai:443 bị từ chối theo cách tương tự, kèm tên
hub.aggrega.ai. Ngược lại, localhost và các địa chỉ loopback khác được truy cập qua HTTP thường,
nơi 443 là một cổng bình thường, nên localhost:443 được chấp nhận như đã viết. Một
default_registry rỗng không nêu tên registry mặc định nào.
default_registry có thể mang một đường dẫn repository. Nhiều registry giữ mọi repository dưới một
chủ sở hữu hoặc một dự án — ghcr.io/<owner>, <host>/<project> trên Harbor — và một registry mặc định trên một
trong số đó được viết là host theo sau là đường dẫn đó:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueĐường dẫn là nơi nội dung được xuất bản và tải về. Thông qua mặc định này, aggrega push xuất bản
core/api-server phiên bản 1.0.0 tại ghcr.io/acme/component/core/api-server:1.0.0, và một lần pull
phân giải core/api-server sẽ tải nó từ cùng nơi đó, nên chữ ký được đính kèm khi xuất bản
cũng được tìm thấy ở đó. Đường dẫn là một đường dẫn repository theo ngữ pháp phân phối OCI: một hoặc
nhiều phân đoạn gồm chữ thường và chữ số nối với nhau bằng /, bên trong một phân đoạn có thể được phân tách
bằng ., _, __ hoặc dấu gạch ngang, không có tag, digest hay / ở cuối.
Đường dẫn không bao giờ là một phần của cách registry được tin cậy. Mục registries có chính sách
được áp dụng, thông tin xác thực mà aggrega login lưu, yêu cầu ký và các danh tính được tin cậy đều
được tìm chỉ theo host, nên mục cho ghcr.io ở trên chi phối ghcr.io/acme và mọi đường dẫn khác
trên host đó, và không cách viết đường dẫn nào vượt qua được nó; bản thân host: của một mục không mang
đường dẫn. Một host viết theo cách khác trước một đường dẫn bị từ chối kèm vị trí cần viết —
GHCR.io/acme và https://ghcr.io/acme nêu ghcr.io/acme — và phần theo sau host khi nó
không phải là đường dẫn repository bị từ chối kèm tên host đứng trước nó.
Thay vào đó, default_registry có thể nêu tên một mục. Khi được viết là name: của một mục dưới
registries, nó đại diện cho host: của mục đó. Khi đó việc xuất bản, pull, xác minh chữ ký và
mọi thiết lập tin cậy theo từng registry đều dùng host đó, và không nội dung nào được tải từ một host viết
giống tên đó:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Tên được so khớp trước cách viết host, giống như cờ --registry so khớp, nên một giá trị là
name: của một mục sẽ đại diện cho mục đó ngay cả khi nó cũng được viết giống một host. Một tên mà hai
mục cùng mang bị từ chối vì mơ hồ, kèm tên cả hai host. Mục có thể nằm trong một trong hai tệp — default_registry của
một dự án có thể nêu tên một mục mà tệp toàn cục khai báo — vì tên được đọc
một lần, đối chiếu với các mục có hiệu lực sau khi mọi tệp và môi trường đã được đọc. Một giá trị
không phải tên của mục nào cũng không phải host registry — đứng riêng hay kèm đường dẫn repository — bị
từ chối, và thông báo từ chối cho biết cách nào cũng khắc phục được. Một tên theo sau là đường dẫn, như local/acme,
cũng bị từ chối: tên đại diện cho host của mục chứ không cho một vị trí bên dưới nó, nên thông báo từ chối
nêu hai cách viết thay thế — local, hoặc host của mục theo sau là đường dẫn,
127.0.0.1:5000/acme. Xóa một mục bằng aggrega registry remove giữ nguyên default_registry như
đã viết, nên một mặc định từng nêu tên mục bị xóa sẽ không còn nêu tên gì và bị từ chối cho đến khi
được viết lại.
Mọi tầng đều tuân theo cùng một cách viết. Một giá trị bị từ chối với cùng lời lẽ dù nó đến
từ tệp cấu hình, từ AGGREGA_DEFAULT_REGISTRY, hay từ cờ --registry nêu
đích đến của một lần aggrega push hoặc aggrega push-artifact. Cờ đó nêu tên một host, và
bản xuất bản nó chỉ định sẽ đến host đó mà không có đường dẫn repository: đường dẫn thuộc về
default_registry. aggrega registry add và
aggrega config init --registry cũng buộc host được truyền vào tuân theo cách viết đó; chúng còn chấp nhận một
reference thay thế, và lưu mục theo host mà reference nêu. Thông báo từ chối từ một tệp
nêu tên tệp và khóa; từ môi trường thì nêu tên biến. Schema nêu hình dạng host
dưới dạng pattern trên registries[].host và không nêu gì trên default_registry, vì giá trị của nó có thể là
tên của bất kỳ mục nào — nên một trình soạn thảo chỉ đọc schema sẽ không đánh dấu một mặc định gõ sai, và chính việc
tải cấu hình mới từ chối nó.
Một host chỉ được đánh giá theo cách viết, và đường dẫn cũng vậy. Việc tên có phân giải được không, có registry nào trả lời ở đó không, hay đường dẫn có tồn tại trên đó không, đều không được kiểm tra khi cấu hình được tải.
Cái gì ghi đè cái gì
CLI flag > environment variable > configuration file > built-in defaultCờ là tín hiệu tường minh nhất và thắng tuyệt đối. Biến môi trường ghi đè tệp đã commit, nhờ đó pipeline có thể thay đổi một thiết lập mà không sửa tệp được theo dõi. Một biến chưa đặt — hoặc đặt là chuỗi rỗng — sẽ chuyển xuống tầng bên dưới thay vì xóa trắng một giá trị đã cấu hình. Giữa hai tệp, tệp của dự án bạn thắng tệp toàn cục.
Cờ thắng vì đã được gõ, không phải vì giá trị nó mang, và với một thiết lập đúng-hoặc-sai
đó là khác biệt giữa có một tầng trên cùng dùng được và không có. --offline bật chế độ này cho một
lần chạy; --offline=false tắt nó cho một lần chạy khi tệp đã commit hoặc biến đã export
bật nó. Một tầng chỉ đọc giá trị sẽ không phân biệt được “tắt” với “không đề cập”, nên mọi
lệnh sẽ trông như đã yêu cầu giá trị mặc định của cờ và sẽ không có cách nào
hủy bỏ một thiết lập đã cấu hình.
Đó là toàn bộ mô hình cho một dự án trên một máy. Mọi thứ bên dưới tồn tại cho các dự án vượt quá mô hình đó.
Vượt ra ngoài hai tệp
Các cơ chế này được xây dựng cho những cấu trúc lớn hơn — một monorepo gồm các dự án liên quan, một pipeline đóng góp các thiết lập riêng của nó, một catalog dùng chung mà nhiều dự án mở rộng. Hãy dùng đến một cơ chế khi bạn gặp đúng vấn đề mà nó giải quyết.
Nhiều tệp cấu hình bên trong một dự án
Mọi tệp .aggrega-config.yaml từ thư mục gốc của dự án xuống đến thư mục nơi lệnh chạy
đều đóng góp, và tệp gần hơn ghi đè tệp xa hơn. Vì vậy một dự án con có thể mang tệp riêng để
điều chỉnh những gì thư mục gốc đã khai báo mà không cần lặp lại.
Chỉ một tệp có khối workspace: mới đánh dấu thư mục gốc. Một tệp không có khối này vẫn đóng góp các
thiết lập của nó — chỉ là nó không biến thư mục của mình thành thư mục gốc của dự án, điều này giúp tệp
thiết lập của một dự án con không định nghĩa lại nơi dự án bắt đầu.
Truyền --workspace-root thay đổi điều này, đồng thời bỏ qua việc dò tìm: tệp cấu hình riêng của thư mục gốc
được chỉ định là tệp duy nhất được thu thập, nên các tệp trong thư mục bên dưới không đóng góp.
Điều đó giữ cho cấu hình của một thư mục gốc được ghim là như nhau dù lệnh được chạy từ đâu.
Mọi tệp được thu thập theo cách này đều được đọc từ bên trong dự án. Một tệp là liên kết tượng trưng dẫn ra ngoài dự án — hoặc nằm trong một thư mục đến được qua liên kết như vậy — sẽ không được đọc, và mọi lệnh đọc cấu hình đều dừng lại tại đó, nêu tên liên kết, thay vì cấu hình dự án từ các tệp còn lại; điều tương tự áp dụng cho tệp của pipeline, ở bên dưới. Số ít lệnh không bao giờ đọc cấu hình, như aggrega version và aggrega help, vẫn chạy kèm một cảnh báo nêu tên liên kết. Language server của trình soạn thảo và các công cụ của trợ lý đọc cấu hình theo cùng cách, và vẫn khởi động trên một dự án như vậy để có thể liệt kê nó: các danh sách Release và thực thể của chúng vẫn trả lời, được đọc mà không có gì được cấu hình, và nêu tên tệp trong số các liên kết không được đọc, trong khi mọi yêu cầu khác mà cấu hình quyết định đều dừng lại tại đó, nêu tên liên kết. Một cấu hình đặt bên ngoài dự án được đọc bằng cách chỉ định nó làm tệp toàn cục, như Chỉ định tệp toàn cục một cách tường minh mô tả. Xem Ranh giới workspace.
Mở rộng một danh sách thay vì thay thế nó
Một thiết lập có giá trị là danh sách hoạt động như mọi thiết lập khác: giá trị của tệp gần hơn thay thế giá trị của tệp xa hơn. Khi bạn muốn thêm vào những gì một tệp bên ngoài đã khai báo thay vì nhắc lại, hãy dùng thiết lập bổ sung đi kèm bên cạnh nó:
| thiết lập danh sách | thiết lập bổ sung đi kèm |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Các mục dưới một thiết lập đi kèm được nối vào danh sách đã phân giải ở mỗi lớp thay vì che khuất nó, nên một dự án con thêm một linter vào bất cứ gì thư mục gốc đã khai báo:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmKhi một tệp đặt cả danh sách gốc lẫn thiết lập đi kèm, giá trị của tệp đó là danh sách gốc theo sau là các mục được bổ sung.
Khối workspace: là ngoại lệ về nơi có thể viết một thiết lập đi kèm. Một tệp có khối đó
đánh dấu thư mục của chính nó là thư mục gốc của dự án, nên tệp của một dự án con viết
workspace.catalog_dirs_append sẽ bắt đầu một dự án riêng thay vì bổ sung vào dự án
bao quanh. Thiết lập đi kèm cho thư mục catalog kết hợp giữa tệp toàn cục của bạn và tệp gốc của dự án.
Danh sách plugins.cli tự kết hợp qua các tệp và không có thiết lập đi kèm: một phần mở rộng lệnh
khai báo trong tệp toàn cục đăng ký lệnh của nó trong mọi dự án, một phần mở rộng khai báo trong một dự án
chỉ đăng ký ở đó, và cả hai cùng đăng ký. Mỗi mục ghim một plugin: uri mà nó phân giải
và digest của các byte mà aggrega plugin add cli đã xác minh, viết là sha256: theo sau là 64
chữ số thập lục phân viết thường. Một digest viết theo bất kỳ cách nào khác không bao giờ có thể bằng digest mà
các byte đã phân giải băm ra, nên nó bị từ chối khi tệp được nạp, nêu tên tệp và mục.
Cấp cho một Release các thư mục catalog riêng
Một dự án có thể giữ nhiều biến thể catalog song song — mỗi biến thể cho một đích, mỗi biến thể chứa các Recipes
render cùng các Components cho một provider khác — và build mỗi Release dựa trên một trong
số đó. Hãy đặt tên mỗi Release dưới workspace.releases và cấp cho nó catalog_dirs riêng:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmMỗi khóa là một tệp Release, viết tương đối với tệp cấu hình chỉ định nó. Một khóa — như
build.authoring_release — có thể chỉ định một Release đặt bên ngoài dự án, và chỉ định nó ở đây là cách
một dự án tiếp cận nó: một liên kết bên trong dự án dẫn đến nó sẽ được đọc thay vì bị bỏ qua, như
Ranh giới workspace mô tả. Hai
khóa bên dưới có nghĩa như trên khối workspace:, giới hạn trong một Release đó:
catalog_dirsthay thế danh sách của workspace cho Release đó. Thứ tự tìm kiếm, thư mụccatalogđược đọc sau nó, và ý nghĩa của một danh sách rỗng đều giống như với danh sách riêng của workspace.catalog_dirs_appendđược đọc sau danh sách của Release. Một mục chỉ viếtcatalog_dirs_appendgiữ nguyên danh sách của workspace và bổ sung vào đó.
Một Release mà bảng ánh xạ không chỉ định đọc workspace.catalog_dirs riêng của workspace. Một Release mà bảng ánh xạ có chỉ định đọc các thư mục riêng của nó dù được build theo cách nào — aggrega build hoặc aggrega pull tại terminal, trình soạn thảo qua aggrega serve, một trợ lý qua aggrega mcp — nên không cách nào trong số đó cần cờ để tìm catalog của nó. Một --catalog <dir> trên dòng lệnh vẫn được tìm trước các thư mục của Release, cho lần gọi đó. Và một lần tra cứu không tìm thấy thực thể nào dưới tên bạn đã dùng sẽ nêu mục của Release đó là nơi cần liệt kê thư mục chứa thực thể.
Một mục chỉ định tệp không tồn tại sẽ bị từ chối khi cấu hình được nạp, nêu tên mục và tệp. Vì vậy, đổi tên một Release sẽ khiến mọi lệnh dừng lại cho đến khi mục được đổi tên theo, thay vì để Release build dựa trên danh sách của workspace mà không có gì báo hiệu. Một thư mục mà một mục liệt kê phải là một thư mục, giống như thư mục mà danh sách của workspace chỉ định: cái nào không phải là thư mục sẽ bị mọi lệnh đọc danh mục của Release đó từ chối, nêu tên mục và dòng của nó.
Những gì không liên quan đến một Release riêng lẻ nào vẫn đọc danh sách của workspace: lint hoặc kiểm tra hợp lệ toàn bộ
catalog, tra cứu một thực thể theo tên, một Aggregate được kiểm tra riêng, và danh sách
các thực thể của workspace trong trình soạn thảo. AGGREGA_CATALOG_DIRS đặt danh sách của workspace và không tác động đến mục nào ở đây,
và một tệp cấu hình do pipeline của bạn sở hữu hoàn toàn không đọc bảng ánh xạ này.
Tệp cấu hình do pipeline của bạn sở hữu
Một tệp tên .aggrega-config-append-ci.yaml có thể nằm cạnh tệp viết tay trong bất kỳ
thư mục nào mà quá trình duyệt đi qua. Nó là một tệp riêng để một pipeline tự động có thể sở hữu và ghi đè toàn bộ
mà không bao giờ chạm vào những gì con người đã viết.
Nó chỉ mang tính bổ sung. Các mục của nó cho năm thiết lập danh sách ở trên được nối vào các danh sách đã phân giải; nó không thể xóa gì hay ghi đè một giá trị vô hướng. Một khóa vô hướng hoặc khóa map viết trong đó không có ý nghĩa bổ sung, nên nó bị bỏ qua và được nêu trong một cảnh báo thay vì âm thầm áp dụng. Nó cũng không bao giờ đánh dấu thư mục gốc của dự án, nên đặt một tệp như vậy vào một thư mục sẽ thêm các attachment mà không làm thay đổi nơi dự án bắt đầu.
Đường dẫn tương đối trỏ đến đâu
Một đường dẫn hệ thống tệp tương đối được phân giải theo thư mục của tệp đã khai báo nó — không theo thư mục gốc của dự án, và không theo thư mục mà bạn chạy lệnh. Đây là quy tắc đáng đọc hai lần, vì một đường dẫn trông như tương đối với dự án lại được phân giải ở nơi khác và bản build vẫn thành công, dựa trên nội dung mà bạn không định dùng.
Quy tắc này áp dụng cho workspace.catalog_dirs, cho các tệp Release được đặt làm khóa dưới workspace.releases và các thư mục mà mỗi mục liệt kê, cho các đường dẫn hệ thống tệp cục bộ trên một attachment plugins.governance hoặc plugins.linter — một uri chỉ đến một tệp .wasm trên đĩa, và mỗi mục dưới with.sources của attachment đó — và cho mỗi mục dưới with.sources của một attachment plugins.importer. Trên cả ba danh sách, một uri không có dấu hai chấm và không chỉ đến registry nào — importer/agent-flows cũng như ./lint/api-rules.wasm — là một đường dẫn như vậy, còn một uri chỉ đến một plugin theo định danh của nó thì mang phiên bản sau dấu hai chấm, importer/agent-flows:1.2.0, và được giữ nguyên đúng như đã viết. uri của một attachment importer chỉ đến importer mà nó gắn vào, như Importer nào biến một nguồn thành bản nháp mô tả; một lần import không đọc module nào từ đường dẫn viết ở đó.
Quy tắc cũng áp dụng cho các mục dưới các trường append đi kèm, và mỗi mục đó neo vào chính tệp đã khai báo nó chứ không phải vào tệp mà phép hợp nhất tình cờ kết thúc. Và quy tắc áp dụng cho mcp.tls.cert_file, mcp.tls.key_file và
mcp.authorization.jwks_file, để một tệp nằm cạnh tệp chỉ đến nó được tìm thấy bất kể máy chủ được khởi chạy ở đâu.
Vậy với bố cục sau:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/và ./catalog được viết trong tệp gốc, đường dẫn chỉ đến myproject/catalog. Nếu viết trong
services/.aggrega-config.yaml, cùng văn bản đó chỉ đến myproject/services/catalog. Một đường dẫn tuyệt đối được giữ nguyên đúng như đã viết, và một tham chiếu registry như
oci://hub.aggrega.ai/plugins/helm:1.0.0 cũng vậy.
Các thiết lập sau cố ý không tuân theo quy tắc này, vì chúng không có tệp khai báo nào để neo vào hoặc vì mọi nơi đọc chúng đều phân giải chúng ở chỗ khác:
artifact_cache_dirđược hiểu là tương đối với thư mục gốc của dự án, bất kể lệnh chạy từ đâu, nên bộ đệm là một thư mục duy nhất chứ không phải một thư mục cho mỗi vị trí gọi lệnh. Một giá trị tuyệt đối bị từ chối khi cấu hình được nạp.AGGREGA_CATALOG_DIRSđến từ môi trường và hoàn toàn không có tệp khai báo, vì vậy hãy cung cấp đường dẫn tuyệt đối trong đó.mcp.listenđược lấy đúng như đã viết, kể cả đường dẫn hệ thống tệp trong dạngunix:<path>của nó. Cùng địa chỉ đó cũng có thể đến từaggrega mcp --listen, vốn không có tệp khai báo, nên nếu chỉ neo cách viết trong cấu hình thì một chuỗi sẽ chỉ đến hai nơi khác nhau tùy theo nguồn của nó. Hãy dùng đường dẫn tuyệt đối cho socket.
Một thiết lập có kho lưu trữ dùng chung
Gần như mọi thiết lập đều điều khiển một thứ thuộc về dự án bạn đang làm việc — dự án phân giải nội dung catalog qua những thư mục nào, những plugin nào render các target của nó, nội dung của nó được đánh giá nghiêm ngặt đến mức nào, các bộ đệm trong bộ nhớ của daemon được phép lớn đến đâu. Một giá trị trong tệp của một dự án điều khiển thứ của riêng dự án đó, và không có gì phải lưu ý.
compiled_module_cache.max_bytes là ngoại lệ duy nhất, vì thứ nó giới hạn không thuộc riêng từng dự án. Mã plugin đã biên dịch được giữ trong một thư mục duy nhất mà mọi dự án trên máy bạn dùng lại, nên một plugin chỉ được biên dịch một lần chứ không phải một lần cho mỗi dự án. Bản thân giới hạn được phân giải như mọi thiết lập khác — viết nó trong tệp của một dự án thì giá trị đó thắng cho dự án đó — nhưng kho lưu trữ vẫn chỉ có một kích thước, và kích thước đang có hiệu lực là kích thước từ lần build gần nhất. Hai dự án đặt giới hạn khác nhau sẽ lần lượt có hiệu lực, và giới hạn thấp hơn sẽ loại bỏ mã đã biên dịch mà dự án kia đã tốn công tạo ra.
Vì vậy, hãy đặt nó trong tệp toàn cục khi bạn muốn một câu trả lời cho mọi thứ bạn build, và giữ nó lớn hơn lượng mà một lần build biên dịch. aggrega cache status báo cáo những gì kho đang chứa, và
aggrega config show --origin cho bạn biết giới hạn bạn đang chạy thực sự đến từ tệp nào.
Thiết lập cho một máy chủ mà người khác truy cập
aggrega mcp nói giao thức Model Context Protocol. Trên máy của bạn, một client khởi chạy nó như một tiến trình con và trao đổi với nó qua đầu vào và đầu ra chuẩn, đây là mặc định, và các thiết lập duy nhất mà dạng đó đọc là mcp.transport, để ở mặc định đó, và mcp.announce_tools. Phần còn lại của khối mcp dành cho dạng kia, được chọn bằng mcp.transport: http: một tiến trình chạy lâu dài trên một host, được truy cập qua HTTP bởi những bên gọi không ngồi trước bàn phím của nó.
# <project>/.aggrega-config.yamlmcp: transport: http listen: 127.0.0.1:7777 authorization: issuer: https://login.example.com resource: https://mcp.example.com/mcp allowed_origins: - https://studio.example.com limits: max_concurrent_requests: 32 deny_reach: - registry announce_tools: - list-entities - get-schema - validate - build health: listen: 127.0.0.1:7778mcp.transport là thứ chọn transport. http khởi động một listener; stdio, mặc định, giao tiếp qua đầu vào và đầu ra chuẩn, đúng như một client tiến trình con mong đợi. Mọi giá trị khác đều bị từ chối khi tệp này được nạp. aggrega mcp --transport <stdio|http> làm điều tương tự cho một lần gọi và thắng khóa này, như mọi flag đều thắng mọi tệp.
mcp.listen chỉ định nơi listener đó bind, và không chọn gì cả. Hãy cho nó một địa chỉ host:port hoặc một socket unix:<path>; aggrega mcp --listen <address> thắng nó cho một lần gọi.
Khi chọn http mà không có địa chỉ từ nguồn nào, việc khởi chạy bị từ chối trước khi bất cứ thứ gì bind. Khi chọn stdio, một --listen được gõ vào bị từ chối, còn một địa chỉ chỉ có khóa này nêu thì không được dùng — máy chủ thông báo điều đó bằng một dòng trên luồng lỗi của nó, nêu tên tệp này và mcp.transport: http. Vì vậy một máy chủ mà người khác truy cập đặt cả hai khóa, như trên, và một client khởi chạy từ một thư mục mà tệp đó bao phủ vẫn truy cập máy chủ qua các luồng của chính nó. Một đường dẫn unix: được lấy đúng như đã viết thay vì được neo —
xem Đường dẫn tương đối trỏ đến đâu.
mcp.tls.cert_file và mcp.tls.key_file đưa TLS vào trong tiến trình. Đặt cả hai thì listener tự phục vụ HTTPS. Bỏ cả hai thì nó phục vụ plaintext, điều chỉ được chấp nhận trên loopback hoặc trên một Unix socket — dạng bạn dùng khi một proxy phía trước giữ chứng chỉ và chuyển tiếp đến tiến trình. Một listener plaintext trên bất kỳ địa chỉ nào khác bị từ chối trước khi bất cứ thứ gì bind, nêu tên hai khóa này, và việc chỉ đặt một trong hai khóa mà không có khóa kia cũng vậy. Cả hai đều là đường dẫn hệ thống tệp và tuân theo quy tắc ở trên: một đường dẫn tương đối được phân giải theo thư mục của tệp đã khai báo nó, nên một chứng chỉ được commit cạnh tệp đó sẽ được tìm thấy bất kể máy chủ được khởi chạy từ đâu. Hãy viết chúng dưới dạng tuyệt đối khi chứng chỉ được quản lý bên ngoài dự án.
mcp.authorization.issuer và mcp.authorization.resource cho biết ai cấp các token mà bên gọi
xuất trình, và máy chủ này được gọi là gì với tư cách tài nguyên mà các token đó được cấp cho. Cả hai đều bắt buộc
bất cứ khi nào transport http được chọn, và một listener bị từ chối trước khi bất cứ thứ gì được bind nếu thiếu chúng, vì
mọi yêu cầu tới endpoint đều được trả lời bằng một challenge bearer-token, và một challenge không chỉ ra
nơi nào để đến là challenge mà client không thể hành động theo. Hãy viết địa chỉ đầy đủ, gồm cả scheme và host: issuer
đúng như máy chủ ủy quyền đó khai báo định danh của chính nó, và resource là địa chỉ mà bên gọi của bạn thực sự truy cập — host mà proxy phía trước trình ra, nếu có, thay vì
địa chỉ mà tiến trình này bind. Cả hai được công bố, không yêu cầu thông tin xác thực, trong tài liệu metadata OAuth
protected-resource mà listener phục vụ, đó là nơi client tìm để biết
lấy token ở đâu. Không cái nào chứa gì bí mật: token đến cùng yêu cầu
xuất trình nó và không bao giờ được viết trong tệp cấu hình. Issuer là một địa chỉ https trừ khi
máy chủ ủy quyền chạy trên chính máy này — localhost, 127.0.0.1 hoặc ::1 — và một listener
chỉ định issuer http thuần trên bất kỳ host nào khác bị từ chối trước khi bất cứ thứ gì được bind, bất kể nó
đọc khóa và bên gọi theo cách nào: mọi client đều được chuyển tới issuer để lấy token, nên qua
http thuần, mã ủy quyền và token của nó sẽ đi qua mạng mà không được bảo vệ, và nếu khóa cũng
được đọc từ đó, bất kỳ ai nằm trên đường truyền đó đều có thể thay thế chúng.
mcp.authorization.jwks_file chỉ định một tệp chứa các khóa dùng để xác minh token, thay
vì đọc chúng từ máy chủ ủy quyền. Bỏ qua nó thì máy chủ đọc metadata của máy chủ ủy quyền
tại địa chỉ well-known của nó và đi theo jwks_uri được công bố ở đó, đó là điều một
workspace có truy cập mạng làm. Địa chỉ khóa đó tuân theo cùng quy tắc như issuer, và
mọi địa chỉ mà một trong hai lần đọc bị chuyển hướng tới cũng vậy: địa chỉ http thuần trên host khác không bao giờ
được truy vấn, và một token cần các khóa đó được trả lời 503 cho đến khi máy chủ ủy quyền công bố
metadata và khóa qua https. Đặt nó thì máy chủ ủy quyền không bao giờ được liên hệ — đó
là điều một workspace khai báo offline: true cần, và một workspace như vậy bị từ chối trước khi
listener của nó bind trừ khi khóa này chỉ định một tệp. Đây là một đường dẫn và tuân theo quy tắc ở trên: đường dẫn tương đối
được phân giải theo thư mục của tệp đã khai báo nó, nên một bộ khóa được commit cạnh tệp đó
sẽ được tìm thấy bất kể máy chủ được khởi chạy từ đâu. Tệp chứa các khóa xác minh công khai, là
những gì máy chủ ủy quyền công bố — không có gì dùng để ký, và không có gì bí mật.
mcp.allowed_origins chỉ được tham chiếu khi yêu cầu mang header Origin, mà trên
thực tế nghĩa là một trình duyệt đã gửi nó. Hãy liệt kê ở đó các origin bạn phục vụ; yêu cầu chỉ định một origin
không có trong danh sách bị từ chối, và yêu cầu không mang header đó vẫn được phục vụ. Client không phải
trình duyệt không gửi header đó và không cần mục nào. Mỗi mục được so sánh chính xác với header,
nên hãy viết nó theo cách trình duyệt gửi: scheme viết thường, ://, host viết thường, và
: kèm cổng chỉ khi cổng không phải cổng mặc định của scheme — https://studio.example.com,
hoặc http://localhost:3000 cho một trang được phục vụ trên máy của bạn — không có đường dẫn và không có
/ ở cuối. Một mục ở bất kỳ dạng nào khác không bao giờ có thể khớp, và bị từ chối khi tệp này được tải, kèm tên
mục đó.
mcp.limits giới hạn những gì một bên gọi có thể yêu cầu — kích thước tối đa của một thân yêu cầu,
số yêu cầu chạy đồng thời, và số yêu cầu một bên gọi có thể gửi trong một phút. Cả ba luôn có
hiệu lực; không cái nào có giá trị gỡ bỏ nó. Giới hạn thứ ba, requests_per_minute, được tính riêng cho từng
bên gọi, nên một bên gọi gửi dồn dập không làm tốn gì của bên khác.
mcp.authorization.trusted_proxy đọc bên gọi từ một proxy phía trước thay vì kiểm tra
token tại đây. Đặt principal_header thành header mà proxy đó dùng để cho biết bên gọi là ai, và
tùy chọn scopes_header thành header mang các scope của bên gọi đó. Cả hai là tên header HTTP, chẳng hạn
X-Forwarded-User — chữ cái, chữ số, dấu gạch nối và một vài ký tự khác mà tên header có thể chứa,
không có dấu cách hay dấu hai chấm — và một tên ở bất kỳ dạng nào khác bị từ chối khi tệp này được tải, kèm tên
khóa, vì không yêu cầu nào có thể mang nó. Ở chế độ đó hoàn toàn không có token nào được đọc, và yêu cầu thiếu
principal header bị từ chối. Vì khi đó header là toàn bộ thông tin xác thực, nó chỉ đáng tin cậy
ở nơi không gì khác có thể đặt nó: tiến trình bị từ chối trước khi bind trừ khi mcp.listen là
loopback hoặc Unix socket. Bỏ khối này đi thì máy chủ này tự kiểm tra token, đó là
mặc định; một khối có principal_header rỗng bị từ chối thay vì được hiểu là mặc định đó.
mcp.deny_reach rút một loại phạm vi tác động khỏi triển khai này. Mọi thao tác máy chủ
thực hiện đều khai báo tác động của nó lan xa đến đâu — none cho thao tác đọc hoặc render và không để lại
gì, workspace cho thao tác ghi bên trong workspace mà tiến trình này phục vụ, registry
cho thao tác publish, ký hoặc thu hồi, và machine cho thao tác thay đổi những gì mọi workspace trên
host dùng chung. Nêu một loại ở đây sẽ rút mọi tool chạm tới nó: tool vắng mặt khỏi
danh sách tool của mọi bên gọi bất kể token của bên gọi đó mang gì, và lời gọi tới nó bị từ chối kèm tên
thiết lập này. Điều đó biến nó thành giới hạn của triển khai chứ không phải của bên gọi, và không thông tin xác thực nào gỡ được — một
máy chủ chỉ nhằm phục vụ thao tác đọc sẽ liệt kê ba loại ghi ở đây và khi đó không thể
publish ngay cả cho bên gọi có token mang mọi scope. Bỏ nó đi, đó là mặc định, thì
triển khai này mang bất cứ gì scope của bên gọi cho phép. Giá trị không thuộc bốn loại trên bị
từ chối khi tệp này được tải, thay vì bị bỏ qua. Không có gì thuộc loại machine được cung cấp qua
HTTP dù thiết lập này nói gì, nên nêu nó được chấp nhận và không thay đổi gì;
aggrega-mcp.md trình bày các loại và các scope cho phép
chúng.
mcp.announce_tools thu hẹp những gì máy chủ công bố, và đây là một giới hạn khác với khóa
ở trên. Hãy nêu các tool mà máy chủ này công bố, viết đúng như danh sách tool báo cáo, và chính xác
những tool đó được công bố: tool bị bỏ ra vắng mặt khỏi danh sách tool của mọi bên gọi và bị từ chối nếu vẫn được gọi
theo tên, kèm tên thiết lập này. Bỏ khóa đi — mặc định — thì mọi tool máy chủ
mang đều được công bố; viết một danh sách rỗng thì không tool nào được công bố, nên hai cách viết đó là hai phát biểu khác nhau
và không có mặc định nào được điền thay bạn. Điều phân biệt nó với deny_reach là thứ mỗi cái
lấy đi. deny_reach lấy đi một khả năng: các thao tác thuộc loại bị rút hoàn toàn không được mang
ở đây và không thông tin xác thực nào mang chúng trở lại. announce_tools chỉ lấy đi một lời công bố — các
tool nó bỏ ra vẫn là khả năng máy chủ có — và thứ nó đáp ứng là một client giới hạn
số tool nó sẽ đăng ký, đôi khi trên tất cả các máy chủ nó kết nối cùng lúc. Khi cả hai
được đặt thì việc rút thắng, nên một tool thuộc loại bị rút vẫn vắng mặt dù khóa này nêu nó thế nào. Một
tên không ứng với tool nào sẽ dừng máy chủ trước khi nó phục vụ bất cứ gì, liệt kê các tool nó có,
thay vì để bạn với một bề mặt hẹp hơn bề mặt bạn yêu cầu. Khác với các khóa khác
ở đây, vốn cấu hình listener mà transport http khởi động, khóa này được đọc bất kể máy chủ
dùng transport nào, vì client mà việc thu hẹp hướng tới thường là client đã khởi chạy tiến trình qua
standard input và output của chính nó;
aggrega-mcp.md trình bày phần còn lại.
mcp.health.listen đặt các kiểm tra liveness và readiness trên một địa chỉ riêng. Cung cấp cho nó một
address theo một trong hai dạng của mcp.listen và một listener thứ hai sẽ trả lời GET /healthz tại đó —
200 kể từ lúc tiến trình chạy — và GET /readyz — 503 cho đến khi workspace đã
được phân giải và endpoint đã bind, 200 từ đó trở đi, điều này cho phép một bộ cân bằng tải giữ lưu lượng
lại cho đến khi tiến trình thực sự có thể trả lời một lệnh gọi. Bỏ nó đi thì không kiểm tra nào được trả lời
ở đâu cả. Chúng không bao giờ được trả lời trên địa chỉ mà mcp.listen chỉ định; địa chỉ đó trả cho chúng 404 như
mọi đường dẫn mà nó không phục vụ: một probe ở đó sẽ là một lần đọc không xác thực một listener
vốn từ chối mọi thứ khác. Không giống mcp.listen, địa chỉ này không bị giới hạn và không địa chỉ nào bị
từ chối cho nó — hãy trỏ nó vào loopback hoặc một Unix socket, là thứ mà một supervisor bên cạnh tiến trình
này truy cập được, và lưu ý rằng bất cứ thứ gì truy cập được địa chỉ bạn chọn đều đọc được hai câu trả lời đó.
schema/other/aggrega-config.md nêu từng khóa này cùng với giá trị mặc định của nó, nếu có.
Những cách khác để nhận diện thư mục gốc của dự án
--workspace-root <path>, hoặc biến tương ứng AGGREGA_WORKSPACE_ROOT, chỉ định thẳng thư mục gốc và
bỏ qua việc dò tìm. Thư mục mà nó chỉ định phải tồn tại: một đường dẫn không trỏ tới gì, hoặc trỏ tới một tệp, sẽ bị
từ chối trước khi lệnh làm bất cứ điều gì khác, và thông báo từ chối nêu tên nguồn nào trong hai nguồn đã cung cấp
giá trị và trích nguyên văn giá trị đó. Nếu không, việc dò tìm đi ngược lên từ thư mục làm việc,
và các loại mốc được xếp hạng với nhau thay vì theo độ gần:
- Một
.aggrega-config.yamlmang khốiworkspace:thắng tuyệt đối, ở bất kỳ độ sâu nào mà nó nằm. Quá trình dò tiếp tục leo lên để tìm một tệp như vậy ngay cả sau khi đã đi qua một dấu mốc thuộc loại dưới đây, nên một thư mục gốc được đánh dấu tường minh ở trên luôn thắng một dấu mốc ngẫu nhiên ở dưới nó. - Nếu không có, dấu mốc gần nhất trong số sau đây xác định thư mục gốc, và trong cùng một thư mục chúng
được xếp hạng theo thứ tự này: một thư mục
.aggrega/, rồi mộtaggregate*.yaml, rồi mộtrelease*.yaml, rồi mộtmanifest*.yaml. - Khi mọi cách đều không được, thư mục làm việc được dùng — các lệnh vẫn chạy thay vì từ chối khởi động. Một lệnh có kết quả phụ thuộc vào workspace — lệnh đọc hoặc ghi các tài liệu của workspace, đọc hoặc lấp đầy bộ nhớ đệm artifact của nó, hoặc phục vụ nó — cảnh báo một lần trên standard error:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Một lệnh có kết quả không phụ thuộc vào việc thư mục nào là gốc thì không nói gì, kể cả khi nó đọc cấu hình: trong số đó cóaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explainvàaggrega login.aggrega config capture, với công việc là ghi chính tệp cấu hình của workspace, không ghi gì trong một thư mục như vậy và thoát với một lỗi nói rõ điều đó.
Không có gì được ghi vào bộ nhớ đệm artifact trong một thư mục như vậy. Bản thân một thư mục .aggrega/ là một trong
các dấu mốc ở trên, nên một bộ nhớ đệm ghi ở đó sẽ biến thư mục thành một workspace chỉ vì đã từng có thứ gì đó
được tải về trong nó. Một lệnh mà công việc làm đầy bộ nhớ đệm — aggrega pull, một lần build phân giải các
phụ thuộc trước, aggrega registry update, việc thêm một plugin mở rộng lệnh từ một registry — sẽ bị
từ chối trước khi tải bất cứ thứ gì, nêu tên thư mục và hai lối ra: chỉ định workspace bằng
--workspace-root hoặc AGGREGA_WORKSPACE_ROOT, hoặc cho thư mục một .aggrega-config.yaml mang một
khối workspace:. aggrega pin, và aggrega push của một Recipe hoặc FeatureRecipe, vốn bị ràng buộc bởi
các pin mà entity.lock bên cạnh nó ghi lại, chỉ làm đầy bộ nhớ đệm bằng các nguồn từ xa mà entity
viết đầy đủ, những nguồn mà việc pin một entity hoặc so sánh pin của nó sẽ tải về: chúng bị từ chối theo cùng cách ở nơi
chúng sẽ tải một nguồn như vậy, trước khi tải nó. Một entity không có nguồn như vậy — không có nguồn nào
cả, một nguồn cục bộ, hoặc một nguồn mà tọa độ do từng Release điền vào — được pin hoặc publish ở đó như
ở bất kỳ nơi nào khác. Một lần build ở đó không bị từ chối, nhưng một
đầu vào bên ngoài mà lockfile của nó pin và bộ nhớ đệm không còn giữ sẽ không được tải lại để sửa chữa: quá trình
render nhận cùng câu thông báo đó thay cho đầu vào ấy, giống như cách nó nhận thông báo của chế độ offline, và
báo cáo nó. Việc artifact_cache_dir đặt bộ nhớ đệm ở đâu không thay đổi gì ở đây, vì thư mục được
nối vào thư mục gốc nào đã được tìm thấy. Các lệnh chỉ đọc vẫn trả lời.
Phương án dự phòng cuối cùng đó có một ngoại lệ. Khi không có gì chỉ định thư mục gốc và thư mục làm việc không xác định
được gì, một lệnh về một Release hoặc một tài liệu entity mà chỉ định tệp đó bằng đường dẫn tuyệt đối
sẽ dò tìm thư mục gốc lại, đi ngược lên từ thư mục chứa tệp, và dùng bất cứ thứ gì nó
tìm thấy: workspace mà tệp thuộc về, hoặc, nếu không có gì cả, chính thư mục đó. Tệp đó là tệp mà
--release chỉ định trên aggrega build và aggrega pull; Release mà aggrega validate,
aggrega lint và aggrega inspect được truyền vào, hoặc nếu không thì tệp chúng được truyền vào; và tài liệu
mà aggrega pin, aggrega push và aggrega edit-document được truyền vào. Vì vậy một Release của dự án được build từ
bên ngoài dự án sẽ đọc cấu hình riêng của dự án, như khi lệnh chạy bên trong
nó, và các cảnh báo cấu hình mà lệnh in ra là của workspace đó. Ở nơi thư mục của chính tệp
cũng không xác định được gì, thư mục đó là thư mục mà thông báo của lệnh nêu tên và là thư mục không có bộ nhớ đệm
nào được ghi vào. Một đường dẫn tương đối được đọc theo thư mục bạn chạy lệnh và không thay đổi
gì, và một thư mục gốc được chỉ định, hoặc một thư mục làm việc vốn nằm bên trong một workspace, được dùng nguyên
trạng.
Máy chủ trợ lý áp dụng cùng quy tắc cho một
lệnh gọi chỉ định Release hoặc tài liệu của nó bằng đường dẫn tuyệt đối.
Đánh dấu thư mục gốc bằng một khối workspace: là lựa chọn tường minh và là lựa chọn nên ưu tiên; các dấu mốc tệp
và thư mục cho phép một dự án chưa khai báo khối đó vẫn được build.
Chỉ định tường minh tệp toàn cục
Lớp toàn cục được phân giải theo thứ tự này:
--config <path>, dạng cho từng lần gọi.- Biến môi trường
AGGREGA_CONFIG. - Vị trí mặc định: trên Windows là
aggrega\config.yamlbên trong thư mục mà biến môi trườngAPPDATAchỉ định, và ở nơi khác làaggrega/config.yamlbên trong thư mục màXDG_CONFIG_HOMEchỉ định, nếu không có thì dùng~/.config/aggrega/config.yaml.
Hai cách đầu chỉ định một tệp tường minh, nên một đường dẫn không tồn tại là một lỗi rõ ràng thay vì một
phương án dự phòng âm thầm — bạn đã yêu cầu một tệp cụ thể. Một lệnh đọc cấu hình của nó sẽ dừng lại
với một câu kết thúc bằng đường dẫn, để bạn có thể sao chép. aggrega config init là
ngoại lệ, vì tạo tệp đó
là mục đích của nó: nó tạo tệp được chỉ định và báo điều đó. Vị trí mặc định được nạp khi
tệp có ở đó và được bỏ qua lặng lẽ khi không có. Dù tệp nào được phân giải, các tệp của dự án
bạn vẫn xếp lớp lên trên nó.
Khi không cách nào trong số này phân giải được — không tệp nào được chỉ định, và các biến mà vị trí mặc định được đọc từ đó chưa được đặt — một lệnh ghi tệp toàn cục sẽ dừng lại và nêu những gì cần đặt. Biến môi trường liệt kê, theo từng nền tảng, các biến mà mỗi vị trí được đọc từ đó.
Lựa chọn đó cũng quyết định nơi một lệnh ghi cấu hình sẽ ghi. Một lệnh chạy với
--config <path> đọc cấu hình từ tệp đó và áp dụng thay đổi của nó vào chính tệp đó,
nên những gì một lệnh ghi là những gì lệnh tiếp theo đọc lại.
Một lệnh mặc định ghi vào tệp nào trong hai tệp phụ thuộc vào bản chất của thiết lập:
công cụ dùng trên toàn máy như một registry được ghi vào tệp toàn cục, còn các thiết lập
tham gia vào build như một ràng buộc provider hay một kết nối socket được ghi vào tệp đã commit của dự án, để
chúng đi cùng dự án. Truyền --global hoặc --workspace để ghi đè, và lệnh sẽ in ra
tệp mà nó đã ghi.
Xem thêm
- aggrega-config.md — các lệnh
aggrega configdùng để khởi tạo, kiểm tra và cố định cấu hình. - environment-variables.md — mọi biến có tiền tố
AGGREGA_, và nơi cung cấp các bí mật. - global-flags.md —
--config,--workspace-root, và các flag khác mà mọi lệnh con đều chấp nhận. - schema/other/aggrega-config.md — mọi khóa cấu hình, kiểu của nó và giá trị mặc định của nó.
- aggrega-cache.md — những gì
artifact_cache_dirthực sự chứa. - workspace-boundary.md — những đường dẫn nào nằm trong workspace, và cách các thư mục và tệp mà cấu hình này chỉ định vươn ra ngoài nó.
- aggrega-mcp.md — máy chủ mà khối
mcpcấu hình.