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

环境变量

aggrega CLI 读取一组固定的、以 AGGREGA_ 为前缀的环境变量。每个变量都会在运行时覆盖 .aggrega-config.yaml 中对应的设置——这一层由 CI 作业或注入密钥的编排器控制,无需编辑受版本跟踪的文件——而命令行标志仍然优先于其他所有设置。

优先级

环境变量位于已提交的配置文件之上(即流水线或注入密钥的编排器无需编辑受跟踪文件即可应用的运行时覆盖),并位于命令行标志之下,因此在命令行上显式输入的值绝不会被所处环境静默覆盖。配置给出了完整的优先级阶梯以及其下各配置文件的分层方式。

未设置(或为空)的变量会回落到下一层:它绝不会用空值覆盖已配置的值。要查看当前生效的配置以及每项设置由哪一层决定,请运行 aggrega config show --origin。

命名

变量名由 AGGREGA_ 加上转换为大写蛇形命名的配置路径组成(点号变为下划线):signing.fulcio_url 变为 AGGREGA_SIGNING_FULCIO_URL。为便于使用,有一个名称经过了缩短:workspace.catalog_dirs 绑定到 AGGREGA_CATALOG_DIRS,与 PATH 相对应。

按注册表的设置(registries[].*)没有对应的环境变量:由按主机划分的策略块组成的列表无法用单个变量表达,而且注册表的信任和签名策略属于提交的配置,而非环境中的覆盖。情境性、一次性和位置性的标志(--dry-run、--trace、--detail、--output、--skip-verify、--release、--entity,以及 lint --allow-*/--no-allow-* 系列)同样没有环境变量,因为它们是针对单次运行的决定。

基于配置的设置

变量配置路径说明
AGGREGA_DEFAULT_REGISTRYdefault_registry目标/注册表主机(默认为 hub.aggrega.ai)。写法与文件中 default_registry 的写法相同(参见注册表主机的写法),不符合该写法的值会在配置解析时被拒绝,并指明此变量。
AGGREGA_OFFLINEoffline布尔值。禁止所有网络出站:每个本会获取、拉取、取得、推送、签名或联系注册表的命令都会明确报错拒绝,而不是发起连接;构建只使用本机已有的内容——其锁文件、缓存和本地目录(catalog)目录,--auto-pull 会从这些本地目录填充锁文件中的目录实体,而不访问注册表(其 chart 需从远程源获取的 Recipe 在离线时仍会中止)。此时发现过程读取本地索引——弃用提示来自已构建的索引,而不是实时探测,并且会跳过远程注册表目录解析层级;无法识别的命令所打印的插件提示,无论此设置如何,都只读取本地索引。对已缓存或已固定内容的验证仍会运行——离线禁止的是获取,而不是本地检查。--offline 是其上一层的标志,作用于两个方向:它为单次运行设定该状态,而 --offline=false 会在此变量或配置文件已启用离线时,为单次运行允许网络访问。
AGGREGA_AUTO_PULLauto_pull布尔值。在构建时自动获取缺失的依赖。
AGGREGA_ARTIFACT_CACHE_DIRartifact_cache_dir磁盘内容缓存目录,相对于工作区根目录书写,因此无论命令在何处运行,它都指向同一个目录。绝对路径值会被拒绝,指向工作区根目录本身的值同样会被拒绝——请为缓存指定单独的子目录。
AGGREGA_CATALOG_DIRSworkspace.catalog_dirs以操作系统路径列表分隔符分隔(Unix 上为 :)。请提供绝对路径。替换已配置的列表;在 workspace.releases 下拥有自己列表的 Release 保留该列表。
AGGREGA_SIGNING_FULCIO_URLsigning.fulcio_url无密钥签名的 Fulcio CA URL。
AGGREGA_SIGNING_REKOR_URLsigning.rekor_url无密钥签名的 Rekor 透明日志 URL。
AGGREGA_SIGNING_TIMESTAMP_URLsigning.timestamp_url无密钥签名的 RFC3161 时间戳机构 URL。
AGGREGA_SIGNING_KEY_PATHsigning.key_path用于有密钥签名的本地 ECDSA P-256 密钥 PEM 文件路径。仅为路径指针——绝不是密钥内容本身。
AGGREGA_SIGNING_REQUIREDsigning.required布尔值。要求在发布和使用 signing.kinds 所涵盖的种类时必须有签名。它只会开启该要求,从不关闭:设置了它的配置文件会让它保持开启。
AGGREGA_SIGNING_KINDSsigning.kinds以操作系统路径列表分隔符分隔(Unix 上为 :),每个条目是按其 kind: 写法书写的一个种类,或 all。它只会扩大该要求所涵盖的种类,从不缩小;不是可签名种类的值会被拒绝,并指出此变量。
AGGREGA_SKIP_SIGNATURE_VERIFICATIONskip_signature_verification布尔值。全局禁用签名验证——会明确提示:每次拉取都会记录一条警告。
AGGREGA_WORKSPACE_ROOT(与 --workspace-root 对应)绝对路径形式的工作区根目录,跳过发现过程——作用于每个命令,以及每个发往 aggrega mcp 且未指定自身工作区的请求。不是配置字段;设置了标志时以标志为准。设为空值时视为未设置——但有一个例外:通过标准输入输出运行、带有 AGGREGA_BUNDLE_VERSION 且未给出 --workspace-root 的 aggrega mcp,即桌面套件在其 Workspace folder 设置为空时的启动方式,此时它会以指明该设置的拒绝信息回应每个未指定自身工作区的调用。当它指向的文件夹不存在时,每个读取工作区的命令都会在执行任何其他操作之前拒绝,aggrega serve 和 aggrega mcp 监听器会拒绝启动,而通过标准输入输出运行的 aggrega mcp 仍会照常启动,并以该拒绝信息回应每个在该工作区中执行操作的调用——每条拒绝信息都会指明此变量以及设置它的桌面应用 Workspace folder 设置,并按原样引用给定的值。
AGGREGA_BUNDLE_VERSION(由桌面套件设置)启动 aggrega mcp 的桌面套件版本,由套件设置在服务器的环境中。不是配置字段。服务器在启动时读取一次,并在不带参数调用 describe-capabilities 时将其与自身版本一同报告,若两者来自不同的发行版本则予以说明;版本不同不会导致任何拒绝。它的存在也标志着由套件启动,因此与它同时出现的空 AGGREGA_WORKSPACE_ROOT 会被拒绝,而不是视为未设置,如上一行所述。设为空值时视为未设置。

AGGREGA_CONFIG 指向一个显式指定的全局配置文件,在项目自身的文件之下加载;它选择应用哪个文件,而不是覆盖某个单独设置。未设置时,该层会从平台的默认位置自动加载——在 Windows 上为 APPDATA 环境变量所指目录中的 aggrega\config.yaml,在其他平台上为 XDG_CONFIG_HOME 所指目录中的 aggrega/config.yaml,并回退到 ~/.config/aggrega/config.yaml。参见配置。

本机自身文件的位置

全局配置文件和本机范围的缓存位于各平台存放用户自身文件的位置,因此 aggrega 也会读取指明这些位置的变量。它们都不是 AGGREGA_ 变量,也都不覆盖任何设置:每个变量只说明在没有其他指定时到哪里查找文件。

变量读取平台所定位的内容
APPDATAWindows全局配置文件,位于 APPDATA 所指目录中的 aggrega\config.yaml。
LOCALAPPDATAWindows本机范围的缓存,位于 LOCALAPPDATA 所指目录中的 aggrega\cache 下。
XDG_CONFIG_HOME,其次 HOMELinux、macOS 及其他 Unix 系统全局配置文件,位于 XDG_CONFIG_HOME 所指目录中的 aggrega/config.yaml;未设置 XDG_CONFIG_HOME 时位于 ~/.config/aggrega/config.yaml。
XDG_CACHE_HOME,其次 HOMELinux 及其他 Unix 系统本机范围的缓存,位于 XDG_CACHE_HOME 所指目录中的 aggrega 目录下;未设置 XDG_CACHE_HOME 时位于 ~/.cache/aggrega 下。若 XDG_CACHE_HOME 不是绝对路径,则不放置任何缓存,编译后的插件仅在本次运行期间保留。
HOMEmacOS本机范围的缓存,位于 ~/Library/Caches/aggrega 下。

AGGREGA_CONFIG 或 --config 在所有平台上直接指定全局文件,且优先于这些变量。项目自身的缓存不由其中任何变量定位:它们位于项目内部的 artifact_cache_dir 下。aggrega config init 会说明在其运行的机器上全局文件和本机范围缓存所在的位置。

布尔值

布尔变量接受 true、false、1 或 0(不区分大小写)。任何其他非空值都会明确报错,而不是静默猜测——与 YAML 不同,不接受 yes/no/on/off。

密钥

密钥通过环境变量或标志提供,绝不作为配置字段。

变量用途优先级
AGGREGA_IDENTITY_TOKEN无密钥签名的 OIDC 身份令牌。--identity-token 标志 > AGGREGA_IDENTITY_TOKEN > 环境中的 GitHub Actions OIDC > SIGSTORE_ID_TOKEN。
AGGREGA_REGISTRY_PASSWORD用于非交互式 aggrega login 的注册表密码。--password-stdin > AGGREGA_REGISTRY_PASSWORD > 交互式提示。

SIGSTORE_ID_TOKEN 作为 sigstore 生态互操作的身份令牌别名被接受,优先级低于 AGGREGA_IDENTITY_TOKEN 和环境中的 GitHub Actions 端点。更广泛的 sigstore 工具本就会设置这个变量。

同一套身份解析服务于全部三个签名命令:aggrega push --sign、aggrega sign 和 aggrega deprecate。在交互式终端中,每个命令无需任何标志,通过浏览器流程获取短期令牌。在 GitHub Actions 上,每个命令自动从运行器的环境端点签发新的工作流 OIDC 令牌,因此无需导出令牌。其他任何非交互式运行既没有终端,也没有环境端点,因此必须显式提供令牌(导出 AGGREGA_IDENTITY_TOKEN,或传入 --identity-token)。若未提供令牌、没有环境端点且没有终端,无密钥签名会被拒绝,而不是一直挂起。

CI 指南(GitHub Actions)

在 GitHub Actions 上,CLI 会检测运行器的环境 OIDC 端点,并为每次签名自动签发新的工作流令牌。授予作业签发令牌的权限,即可在不导出令牌的情况下签名:

permissions:
id-token: write # allow the job to mint a workflow OIDC token
# ...
- run: aggrega push <entity> --sign

aggrega sign 和 aggrega deprecate 同样如此。若要固定某个特定身份而非自动签发的身份,请显式导出 AGGREGA_IDENTITY_TOKEN;显式令牌(或 --identity-token)始终优先于环境端点:

- run: |
AGGREGA_IDENTITY_TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r .value)
export AGGREGA_IDENTITY_TOKEN
aggrega push <entity> --sign

非 GitHub Actions 的 CI 没有环境端点:请从该提供方的 OIDC 机制导出 AGGREGA_IDENTITY_TOKEN,或传入 --identity-token。

对于交互式批处理,对应的方式是 aggrega auth token,它运行一次浏览器 OIDC 流程,并将身份令牌输出到 stdout,以便以同样方式导出:

Terminal window
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)

参见 aggrega-auth.md。两种方式都能让一批 aggrega sign 调用复用同一个身份,而无需为每个制品往返浏览器。

优先使用 --password-stdin 而非 AGGREGA_REGISTRY_PASSWORD。 环境变量可被子进程读取,并可能在 shell 中留存;stdin 是传递密码更安全的途径。该环境变量是为方便 CI 而提供的。

另请参阅