架构决策记录
ADR 0038: 推理模板声明镜像来源,系统改写规则只作用于系统镜像
本文目录
日期:2026-10-08 · 状态:已接受(补充 ADR 0018 的镜像候选来源;模板镜像的 digest 处理修订 79e97549 的"只接受同 digest 候选")
2026-10-16:决策 5「系统改写规则只作用于系统镜像」由 ADR 0048 取代:来源规则对所有镜像(含模板声明的来源)按仓库或前缀生效;模板
image_sources仍是镜像的等价副本,排在目录来源之前。
背景
平台为镜像准备了一套"系统镜像"机制:镜像目录行的 registry_sources、image_registry_rewrites 里的 quay / SWR / registry.zstack.ai
改写规则、pullref 产出的候选顺序。它们的前提是镜像能解析到镜像目录里的一行,也就是 gpuworks 自己发布、自己维护的镜像。
推理模板的镜像多半不在镜像目录里(ADR 0018 背景已指出,候选因此退化成 canonical 一条)。第三方作者发布的模板,如钉 digest 的
ghcr.io/…@sha256:…,常常在国内网络拉不动,作者手上却有现成的出路:一份逐字节相同的公开副本、一个 ghcr 镜像站。此前这类地址只能靠:
- 全局改写规则:对所有部署生效,规则表里也写不下"某个模板的某个镜像";
- 把镜像登记进镜像目录:把一个模板的事实变成平台目录的事实,还要接受目录的"带 tag、拒 digest"约束;
- 部署时手写镜像覆盖:部署被记为偏离模板,且每次都要重填。
同时,agent 对钉 digest 的镜像只接受同 digest 的候选(79e97549)。这等于节点替服务端判断来源内容:作者声明的来源若是 tag 引用,或是另一个 digest 下的副本,节点会在拉取前就拒绝它。
决策
- 模板可以为自己的镜像声明多个来源。 spec 增加
image_sources: [ref, …],与weights.sources同构:作者按偏好顺序列出,部署者在部署页已有的 「获取 → 公网下载」镜像来源选择器里选一个。image仍必填,仍是模板的身份和"是否偏离模板"的比较基准。 - 模板写什么就接受什么。 只做语法校验:去首尾空白后非空、不含空白、不含
://、不超过 512 个字符、不重复(按 registry 解析后的引用比较,见pullref.RefKey)。不要求来源和image钉同一个 digest,image钉了 digest 时来源也可以是 tag;是否可达不检查。与image相同的项在规范化时丢弃,因为image本来就是候选。 - 候选顺序:模板来源(按声明顺序)→ 镜像目录行的
registry_sources(仅当镜像解析得到目录行)→image自身,去重;归档地址仍在最后。ImagePullPlanFor的默认链(没有显式选择时)按同一顺序:模板来源在前,其后是目录链(有目录行)或image本身。显式选择仍然替换整条链。部署页的候选与默认链都由pullref.DeclaredFirst拼出(拉取候选顺序仍只有pullref一处实现)。 - 只有部署用的镜像就是 spec 的
image时,才有模板来源。 请求覆盖了镜像,就是另一个镜像,模板的来源既不展示、不接受,快照里也不记。 - 系统改写规则只作用于系统镜像。
image_registry_rewrites、目录registry_sources和pullref的出厂规则继续只对解析得到目录行的镜像生效; 模板来源原样使用,不被改写、不被重排。节点自己的network.rewrites是节点配置,仍然叠加在最终候选上。 - 选择模板来源不算偏离模板。
image_pull不参与偏离判断;偏离只来自请求对 engine、scenario、image、spec、env、参数的修改。 - 服务端候选是权威,节点不再核对内容。 对钉 digest 的
spec.Image,agent 接受服务端给出的任一候选(含节点网络规则改写后的地址): 已在本地的候选直接算数,拉成功的候选直接作为启动引用,不docker tag(运行时拒绝 digest 作为 tag 目标)。tag 引用的spec.Image保持原行为。 候选是否是"同一个镜像"是作者和部署者的责任,节点不二次判断。 - 持久化:
inference_specs.image_sources(text,JSON[]string,空为无;迁移 133);部署侧在目录选择快照里记image_sources(仅当镜像等于 spec 的image),重启时按快照重建候选。旧快照没有该键,读作无来源。
取舍
- 放弃了"平台保证来源内容与
image一致"。校验 digest 一致需要平台去拉取、比对每个来源,且不能覆盖 tag 引用的来源;而一个来源指向别的内容, 作者可以把它写进image本身——这是模板作者的责任,和weights.sources不核对各来源权重字节相同的取舍。 - "已缓存"事实仍只按
image的规范名查询。钉 digest 的镜像从别的来源拉下后只以那个来源的名字存在于节点上,部署页的"本地已有"不会命中它; 再次部署时只要服务端给出的候选里含那个来源,agent 就会在本地检查里发现该副本、不会重拉,但部署页显示的缓存状态与调度的磁盘估算不会反映这一点。 - 模板来源只扩展公网 Registry 候选,不改变节点间同步和归档下载:这两条路依赖镜像目录行,模板镜像没有目录行时就没有这些候选。
- 与
image相同的来源被丢弃而不是拒绝,作者因此无法通过重复写image把它排到别的来源之前;image总是排在声明的来源之后。
后果
- 模板作者可以在包里声明国内可达的副本,用户在部署页选一个即可,不必改全局规则,也不用登记镜像目录。
- agent 不再因 digest 与 spec 不一致而在拉取前拒绝候选;旧版 agent 在升级前仍保持原行为(候选 digest 不同会被跳过)。
- 模板 DTO(
GET /inference-templates*)每个 spec 多一个可选的image_sources;evaluate 的acquisition.image.providers把模板来源排在最前, 其reason为image source declared by the inference template。 - 导出/克隆模板时来源随 spec 保留;部署页不需要新控件。
这篇文档有帮助吗?