跳转到正文

ADR 0022: 部署启动配置由模板与显式选择确定,镜像目录不再提供可编辑默认层

本文目录

日期:2026-09-19 · 状态:已接受;「存量部署沿用镜像默认值」与 launch_contract 标记已被 ADR 0031 取代(按本次部署页设计与实施授权;补充 ADR 0020,取代 ADR 0013 的按镜像来源选择默认命令模式,以及 ADR 0019 中新部署读取镜像运行时默认值的部分)

用户可能直接填写一个 RTX 专用、医学模型专用或私有镜像。专用模型的参数、环境、准备脚本和运行资产应由推理模板表达,用户可覆盖或直接接管命令;不再在镜像目录维护另一份会隐式改写新部署的配置。否则,评估后修改镜像目录,即可使相同部署在首次启动或重建时运行不同命令,违背所见即所得。

新部署的启动配置由引擎字典、所选模板与本次用户输入经现有 Materialize / ResolveLaunch 管道确定,并保存到现有部署字段和选择快照。默认命令模式为 engine;image-entry 和 manual 必须是本次部署的显式选择。更换镜像或切换表单视图不改变该选择,不重新应用镜像目录的 env、挂载或启动命令。自定义镜像无需先登记,兼容性未知只产生提示,已知资源和放置冲突仍需拒绝。

镜像仍是运行制品。引擎版本、框架、架构、获取地址,以及实际 OCI ENTRYPOINT/CMD/ENV 都是镜像事实;本决策没有改变容器运行时如何消费它们。未读取的 OCI 内容必须显示未知,配置环境变量不能冒充包含镜像内置环境的最终进程环境。推理模板保存模型与特定软硬件组合知识;引擎方言和启动适配由各引擎模块持有,例如 SGLang 的日志环境与准备脚本,不在 API、通用部署流程或前端重复实现。

为避免升级修改存量启动语义,在现有选择快照记录启动合同标记,只有新合同停止读取可编辑镜像默认层;无标记的存量部署继续沿用原有语义。标记只说明解释版本,不保存另一份可编辑配置。存量迁移需要独立核对,不能通过补标记改变其启动行为。

代价是新建部署不能继续依赖镜像目录中曾经隐式注入的配置;这类配置必须明确写入模板或本次部署。镜像目录旧字段保留用于存量兼容。保留动态默认合并会让启动结果继续依赖可变外部状态,因此不采用。

后果(2026-09-22 补充)

  • 选择快照类型化:部署的选择快照(deployments.template_snapshot)由 deploy.CatalogSelection 一个类型持有,写入方与六个读取点共用一套字段标签。此前每个读取点各自解码,新增模板字段可以落进五处而漏掉第六处;现在未知键保留在 Extra、已存行重新编码时保持原字节(fixture internal/server/deployment/testdata/catalog_selection_{template,custom_model}.golden)。快照仍是历史记录,不是可重算的配置。
  • 存量快照的 GPU 谓词复查:带 launch_contract 标记的部署按本 ADR 的启动语义解释快照;但快照里的 gpus/unsupported 谓词对所有部署(含无标记的存量行)在每次重调度时都对照当前卡复查,失配记 placement_rejected 并拒绝启动。这是阶段 0 引入并保留的安全属性:标记只解释"启动配置从哪来",不解释"硬件是否还符合模板"。它确实把无标记存量部署从"按旧快照启动"改成了"硬件换过之后拒绝启动",特此记录。

这篇文档有帮助吗?