📚 课程目录第4章依赖安装缓存

4、依赖安装缓存：利用apt/yum缓存、pip/npm缓存目录挂载

在容器镜像构建过程中，依赖安装（如系统包管理器、语言包管理器）往往是耗时最长的阶段之一。每次构建都从远程仓库重新下载所有依赖，不仅浪费带宽，还显著延长流水线等待时间。本章聚焦于如何通过缓存目录挂载策略，将 apt/yum、pip/npm 的下载缓存持久化，实现增量构建加速。

4.1 依赖缓存的核心原理

容器镜像构建的每一层（Layer）都是只读的。当 RUN apt-get install 或 RUN pip install 执行时，下载的包文件默认存储在临时目录中，层提交后即被丢弃。下一次构建即使代码未变，仍需重新下载。缓存策略的核心思路是：将包管理器的缓存目录挂载为持久化卷（Volume）或绑定挂载（Bind Mount），使后续构建复用已下载的包文件。

  关键指标： 启用依赖缓存后，典型 Python 项目构建时间可从 120s 降至 25s（节省约 80%）；Java Maven 项目从 90s 降至 18s；Node.js 项目从 60s 降至 12s。

4.2 主流包管理器缓存目录对照

包管理器	默认缓存路径	缓存文件类型	挂载建议
apt (Debian/Ubuntu)	`/var/cache/apt/archives/`	`.deb` 包文件	挂载为持久卷，注意清理过期包
yum (RHEL/CentOS)	`/var/cache/yum/`	RPM 包及元数据	挂载整个缓存目录，定期 `yum clean all`
pip (Python)	`~/.cache/pip/` 或 `/root/.cache/pip/`	Wheel 包、源码包	挂载 `/root/.cache/pip` 或自定义 `PIP_CACHE_DIR`
npm (Node.js)	`~/.npm/` 或 `/root/.npm/`	压缩包、解压后的模块	挂载 `/root/.npm`，配合 `npm cache verify`
maven (Java)	`~/.m2/repository/`	JAR、POM、SNAPSHOT	挂载 `/root/.m2`，注意 SNAPSHOT 版本更新

4.3 Docker BuildKit 缓存挂载实现

Docker 18.09+ 引入的 BuildKit 提供了原生的 --mount=type=cache 语法，无需手动管理卷或绑定挂载。在 Dockerfile 中通过 RUN --mount=type=cache,target= 声明缓存目录，BuildKit 会自动维护持久化缓存层。

4.3.1 apt 缓存挂载示例

# syntax=docker/dockerfile:1.4
FROM ubuntu:22.04 AS builder

# 挂载 apt 缓存目录
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
    apt-get update && apt-get install -y \
    build-essential \
    libssl-dev \
    libffi-dev \
    python3-dev \
    && rm -rf /var/lib/apt/lists/*

注意： sharing=locked 确保同一时间只有一个构建任务写入缓存，避免并发冲突。对于 apt，建议同时挂载 /var/cache/apt（包文件）和 /var/lib/apt/lists（元数据索引），后者可显著加速 apt-get update。

4.3.2 pip 缓存挂载示例

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

WORKDIR /app
COPY requirements.txt .

# 挂载 pip 缓存目录
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

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

避坑： 不要同时使用 --no-cache-dir 和缓存挂载。如果使用 --no-cache-dir，pip 不会写入缓存，挂载将失效。正确做法是去掉 --no-cache-dir，让 pip 自然使用缓存目录。

4.3.3 npm 缓存挂载示例

# syntax=docker/dockerfile:1.4
FROM node:18-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json .

# 挂载 npm 缓存目录
RUN --mount=type=cache,target=/root/.npm \
    npm ci --prefer-offline

COPY . .
RUN npm run build

  性能对比： 使用 --prefer-offline 配合缓存挂载，npm install 时间从 45s 降至 8s（节省 82%）。首次构建仍会下载全部依赖，后续构建仅下载变更部分。

4.4 缓存目录挂载架构

下图展示了 BuildKit 缓存挂载在流水线中的工作流程：构建节点上的缓存卷被多个构建任务共享，包管理器优先从本地缓存读取，仅当缓存未命中时才回源到远程仓库。

4.5 缓存失效与清理策略

缓存并非越大越好。长期运行的流水线中，缓存目录会积累大量过期包文件，导致磁盘占用膨胀、查找效率下降。需要建立合理的失效与清理机制。

策略	适用场景	实现方式	推荐频率
时间窗口清理	依赖版本更新频繁	定时任务删除超过 N 天未访问的缓存文件	每周一次
磁盘阈值清理	缓存卷空间有限	当磁盘使用率超过 80% 时触发清理	按需触发
构建后清理	确保缓存不包含敏感或临时文件	在 Dockerfile 末尾执行 `apt-get clean` / `npm cache clean --force`	每次构建
版本锁清理	使用 lock 文件锁定版本	仅保留 lock 文件中声明的版本，删除其余	每次 lock 文件变更时

4.6 多阶段构建中的缓存优化

在多阶段构建（Multi-stage Build）中，缓存挂载可以跨阶段共享。例如，在 builder 阶段安装编译依赖，在 runtime 阶段仅复制产物，但缓存目录可以复用。

# syntax=docker/dockerfile:1.4
# 第一阶段：编译依赖
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --user -r requirements.txt

# 第二阶段：运行环境
FROM python:3.11-slim AS runtime
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD ["python", "app.py"]

最佳实践： 将 requirements.txt 或 package.json 单独复制并安装，利用 Docker 层缓存（Layer Cache）避免每次代码变更都重新安装依赖。结合缓存挂载，可实现“代码变更秒级构建，依赖变更分钟级构建”的效果。

4.7 流水线集成示例（GitLab CI）

在 CI/CD 流水线中，缓存挂载需要与 Runner 配置配合。以下为 GitLab CI 中使用 BuildKit 缓存挂载的示例：

# .gitlab-ci.yml
variables:
  DOCKER_BUILDKIT: "1"
  BUILDKIT_PROGRESS: "plain"

build:
  stage: build
  script:
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
  tags:
    - docker-buildkit

同时需要在 Runner 的 config.toml 中启用 BuildKit 并配置缓存卷：

[[runners]]
  name = "docker-buildkit-runner"
  url = "https://gitlab.com/"
   = "YOUR_"
  executor = "docker"
  [runners.docker]
    image = "docker:24.0"
    privileged = true
    volumes = [
      "/cache",
      "/var/lib/docker"
    ]
  [runners.cache]
    Type = "s3"
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "YOUR_ACCESS_KEY"
    SecretKey = "YOUR_SECRET_KEY"
    BucketName = "runner-cache-bucket"
    Insecure = false

安全提醒： 缓存目录可能包含敏感信息（如私有仓库的认证令牌）。确保缓存卷的访问权限仅限于构建任务，并在流水线结束后清理包含敏感数据的缓存文件。对于公共项目，建议使用临时缓存卷，避免跨构建泄露。

4.8 缓存命中率监控

为了评估缓存策略的有效性，建议在流水线中采集以下指标：

缓存命中率：缓存读取次数 / 总依赖请求次数。理想值应 > 90%。
缓存大小：定期记录缓存目录的磁盘占用，避免无限增长。
构建时间节省：对比启用缓存前后的构建时长，计算节省百分比。
缓存失效次数：因版本变更或清理策略导致的缓存重建次数。

通过持续监控这些指标，可以动态调整缓存策略，在加速构建与磁盘成本之间取得平衡。