Docker镜像构建：从规范到实战

构建镜像这回事，说白了就是写一份「食谱」。你告诉 Docker 需要什么原料、怎么加工、最后怎么呈现。我在质控流程里折腾过不少次，发现很多坑其实都出在 Dockerfile 写得不够严谨上。今天咱们就好好聊聊，怎么把这份食谱写得漂亮又可靠。

核心观点：Dockerfile 的每一行指令都会产生一个中间层。层是基础，但层多了未必是好事。作为质控工程师，我们要在可复现性和镜像体积之间找到平衡。

Dockerfile 镜像构建核心流程 1. FROM 选择基础镜像 2. RUN / ENV 配置环境 3. COPY / ADD 放入项目文件 4. 多阶段构建（按需选） 5. CMD / ENTRYPOINT 定义启动 关键：每条指令对应一个只读层，修改任何一层会重建后续所有层 合理的层顺序 = 更快的构建 + 更小的镜像 + 更高的缓存命中率

编写规范：我的几条铁律

先说规范。我用 Dockerfile 这几年，总结了几条原则，分享给你：

  1. 基础镜像要锁定版本——别写 FROM python，要写 FROM python:3.11-slim。我吃过一次亏，年初用的 python:3，到年中发现拉下来的镜像变了，质控结果怎么都对不上。从那时起，所有镜像全都钉死 tag。
  2. 尽量用官方镜像——为什么？安全更新有人盯着，漏洞有人修。自己从 Alpine 开始搭，万一漏了某个依赖，质控流程跑出来就是错的。
  3. 每条 RUN 指令合并成一条——这是我踩坑踩出来的教训。曾经为了调试方便拆成 5 条 RUN，结果镜像多了 200MB。现在习惯用 RUN apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/* 结束。
  4. .dockerignore 一定要写——不写的话，整个项目目录都塞进构建上下文。质控数据文件多，我曾经不小心把一个 2GB 的数据集打包进了镜像，构建了半小时还报错。

个人习惯是把 .dockerignore 放在版本控制里，至少排除掉 node_modules、.git、.env 和临时文件。

常用指令深度解析

下面这张表总结了我日常最常用的指令，每个都跟质控流程有关：

指令 用途 注意事项（个人经验）
FROM 指定基础镜像 每个 Dockerfile 只能有一个 FROM（多阶段构建可以有多个）。建议第一轮先用 alpine 版本，后期需要再换 slim。
RUN 执行命令，安装依赖 合并成一条可以减少层数。记得清理缓存：apt-get clean && rm -rf /var/lib/apt/lists/*
COPY 把本地文件复制到镜像 比 ADD 更可控。ADD 会自动解压 tar 包，但行为不明显。我遇到过 ADD 解压导致目录结构错乱的事，后来只用 COPY。
CMD 容器启动时的默认命令 可以被 docker run 的参数覆盖。质控流程里，我习惯把主脚本写成 CMD，方便测试时临时换参数。
ENTRYPOINT 容器启动时的入口 和 CMD 配合使用效果最好——ENTRYPOINT 固定，CMD 提供默认参数。
ENV 设置环境变量 质控版本号、数据库连接串都放这里。别写死，留给 --env-file 注入。
WORKDIR 设置工作目录 相当于 cd。一定要在 RUN 和 COPY 之前设置好，不然文件路径容易乱。

注意：我曾经见过有人在 Dockerfile 里用 ADD https://... 直接下载文件，结果每次构建都重新下载，缓存根本用不上。下载任务应该在 RUN 里配合 curl 或 wget 做，还可以加 --timestamping 优化。

多阶段构建：专治体积焦虑

说实话，我刚开始做质控流程镜像时，体积动不动就上 1GB。编译依赖、测试工具、调试工具全塞了进去。后来发现多阶段构建简直是救星。

多阶段构建的核心理念：一个 Dockerfile 里写多个 FROM，前面的阶段用来编译，后面的阶段只拷贝产物。

举个例子，假设我们有个 Python 质控脚本，需要先编译一个 C 扩展：

# 第一阶段：编译环境
FROM python:3.11-slim AS builder

WORKDIR /app
RUN apt-get update && apt-get install -y \
    gcc \
    libc6-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --user -r requirements.txt

COPY src/ ./src/
RUN python setup.py build_ext --inplace

# 第二阶段：运行环境
FROM python:3.11-slim AS runtime

WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY --from=builder /app/build/ ./build/
COPY --from=builder /app/src/ ./src/

ENV PATH=/root/.local/bin:$PATH
CMD ["python", "src/run_qc.py"]

为什么这样做能省体积？你想想看，gcc、libc6-dev 这些只在编译时有用，运行时根本不需要。把它们留在最终镜像里，等于带了一堆没用的工具。多阶段构建完美解决了这个问题。

我的经验：在质控流程里，我通常分三个阶段：基础工具链（git、wget）、编译环境（gcc、cmake）、运行环境（Python、R、Java）。前两个阶段的产物压缩后可能不超过 50MB，但如果不分离，镜像体积能差 600MB 以上。构建时加上 --target runtime 参数，可以指定只构建生产阶段。

构建时优化：让缓存为你工作

Docker 构建时有一个很聪明的机制——层缓存。如果某层的内容没变，Docker 会直接用缓存层，跳过执行。

利用这个特性，我总结出一套顺序法则：

  1. 最稳定的放最前面——基础镜像、系统包、环境变量
  2. 次稳定的放中间——依赖声明文件（requirements.txt、package.json）
  3. 最常变的放最后——源代码、配置文件

为什么要这样？因为一旦某一层的内容变了，这一层和它后面的所有层都必须重新构建。如果把 COPY . . 放在最前面，那每次修改代码都得重新安装依赖——时间全浪费了。

好的 Dockerfile 大致长这样：

FROM python:3.11-slim AS base

# 第1层：系统级依赖（几乎不变）
RUN apt-get update && apt-get install -y \
    libpq-dev \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 第2层：Python 依赖（代码不变时可以用缓存）
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 第3层：应用代码（常变）
COPY . .
CMD ["python", "main.py"]

关键数据：利用好层缓存后，如果只改代码不改依赖，构建时间从 3 分 20 秒降到了 18 秒。这在质控流程里非常实用——你每天可能要好几次小修改，时间就是成本。

避坑指南

最后分享几个我亲身踩过的坑：

  • 乱用 latest tag——我曾用 FROM ubuntu:latest，结果某天 Ubuntu 发布了新版本，镜像里的软件包冲突，质控流程直接崩溃。现在我用的是 ubuntu:22.04，钉死。
  • CMD 和 ENTRYPOINT 混用——我记得刚学 Docker 那会儿，在同一个 Dockerfile 里写了两个 CMD，结果只有最后一个生效，调试了半天。正确的用法是「一个 CMD + 一个 ENTRYPOINT」，或者只用其中一个。
  • 忽略文件权限——COPY 进来的文件默认是 root 所有，运行时会遇到权限问题。我习惯在 CMD 之前加一行 RUN useradd -m qcuser && chown -R qcuser:qcuser /app，然后 USER qcuser 切换到普通用户运行。
  • 忘记清理敏感信息——有一次我把数据库密码通过 ENV 写进了 Dockerfile，结果所有人都能看到镜像的历史层。后来学会了用 --secret 参数或 docker build --secret 注入敏感信息，历史层里就查不到了。

嗯，镜像构建这一块，说白了就是「越简单越可靠」。别搞花哨的写法，多用官方做法，多测试几轮。质控流程对确定性要求极高，镜像构建也是如此——每次从同一个 Dockerfile 构建，应该得到完全一致的运行环境。

← 上一章 📖 返回目录 下一章 →