OCI Image Spec 怎样理解镜像配置与层的关系
来源:17golang原创
时间:2026-11-20 09:56:54 134浏览 收藏
OCI Image Spec 里,镜像配置和镜像层不是同一种东西:config 描述镜像整体的创建信息、运行参数、历史和根文件系统摘要;layers 描述按顺序叠加的文件系统变更。manifest 只是把这些对象用 descriptor 和 digest 连接起来。把它们分开看,很多“改了配置却重新上传层”或“层摘要对不上”的问题就容易定位。
官方地址:https://github.com/opencontainers/image-spec
本文只讨论 OCI 对象之间的静态关系,不把某个镜像仓库、构建器或运行时的扩展行为当成规范必然行为。
先把三个对象放回同一张图
一份面向单个平台的 OCI image manifest 至少要回答三件事:使用哪个 schema,配置对象在哪里,以及文件系统层按什么顺序排列。manifest 自己通常不承载环境变量、入口参数或文件内容,而是通过 descriptor 引用对应对象。
config 是镜像整体的 JSON 配置。它可以包含创建时间、作者、环境变量、入口点、默认参数、工作目录、网络和卷等执行相关信息,也会保存历史信息与 rootfs.diff_ids。层则是以 tar 变化集表达的新增、修改和删除,应用后才组成容器看到的根文件系统。

因此,读取 manifest 时可以先把字段分成两组:config 指向运行元数据,layers 指向文件系统内容。两者都是 descriptor,但 descriptor 的存在不代表它们可以互相替代。
config 和 layer 为什么各有一套摘要
最容易混淆的是 rootfs.diff_ids 与 manifest 中 layer descriptor 的 digest。规范把 DiffID 定义为未压缩 tar 归档的摘要;而 manifest 中常见的 layer digest 通常用于引用压缩或未压缩的内容。它们的输入字节不同,不能只看字符串是否相似。
下面是一个缩小后的关系示例。它是严格 JSON,不能在里面插入注释;关键字段的含义放在代码块之后说明。
{
"config": {
"digest": "sha256:config-object",
"mediaType": "application/vnd.oci.image.config.v1+json"
},
"layers": [
{"digest": "sha256:compressed-layer-a", "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"},
{"digest": "sha256:compressed-layer-b", "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"}
]
}
这里的 config.digest 指向配置 JSON;layers 保留从底到顶的应用顺序。配置对象中的 rootfs.diff_ids 应与对应层的未压缩变化集顺序一致。压缩层的传输摘要变化,不等于文件系统变化本身发生了变化。
还有一个重要边界:配置 JSON 被修改后,配置摘要会改变,进而使镜像身份发生变化;这不表示每个文件层都必须重新生成。反过来,新增一层会同时影响层列表及根文件系统摘要关系,不能只改 config 的环境变量来“伪造”文件变化。
用最小检查顺序判断问题出在哪一层
遇到镜像描述不符合预期时,可以按 manifest、config、layer 三个入口逐层看,而不是直接展开所有 blob。
- 先看 mediaType。确认当前内容是 OCI image manifest、config JSON 还是 layer blob,避免把 descriptor 当成目标对象。
- 再看 config.digest。取回配置 JSON 后,关注运行参数、history 和
rootfs.diff_ids的数量与顺序。 - 最后对 layers。按 manifest 顺序读取每个 descriptor 的 mediaType、size 和 digest;需要比较文件系统时,再比较未压缩变化集对应的 DiffID。
package main
import "fmt"
type Descriptor struct {
MediaType string `json:"mediaType"`
Digest string `json:"digest"`
Size int64 `json:"size"`
}
func printOrder(config Descriptor, layers []Descriptor) {
// 先打印配置对象,再按 manifest 顺序打印层,避免把传输顺序当成文件层顺序。
fmt.Println("config:", config.MediaType, config.Digest)
for index, layer := range layers {
// index 只表示静态层次位置,不代表运行时一定执行了某个命令。
fmt.Printf("layer[%d]: %s %s %d bytes\n", index, layer.MediaType, layer.Digest, layer.Size)
}
}
这个小函数只展示 descriptor 的阅读顺序,不负责下载、解压或验证摘要。真实工具还要处理未知 mediaType、传输错误和超大层,不能把打印成功当成内容完整。
多平台镜像为什么还要多一层 index
当一个标签要覆盖多个操作系统和 CPU 架构时,OCI 使用 image index 作为更高层的入口。index 的 manifests 列表为每个平台提供 descriptor,并可携带 os、architecture 和 variant 等 platform 信息。每个匹配项再指向一个具体平台的 image manifest。

所以要区分两种问题:用户拿到哪一个平台 manifest,属于 index 的选择;这个 manifest 里有哪些运行参数和文件系统层,属于具体镜像的描述。index 还可以嵌套 index,遇到未知 mediaType 时实现不应因为不认识就把整个镜像当成损坏。
发布前用一张表避免混淆
| 看到的字段 | 应该回答的问题 | 不要得出的结论 |
|---|---|---|
| manifest.config | 配置 JSON 的 descriptor 在哪里 | 它不是配置内容本身 |
| config.rootfs.diff_ids | 未压缩层变化集的摘要顺序是什么 | 它不等于所有传输层 digest |
| manifest.layers | 按什么顺序引用文件系统层 | 它不保存环境变量和入口参数 |
| image index.manifests | 哪些平台 manifest 可以被选择 | 它不是某个平台的完整根文件系统 |
最后可以记成一句话:manifest 负责连线,config 负责描述镜像整体和运行参数,layers 负责表达文件系统变化,image index 负责在多个平台 manifest 之间做选择。需要定位摘要问题时,先确认对象类型和压缩状态,再比较顺序,不要只凭字段名称猜测。
为什么 config 改了镜像 ID 也会变?因为配置 JSON 参与镜像身份计算,修改它会改变配置摘要,即使文件层没有变化。
layer digest 和 DiffID 必须相同吗?不必须。前者常用于内容引用,后者明确针对未压缩 tar 变化集,摘要输入可以不同。
image index 能替代 image manifest 吗?不能简单替代。index 解决多平台入口,具体平台的 manifest 仍负责引用 config 与 layers。
规范资料:https://github.com/opencontainers/image-spec/blob/main/manifest.md
配置说明:https://github.com/opencontainers/image-spec/blob/main/config.md
多平台索引:https://github.com/opencontainers/image-spec/blob/main/image-index.md
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
314 收藏
-
科技周边 · 业界新闻 | 33分钟前 | 依赖管理 · CI/CD · 供应链安全 · Dockerfile GitHub Actions 软件供应链 依赖固定 OpenSSF Scorecard Pinned-Dependencies259 收藏
-
160 收藏
-
249 收藏
-
科技周边 · 业界新闻 | 44分钟前 | 云原生 · 业界新闻 · WIT WASI HTTP WebAssembly Component Model wasi:http/service wasi:http/middleware342 收藏
-
423 收藏
-
科技周边 · 业界新闻 | 48分钟前 | javascript · 可观测性 · 业界新闻 · Node.js ESM CommonJS OpenTelemetry JavaScript SDK 3.0 可观测性迁移177 收藏
-
科技周边 · 业界新闻 | 53分钟前 | devops · CI/CD · gitHub actions · 持续集成 GitHub Actions RHEL 9 RHEL 10 larger runners 托管镜像466 收藏
-
223 收藏
-
科技周边 · 业界新闻 | 19小时前 | devops · CI/CD · gitHub actions · 供应链安全 · workflow GitHub Actions 软件供应链 2026安全路线图 CI/CD安全181 收藏
-
354 收藏
-
411 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习