aggrega push-artifact
Xuất bản một artifact dữ liệu độc lập (chẳng hạn một gói tài liệu) lên một OCI registry
Cú pháp
aggrega push-artifact <file> [flags]Mô tả
Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--dry-run | false | Tính toán tham chiếu và in ra |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | Media type của artifact OCI; mặc định là media type của gói tài liệu |
--name | — | Tên artifact trong không gian tên dành riêng docs/ (ví dụ “aggrega-docs” được xuất bản tại docs/aggrega-docs) |
--registry | — | Máy chủ registry đích (ghi đè default_registry của workspace) |
--tag | — | Thẻ phiên bản dùng để xuất bản artifact (bắt buộc) |
Artifact gói tài liệu
Một gói tài liệu là một artifact dữ liệu độc lập — một tệp tar nén gzip chứa tài liệu đã được kết xuất — chứ không phải một thực thể catalog. Nó mang media type application/vnd.aggrega.docs.v1beta1+tar+gz, là loại artifact mà bên tiêu thụ thấy khi kéo gói từ registry.
Các gói được xuất bản dưới phân đoạn kho docs/: --name aggrega-docs đặt
artifact tại docs/aggrega-docs, và --tag chọn phiên bản, nên tọa độ kéo là <registry>/docs/<name>:<tag> — ví dụ,
hub.aggrega.ai/docs/aggrega-docs:1.0.0. Vì gói là một artifact dữ liệu thuần túy chứ không phải một thực thể catalog, nó được tải về bằng bất kỳ client tương thích OCI nào với tham chiếu và media type đó. Tệp được xuất bản mang tên được chỉ định
bằng --name, nên một client ghi tệp theo tên sẽ ghi nó dưới tên đó:
oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 để lại aggrega-docs trong
thư mục hiện tại, giống hệt từng byte như khi được xuất bản.
Khi registry làm một lần ghi thất bại
Việc xuất bản ghi vào registry theo từng bước — tệp, manifest đặt tên cho nó, thẻ, và sau đó là ngày xuất bản bên cạnh — và mỗi lần ghi đó
được thử lại khi registry hoặc mạng làm nó thất bại theo cách mà một lần thử sau có thể thành công, chẳng hạn lỗi máy chủ, hết thời gian chờ hoặc kết nối bị đặt lại;
aggrega push liệt kê các lỗi đó. Một lần ghi được thử tối đa ba lần, cách nhau nửa giây rồi một giây, và mỗi lần thử là một lần tải lên mới của cùng các byte chứ không phải gửi lại yêu cầu đã thất bại, nên một lần ghi được thử lại cho ra đúng kết quả mà một lần thử sẽ cho.
Một lần ghi vẫn thất bại sau lần thử cuối cùng sẽ làm lệnh thất bại, và lỗi nêu tên bước đó. Lỗi khi gắn ngày xảy ra sau khi artifact đã được đưa lên: artifact vẫn được xuất bản, và lệnh thoát với mã khác không, báo rằng không thể gắn ngày xuất bản của nó. Chạy lại cùng lần xuất bản đó sẽ hoàn tất nó: artifact được báo là đã xuất bản, không có gì được tải lên, và ngày được gắn vào nơi artifact chưa có ngày, ghi theo đồng hồ của lần chạy đó — thời điểm việc xuất bản được hoàn tất. Một artifact đã có ngày sẽ không được gắn thêm gì, và một danh sách không đọc được sẽ thoát với mã khác không mà không gắn gì.
Ngoại tuyến
Xuất bản một artifact là một lượt trao đổi qua mạng, nên ở chế độ ngoại tuyến — khóa cấp cao nhất offline trong một tệp cấu hình, AGGREGA_OFFLINE, hoặc --offline — lệnh này từ chối trước khi đọc tệp, và thông báo từ chối nêu rõ cái nào trong ba cái đó đã đặt chế độ này. --dry-run vẫn hoạt động, vì nó chỉ tính toán tham chiếu và không thực hiện lệnh gọi nào. Để xuất bản cho một lần chạy từ một workspace ngoại tuyến, hãy truyền --offline=false.
Xem thêm
- ./aggrega-sign.md — một artifact dữ liệu được ký sau đó, theo tham chiếu; lệnh này không tự gắn chữ ký nào.
- ./aggrega-serve.md — daemon cung cấp cùng việc xuất bản này tại
aggrega/publishArtifact, nên một trình soạn thảo có thể chạy nó mà không rời phiên làm việc. - ./aggrega-mcp.md — cùng khả năng này dưới dạng công cụ
publish-artifact, mà một trợ lý có thể gọi. Hãy đọc những gì trang đó nói về việc cho phép nó trước khi bạn làm vậy.