4. 编写 Dockerfile：基础镜像选择、层缓存优化、多阶段构建

Dockerfile 是将模型训练管道容器化的“施工图纸”。它的编写质量直接决定镜像体积、构建速度、安全性和可复现性。本章聚焦三个核心决策点：基础镜像选什么、如何利用层缓存加速迭代、如何用多阶段构建剥离冗余。这三者相互关联，共同构成生产级训练镜像的编写范式。

4.1 基础镜像选择：从“能用”到“最优”

基础镜像是所有依赖的起点。选错基础镜像，后续所有优化都会事倍功半。对于 Python 训练任务，常见选择有四种，其适用场景差异显著：

核心原则：GPU 训练必须选择带 CUDA 的镜像作为基底，CPU 训练优先考虑 python:3.11-slim。不要使用 python:3.11 全量镜像作为生产基底，它携带的 build-essential 等工具会显著放大镜像体积和漏洞面。

4.2 层缓存优化：让每次构建只重做必要步骤

Docker 镜像由只读层堆叠而成，每一行指令生成一层。当 Dockerfile 某行指令的上下文未变化时，Docker 会直接复用缓存层，跳过执行。这一机制是加速迭代的关键，但前提是指令顺序必须符合“低频变化在前，高频变化在后”的规律。

以下是一个典型的错误顺序示例，它会导致每次修改代码都全量重装依赖：

# 错误示范：代码先复制，依赖后安装
FROM python:3.11-slim
WORKDIR /app
COPY . /app          # 代码一变，下面所有层缓存失效
RUN pip install -r requirements.txt
RUN python -m nltk.downloader punkt

正确的做法是先复制依赖清单文件，安装依赖，再复制业务代码。这样只要 requirements.txt 不变，即使代码频繁改动，依赖安装层也能命中缓存：

# 正确示范：依赖层与代码层分离
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
COPY config/ ./config/
CMD ["python", "src/train.py"]

层缓存优化还有两个实用技巧：

• 合并易变指令：将 apt-get update 与 apt-get install 用 && 连接，避免因 update 层缓存导致安装过期包。
• 利用 --mount=type=cache：针对 pip 下载缓存或 apt 缓存，使用 BuildKit 挂载缓存目录，避免每次构建重复下载。

# 使用 BuildKit 缓存 pip 下载包
# syntax=docker/dockerfile:1.4
FROM python:3.11-slim
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

4.3 多阶段构建：剥离编译工具，只留运行所需

训练任务常需要编译一些包含 C 扩展的 Python 包（如 pydantic-core、numpy 的某些构建），但运行时并不需要 gcc、make 等编译链。多阶段构建允许我们在一个临时镜像中完成编译，再将产物复制到干净的运行镜像中。

以下是一个面向 GPU 训练任务的多阶段 Dockerfile 骨架：

# 阶段一：构建依赖
FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04 AS builder
ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 python3.11-dev python3-pip gcc g++ \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /build
COPY requirements.txt .
RUN pip install --prefix=/install -r requirements.txt

# 阶段二：运行镜像
FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04
ENV PYTHONPATH=/install/lib/python3.11/site-packages
COPY --from=builder /install /install
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 python3-pip \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY src/ ./src/
COPY config/ ./config/
ENTRYPOINT ["python3.11", "src/train.py"]

该 Dockerfile 的关键点：

• 阶段一（builder）：安装完整编译链，将依赖安装到 /install 前缀目录。
• 阶段二（runtime）：仅安装 Python 解释器，不装 gcc，从 builder 阶段复制已编译的依赖。
• 最终镜像体积：比单阶段方案减少约 40%～60%，且不含任何源码编译工具。

4.4 案例：一个真实训练任务的 Dockerfile 演进

假设我们要容器化一个基于 PyTorch 的文本分类训练任务，代码结构如下：

project/
├── requirements.txt   # torch, transformers, datasets, scikit-learn
├── src/
│   ├── train.py
│   └── model.py
└── config/
    └── hyperparams.yaml

第一版（朴素写法）：

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "src/train.py"]

问题：每次修改 src/ 下任意文件，pip install 都会重跑，且镜像包含大量用不到的样例数据。

第二版（层缓存优化后）：

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY src/ ./src/
COPY config/ ./config/
CMD ["python", "src/train.py"]

改进：依赖层与代码层分离，代码改动不再触发依赖重装。

第三版（多阶段构建后）：

# 阶段一：编译 torchvision 等含 C 扩展的包
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --prefix=/install -r requirements.txt

# 阶段二：精简运行环境
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
ENV PYTHONPATH=/install/lib/python3.10/site-packages
COPY --from=builder /install /install
WORKDIR /app
COPY src/ ./src/
COPY config/ ./config/
CMD ["python", "src/train.py"]

最终镜像中不再包含 pip 的临时编译文件，且由于 PyTorch 官方镜像本身已包含 CUDA 运行时，无需额外安装。构建时间从首次的 8 分钟降至后续迭代的 30 秒左右（命中缓存时）。

4.5 常见误区与复盘

在编写训练管道 Dockerfile 时，以下误区出现频率最高，值得专门复盘：

• 误区一：盲目追求 Alpine 镜像。Alpine 使用 musl libc，与 PyTorch、TensorFlow 等预编译 wheel 包不兼容，经常出现“找不到 libc.musl-x86_64.so.1”或段错误。GPU 训练场景应直接放弃 Alpine。
• 误区二：把所有 RUN 指令合并成一行。虽然减少了层数，但破坏了缓存粒度。例如将 apt-get install 与 pip install 合并后，任何依赖变更都会导致所有层重建。
• 误区三：忽略 .dockerignore。若未排除 .git、__pycache__、*.pyc、data/ 等目录，构建上下文会异常庞大，导致首次构建极慢，且可能将敏感数据（如数据集、密钥）打入镜像。
• 误区四：在运行阶段保留构建用户。生产镜像应使用非 root 用户运行训练进程，降低安全风险。多阶段构建中可在最终阶段创建专用用户。