跳转到正文

ADR 0031: 镜像目录不承载启动配置,所有部署按同一套启动语义解释

本文目录

日期:2026-10-01 · 状态:已接受(取代 ADR 0022 中「存量部署沿用镜像默认值」与 launch_contract 标记的部分,以及 ADR 0013 中命令模式随镜像来源默认的残余)

依据:部署启动配置收口计划。

背景

ADR 0022 让新部署停止读取镜像目录的可编辑默认层(Image Defaults:env、docker 参数、挂载、模型挂载路径、 entrypoint、cmd、命令模式),但为了不改变升级前部署的启动语义,保留了这一层和一个 launch_contract 标记: 无标记的存量部署仍按镜像目录当前值启动。

实际留下的是一套只服务存量的并行语义,且持续产生误导:

  • 部署详情页对每个实例展示「部署时快照 vs 当前镜像默认值」对比表。新部署的快照只有固定基线,而对比拿镜像目录 当前行做基准,只要该行有值就报「已变化」,提示用户「重建时可同步」——重建并不会同步。
  • 内置种子里每个镜像版本的默认层只有 HF_HUB_OFFLINE=1,与三个引擎自己注入的完全重复。
  • entrypoint_display、cmd_display、env、extra_mounts 列在为空时由节点 inspect 回填,使镜像事实与手工配置 混写在同一列,无法分辨来源。
  • 产品尚未发布,没有需要保护的存量部署。

决策

  1. 镜像目录只描述制品:引用、获取地址、引擎与框架版本、架构、厂商、启用与弃用状态、兼容性事实(ADR 0019)。 删除镜像行的 env、docker_args、extra_mounts、model_mount_path、entrypoint_display、cmd_display、 command_mode、run_command、inspect_synced 列,manifest 删除 run_spec 与版本级 command_mode; 旧 manifest 与离线包里的这些键在导入时忽略。
  2. 镜像内置的 ENTRYPOINT/CMD/ENV 是运行事实,不在目录里另存。它们由容器运行时直接使用;需要查看时对节点实时检查, 或读实例的启动事实(运行时观察到的镜像与容器 inspect),不再把 inspect 结果写回目录,节点上报的镜像状态也只带镜像 id。
  3. 所有部署按同一套语义解释:启动配置只来自引擎、所选推理模板档位、放置结果与本次部署的输入。删除 launch_contract 标记与按标记分叉的全部分支;命令模式默认 engine,image-entry 与 manual 只能由部署显式选择。
  4. 部署自定义只有容器覆盖一层(deploy.ContainerOverrides,CONTEXT.md「容器覆盖」):环境变量的设置与删除、 挂载、docker 参数、/dev/shm、模型挂载路径、entrypoint、命令与命令模式。env_unset 删除任何下层(引擎、参数网络、 模板)设置的键;节点侧注入的设备与 dGPU 变量不属于启动 env,不受影响。
  5. 实例不再保存镜像默认值快照。实例期望状态里的解析后启动方案就是它的完整启动配置。

后果

  • 升级到本版本的库里,未标记的部署重建后按新语义启动:非官方镜像原先依赖目录里的 image-entry/manual 或 env/挂载的,需要在部署里显式设置。发布前的演示环境逐个核对重建。
  • 想复用一套非常规启动方式(专用镜像、准备脚本、特定参数),写进用户推理模板档位;一次性的写进容器覆盖。 镜像目录不再是第三个来源。
  • manifest 的 sha256 按解析后的结构计算,删字段后旧 manifest 的校验和不再成立:内置种子已重新计算, 在线发布的目录与离线包需用新版 gpuworks-image-manifest 重新生成。没有 sha256 的旧文件照常导入并忽略已删除的键。
  • 镜像详情不再展示「运行默认值」。选择 image-entry 前想知道镜像入口,在镜像详情里对持有该镜像的节点执行检查: 结果是当场读到的 OCI 配置,只展示不保存;运行过的实例也可以看启动事实。目录里的旧值本来就可能与制品不一致。
  • 各层来源与优先级见 部署启动参数来源。

这篇文档有帮助吗?