OCI 镜像规范变更怎样影响镜像工具链

OCI 镜像规范变化不会自动要求团队把所有镜像重新构建一遍。真正需要调整的是工具链对镜像元数据的理解：构建器要能生成合规的 manifest 或 image index，仓库和复制器要保留未知但合法的媒体类型，运行时则要明确哪些字段会参与启动。当前公开的 OCI Image Spec 最新标签是 v1.1.1，而 v1.2.0 仍处在没有计划日期的 milestone 中，因此更稳妥的做法是先按 v1.x 的兼容边界做审计，再决定是否升级具体工具。

OCI Image Spec 官方地址：https://github.com/opencontainers/image-spec

OCI 规范文档地址：https://specs.opencontainers.org/image-spec/

先把三套规范的职责分开

一个常见误区是把“镜像规范升级”理解成运行时行为整体改变。OCI Image Spec 主要描述镜像如何组织：manifest 记录配置和层，image index 关联不同平台的 manifest，descriptor 通过 mediaType、digest 和 size 指向内容，config 则携带启动参数、环境变量等信息。OCI Runtime Spec 关注解包后的 filesystem bundle 如何运行，Distribution Spec 关注镜像如何通过仓库 API 推送和拉取。

这三个边界决定了排查顺序：如果构建产物的 JSON 结构不对，先看 Image Spec；如果镜像能拉取但不能启动，再看 config 到 runtime bundle 的转换；如果同一 digest 在不同仓库复制时丢字段，则要同时检查 Distribution 实现和复制工具。

v1.1.1 之后要重点检查哪些字段

版本号本身不是迁移清单，字段语义才是。manifest 的 schemaVersion 在当前规范中仍要求为 2；config 指向容器配置，layers 按文件系统叠加顺序排列。多平台镜像还会通过 image index 选择目标平台的 manifest。构建器或仓库如果只按“自己认识的字段”重写 JSON，就可能在复制 artifact 或附加元数据时丢失信息。

下面的最小片段只用于说明字段关系，不代表一个可直接发布的完整镜像。artifactType 用来标识非传统容器镜像的内容类型，subject 表示与另一份 manifest 的弱关联；复制器不能因为这两个字段不是旧版本常见字段就直接删除。

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.example.sbom.v1",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:...",
    "size": 2
  },
  "layers": [],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "digest": "sha256:...",
    "size": 1234
  }
}

工程上至少要做三件事：解析器区分必需字段和可扩展字段；复制逻辑保留未知 mediaType 的 descriptor；测试样例同时覆盖普通镜像、跨平台 index 和带 subject 的 artifact。不要把“当前运行时暂时用不到”误写成“可以在仓库层丢弃”。

构建、仓库和运行时的兼容重点不同

在构建侧，重点是产物声明是否准确。层的 mediaType、config 的 mediaType、artifactType 和 index 中的平台信息都应保持一致；如果生成 zstd 层，要确认下游实现是否支持，而不能只看构建器本身能否压缩。

在仓库与复制侧，OCI manifest 要求实现存储或复制时遇到未知 mediaType 不应直接报错。这个规则不等于“所有工具都必须理解并执行这种内容”，而是要求它们能够把合法 descriptor 原样保存或转运。非分发层仍可能需要支持历史镜像的下载，但规范已不建议继续生成新的 non-distributable layer。

在运行时，真正需要消费的是可启动镜像的 config、rootfs 层和平台选择结果。对 artifact 而言，运行时可能根本不需要启动它；因此不能把所有 OCI manifest 都当成可运行容器，也不能因为一个 artifact 不能启动就判定仓库对象损坏。

把规范变化落成一张迁移清单

升级顺序建议从“保留和转运”开始，再处理“解析和执行”。前者通常能兼容更多新对象，后者则必须明确能力边界。若团队暂时无法支持新 mediaType，可以先保证仓库复制不破坏对象，并在拉取或运行阶段给出可定位的能力错误。

常见问题

OCI Image Spec 升级后必须重建旧镜像吗？

通常不需要。先确认旧镜像的 manifest、config、层媒体类型和平台信息仍符合目标工具的支持范围；只有在构建器输出不再满足目标仓库或运行时契约时，才需要重新构建或转换。

仓库遇到未知 mediaType 应该拒绝吗？

对于存储或复制路径，当前规范明确要求不要因为未知 mediaType 就报错。是否能扫描、解包或运行是另一个能力判断，应该在对应阶段明确提示，而不是在仓库层静默删除对象。

归根结底，OCI 规范变化带来的工作不是追着版本号改代码，而是把“字段能否保留”“对象能否转运”和“内容能否执行”拆成三类测试。这样即使 v1.x 继续扩展，构建器、仓库和运行时也能分别演进，问题会更容易定位。