附录2、Dockerfile 参考及最佳实践

本文是《Docker必知必会系列》第十篇，原文发布于个人博客：悟尘纪。

上一篇：Docker必知必会系列（附录1）：Docker 常用命令及示例

一、Dockerfile 简介

Dockfile 是一种被 Docker 程序解释的脚本，由一条一条的指令组成，每条指令对应 Linux 下面的一条命令。

Docker 通过从Dockerfile文本文件中读取指令来自动构建镜像，该文本文件按顺序包含构建镜像所需的所有命令。遵循特定的格式和指令集，您可以在 Dockerfile 参考 中找到详细信息。

Docker 镜像由只读层组成，每个只读层代表一个 Dockerfile 指令。各个层堆叠在一起，每个层都是上一层变化的增量。运行镜像并生成容器时，可以在基础层之上添加一个新的可写层（“容器层”）。对运行中容器所做的所有更改（例如写入新文件，修改现有文件和删除文件）都将写入到此可写容器层。

二、Dockerfile 编写建议

Dockerfile 的指令是忽略大小写的，建议使用大写，使用#作为注释，每一行只支持一条指令，每条指令可以携带多个参数。Dockerfile 常用指令：

类型	命令
基础镜像信息	FROM
维护者信息	MAINTAINER
镜像操作指令	RUN、COPY、ADD、EXPOSE、WORKDIR、ONBUILD、USER、VOLUME 等
容器启动时执行指令	CMD、ENTRYPOINT

下面针对 Dockerfile 中各种指令的最佳编写方式给出建议。

FROM（指定基础镜像）

该指令有两种格式：使用 FROM 指定基础镜像为该 image 的最后修改版本。或者实使用 FROM : 指定基础 image 为该 image 的一个 tag 版本。

尽可能使用官方仓库当前版本作为你的基础镜像。推荐使用 Alpine 镜像，因为它被严格控制并保持最小尺寸（目前小于 5 MB），但它仍然是一个完整的发行版。

LABEL（向镜像添加元数据）

你可以给镜像添加标签来帮助组织镜像、记录许可信息、辅助自动化构建等。每个标签一行，由 LABEL 开头加上一个或多个键值对。下面的示例展示了各种不同的可能格式。# 开头的行是注释内容。

注意：如果你的字符串中包含空格，必须将字符串放入引号中或者对空格使用转义。如果字符串内容本身就包含引号，必须对引号使用转义。

# Set one or more individual labels
LABEL com.example.version="0.0.1-beta"
LABEL vendor="ACME Incorporated"
LABEL com.example.release-date="2015-02-12"
LABEL com.example.version.is-production=""

一个镜像可以包含多个标签，可以在一行中指定多个标签，但建议将多个标签放入到一个 LABEL 指令中。

# Set multiple labels at once, using line-continuation characters to break long lines
LABEL vendor=ACME\ Incorporated \
    com.example.is-beta= \
    com.example.is-production="" \
    com.example.version="0.0.1-beta" \
    com.example.release-date="2015-02-12"

关于标签的更多信息，可以参考 Understanding object labels。

RUN（一般用于安装软件）

RUN 指令是在新镜像内部执行的命令，可以运行任何被基础 image 支持的命令，如：执行某些动作、安装系统软件、配置系统信息之类。为了保持 Dockerfile 文件的可读性，可理解性，以及可维护性，建议将长的或复杂的 RUN 指令用反斜杠 \ 分割成多行。

apt-get

RUN 指令最常见的用法是安装包用的 apt-get。因为 RUN apt-get 指令会安装包，所以有几个问题需要注意。

不要使用 RUN apt-get upgrade 或 dist-upgrade，因为许多基础镜像中的「必须」包不会在一个非特权容器中升级。如果基础镜像中的某个包过时了，你应该联系它的维护者。如果你确定某个特定的包，比如 foo，需要升级，使用 apt-get install -y foo 就行，该指令会自动升级 foo 包。

永远将 RUN apt-get update 和 apt-get install 组合成一条 RUN 声明，例如：

RUN apt-get update && apt-get install -y \
    package-bar \
    package-baz \
    package-foo

将 apt-get update 放在一条单独的 RUN 声明中会导致缓存问题以及后续的 apt-get install 失败。比如，假设你有一个 Dockerfile 文件：

FROM ubuntu:18.04
RUN apt-get update
RUN apt-get install -y curl

构建镜像后，所有的层都在 Docker 的缓存中。假设你后来又修改了其中的 apt-get install 添加了一个包：

FROM ubuntu:18.04
RUN apt-get update
RUN apt-get install -y curl nginx

Docker 发现修改后的 RUN apt-get update 指令和之前的完全一样。所以，apt-get update 不会执行，而是使用之前的缓存镜像。因为 apt-get update 没有运行，后面的 apt-get install 可能安装的是过时的 curl 和 nginx 版本。

使用 RUN apt-get update && apt-get install -y 可以确保你的 Dockerfiles 每次安装的都是包的最新的版本，而且这个过程不需要进一步的编码或额外干预。这项技术叫作 cache busting。你也可以显示指定一个包的版本号来达到 cache-busting，这就是所谓的固定版本，例如：

RUN apt-get update && apt-get install -y \
    package-bar \
    package-baz \
    package-foo=1.3.*

固定版本会迫使构建过程检索特定的版本，而不管缓存中有什么。这项技术也可以减少因所需包中未预料到的变化而导致的失败。

下面是一个 RUN 指令的示例模板，展示了所有关于 apt-get 的建议。

RUN apt-get update && apt-get install -y \
    aufs-tools \
    automake \
    build-essential \
    curl \
    dpkg-sig \
    libcap-dev \
    libsqlite3-dev \
    mercurial \
    reprepro \
    ruby1.9.1 \
    ruby1.9.1-dev \
    s3cmd=1.1.* \
 && rm -rf /var/lib/apt/lists/*

其中 s3cmd 指令指定了一个版本号 1.1.*。如果之前的镜像使用的是更旧的版本，指定新的版本会导致 apt-get udpate 缓存失效并确保安装的是新版本。

另外，清理掉 apt 缓存 var/lib/apt/lists 可以减小镜像大小。因为 RUN 指令的开头为 apt-get udpate，包缓存总是会在 apt-get install 之前刷新。

注意：官方的 Debian 和 Ubuntu 镜像会自动运行 apt-get clean，所以不需要显式的调用 apt-get clean。

CMD（设置容器启动时默认操作）

CMD 指令的主要目的是为正在执行的容器提供缺省值。指定容器启动时执行的操作。该操作可以是执行自定义脚本，也可以是执行系统命令。该指令只能在文件中存在一次，如果有多个，则只执行最后一条。

CMD 大多数情况下都应该以 CMD ["executable", "param1", "param2"...] 的形式使用。因此，如果创建镜像的目的是为了部署某个服务(比如 Apache)，你可能会执行类似于 CMD ["apache2", "-DFOREGROUND"] 形式的命令。我们建议任何服务镜像都使用这种形式的命令。

多数情况下，CMD 都需要一个交互式的 shell (bash, Python, perl 等)，例如 CMD ["perl", "-de0"]，或者 CMD ["PHP", "-a"]。使用这种形式意味着，当你执行类似 docker run -it python 时，你会进入一个准备好的 shell 中。

CMD 应该在极少的情况下以 CMD ["param", "param"] 的形式与 ENTRYPOINT 协同使用，除非你和你的镜像使用者都对 ENTRYPOINT 的工作方式十分熟悉。

注意: 不要将 RUN 与 CMD 混淆。 Run 实际上是运行一个命令并提交结果; CMD 在构建时不执行任何操作，但会指定镜像的预期命令。

ENTRYPOINT（设置镜像主命令）

ENTRYPOINT 的最佳用处是设置镜像的主命令，与 CMD 非常相似。当 CMD 和 ENTRYPOINT 都存在时，CMD 的指令变成了 ENTRYPOINT 指令的参数。并且此 CMD 提供的参数会被 docker run 后面的命令覆盖。

FROM ubuntu
CMD ["-l"]
ENTRYPOINT ["/usr/bin/ls"]

如果你使用 CMD 命令且 CMD 是一个完整的可执行的命令，那么 CMD 指令和 ENTRYPOINT 会互相覆盖只有最后一个 CMD 或者 ENTRYPOINT 有效。

# CMD指令将不会被执行，只有ENTRYPOINT指令被执行
CMD echo “Hello, World!”
ENTRYPOINT ls -l

ENTRYPOINT 指令也可以结合一个辅助脚本使用，和前面命令行风格类似，即使启动工具需要不止一个步骤。

例如，Postgres 官方镜像使用下面的脚本作为 ENTRYPOINT：

#!/bin/bash
set -e
if [ "$1" = 'postgres' ]; then
    chown -R postgres "$PGDATA"
    if [ -z "$(ls -A "$PGDATA")" ]; then
        gosu postgres initdb
    fi
    exec gosu postgres "$@"
fi
exec "$@"

注意：该脚本使用了 Bash 的内置命令 exec，所以最后运行的进程就是容器的 PID 为 1 的进程。这样，进程就可以接收到任何发送给容器的 Unix 信号了。

该辅助脚本被拷贝到容器，并在容器启动时通过 ENTRYPOINT 执行：

COPY ./docker-entrypoint.sh /

ENTRYPOINT ["/docker-entrypoint.sh"]

该脚本可以让用户用几种不同的方式和 Postgres 交互。

你可以很简单地启动 Postgres：

docker run postgres

也可以执行 Postgres 并传递参数：

docker run postgres postgres --help

最后，你还可以启动另外一个完全不同的工具，比如 Bash：

docker run --rm -it postgres bash

EXPOSE（暴露容器端口）

EXPOSE 指令用于指将容器中的端口映射成宿主机的某个端口。当你需要访问容器的时候，可以不使用容器的 IP 地址而是使用宿主机器的 IP 地址和映射后的端口。因此，你应该为你的应用程序使用常见的端口。例如，提供 Apache web 服务的镜像应该使用 EXPOSE 80，而提供 MongoDB 服务的镜像使用 EXPOSE 27017。

对于外部访问，用户可以在执行 docker run 时使用 -p 标志来将容器的指定端口映射到宿主机所选择的端口。

ENV（设置环境变量）

为了方便新程序运行，你可以使用 ENV 来为容器中安装的程序更新 PATH 环境变量。

例如使用 ENV PATH /usr/local/nginx/bin:$PATH 来确保 CMD ["nginx"] 能正确运行。

ENV 指令也可用于为你想要容器化的服务提供必要的环境变量，比如 Postgres 需要的 PGDATA。

最后，ENV 也能用于设置常见的版本号，比如下面的示例：

ENV PG_MAJOR 9.3
ENV PG_VERSION 9.3.4
RUN curl -SL http://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress && …
ENV PATH /usr/local/postgres-$PG_MAJOR/bin:$PATH

类似于程序中的常量，这种方法可以让你只需改变 ENV 指令来自动的改变容器中的软件版本。

在使用 ENV 设置环境变量时，有几点需要注意：

• 1）具有传递性，也就是当前镜像被用作其它镜像的基础镜像时，新镜像会拥有当前这个基础镜像所有的环境变量
• 2）ENV 定义的环境变量，可以在 dockerfile 被后面的所有指令（CMD 除外）中使用，但不能被 docker run 的命令参数引用

ADD 和 COPY（复制文件到容器）

虽然 ADD 和 COPY 功能类似，但一般优先使用 COPY。因为它比 ADD 更透明。COPY 只支持简单将本地文件拷贝到容器中，而 ADD 有一些并不明显的功能（比如本地 tar 提取和远程 URL 支持）。因此，ADD 的最佳用例是将本地 tar 文件自动提取到镜像中，例如 ADD rootfs.tar.xz。

如果你的 Dockerfile 有多个步骤需要使用上下文中不同的文件。单独 COPY 每个文件，而不是一次性的 COPY 所有文件，这将保证每个步骤的构建缓存只在特定的文件变化时失效。例如：

COPY requirements.txt /tmp/
RUN pip install --requirement /tmp/requirements.txt
COPY . /tmp/

如果将 COPY . /tmp/ 放置在 RUN 指令之前，只要 . 目录中任何一个文件变化，都会导致后续指令的缓存失效。

为了让镜像尽量小，最好不要使用 ADD 指令从远程 URL 获取包，而是使用 curl 和 wget。这样你可以在文件提取完之后删掉不再需要的文件来避免在镜像中额外添加一层。比如尽量避免下面的用法：

ADD http://example.com/big.tar.xz /usr/src/things/

RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things

RUN make -C /usr/src/things all

而是应该使用下面这种方法：

RUN mkdir -p /usr/src/things \
    && curl -SL http://example.com/big.tar.xz \
    | tar -xJC /usr/src/things \
    && make -C /usr/src/things all

上面使用的管道操作，所以没有中间文件需要删除。

对于其他不需要 ADD 的自动提取功能的文件或目录，你应该使用 COPY。

VOLUME（指定挂载点）

VOLUME 指令用于暴露任何数据库存储文件，配置文件，或容器创建的文件和目录。强烈建议使用 VOLUME 来管理镜像中的可变部分和用户可以改变的部分。

USER（指定运行镜像时使用的用户）

如果某个服务不需要特权执行，建议使用 USER 指令切换到非 root 用户。先在 Dockerfile 中使用类似 RUN groupadd -r postgres && useradd -r -g postgres postgres 的指令创建用户和用户组。

注意：在镜像中，用户和用户组每次被分配的 UID/GID 都是不确定的，下次重新构建镜像时被分配到的 UID/GID 可能会不一样。如果要依赖确定的 UID/GID，你应该显示的指定一个 UID/GID。

你应该避免使用 sudo，因为它不可预期的 TTY 和信号转发行为可能造成的问题比它能解决的问题还多。如果你真的需要和 sudo 类似的功能（例如，以 root 权限初始化某个守护进程，以非 root 权限执行它），你可以使用 gosu。

最后，为了减少层数和复杂度，避免频繁地使用 USER 来回切换用户。

WORKDIR（切换目录）

为跟在它后面的 RUN、 CMD、 ENTRYPOINT、 COPY 和 ADD 指令设置工作目录。其效果类似于 Linux 命名中的cd 命令，用于目录的切换，但是和 cd 不一样的是：如果切换到的目录不存在，WORKDIR 会为此创建目录。

为了清晰性和可靠性，你应该总是在 WORKDIR 中使用绝对路径。另外，你应该使用 WORKDIR 来替代类似于 RUN cd ... && do-something 的指令，后者难以阅读、排错和维护。

ONBUILD（在子镜像中执行）

Onbuild 指令向镜像添加一个触发器指令，以便在以后将该镜像用作另一个构建的基础镜像时执行。 意思就是：这个镜像创建时不会执行，以后，如果其它镜像以这个镜像为基础，会先执行这个镜像的 ONBUILD 命令。

任何构建指令都可以注册为触发器。如果 Onbuild 指令执行失败，子镜像的 FROM 指令就会中止。执行完触发器后，将从最终图像中清除触发器。换句话说，它们不会传递到“孙子代”版本镜像中。

ARG（设置构建镜像时变量）

ARG 定义的变量只在建立 image 时有效，建立完成后变量就失效消失。用户可以在 docker build 时使用带有--build-arg = 标志的命令将变量传递给构建器。

同时使用ARG或ENV指令为 RUN 指令设置变量时，ENV 指令定义的环境变量 会始终覆盖ARG同名指令。例如:

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER v1.0.0
RUN echo $CONT_IMG_VER

然后，使用以下命令构建镜像：

docker build --build-arg CONT_IMG_VER=v2.0.1 .

在情况下，RUN指令将使用v1.0.0，而不是ARG用户传递的值：v2.0.1。

Docker 有一组预定义的 ARG 变量，您可以在 Dockerfile 中不使用相应的 ARG 指令而使用它们：

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy
• FTP_PROXY
• ftp_proxy
• NO_PROXY
• no_proxy

要使用它们，只需在命令行上使用 --build-arg = 标志赋值。默认情况下，这些预定义的变量被排除在 docker 历史记录的输出之外。 这可以降低意外泄漏 httpproxy 变量中敏感的身份验证信息的风险。

例如，使用 --build-arg HTTP_PROXY=http://user:[email protected] 构建镜像时，httpproxy 变量的值在 docker 历史记录中不可用，也不会被缓存。

三、一般准则和建议

容器应该是短暂的

通过 Dockerfile 构建的镜像所启动的容器应该尽可能短暂（生命周期短）。「短暂」意味着可以停止和销毁容器，并且创建一个新容器并部署好所需的设置和配置的工作量应该是极小的。

使用 .dockerignore 文件

使用 Dockerfile 构建镜像时最好将 Dockerfile 放置在一个新建的空目录下。然后将构建镜像所需要的文件添加到该目录中。为了提高构建镜像的效率，你可以在目录下新建一个 .dockerignore 文件来指定要忽略的文件和目录。.dockerignore 文件的排除模式语法和 Git 的 .gitignore 文件相似。

使用多阶段构建

在 Docker 17.05 以上版本中，你可以使用多阶段构建来减少所构建镜像的大小。

避免安装不必要的包

为了降低复杂性、减少依赖、减小文件大小、节约构建时间，你应该避免安装任何不必要的包。例如，不要在数据库镜像中包含一个文本编辑器。

一个容器只运行一个进程

应该保证在一个容器中只运行一个进程。将多个应用解耦到不同容器中，保证了容器的横向扩展和复用。例如 web 应用应该包含三个容器：web 应用、数据库、缓存。

如果容器互相依赖，你可以使用 Docker 自定义网络 来把这些容器连接起来。

镜像层数尽可能少

每执行一个指令，都会有一次镜像的提交，镜像是分层的结构，需要在 Dockerfile 可读性（也包括长期的可维护性）和减少层数之间做一个平衡。

将多行参数排序

将多行参数按字母顺序排序（比如要安装多个包时）。这可以帮助你避免重复包含同一个包，更新包列表时也更容易。也便于 PRs 阅读和审查。建议在反斜杠符号 \ 之前添加一个空格，以增加可读性。

下面是来自 buildpack-deps 镜像的例子：

RUN apt-get update && apt-get install -y \
  bzr \
  cvs \
  git \
  mercurial \
  subversion

使用构建缓存

在镜像的构建过程中，Docker 会遍历 Dockerfile 文件中的指令，然后按顺序执行。在执行每条指令之前，Docker 都会在缓存中查找是否已经存在可重用的镜像，如果有就使用现存的镜像，不再重复创建。如果你不想在构建过程中使用缓存，你可以在 docker build 命令中使用 --no-cache=true 选项。

但是，如果你想在构建的过程中使用缓存，你得明白什么时候会或不会找到匹配的镜像，遵循的基本规则如下：

• 从一个基础镜像开始（FROM 指令指定），下一条指令将和该基础镜像的所有子镜像进行匹配，检查这些子镜像被创建时使用的指令是否和被检查的指令完全一样。如果不是，则缓存失效。
• 在大多数情况下，只需要简单地对比 Dockerfile 中的指令和子镜像。然而，有些指令需要更多的检查和解释。
• 对于 ADD 和 COPY 指令，镜像中对应文件的内容也会被检查，每个文件都会计算出一个校验和。文件的最后修改时间和最后访问时间不会纳入校验。在缓存的查找过程中，会将这些校验和和已存在镜像中的文件校验和进行对比。如果文件有任何改变，比如内容和元数据，则缓存失效。
• 除了 ADD 和 COPY 指令，缓存匹配过程不会查看临时容器中的文件来决定缓存是否匹配。例如，当执行完 RUN apt-get -y update 指令后，容器中一些文件被更新，但 Docker 不会检查这些文件。这种情况下，只有指令字符串本身被用来匹配缓存。

一旦缓存失效，所有后续的 Dockerfile 指令都将产生新的镜像，缓存不会被使用。

四、官方镜像示例

这些官方镜像的 Dockerfile 都是参考典范：https://github.com/docker-library/docs。

所有 Markdown 文件都通过 markdownfmt 进行运行（仅添加了一些较小的差异首选项和较小的DockerHub兼容性更改），并通过Travis CI 验证其格式正确。

参考

• 官方文档：Dockerfile reference
• 官方文档：Best practices for writing Dockerfiles

相关文章

• 上一篇：Docker必知必会系列（附录1）：Docker 常用命令及示例
• 下一篇：Docker必知必会系列（附录3）：Docker-compose 命令使用指南