自定义工件源 (`AGENTENGINE_IMAGE_SOURCE=custom`)

custom 源将 CLI 二进制下载和开发堆栈图像拉取转发到您自己的托管基础设施，而不是 MongoDB 的 GitHub Releases 和 GHCR。它专为无法访问 ghcr.io 或 github.com 的隔离网络环境（气隙、出口限制）而设计。

作用方式

两个独立的旋钮，每个都是可选的：

阻止	控件	受影响的命令
`release`	CLI 二进制文件下载托管	`agentengine self-update`，每日一次的更新通知
`registry`	开发镜像托管（5 个镜像）	`agentengine dev up`

自定义源仅替换托管 — 镜像存储库名称和标签在构建时保持不变，因此您的镜像可以机械地复制：相同的名称、相同的标签、您的托管。

五个开发堆栈镜像分别是：playground-ui、orchestration-engine、memory-server、runner-base、runner-base-typescript-langgraph。

先决条件

AGENTENGINE_IMAGE_SOURCE=custom 在您的环境中
source.yaml 在 ~/.agentengine/source.yaml （或在 $AGENTENGINE_IMAGE_SOURCE_FILE 中设置的路径上）
您的企业 CA 必须位于操作系统信任存储中 — 没有 --insecure 标志（请参阅安全)

注意

覆盖变量名称是固定的。CLI 会读取 AGENTENGINE_IMAGE_SOURCE 和 AGENTENGINE_IMAGE_SOURCE_FILE。不再读取已弃用的 AP_SOURCE / AP_SOURCE_FILE 名称，设置其中任何一个都会导致命令失败。

无需平台连接。CLI 在本地解析源，因此气隙或出口受限的机器仅需 AGENTENGINE_IMAGE_SOURCE=custom 即可自行配置。请参阅 public-artifacts。

第 1 步 — 获取镜像名称和标签

运行 agentengine version --full 以获取当前 CLI 构建的确切镜像名称和标签：

agentengine version --full

示例输出：

1.4.2 (commit: abc1234)runner-base: ghcr.io/mongodb/agent-engine-client-libraries/runner-base:v1.4.2runner-base-typescript-langgraph: ghcr.io/mongodb/agent-engine-client-libraries/runner-base-typescript-langgraph:v1.4.2playground-ui: ghcr.io/mongodb/agent-engine-client-libraries/playground-ui:v1.4.2orchestrator: ghcr.io/mongodb/agent-engine-client-libraries/orchestration-engine:v1.4.2memory-server: ghcr.io/mongodb/agent-engine-client-libraries/memory-server:v1.4.2

在镜像时，请使用这些准确的名称和标签。在主版本内的所有修补版本中都很稳定；只有版本后缀会变化。

第 2 步：复制图像（如果复制开发堆栈）

docker login ghcr.io                           # read access to MongoDB's GHCRdocker login artifactory.example.com           # write access to your registry
for img in playground-ui orchestration-engine memory-server runner-base runner-base-typescript-langgraph; do  docker pull ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2  docker tag  ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2 artifactory.example.com/acme-docker/$img:v1.4.2  docker push artifactory.example.com/acme-docker/$img:v1.4.2done

对每个新 CLI 版本重复此操作。存储库名称和标签格式是稳定的；只有版本号会发生变化。

第 3 步 — 托管 CLI 二进制文件（如果镜像二进制文件下载）

如果您的网络也阻止了 Github 发布，请将 CLI 二进制文件托管在 HTTPS 服务器上（Artifactory 通用存储库效果很好），并发布一个符合静态清单格式的 manifest.json。

上传每个操作系统/架构组合的二进制文件，然后创建指向它们的文件清单。在 source.yaml 中，清单 URL 变为 release.url。

第 4 步 — 写入 `source.yaml`

放置在 ~/.agentengine/source.yaml，或放置在您在 $AGENTENGINE_IMAGE_SOURCE_FILE 中设置的路径中。

推荐：使用 CLI 生成

agentengine agent source setup      # interactive wizard: asks base/release/registry, validates before writingagentengine agent source template   # writes a commented, ready-to-edit starting point insteadagentengine agent source template --stdout   # print the template instead of writing it

两者都写入标准发现路径（或使用 --force 跳过现有文件的覆盖提示），并在写入前进行自我验证，因此保证结果可以加载。当回答提示比手动编辑 YAML 更容易时，请使用 agentengine agent source setup；当您宁愿自己编辑文件时，请使用 agentengine agent source template — 下面的示例显示了要填写的内容。

完整镜像 — 来自您的托管的二进制文件和镜像

base: publicrelease:  type: static  url: https://artifactory.example.com/acme-generic/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/acme-docker

仅限镜像 — 二进制文件保留在 Github 上

当您的网络允许 github.com 但阻止 ghcr.io 时使用：

base: publicregistry:  prefix: artifactory.example.com/acme-docker

仅限二进制文件 — 镜像保留在 GHCR 上

当您的网络允许 ghcr.io 但阻止 Github 发布下载时使用：

base: publicrelease:  type: static  url: https://nexus.example.com/agentic-cli/manifest.json

Github 风格的发布 API — 本地部署的 Github 企业

当您的基础设施公开了一个具有 GitHub JSON 格式的发布 API 时使用（例如Github 企业版），而不是托管静态清单：

base: publicrelease:  type: github  url: https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releasesregistry:  prefix: registry.example.internal/agentic

与公开发布保持一致

对于镜像公共发布工件的部署：

base: publicrelease:  type: static  url: https://artifactory.example.com/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/agent-engine-mirror

base: public 继承 public 当前解析到的任何内容。这仅应用于您未覆盖的块：固定的 registry.prefix 或 release.url 是您的。固定该块以确保其安全。请参阅 public-artifacts.md。

`source.yaml` 字段引用

字段	必需	说明
`base`	No (default: `public`)	未被覆盖内容的后备来源： `public`
`release.type`	如果存在 `release`，则为是	`static` — 静态 JSON 清单（本文档）；`github` — GitHub 风格的发布 API
`release.url`	如果存在 `release`，则为是	清单（静态）或 API 基础（Github）的完整 HTTPS URL。必须使用 `https://`
`registry.prefix`	如果存在 `registry`，则为是	注册表托管 + 路径，无方案，无标签 (例如：`artifactory.example.com/acme-docker`）

至少需要 release 或 registry 中的一个 — 如果 source.yaml 两者都没有，则等同于基础源，将被拒绝。

$AGENTENGINE_IMAGE_SOURCE_FILE 覆盖 ~/.agentengine/source.yaml 发现路径。设置后，如果文件丢失或不可读，则会产生严重错误，而不是静默回退到主文件。

第 5 步 — 验证

agentengine agent source validate 检查文件，无需先设置 $AGENTENGINE_IMAGE_SOURCE，成功后会打印激活它的确切环境变量：

agentengine agent source validate                          # standard discovery pathagentengine agent source validate ./some/other/source.yaml  # or an explicit path

AGENTENGINE_IMAGE_SOURCE=customAGENTENGINE_IMAGE_SOURCE_FILE=/Users/you/.agentengine/source.yaml

无论文件来自 agentengine agent source setup、agentengine agent source template 还是手动编辑，验证失败都会显示下面“故障排除”中列出的相同固定消息。

然后激活它并确认已解析的路由：

export AGENTENGINE_IMAGE_SOURCE=customagentengine version --full

对于完整镜像，您应该看到：

1.4.2 (commit: abc1234)source: custom  release:  https://artifactory.example.com/acme-generic/agentic-cli/manifest.json (static)  registry: artifactory.example.com/acme-dockerrunner-base: artifactory.example.com/acme-docker/runner-base:v1.4.2runner-base-typescript-langgraph: artifactory.example.com/acme-docker/runner-base-typescript-langgraph:v1.4.2playground-ui: artifactory.example.com/acme-docker/playground-ui:v1.4.2orchestrator: artifactory.example.com/acme-docker/orchestration-engine:v1.4.2memory-server: artifactory.example.com/acme-docker/memory-server:v1.4.2

输出中的图像是 agentengine dev up 传递给 docker pull 的确切字符串。

然后运行 agentengine self-update 以测试二进制更新路径，并运行 agentengine dev up 以确认镜像拉取成功。

静态发布清单格式

CLI 从 release.url 获取此文件，选择最高的 semver 版本，并选择与当前操作系统和架构匹配的资产。没有 latest 字段 — CLI 从 releases 数组中计算最大版本，因此过时的指针永远不会与可用资产不一致。

{  "releases": [    {      "version": "1.4.2",      "assets": [        {          "os": "darwin",          "arch": "arm64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64",          "sha256": "9f2b...e1"        },        {          "os": "linux",          "arch": "amd64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_linux_amd64",          "sha256": "4c7a...bd"        }      ]    }  ]}

字段	类型	说明
`releases`	阵列	每个版本一个条目。CLI 会选择最高的 semver。
`releases[].version`	字符串	语义版本（例如`1.4.2`）
`releases[].assets`	阵列	每个操作系统/架构组合对应一个条目
`assets[].os`	字符串	`darwin`、`linux` 或 `windows`
`assets[].arch`	字符串	`amd64` or `arm64`
`assets[].url`	字符串	二进制文件的完整 HTTPS URL
`assets[].sha256`	字符串	二进制文件的 64 字符十六进制 SHA-256 摘要

CLI 会在解析时验证 sha256 是否为 64 个字符的十六进制 string，并在安装前重新验证下载的二进制文件。

安全性

必须使用 HTTPS，不支持 ``--insecure`` 覆盖。SHA-256 可以验证二进制文件是否与清单匹配，但没有任何加密签名来验证清单本身。通过普通 HTTP，攻击者可以同时重写下载 URL 和哈希，验证仍然会通过。TLS 是唯一的清单完整性 ACID 一致性保证。本地部署的发布服务器必须使用 TLS。

企业 CA。气隙企业通常运行内部证书颁发机构。CLI 使用 Go 的 TLS 堆栈，该堆栈遵循操作系统证书存储。在使用 AGENTENGINE_IMAGE_SOURCE=custom 和内部 HTTPS 托管之前，必须将企业 CA 安装在操作系统信任存储中。没有 --insecure 或 --cacert 标志。针对内部托管的 TLS 验证失败是信任存储问题，而不是 CLI 错误。

在生成的 local-dev 镜像中安装的包属于一个单独的信任存储。请参阅本地 agentengine dev up 中的企业 TLS 检查。

注册表身份验证。CLI 绝不会存储或托管 Docker 凭证。如果您的注册表需要身份验证，请在运行 agentengine dev up 之前运行一次 docker login <registry>。CLI 将镜像引用传递给 Docker，Docker 使用其自己的环境凭证存储。

``source.yaml`` 发现。CLI 仅从 $AGENTENGINE_IMAGE_SOURCE_FILE（如果已设置）或 ~/.agentengine/source.yaml 加载 source.yaml。它绝不会从当前工作目录自动加载——这样做会允许克隆的存储库将自我更新重定向到攻击者控制的托管主机。

故障排除

错误	原因	修复
`AGENTENGINE_IMAGE_SOURCE=custom but no source.yaml found`	两个搜索路径下均无文件	创建 `~/.agentengine/source.yaml` 或设置 `$AGENTENGINE_IMAGE_SOURCE_FILE`
`$AGENTENGINE_IMAGE_SOURCE_FILE points to "..." which does not exist`	`$AGENTENGINE_IMAGE_SOURCE_FILE` 已设置但缺少文件	检查路径；设置环境变量时，该文件必须存在
`source.yaml: release.url must be an https:// URL`	URL 以...开头 `http://`	使用 `https://`；将 TLS 添加到您的服务器
`source.yaml: registry.prefix "..." must not include a scheme`	Prefix 具有 `https://`	删除方案；使用裸机 `host/path`
`source.yaml: registry.prefix "..." must not contain a tag or digest`	前缀包含 `:v1` 后缀	仅使用托管 + 路径（最后一个 `/` 后面没有冒号）
`source.yaml: custom source needs at least one of 'release' or 'registry'`	两个块都不存在	至少添加一个区块
`release manifest: HTTP 404 fetching ...`	URL 错误或文件尚未上传	检查 `release.url` 并确认该文件可访问
`release manifest: no asset for darwin/arm64 in version 1.4.2`	缺少 OS/arch 条目	将缺少的资产条目添加到您的清单中
`release manifest: asset sha256 "xyz" is not a 64-char hex digest`	摘要太短或非十六进制	计算二进制文件的 `sha256sum`，并粘贴完整的 64 字符十六进制字符串
内部托管的 TLS 验证失败	企业 CA 不在操作系统信任存储中	安装您的 CA；没有 `--insecure` 标志
在... 上拉取图像失败 `agentengine dev up`	镜像未同步，或缺少 `docker login`	镜像；首先运行 `docker login <registry>`

自定义工件源 (AGENTENGINE_IMAGE_SOURCE=custom)