用 Docker BuildKit 的 cache mount 加速 Python 镜像构建

问题场景

Python 镜像常见写法是先把源码整体复制进镜像，再安装依赖：

COPY . .
RUN pip install -r requirements.txt

只要业务代码变化，COPY . . 层就会失效，后面的 pip 安装层也会重跑，构建时重新解析并下载依赖。依赖多或网络不稳定时，构建时间会被明显拉长。

更稳妥的做法是：先复制 requirements.txt，安装依赖，再复制源码；同时用 BuildKit 的 cache mount 把 pip 下载缓存挂载到构建过程中。这样修改代码时依赖层可以命中 Docker 层缓存；即使依赖层因其他原因需要重跑，pip 也能复用之前下载过的包。

最小可运行示例

目录结构：

.
├── Dockerfile
├── app.py
└── requirements.txt

requirements.txt：

requests==2.31.0

app.py：

import requests

print("requests version:", requests.__version__)

Dockerfile：

# syntax=docker/dockerfile:1.4
FROM python:3.11-slim

WORKDIR /app

ENV PIP_DISABLE_PIP_VERSION_CHECK=1

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt

COPY app.py .

CMD ["python", "app.py"]

关键点：

• COPY requirements.txt . 放在 pip 安装之前，源码变化不会影响依赖安装层。
• RUN --mount=type=cache,target=/root/.cache/pip 把 pip 缓存目录挂载为 BuildKit 缓存，缓存内容不会写入最终镜像层。
• 不要在这个 RUN 中加 --no-cache-dir，否则 pip 不使用缓存，cache mount 的意义会被削弱。
• target 需要与 pip 实际使用的缓存目录一致。默认 root 用户的 pip 缓存目录通常是 /root/.cache/pip；如果切换了用户或设置了 PIP_CACHE_DIR，要同步调整。

构建与运行

首次构建：

DOCKER_BUILDKIT=1 docker build --progress=plain -t pip-cache-demo .
docker run --rm pip-cache-demo

预期容器输出类似：

requests version: 2.31.0

修改 app.py（例如改一行打印内容）后再次构建：

DOCKER_BUILDKIT=1 docker build --progress=plain -t pip-cache-demo .

观察 --progress=plain 的输出。由于 requirements.txt 没变，pip 安装对应的 RUN 步骤应显示为 CACHED，只有复制 app.py 及之后的步骤重新执行。这就是“修改代码不重复下载依赖”的验证方法。

如果想进一步观察 cache mount 本身，可以临时加一个只用于验证的构建参数，让 pip 的 RUN 层失效但缓存挂载仍然存在：

ARG PIP_REFRESH=1
RUN --mount=type=cache,target=/root/.cache/pip echo "refresh=$PIP_REFRESH" && pip install -r requirements.txt

然后用不同的参数值构建两次：

DOCKER_BUILDKIT=1 docker build --progress=plain --build-arg PIP_REFRESH=1 -t pip-cache-demo .
DOCKER_BUILDKIT=1 docker build --progress=plain --build-arg PIP_REFRESH=2 -t pip-cache-demo .

第二次 pip 步骤会重新执行，但可以观察它是否复用缓存中的 wheel/HTTP 缓存。不同 pip 版本的日志措辞可能不同，不要只依赖某一句固定输出。

边界与限制

• 该写法依赖 BuildKit。传统构建器不支持 RUN --mount=type=cache，需要启用 BuildKit 或使用支持该语法的构建前端。
• cache mount 只影响构建过程中的缓存挂载，不会把缓存目录打进最终镜像；镜像大小仍主要由已安装依赖决定。
• 修改代码时不重复安装依赖，主要来自“先复制 requirements.txt、后复制源码”的层缓存设计；cache mount 解决的是 pip 层需要重跑时复用下载缓存的问题，两者应配合使用。
• requirements.txt 变化后 pip 层会失效，新增或升级依赖仍然需要下载。缓存命中情况受包版本、索引和 pip 行为影响。
• 在 CI 中，如果每次构建都使用全新的构建器，本地 cache mount 可能无法跨流水线保留。需要结合持久化构建节点或团队现有的缓存方案评估，不能只依赖 Dockerfile 中的一行 mount。
• 如果镜像使用非 root 用户，应把 target 指向该用户的 pip 缓存目录，并确认目录权限；必要时通过缓存挂载的用户/权限参数或环境变量统一配置。
• 不要把密钥、私有源凭据写入会被缓存或复制的文件。涉及私有依赖时，优先使用构建密钥等机制，避免凭据进入镜像层或长期缓存。
• 建议配合 .dockerignore 排除 __pycache__/、.venv/ 等目录，减少无关文件进入构建上下文。

小结

用 BuildKit cache mount 加速 Python 镜像构建的核心不是单独一行 mount，而是“依赖文件先复制 + pip 安装层前置 + 缓存目录挂载”的组合。先复制 requirements.txt 可以让代码改动不触发依赖安装；cache mount 则在 pip 层需要重跑时复用下载缓存。用 --progress=plain 对比两次构建日志，可以直观看到依赖层是否命中缓存。