镜像构建与分发：从概念到可验证实践
0. 元信息
- 主题路径：
docs/topics/docker-basics/subtopics/image-build-and-distribution/README.md - 主分类：工程技术
- 辅助分类：安全与可靠性
- 适合对象：完成 Linux 基础并按父主题路线学习的开发者
- 建议周期：5～8 天，每天 1.5～2 小时
- 前置知识：Linux shell、文件权限与基础网络
- 最终目标：能独立完成并解释 Dockerfile、layer、BuildKit、registry、save/load、buildx 与多平台 manifest 的实验，留下配置、命令和输出证据
1. 学习路线
概念与对象 → 最小正常实验 → inspect/日志验证 → 边界与失败实验 → 自动化配置 → 交付说明
2. 阶段周数分配
精简子主题不固定周数。按概念、正常路径、失败路径、综合实验四段推进，共 5～8 天。
3. 九阶段表
| 阶段 | 核心知识 | 实践产出 | 可观察学会标准 |
|---|---|---|---|
| 1 | 术语与对象边界 | 对象关系图 | 不混淆声明、制品与运行状态 |
| 2 | 默认行为 | 最小正常实验 | 能从空环境重现 |
| 3 | 配置语法 | 可版本化配置 | config/inspect 与预期一致 |
| 4 | 生命周期 | 状态变化记录 | 能解释 create/start/stop/remove 影响 |
| 5 | 隔离与依赖 | 拓扑或 mount 图 | 能指出宿主与容器边界 |
| 6 | 错误路径 | 至少四类故障 | 结论指向日志、事件或状态证据 |
| 7 | 安全与资源 | 最小权限配置 | 默认权限和 limit 有解释 |
| 8 | 可重复性 | 清理后重建记录 | 第三方按 README 可重现 |
| 9 | 综合实验 | 可运行交付物 | 能演示、排错、恢复与清理 |
4. 第一周任务
精简子主题省略逐日表。每天只引入一个变量；先跑正常路径，再做四类失败实验。
5. 阶段通用验收
采用父主题 §5；本页额外要求保存版本、完整配置、关键输出和清理命令。
6. 最终验收
完成一份可运行配置、至少四个失败案例、一次清理后重建，并用 10 分钟解释关键边界。
7. 综合项目
把本页产出合入父主题 Compose Web 应用。单独交付时，提供最小 demo、README、测试记录与 notes/retrospective.md。
本主题贡献
镜像构建与分发这条链路的核心矛盾是：layer 缓存、BuildKit secret mount、SBOM、cosign 签名、multi-platform manifest 各自独立时很轻量，串起来一旦断点就难追溯。本子主题专门盯住”声明 → 制品 → 验证 → 分发”四步，把 layer 与 BuildKit 的关系讲透，把 multi-stage 的瘦身边界算清楚。
3 职责
- 把 Dockerfile 每一行的 layer 责任拆清：哪些是 base、哪些是 cache、哪些是 runtime，避免任一层变化让其后续 layer cache 全部失效。
- 用 BuildKit 的
--mount=type=secret/--mount=type=cache/--cache-to=type=registry把 secret 与远端 cache 注入构建流程，告别 ARG/ENV 泄露与本机 cache 依赖。 - 用 SBOM（SPDX / CycloneDX）+ cosign sign / verify / attach 把 digest 锁定与签名验证串成可拒绝未签名 image 的门禁。
4 交付物
- 一份多阶段 Dockerfile（multi-stage + distroless + nonroot），附 layer 大小与 history 截图，证明瘦身后 image 体积 < 200 MB。
- 一份 buildx 多平台脚本（linux/amd64 + linux/arm64），含
--push/--cache-from/--cache-to三件套与 manifest list 验证。 - 一份 SBOM 与签名脚本（
docker sbom+syft+cosign sign+cosign verify-attestation），含签名缺失时的 verify 失败反例。 - 一份 save/load 离线分发记录，含
gzip压缩后大小与docker load后的 digest 校验，证 save/load 保留 image history 与 tag。
3 指标
- Cold build < 5 min / incremental build < 30 s（看 layer cache 命中率与 BuildKit
llbsolver复用）。 - SBOM 覆盖率 100%（
syft/docker sbom比对 package 数等于 image 内动态/静态链接包数）。 - 签名验证拦截率 100%（在 admission 阶段用
cosign verify拒绝未签名或 digest 不符 image 的次数 / 部署次数）。
Docker Docs 作主线；OCI 文档用于契约；Moby、BuildKit、containerd、runc 源码只在需要确认实现时查。复制前核对当前 LICENSE。
8. 推荐开源资料
Docker Docs 作主线；OCI 文档用于契约；Moby、BuildKit、containerd、runc 源码只在需要确认实现时查。复制前核对当前 LICENSE。
9. 学习资料汇聚（v0.3 自包含）
9.1 背景与动机
本子主题处理：从 Dockerfile、layer、BuildKit 缓存到 registry、buildx 多平台与 save/load。。Docker 的易用 CLI 会隐藏多层状态。我们通过最小实验、inspect 和失败注入把对象关系变成可观察事实。
9.2 概念地图
flowchart LR
Spec[声明 / Spec] --> Engine[Docker Engine / BuildKit]
Engine --> Artifact[image / config / state]
Artifact --> Runtime[container runtime]
Runtime --> Evidence[inspect / logs / events / metrics]
Failure[故障注入] --> Runtime
Evidence --> Fix[修改与验证]
本页核心概念：Dockerfile、layer、BuildKit、registry、save/load、buildx 与多平台 manifest。声明经过 engine 产生制品或运行状态，所有判断回到 evidence。
9.3 基础知识讲解
9.3.1 论文 / 规范
| 资料 | 用法 |
|---|---|
| OCI Image Format Specification | 核对 manifest、config 与 layer digest |
| OCI Runtime Specification | 核对 bundle、config.json 与 lifecycle |
| NIST SP 800-190 Application Container Security Guide | 建立镜像、registry、orchestrator、host 风险模型 |
9.3.2 书
| 资料 | 用法 |
|---|---|
| Brendan Burns, Designing Distributed Systems | 学 sidecar、ambassador、adapter 等容器协作模式 |
| Liz Rice, Container Security | 结合 namespace、capability、seccomp 理解隔离边界 |
| Nigel Poulton, Docker Deep Dive | 补 Docker Engine、image、network、volume 主线 |
9.3.3 博客 / 文档
| 资料 | 用法 |
|---|---|
| Docker 官方文档 | 命令、Dockerfile、Compose、BuildKit 主线 |
| OWASP Docker Security Cheat Sheet | 配置安全检查表；并延伸阅读 OWASP Docker Top 10 |
| Kubernetes The Hard Way | 由 Kelsey Hightower 维护，用手工部署理解容器编排边界 |
| Aqua Trivy | 扫 image、filesystem、SBOM 与 misconfiguration |
| Snyk Container | 对照另一套 image dependency 风险视图 |
9.3.4 人物
| 人物 | 关注点 |
|---|---|
| Solomon Hykes | Docker 项目起点与开发者体验 |
| Kelsey Hightower | Kubernetes 教学、The Hard Way 与运维实践 |
| Liz Rice | 容器运行时、安全、eBPF 与隔离边界 |
| Brendan Burns | 容器编排与分布式系统模式 |
9.3.5 方法
| 方法 | 动作 |
|---|---|
| Inspect-first | 用 docker inspect、history、diff 看真实状态，不猜 |
| Immutable build | image 构建一次，按 digest 提升到各环境 |
| Least privilege | 非 root、drop capabilities、只读文件系统、限制资源 |
| Reproducible build | 锁 base digest、依赖版本与 build context，保留 provenance |
| Failure injection | 主动停服务、断网络、损坏健康检查，观察恢复和告警 |
| Evidence-based sizing | 用 metrics 决定 CPU/memory limit，不复制默认值 |
9.4 经典问题与经典案例
| # | 问题 | 最简答案 |
|---|---|---|
| 1 | 为什么 tag 不能作为不可变版本？ | tag 可移动，部署与审计记录 digest。 |
| 2 | COPY 顺序为何改变 build time？ | 任一层变化会使其后层 cache 失效。 |
| 3 | 删除文件为何 image 仍大？ | 旧 layer 内容仍存在，改用 multi-stage。 |
| 4 | save/load 与 export/import 区别？ | 前者保留 image history/tag，后者处理 container filesystem。 |
| 5 | buildx 双平台为何需要 registry？ | 多平台 manifest list 通常需 --push，本地 image store 支持有限。 |
| 6 | 怎样传构建 secret？ | 用 BuildKit secret mount，不用 ARG/ENV。 |
9.4.1 实战片段：buildx 多平台、secret mount、save/load
# syntax=docker/dockerfile:1.7
FROM node:22-bookworm-slim AS build
WORKDIR /src
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN --mount=type=secret,id=github_token \
--mount=type=cache,target=/root/.npm \
pnpm run build
FROM gcr.io/distroless/nodejs20-debian12:nonroot
COPY --from=build /src/dist /app
USER nonroot:nonroot
EXPOSE 3000
ENTRYPOINT ["/app/server.js"]
# 1. 引导多平台 builder
docker buildx create --name multi --driver docker-container --bootstrap
docker buildx use multi
# 2. 多平台构建 + 缓存导出到 registry
docker buildx build \
--platform linux/amd64,linux/arm64 \
--secret id=github_token,env=GITHUB_TOKEN \
--cache-from type=registry,ref=ghcr.io/acme/app:cache \
--cache-to type=registry,ref=ghcr.io/acme/app:cache,mode=max \
--tag ghcr.io/acme/app:v1 \
--push .
# 3. 离线分发：保存与恢复
docker buildx build --platform linux/amd64 \
--output type=docker,dest=- \
--tag ghcr.io/acme/app:v1 . \
| gzip > app-v1.tgz
gunzip -c app-v1.tgz | docker load
# 4. 看 image layer、digest、history
docker images --digests ghcr.io/acme/app:v1
docker history ghcr.io/acme/app:v1
docker buildx imagetools inspect ghcr.io/acme/app:v1 --raw
9.5 学习难点
概念难点
| 难点 | 为什么会卡 | 突破路径 |
|---|---|---|
| 声明与状态 | 文件正确不代表运行状态正确 | 同时看配置渲染、inspect 和实际 I/O |
| 隔离边界 | UI 隐藏 namespace、mount、network | 画宿主、daemon、runtime、进程四层图 |
| 默认值 | 版本和平台会改变行为 | 记录版本，查官方 reference，显式写关键值 |
思维难点
| 难点 | 为什么会卡 | 突破路径 |
|---|---|---|
| 从错误文本找层级 | client、daemon、runtime、app 都能报错 | 先标错误产生者，再沿调用链检查 |
| 正常路径偏见 | 跑通一次容易误判稳定 | 端口、权限、资源、依赖各造一次故障 |
| 可变状态 | tag、container、volume 会随操作变化 | 每步记录对象 ID/digest 与前后状态 |
工程难点
| 难点 | 为什么会卡 | 突破路径 |
|---|---|---|
| 跨平台与权限 | kernel、filesystem、UID 行为不同 | 在目标平台跑验收，写明已知限制 |
| 清理与数据安全 | remove/prune 可能不可逆 | 先列对象与备份，再执行精确删除 |
| 可观测性 | 单一日志缺上下文 | 关联 inspect、events、stats、health 与应用指标 |
9.6 技术标准与接口
9.6.1 Entity
| 名称 | 发布组织 | 角色 | 状态 / 可访问性 |
|---|---|---|---|
| OCI Image Spec | Open Container Initiative | image manifest、config、layer 格式 | 开放标准，Apache-2.0 |
| OCI Runtime Spec | Open Container Initiative | bundle 与容器运行生命周期 | 开放标准，Apache-2.0 |
| containerd | CNCF | image、snapshot、container、task 管理 | 活跃，Apache-2.0 |
| runc | Open Container Initiative | OCI runtime reference implementation | 活跃，Apache-2.0 |
| CNI | CNCF | 容器网络插件接口 | 活跃，Apache-2.0 |
| CSI | CNCF | 容器编排系统存储接口 | 活跃，Apache-2.0 |
9.6.2 Scope
OCI 定义 image 与 runtime 契约，不定义完整编排。containerd 管高层生命周期，runc 执行 OCI bundle。CNI、CSI 面向编排系统；Docker bridge、volume driver 有自己的实现接口。Docker Compose 处理单机或 context 上的多服务应用，不替代 Kubernetes 的集群调度。
9.6.3 Structure
必须掌握 image manifest/config/layer、content digest、OCI bundle、config.json、namespace、cgroup、capability、seccomp、network namespace、mount、snapshotter。常用接口是 Docker CLI/API、Dockerfile、Compose Specification、registry HTTP API。
9.6.4 Ecosystem
Docker Engine 由 daemon、containerd、runc 等组成。替代或邻接实现有 Podman、Buildah、BuildKit、nerdctl、CRI-O、Kubernetes。扩展点包括 BuildKit frontend/cache exporter、network/volume/logging plugin、CNI 与 CSI driver。Compose 文件规范与具体 engine 支持范围要分开核对。
9.6.5 Depth Tiers
| 层级 | 可观察能力 |
|---|---|
| L0 | 知道 image、container、registry、volume、network、Compose 的职责 |
| L1 | 看懂 Dockerfile、docker run 和 compose.yaml 示例 |
| L2 | 能正确 build、run、push、备份、编排并处理常见参数错误 |
| L3 | 能解释 layer、namespace/cgroup、网络存储路径并用日志、stats、inspect 排错 |
| L4 | 能设计 runtime、plugin、供应链策略或大规模编排平台 |
本计划目标是 L3。
9.6.6 Source
- Docker 官方文档：CLI、Dockerfile、BuildKit、Compose、rootless 与生产建议。
- Moby 项目仓库：Docker Engine 核心实现，Apache-2.0。
- containerd 仓库：runtime 管理实现，Apache-2.0。
- 引用版本快照日期：2026-07-30；实作前运行
docker version与docker compose version。
10. 常见误区
- 只复制命令，不理解对象状态；
- 以 tag 代替 digest；
- 默认 root；
- 把 secret 写进 image 或仓库；
- 用重启掩盖 readiness 和数据问题；
- 只测试正常路径；
- 不记录 Docker/Compose 版本；
- 不区分 Docker 行为、OCI 契约和 Linux kernel 能力；
- 看见报错就重建全部对象；
- 未备份就 remove volume 或 prune。
11. 所有知识点分类（统一规则）
- 编程语言；2. 数据结构与算法；3. 计算机基础；4. 工程技术；5. Web 与后端；6. 前端与客户端；7. 数据与人工智能；8. 项目与职业能力；9. 安全与可靠性。
本计划归属：工程技术 主 + 安全与可靠性 辅。