2.1 镜像分层设计：让 8 GB 依赖不必每次重装

2.1 镜像分层设计：让 8 GB 依赖不必每次重装

读者读完这一节，应该能一句话说出他学到了什么：Docker 镜像的分层不是装饰，它直接决定了你每次改依赖要不要重新拉 8 GB；而分层顺序的微小调整，能让团队 CI 从 20 分钟降到 2 分钟。

我见过太多团队的 Dockerfile 是这样写的：把 apt 安装、pip install、拷贝源码、下载模型权重全堆在最后几行，改动任何一处都触发整层重建。结果就是——改一个训练超参，CI 重新拉一遍 PyTorch 的 2 GB 轮子。这不是"慢一点"的问题，而是会让"复用沙箱"这件事在团队里根本推不动，因为每次构建都贵得离谱，没人愿意等。

分层设计，是沙箱工程化第一步，也是最容易被忽视的一步。下面从原理到实战把它彻底讲透。

一、镜像分层到底在分什么

Docker 镜像是只读层的栈。每一条 RUN、COPY、ADD 在构建时都会产出一个新层，层与层之间是内容寻址的——只要某一层的内容（和它的前驱层）没变，这一层就能被缓存复用。关键点在于：缓存是按顺序命中的，且是"短路"的。一旦某一层失效，它之后所有层都必须重建，即便后面的层内容其实没变。

这就引出一个被 90% 的人忽略的事实：层顺序 = 缓存命中率。把"容易变的"放在后面，把"几乎不变的"放在前面，是分层设计的唯一铁律。很多人把 COPY . . 写在 pip install 之前，于是代码一改，整条依赖链全废。

颜色越红越容易变。把红层往后放，前面绿色层就能一直命中缓存。反过来放，绿色层也会被红色层拖着重建。

二、一个"反例" Dockerfile 与它的代价

下面这段是真实项目里常见的写法（已简化），问题不在"能不能跑"，而在"改一次重建一次"：

FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
WORKDIR /app
# 系统依赖、Python 依赖、源码全挤在一起
RUN apt-get update && apt-get install -y python3-pip git ffmpeg
COPY . /app
RUN pip install --no-cache-dir -r requirements.txt
RUN python -c "import torch; print(torch.__version__)"
CMD ["python", "train.py"]
​

看起来没问题。但注意：COPY . /app 在装依赖之前。这意味着任何一次源码改动，都会让 apt-get 之后的所有层（包括最贵的 pip install）全部失效。哪怕你只是改了 README 里的一个字，PyTorch 那 2 GB 轮子也要重新拉一遍。

更要命的是 requirements.txt 和源码放在同一时间窗口拷贝，pip 层永远和代码层绑定，没法独立缓存。一次普通的"加一行日志"改动，CI 从几十秒变成十几分钟，团队成员会本能地回避重建——于是沙箱逐渐腐烂。

三、正确的分层顺序：先依赖、后代码

把"不变的多"提前，把"变的快"推后。改写如下：

FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04

# ① 系统层：几乎不变
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3-pip python3-dev git ffmpeg ca-certificates && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# ② 依赖层：先单独拷 requirements，再装
COPY requirements.txt /app/
RUN pip install --no-cache-dir -r requirements.txt

# ③ 代码层：最后拷源码，变动只重建这一层
COPY . /app

CMD ["python", "train.py"]
​

差别在哪？当你只改业务代码时，①② 两层因为内容没变而直接命中缓存，只有 ③ 重建。pip install torch 那 2 GB 再也不会因为改个超参被重新拉取。在团队 CI 里，这一个改动往往把构建时间从 15–20 分钟压到 2–3 分钟。

还有一个细节：--no-install-recommends 和 rm -rf /var/lib/apt/lists/* 不是可有可无的。前者避免 apt 顺手装一堆用不上的推荐包，后者清掉 apt 的索引缓存——这两行能为一个镜像省下几十到上百 MB，且减少攻击面。每一层都在为"瘦"和"快"投票。

横轴为相对耗时（秒级示意）。正确分层下，一次常规代码改动只需重建最小层。

四、.dockerignore：别让 COPY . 把仓库垃圾也塞进去

当你写 COPY . /app，Docker 会把构建上下文（你执行 docker build 时的那个目录）整个打包发给守护进程。如果你的仓库里有 outputs/（几十 GB 的 checkpoint）、.git/、node_modules/、虚拟环境目录，它们会被全部传上去，既拖慢传输，又让代码层频繁失效（因为 outputs 在变）。

.dockerignore 就是 Docker 版的 .gitignore，告诉构建上下文"这些别传"：

.git
outputs
*.log
__pycache__
.venv
node_modules
​

加上它之后，COPY . /app 只拷真正需要的源码，代码层更稳定、传输更轻。这是分层设计的隐形搭档，90% 的慢构建问题加上它就缓解了一半。

五、用多阶段构建进一步瘦身

如果你的最终产物只是训练好的权重或服务镜像，完全没必要把编译工具链留在运行镜像里。多阶段构建（multi-stage）可以把"编译环境"和"运行环境"分开：

# 构建阶段：带编译工具
FROM nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04 AS builder
RUN apt-get update && apt-get install -y build-essential
WORKDIR /build
COPY . /build
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# 运行阶段：只拿成品轮子
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/* && rm -rf /wheels
​

运行镜像不含 build-essential，体积更小、攻击面更窄。对需要分发镜像的团队，这一步几乎是必做的。注意 COPY --from=builder 只复制产物，编译阶段的中间层不会进入最终镜像。

六、CUDA 基础镜像该怎么选

分层设计里最底层、也最影响一切的，是 FROM 哪一对基础镜像。NVIDIA 在 Docker Hub 上提供 nvidia/cuda 系列，标签形如 12.1.1-cudnn8-runtime-ubuntu22.04，其中关键后缀有三个档位：

• base：只有 CUDA 运行时库，最小，但很多包编译时需要头文件会失败。
• runtime：含运行时 + cuDNN，跑 PyTorch/TensorFlow 推理和训练够用，是大多数人的默认选择（也是本教程主力）。
• devel：含 nvcc 编译器与头文件，只在你需要从源码编译 CUDA 扩展（如某些自定义算子、flash-attention）时才需要。它体积最大，单镜像常超 5 GB。

我的建议很明确：默认用 runtime，只有遇到"需要编译 CUDA 扩展"才上 devel，并且用多阶段把 devel 留在构建期。不要用 devel 当运行镜像——你不会想给每个同事的笔记本塞一个 6 GB 的编译器镜像，还顺带放大了被攻击面。

七、分层的两个实战陷阱

陷阱一：把数据下载写进镜像层。 有人喜欢在 Dockerfile 里 RUN wget 模型权重。后果是权重进了镜像层，每次改代码镜像都要重下，且镜像体积爆炸、无法共享。正确做法是把权重放到挂载卷（见 2.3），构建时绝不下载大文件。镜像应该是"代码+依赖"的封装，不是数据仓库。

陷阱二：混用 latest 与不锁版本。 FROM nvidia/cuda:latest 会让半年后重建的镜像悄悄换成新 CUDA，导致与锁死的 PyTorch 版本不兼容。基础镜像必须锁具体版本号，这是可复现性的第一道闸门（2.2 会展开依赖锁定）。

陷阱三：ARG 引发的"伪缓存失效"。 ARG 在 FROM 之前定义会影响基础镜像选择，但 ARG 变量出现在 RUN 指令里时，含该变量的层会因为变量值不同而无法跨构建共享缓存。能用 ENV 固定就别用 ARG 传易变的值。

八、如何验证你的分层真的生效

不要凭感觉。两个工具能帮你看见层：

• docker history <镜像>：列出每一层的大小和构建命令，你能立刻发现"为什么这一层这么大""为什么代码改动后这层重建了"。
• 社区工具 dive：交互式分析镜像层，直接标出每层浪费的空间，是优化分层的利器。

我建议每次改完 Dockerfile 都跑一次 docker history，确认"改代码只动了最小的层"。当这一条成立，分层设计才算真的做对了。

九、跨 CI Runner 共享构建缓存

分层设计的收益，在单机本地构建时已经明显；但在团队 CI 里，每个 Runner 是干净的，缓存本该全失效——除非你主动共享。两个常用做法：

• docker buildx 的缓存导出：用 --cache-from / --cache-to 把构建缓存推到远端仓库（如 OCI 镜像仓库）或共享目录。这样不同 Runner、甚至不同人本地，都能命中彼此的层，8 GB 依赖只拉一次。
• 挂载宿主缓存目录：在自建 Runner 上把缓存盘挂成持久卷，让层缓存在多次构建间留存。适合固定 Runner 的私服场景。

我的判断：如果你们有常驻 Runner，第二种零成本；如果要弹性扩缩，第一种是标配。无论哪种，目的都是让分层换来的缓存命中率在团队尺度上生效，否则它只是你个人的优化。

十、一份可复用的优化版 Dockerfile 总览

把本章要点收敛成一份可直接抄的骨架（CUDA 12.1 + runtime + 多阶段）：

# syntax=docker/dockerfile:1
FROM nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04 AS builder
RUN apt-get update && apt-get install -y --no-install-recommends build-essential python3.10 python3.10-venv && \
    rm -rf /var/lib/apt/lists/*
RUN python3.10 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /build
COPY requirements.lock /build/
RUN pip install --no-cache-dir -r requirements.lock

FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
RUN apt-get update && apt-get install -y --no-install-recommends python3.10 python3.10-venv ca-certificates && \
    rm -rf /var/lib/apt/lists/*
RUN python3.10 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY --from=builder /opt/venv /opt/venv
WORKDIR /app
COPY . /app
ENTRYPOINT ["/opt/venv/bin/python", "train.py"]
​

要点回顾：基础镜像锁版本、系统层先装并清缓存、依赖层单独拷 lock 再装、代码层最后拷、多阶段把 devel 留在构建期、解释器固定在 venv 且用 ENTRYPOINT 指死。这份骨架同时满足高效与可复现，是第二章三节思想的合体。

十一、镜像体积监控与 CI 门禁

分层优化不是一次性工作，要靠机制守住。建议在 CI 里加一道镜像体积门禁：构建后用 docker images 取体积，超过阈值（如 6 GB）就告警，逼着作者回去看是不是又把大文件写进了层。配合前面提到的 dive 工具，可以把层浪费空间也量化出来，作为门禁指标。

我见过一个团队因为有人把数据集 COPY 进了镜像，单镜像涨到 30 GB，推送到仓库后所有人拉取都要十几分钟，整条流水线被拖死。如果当时有体积门禁，这个错误在合并前就会被拦下。机制的意义，就是把靠个人记性变成靠系统拦截。

小结与下一节衔接

分层设计的本质，是用层顺序换变更成本。把不变的前置、把易变的后置，配合 .dockerignore、多阶段瘦身和锁版本的基础镜像，你就得到了一个"改代码秒级重建、改依赖才重装"的骨架。

但分层只解决了"镜像怎么长得高效"。下一节 2.2 要解决更根本的问题：镜像里的依赖本身能不能复现——也就是"在我机器上能跑"能不能变成"在任何人机器上能跑"。那是隔离式沙箱真正兑现价值的时刻。

十二、实战对照：把一个踩坑仓库改造成分层镜像

光讲原则还不够，我们顺着一条真实改造线走一遍。假设有个仓库的 Dockerfile 长这样（痛点集合体）：

FROM nvidia/cuda:latest
COPY . /app
RUN apt-get update && apt-get install -y python3-pip git
RUN pip install torch transformers datasets
CMD ["python","train.py"]
​

它同时踩了三个雷：基础镜像用 latest、代码先于依赖拷贝、依赖不锁版本。改造后的版本：

FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04
RUN apt-get update && apt-get install -y --no-install-recommends python3.10 python3.10-venv && rm -rf /var/lib/apt/lists/*
RUN python3.10 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY requirements.lock /app/
RUN pip install --no-cache-dir -r requirements.lock
COPY . /app
ENTRYPOINT ["/opt/venv/bin/python","train.py"]
​

改造前后对比：构建时间从平均 18 分钟降到 3 分钟（代码改动只重建最后一层）；半年后重建不再因为 latest 漂到新 CUDA 而失败；新人 docker build 出来和原作者行为一致。这个例子说明，分层设计不是炫技，而是把"每次都痛"变成"一次解决、长期免费"。

小结与下一节衔接

十三、落地清单：给你的 Dockerfile 做一次体检

读完本节，对照下面七条给你的镜像做次体检，任一条不满足就回去改：

1. 基础镜像是否锁了具体 CUDA 版本，而非 latest？
2. 系统依赖层是否带 --no-install-recommends 并清理了 apt 缓存？
3. 依赖层是否单独 COPY 依赖清单后再安装，而非和代码混在一起？
4. 代码层是否放在最后，且配了 .dockerignore 排除 outputs/.git/虚拟环境？
5. 是否用了多阶段构建，把 devel 留在构建期、runtime 用于运行？
6. 是否用 ENTRYPOINT 指死镜像内解释器，避免误调宿主机 python？
7. 是否用 docker history 确认"改代码只动最小层"？

七条全过，你的镜像分层才算及格。记住：分层设计的目标不是"能构建"，而是"每次只重建该重建的那一层"。

需要提醒的是，分层顺序的优化没有银弹：如果你的依赖几乎天天变而代码很少变，那就该把代码层放前面、依赖层放后面。铁律只有一个，把变得慢的放前面。先搞清楚你项目的变更频率，再决定顺序，而不是死板套用模板。