跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

aggrega registry

管理注册表及其签名信任策略

概要

aggrega registry

说明

Manage the OCI registries Aggrega publishes to and resolves from, together with
the signature trust policy for each.
A registry entry records where to reach the registry and what to require of the
signatures on artifacts it serves — which identities are trusted, and whether a
signature is required at all. That policy is what "aggrega pull" enforces when
it verifies an artifact and what "aggrega push" honours when it decides whether
to sign.
"aggrega registry add" can fetch a registry's own advertised trust policy rather
than having you write it out. "aggrega registry update" builds the local
searchable index that "aggrega search" and "aggrega plugin add" read.
A registry entry is written to the global config shared across every workspace
on this machine, because a registry and the identities you trust on it are
usually the same wherever you work. That makes adding or removing one a
machine-wide change: every project on this machine resolves through the entry
you just wrote or dropped. Pass --workspace to write it to this project's config
file instead. Building the searchable index is the exception — that lands in
this workspace's own artifact cache and reaches no other project.

子命令

命令描述
aggrega registry add注册一个注册表及其签名信任策略
aggrega registry list列出已配置的注册表及其信任状态
aggrega registry remove从配置文件中移除一个注册表及其信任策略
aggrega registry update为已配置的注册表构建本地可搜索索引

aggrega registry add 说明

Register a registry host and its signature trust policy.
The entry is keyed under the host exactly as written, and every lookup of it is
made in one spelling: a lowercase host name containing a dot, localhost, a single
name followed by a port (registry:5000), an IPv4 address, or an IPv6 address in
brackets, each with an optional :port. A reference may be given instead — its
scheme, path and credentials are dropped and the entry is keyed under the host it
names — but a host written in capitals, with the default HTTPS port, or as a
single name with no port is refused, naming the spelling to write where there is
one.
The entry is written to the global config shared across every workspace, since a
registry and the identities you trust on it are usually the same wherever you
work. Pass --workspace to write it to this project's config file instead; the two
flags are mutually exclusive.
By default the registry's advertised trust policy is fetched once from the
registry's own origin (https://<host>/.well-known/aggrega-trust) and pinned
locally — trust-on-first-use. Verification at pull time always runs against the
pinned local policy, never a live re-fetch. Pass --fetch-trust=false to skip the
fetch and pin only what the flags supply.
A trust policy can also be set by hand: keyless (one or more --identity entries,
each an "identity=issuer" pair) or keyed (--key pointing at a pinned public-key
PEM). Manual --identity / --key flags OVERRIDE the fetched set — when either is
supplied, the fetch is skipped and the policy is built from the flags alone.
Pass --trusted-root to pin a Sigstore trust-root bundle for air-gapped keyless
verification. Adding the official hub host with no policy flags pins the built-in
official baseline.
When the registry advertises no trust policy (a 404 or an unreachable endpoint),
the add does not fail: it writes the policy from the flags (or an empty policy)
and prints a notice suggesting manual --identity / --key pinning. The official
hub writes its built-in baseline instead, and the notice says the baseline was
pinned.
When the workspace is offline the advertised policy cannot be fetched, so the
registry is never asked. Adding a registry other than the official hub is then
refused unless --identity or --key supplies the policy, rather than writing an
entry that trusts nothing: register it once while online, or pin it by hand.
Adding the official hub offline pins its built-in baseline, with a notice saying
so, and a manual policy registers offline exactly as it does online.
Existing settings in the target config file are preserved.

aggrega registry add 标志

标志默认值描述
--advisoryfalse将此注册表的验证失败降级为警告,而不是中止
--fetch-trusttrue首次使用时获取并固定注册表公布的信任策略。使用 —fetch-trust=false 跳过;手动指定 —identity/—key 也会跳过获取。
--globalfalse将条目写入所有工作区共享的全局配置。注册表默认写入此处。
--identity[]受信任的无密钥身份,格式为 identity=issuer,例如 dev@example.com=https://accounts.google.com (可重复;OR 集合)。覆盖获取到的信任策略。
--key—用于密钥验证的、已固定的 cosign 兼容公钥 PEM 文件路径。覆盖获取的信任策略。
--name—此注册表的可选友好别名。主机仍是其身份;在任何指定注册表的地方(例如 —registry),别名都会解析为该主机。在所有注册表中必须唯一。
--require-signaturesfalse要求从此注册表拉取(以及推送到此注册表)的每个制品都带有签名
--trusted-root—用于离线环境无密钥验证的、已固定的 Sigstore 信任根包路径
--workspacefalse将条目写入此项目的工作区配置,而不是全局配置。

aggrega registry list 说明

List every registry configured in the effective merged config, one per line,
with its friendly alias (if any), a short trust-posture summary, and a marker on
the default registry.
This reads the resolved configuration and never contacts a registry. Registries
are listed in ascending host order.
With -o json the same set is emitted as one structured document per registry:
its host, its alias, whether it is the default, its trust posture as discrete
fields rather than the table's rendered sentence, and whether a credential for
that host is present in the shared credential store. The credential state reports
presence only — a credential is never read out, measured, or shown in any form,
and whether the registry would accept it is not asked, since that would take a
network round trip. Reading it consults the local credential store, which honors
a configured credential helper. The order is the same ascending host order the
table uses.

aggrega registry list 标志

标志默认值描述
--output, -otable输出格式:table|json。

aggrega registry remove 说明

Remove a registry's trust-policy entry from a config file, addressed by its host
or its friendly alias.
By default the entry is removed from the global config shared across every
workspace; pass --workspace to remove it from this project's workspace config
instead. Setting both --global and --workspace is a usage error.
The default_registry pointer is left untouched — removing a registry's trust
policy reverts that host to default trust; it does not change which registry is
the default. Where default_registry names the removed entry by its alias, that
alias names nothing afterwards, and the configuration is refused until
default_registry is written as a host or as another entry's name.

aggrega registry remove 标志

标志默认值描述
--globalfalse从所有工作区共享的全局配置中移除条目。
--workspacefalse从此项目的工作区配置中移除条目,而不是从全局配置中移除。

aggrega registry update 说明

Walk each configured registry's repositories, read the latest published version
of each, and write a deterministic local searchable index to the artifact cache.
With no argument, every configured registry is indexed. With a single registry
argument (a host or a friendly alias), only that registry is indexed.
This is the one registry command that reaches the network. The index it writes
lands in this workspace's own artifact cache, so refreshing it changes nothing
another project on this machine resolves through. Credentials are read from a
supplied or ambient source and never asked for: a registry that needs one you do
not have fails with a message naming what it wanted.
For each repository the highest strict-SemVer version is selected (pre-release
versions are skipped) and its catalog facets — kind, description, category,
labels, and, for plugins, socket type and capabilities — are recorded from the
published manifest. A repository with no conforming version is skipped; a
repository that cannot be read is skipped with a note, so one unreadable
repository does not abandon the whole index.
A registry that asks the walk to slow down — a 429 answer, or a 503 that says
how long to wait (Retry-After) — is left alone for as long as it asks, or ten
seconds where it does not say, and the walk reads fewer of its repositories at
once until it answers again, then returns to its usual pace; on a terminal the
wait is shown beside that registry's row. A registry that answers nothing but
"slow down" for five minutes is not indexed: it keeps the index it had before
the run, and the command names it, its last answer and how long it waited.
A read the registry fails or drops in passing — a 5xx answer, a connection
reset or timed out, an answer cut short — is asked again a few times, with a
growing wait between attempts. A repository with a read still
failing after that is not recorded from this run: it keeps the record the index
already holds for it, where that record was judged under the trust policy now in
force, and is otherwise left out of the index; either way it is named as a
repository that could not be read, as the walk goes and again in the closing
summary under its registry's row, with the kind of the read's last failure — the
status the registry answered, a timeout, a reset, an answer cut short — and the
read that failed. So a version is never recorded unsigned,
undated or without its deprecation marker because a read failed, with or without
--upgrade. Each registry's row in the closing summary also says how many reads
were asked again, whether or not they then succeeded — a read sent again after
the registry asked the walk to slow down among them — and says zero when none
was.
Every signature a registry's walk verifies against the public Sigstore trust root
is verified against the same copy of that root, fetched once for the walk rather
than once per signature; a registry whose trust policy pins a trust root of its
own is verified against that file.
A registry whose repository listing repeats itself — naming a repository it has
already named, or answering two pages in a row with no repository while still
pointing to a next page — is not followed round again. That registry is reported
as not indexed, with a message naming it and saying its repository listing
repeated itself; the other registries are still indexed, and the command exits
non-zero.
A registry that is not indexed keeps the index it had before the run, unchanged:
nothing is written for a registry whose walk failed, whose listing repeated
itself, or that was being walked when the command was interrupted. Registries
indexed earlier in the same run keep what this run wrote for them. A registry's
new index is written aside and put in place whole, so a command stopped while
writing one leaves that registry with a complete index — the one it had before
the run, or the new one — or with none, never with a partial one.
Every strict-SemVer version a recorded repository publishes is listed too, each
with the manifest digest its tag resolves to — the address of the exact bytes
published under that version. Where the registry's trust policy pins a public key
or trusted identities, and verification is not switched off, each version's own
signatures are verified against that policy and the signer is recorded when one
verifies; a version with no signature, or none that verifies, is recorded with no
signer. Where several verify, the signer recorded is the one the transparency log
recorded earliest, whatever order the registry lists them in, so signing a version
again never changes its recorded signer.
Each version's publication date is recorded too, with its source. Where one of the
version's keyless signatures verified, the date is the time the transparency log
recorded that earliest signature, as the verified log entry attests it (source
'transparency-log') — so signing a version again never moves its date. Otherwise
it is the date the publication itself stated beside what it published (source
'publisher'), the earliest where several are stated: the publishing machine's own
clock, which nothing attests, read from any registry whatever its trust policy.
A version with neither — published without stating a date, and not signed
keyless in a way this policy verifies — is recorded with no date.
Only manifests, signature attachments and publication-date attachments are read:
no entity's content is fetched. 'aggrega search -o json' reports these under each
record's 'published' field.
The per-repository records are byte-identical across two runs against the same
registry state; the freshness timestamp is written to a sibling file so it never
disturbs the records.
A refresh reads again only what changed, and finds every change a full re-read
would. For each repository it revalidates the tag listing with a conditional
request, resolves every version's tag to its manifest digest, and revalidates every
version's attachments — its signatures, publication-date statements and deprecation
markers — with one conditional request, plus one for the signatures of a
deprecation marker it judged before. A version whose digest or attachments changed
is read again in full, and its signatures and markers are verified again exactly as
a full re-read verifies them; everything else is kept as recorded. A change to this
registry's trust policy reads every version again under the policy now in force, and
so does a repository whose entry in the index records none of these checks. An
unchanged registry therefore costs one conditional request per repository and two
small requests per version (three where a deprecation marker was judged), with
nothing downloaded. A version is read again on the next refresh where it carries a
deprecation marker that was not honored, or where this run got no way to
revalidate its attachments — which, on a registry that offers none, is every
version.
Several repositories are read at a time. Everything the command records and prints
comes out in repository order, so the index and the output are the same as reading
one repository at a time would produce.
While it walks, a terminal shows the walk's progress on standard error, the way
build and pull show theirs: a row naming each registry, a spinner while that
registry's repository listing is read, then how many of its repositories the walk
has finished out of how many it lists, counted in repository order, and a bar for
the whole walk below the rows. On a terminal that cannot redraw in place, or with
--plain, each registry gets one plain line instead, written when its walk ends,
with the count it ended on and the time it took. When standard error is not a
terminal, no progress is shown. The progress changes nothing the command prints on
standard output.
Use --upgrade to read every repository in full, comparing nothing with the index
already written — to rebuild an index from the registry alone. It finds no change a
refresh without it would miss.
Each published version's deprecation markers are read as the walk goes, and the ones
whose own signature verifies are recorded into the index. Every marker read is
reported, whether or not it was recorded — a version kept as recorded is not read, so
its marker is not reported again — and each registry reports how many markers its
index now records, including when that number is zero. Where signature
verification is disabled for a registry, the walk reports that its markers were not
examined rather than a count, so a registry that published nothing is never confused
with one this run had no basis to judge.

aggrega registry update 标志

标志默认值描述
--upgradefalse完整读取每个仓库,不与已写入的索引作任何比较(不带此标志的刷新本就会重新读取所有已更改的内容)

registry update 关于弃用标记报告的内容

aggrega registry update 在遍历注册表时,会读取每个已发布版本的 弃用标记,并将其能够验证的标记记录到本地索引中。 它在每条路径上都会报告这次扫描的结果,因此未发布任何 标记的注册表与未查找标记的运行可以区分开来。

遍历读取的每个标记都会生成一行,列出仓库、版本以及发布者记录的严重级别(warning、error 或 retracted),同时说明该标记是否已被记录。自上次刷新以来附件未发生变化的版本会保留已记录的内容而不再读取,因此其标记不会再次报告;下面的计数仍包含它。只有当标记自身的签名能够通过注册表信任策略所认可的签名者验证时,该标记才会被记录。存在但无法解码、或存在但未被认可的标记会如实报告,并且不会写入索引,而不是基于无法验证的证据被记录——注册表回答其并不持有的标记也是如此。读取失败的标记属于另一种情况:参见失败的读取。

随后,每个注册表会报告其索引当前记录了多少个标记,包括 该数量为零的情况。如果签名验证被关闭(全局关闭,或仅针对 该注册表关闭),遍历会改为报告未对其检查标记。 这是两个不同的事实:前者表示该注册表未发布任何此 工作区可以据以采取行动的内容,后者表示此次运行根本没有可用于判断 标记的信任依据。未检查标记的注册表不会为版本选择提供任何撤回信息, 因此附加了标记却看到这一行的作者便能知道 该标记为何没有生效。

每个版本记录的发布日期

已发布 manifest 的创建时间是固定的,因此其摘要只取决于发布了什么,而与何时发布无关。所以版本的发布日期从 manifest 旁边读取,aggrega registry update 会为每个版本记录该日期及其来源:

  • transparency-log — 当版本的签名为无密钥签名,且能依据该仓库的信任策略通过验证时,取透明日志记录该签名的时间,由日志的签名承诺予以证明。当该版本有多个签名通过验证时,取其中最早的时间,且为该版本记录的签名者也是同一签名的签名者——无论仓库以何种顺序列出这些签名——因此再次签名的版本会保留其日期和签名者。对于发布时即签名的版本,这就是其发布时间;对于发布后才首次通过 aggrega sign 签名的版本,这是其签名时间。 只要存在此来源,就以它为准。
  • publisher — 否则,取发布方在所发布内容旁声明的时间:这是 aggrega push 和 aggrega push-artifact 写入的一个小型 published-at 附件,携带发布机器自身的时钟时间,没有任何证明。无论仓库的信任策略如何,都会读取它,因为它是发布方的声明,而非信任决策。当附加了多个时,取最早的一个。

两者都没有的版本不记录日期。这种情况是:发布时未声明日期,且其签名不是此策略能验证的无密钥签名——例如,在不信任任何无密钥身份的策略下读取的无密钥发布,因为无密钥发布本身不声明日期。aggrega search -o json 在每个版本下的 published 中报告该日期。

刷新会重新读取什么

刷新会将注册表当前提供的内容与索引已记录的内容进行比较,并重新读取所有发生变化的内容——得到的答案与完整重新读取相同。对于每个仓库,它会:

  • 重新验证标签列表,从而发现此后发布或删除的版本;
  • 将每个版本的标签解析为其指向的清单,从而重新读取以现有标签再次发布的旧版本;
  • 重新验证每个版本的附件——其签名、发布日期声明和弃用标记——从而读取并验证此后附加到某个版本的签名、日期或标记,并对之前已判定过的弃用标记的签名做同样的处理;
  • 将注册表的信任策略与构建索引时所依据的策略进行比较,从而在策略发生变化时按新策略重新读取每个版本。

弃用标记、签名和发布日期各自作为一个单独的对象附加到已发布的版本上,并指回该版本——正是这一点让发布者无需重新发布即可弃用或签名某个版本——因此它们都不会新增标签,也不会改动该版本自身的清单。它们改变的是该版本的附件,而这正是第三项检查所重新验证的内容。版本排除和 aggrega inspect 都读取此索引,因此自上次刷新以来被撤回的版本,会在下一次刷新运行后被排除在选择之外,并被显示出来。

每项检查都是一个小请求——解析清单摘要,或注册表在不发送任何内容的情况下以“未更改”应答的条件请求——因此刷新一个未发生变化的注册表不会下载任何内容。带有未被认可的弃用标记的版本,或本次运行无法重新验证其附件的版本,会在下一次刷新时被重新读取。无法说明某个版本的附件是否发生变化的注册表,会在每次刷新时重新读取每个版本:答案相同,代价也与完整重新读取相同。

--upgrade 会完整读取每个仓库,不与已写入的索引作任何比较。可用它仅凭注册表重建索引;它不会发现任何刷新所遗漏的内容。

要求放慢速度的注册表

官方 hub hub.aggrega.ai 会限制短时间内来自同一地址的请求数量,因此共享同一地址的机器共享这一配额,任何注册表也都可以用同样的方式限制其客户端。超出限制的注册表会回答 429 Too Many Requests,或带有说明需等待多久的 Retry-After 标头的 503 Service Unavailable。命令行向注册表发出的每个请求,无论是哪个命令,都以相同方式应对这一回答:按注册表要求的时间等待,回答中未说明时等待十秒,再随机加上最多一秒,然后再次请求,没有固定的尝试次数。发往该注册表的每个请求都会随之等待,而不仅是被拒绝的那个,同时向其并发发送的请求会减少:每次它提出要求时减半,最少到一个;它每无故障地处理完一批请求后再加一个,直到恢复命令的常规数量。等待的显示方式与命令其余进度相同,显示为类似 hub.aggrega.ai asked to slow down; waiting 11 s 的一行:aggrega build、aggrega pull 和 aggrega registry update 将其显示在正在进行的步骤旁边,其他会显示所等待内容的命令将其显示为单独的步骤(但同时签名多个引用的 aggrega sign --jobs 除外,它将这些等待显示为一个步骤);当标准错误不是终端时,除非命令的 --progress 要求显示,否则不显示任何内容。如果注册表在五分钟内只回答“放慢速度”,则以 E0378 拒绝,并指出该注册表、其最后一次回答以及它只给出这一回答的时长;这五分钟是固定的,没有任何设置可以更改。随后 aggrega registry update 会在结束摘要的 Not indexed: 下列出该注册表,而该注册表保留运行前的索引。

失败的读取

遍历会从注册表读取许多小对象,其中一些读取会临时失败:注册表回答其出错或不可用(5xx 状态,但说明需要等待多久的 503 除外),或回答请求超时(408),连接被重置或超时,或者应答在完整之前中断。每个这样的读取都会重试几次,两次尝试之间的等待时间逐渐增加。要求遍历放慢速度的注册表并不是让读取失败:读取会按要求放慢速度的注册表所述等待并重试,而持续要求五分钟的注册表会结束该注册表的遍历,而不是某一个仓库的遍历。

仍然失败的读取永远不会被当作应答。无法读取的签名并不意味着该版本没有签名,无法读取的弃用标记也并不意味着该版本从未被撤回,因此遍历不会根据本次运行记录该仓库的任何内容。若索引中已为该仓库保存的记录是在当前生效的注册表信任策略下判定的,该仓库就保留这条记录;否则它会被排除在索引之外。无论哪种情况,遍历都会在运行过程的说明中指明该仓库,说明发生的是两者中的哪一种以及哪次读取失败,并在结尾摘要中再次指明它:在其注册表所在行下方单独占一行,列在无法读取的仓库之中:

Indexed 1 registry.
registry.example.com: 41 entities, 1 repository could not be read, 4 reads retried
component/core/web: the registry answered 503 Service Unavailable: …

注册表所在行还会说明有多少次读取被重试,每次读取无论尝试了多少次、之后是否成功,都只计一次;没有任何读取被重试时,则显示 0 reads retried。读取最终全部成功的遍历不会在其行中显示任何仓库,因此正是这个计数说明了它离遗漏某个仓库有多近。

每一行都以该读取最后一次失败的类别开头——注册表应答的状态、超时的读取、被重置的连接,或被截断的应答——随后是失败本身,它说明是哪一次读取。不属于这些类别的失败,例如无法获取用于验证签名的信任根,则只给出失败本身。aggrega serve 的 aggrega/registryUpdate 方法会在每个主机的 skipped 下返回相同的仓库,每个仓库带有相同的 reason,并以 readsRetried 给出重试的读取次数。刷新和 --upgrade 同样如此,下一次遍历从索引届时所保存的内容开始,与任何仓库的情况相同。

带密钥的策略所固定的公钥

带密钥的信任策略以内联方式固定注册表的公钥,即该条目的 public_key: aggrega registry add --key <file> 会把该文件的内容复制到这里,固定注册表所公布的、其中包含密钥的 策略时也是如此。该值是一个 PEM 公钥块——从 -----BEGIN PUBLIC KEY----- 行(或 -----BEGIN RSA PUBLIC KEY----- 行)到与之 匹配的 -----END 行之间的文本——块之前的任何文本都会被忽略。

不含 -----BEGIN … PUBLIC KEY----- 行的值会在加载配置文件时被拒绝, 并指出该文件和该条目。registry add 在写入之前会进行同样的检查, 因此若 --key 文件包含其他任何内容——私钥、证书或采用 其他编码的密钥——都会被拒绝,配置文件保持原样。只检查该行: 该块能否解码为可用的密钥,要到用它验证来自该注册表的签名时才能得知。

离线

aggrega registry update 是该命令组中唯一一个全部工作都是遍历各注册表的命令;在离线模式下——即配置文件中的顶层 offline 键、AGGREGA_OFFLINE 或 --offline——它会在遍历任何内容之前拒绝执行。拒绝信息会指明是这三者中的哪一个设置了离线模式。

不存在可以退而使用的部分执行形式,因为索引记录的是每个注册表当前提供的内容,而不询问注册表就无法得知这一点。离线工作区能做的是读取它已有的索引:aggrega search 和 aggrega inspect 上的弃用提示都读取本地快照,完全不需要网络,因此离线模式唯一去掉的就是刷新。若要在离线工作区中为单次运行执行刷新,请传入 --offline=false。

aggrega registry add 会访问一次网络,以获取注册表所公布的信任策略,除非 --fetch-trust=false、--identity 或 --key 指明不获取。在离线模式下,该获取会在任何连接发起之前被拒绝,因此注册表永远不会被询问。此时添加官方 hub 以外的注册表会被拒绝——添加注册表是固定其信任的唯一时刻,而没有策略就写入的条目将不信任任何内容,同时之后的每次拉取都会按此要求该注册表。该拒绝带有简码 E0310,并指明两种解决方式:在联网状态下注册一次(--offline=false 允许单次运行这样做),或者使用 --identity 或 --key 手动固定策略,这会严格按你提供的内容注册,完全不进行获取。官方 hub 会基于其内置基线添加,并附带一条提示,说明由于工作区处于离线状态,未向 hub 询问其信任策略,而是改用基线;--fetch-trust=false 则与联网时完全一样,根据其标志注册该条目。通过 aggrega serve 或 aggrega mcp 进行的相同注册行为也相同:同样的拒绝、同样的措辞,否则得到同样的条目。A registry is added offline with no trust policy to pin(离线添加注册表时没有可固定的信任策略) 引用了该拒绝信息。

list 和 remove 只修改或读取本地配置,不受影响。