OCI 镜像标签和摘要怎样选择部署引用

需要可追踪、可重复部署的正式发布，优先用摘要固定镜像内容，并在发布记录中保留便于阅读的标签。开发环境如果明确需要跟随某个通道，可以使用标签，但要接受它可能被重新指向。标签负责命名，摘要负责定位具体内容。

官方资料入口：https://kubernetes.io/docs/concepts/containers/images/。本文解释现有 OCI 镜像引用机制及部署选择，不把它包装成某个新版本刚发布的能力。

部署引用改变的是什么

假设报表服务已经通过测试，准备从测试环境推广到生产环境。若清单写的是 report:stable，部署入口保留了一个名称；若写成 report@sha256:…，它固定的是一个内容对象。把引用改为摘要，改变的是发布时允许解析到哪些内容，并不要求修改应用业务代码。

不要把“带版本号的标签”直接当成不可变对象。v2.4.0 看起来稳定，但是否允许覆盖仍与仓库策略有关。摘要的内容寻址语义与团队给标签取什么名字无关。

标签与摘要为何承担不同职责

OCI Distribution 规范把标签定义为指向清单的人类可读指针，摘要则是基于内容计算的标识。一个清单可以有多个标签，所以“测试通过的版本号”“发布通道名”和“具体交付物”可以形成不同层次的记录。

这给发布设计带来一个实际好处：团队仍可用标签描述业务版本，同时在部署清单中固定摘要。发布记录可以同时保存代码提交、构建编号、标签、仓库路径与摘要；回滚时选择原先记录的交付物，而不是假定某个旧标签从未变化。

摘要也不是持久保存服务。仓库中对象被删除、访问权限改变或网络不可达，都可能导致新节点无法获取镜像。固定引用应与仓库保留策略配合，而不是用摘要替代制品保存制度。

旧清单需要注意拉取策略与平台

在 Kubernetes 中，imagePullPolicy 影响容器启动时如何拉取镜像。Always 不意味着所有层每次都重新下载；运行时仍可使用已有层。它也不能让一个可移动的标签获得摘要的固定内容语义。

对象创建时确定的默认拉取策略，不会仅因后续修改标签或摘要就自动重算。迁移已有清单时，应显式检查原来的字段。修改远端标签也不会让已经运行的容器自己换成另一份镜像。

多平台镜像还多一层对象关系：OCI image index 可以引用多个平台清单，描述符通过操作系统、CPU 架构等信息区分目标平台。记录摘要时，要知道它标识的是索引还是单个平台的 manifest。

混合架构集群通常需要保留适合目标平台集合的索引引用。固定索引并不表示 amd64 与 arm64 节点会执行相同字节的二进制；它固定的是包含各平台描述符的索引。若固定单平台清单，则必须确保调度目标与其平台要求一致。

把发布记录迁移到固定摘要

先从实际发布产物记录中取得完整摘要，明确它对应索引还是单平台清单，再把同一交付物推广到下一环境。不要在生产发布时重新构建一份“同名版本”后仍宣称与测试产物相同。

下面是容器字段片段，展示 Kubernetes 同时保留标签与摘要的写法。示例域名和全 a 摘要仅用于说明格式，必须替换为自己的真实仓库与实际交付物摘要；它不是完整 Deployment，也不是可拉取镜像。

# 结构示例：域名与全 a 摘要都是占位值，不能直接部署
# 合并到现有工作负载的对应容器定义中
name: report-service
image: registry.example.com/team/report:v2.4.0@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
# 显式保留拉取策略，避免依赖旧对象上的默认值
imagePullPolicy: IfNotPresent

同时写标签与摘要时，Kubernetes 拉取使用摘要。标签可辅助阅读，但不能表达“标签与摘要必须实时相互匹配”的额外条件。若两个字段已经不再对应，清单仍容易误导维护者，因此发布系统应统一生成这组记录。

推广后保留原摘要作为回滚目标，同时保存该版本需要的配置。镜像回滚不自动恢复数据库数据或外部服务状态，跨版本兼容方案仍要由应用发布流程负责。

上线前应确认的最小信息

最低限度应确认三件事：引用的仓库和摘要来自本次实际产物；它覆盖目标平台；工作负载中的拉取策略已经明确。本文未执行镜像拉取或部署，表格是发布前的选择依据，不是集群运行结果。

使用摘要后，修复版本会自动更新吗？

不会。新内容需要新的摘要，并通过新的发布变更更新清单。固定内容的价值就在于更新必须明确发生。

只禁止覆盖版本标签够不够？

禁止覆盖能改善标签管理，但仍应保存实际摘要以关联交付物。仓库规则与内容标识解决的是不同问题。

能把本地镜像 ID 直接当成部署摘要吗？

不要只凭某个界面上出现的 sha256 字符串判断。应取得发布仓库对应 manifest 或 index 的摘要，确认对象类型与仓库路径，避免把配置对象等其他内容的摘要填入部署引用。

依据：OCI Distribution 规范、OCI Image Index 规范及Kubernetes 镜像文档。