Dockerfile 最佳实践

一般性的指南和建议

容器应该是短暂的

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

使用 .dockerignore 文件

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

使用多阶段构建

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

避免安装不必要的包

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

一个容器只运行一个进程

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

镜像层数尽可能少

你需要在 Dockerfile 可读性（也包括长期的可维护性）和减少层数之间做一个平衡。

将多行参数排序

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

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

  1. RUN apt-get update && apt-get install -y \
  2.   bzr \
  3.   cvs \
  4.   git \
  5.   mercurial \
  6.   subversion

构建缓存

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

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

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

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

Dockerfile 指令

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

FROM

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

为什么说是“比较完整”，因为它缺少 init 系统，会引发类似如下的问题。

LABEL

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

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

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

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

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

关于标签可以接受的键值对，参考 Understanding object labels。关于查询标签信息，参考 Managing labels on objects。

RUN

为了保持 Dockerfile 文件的可读性，可理解性，以及可维护性，建议将长的或复杂的 RUN 指令用反斜杠 \ 分割成多行。

apt-get

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

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

:::tips 永远将 RUN apt-get update 和 apt-get install 组合成一条 RUN 声明。 :::

  1. RUN apt-get update && apt-get install -y \
  2.         package-bar \
  3.     package-baz \
  4.     package-foo

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

  1. FROM ubuntu:18.04
  3. RUN apt-get update
  5. RUN apt-get install -y curl

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

  1. FROM ubuntu:18.04
  3. RUN apt-get update
  5. RUN apt-get install -y curl nginx

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

:::tips 使用 RUN apt-get update && apt-get install -y 可以确保你的 Dockerfiles 每次安装的都是包的最新的版本，而且这个过程不需要进一步的编码或额外干预。这项技术叫作 **cache busting**。 :::

你也可以显示指定一个包的版本号来达到 cache-busting，这就是所谓的固定版本，例如：

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

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

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

  1. RUN apt-get update && apt-get install -y \
  2.     aufs-tools \
  3.     automake \
  4.     build-essential \
  5.     curl \
  6.     dpkg-sig \
  7.     libcap-dev \
  8.     libsqlite3-dev \
  9.     mercurial \
  10.     reprepro \
  11.     ruby1.9.1 \
  12.     ruby1.9.1-dev \
  13.     s3cmd=1.1.* \
  14.  && rm -rf /var/lib/apt/lists/*

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

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

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

CMD

:::tips 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 中。

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

EXPOSE

EXPOSE 指令用于指定容器将要监听的端口。因此，你应该为你的应用程序使用常见的端口。例如，提供 Apache web 服务的镜像应该使用 EXPOSE 80，而提供 MongoDB 服务的镜像使用 EXPOSE 27017。

:::success 对于外部访问，用户可以在执行 docker run 时使用一个标志来指示如何将指定的端口映射到所选择的端口。 :::

ENV

为了方便新程序运行，你可以使用 ENV 来为容器中安装的程序更新 PATH 环境变量。例如使用 ENV PATH /usr/local/nginx/bin:$PATH 来确保 CMD ["nginx"] 能正确运行。

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

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

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

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

ADD 和 COPY

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

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

  1. COPY requirements.txt /tmp/
  3. RUN pip install --requirement /tmp/requirements.txt
  5. COPY . /tmp/

以上如果 requirements.txt 文件不发生变化， RUN pip install 如果不该写则会直接使用缓存内容，加速构建过程。

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

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

比如尽量避免下面的用法：

  1. ADD http://example.com/big.tar.xz /usr/src/things/
  3. RUN tar -xJf /usr/src/things/big.tar.xz -C /usr/src/things
  5. RUN make -C /usr/src/things all

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

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

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

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

ENTRYPOINT

:::tips ENTRYPOINT 的最佳用处是设置镜像的主命令，允许将镜像当成命令本身来运行（用 CMD 提供默认选项）。 :::

例如，下面的示例镜像提供了命令行工具 s3cmd:

  1. ENTRYPOINT ["s3cmd"]
  3. CMD ["--help"]

现在直接运行该镜像创建的容器会显示命令帮助：

  1. $ docker run s3cmd

或者提供正确的参数来执行某个命令：

  1. $ docker run s3cmd ls s3://mybucket

这样镜像名可以当成命令行的参考。

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

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

  1. #!/bin/bash
  2. set -e
  4. if [ "$1" = 'postgres' ]; then
  5.     chown -R postgres "$PGDATA"
  7.     if [ -z "$(ls -A "$PGDATA")" ]; then
  8.         gosu postgres initdb
  9.     fi
  11.     exec gosu postgres "$@"
  12. fi
  14. exec "$@"

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

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

  1. COPY ./docker-entrypoint.sh /
  3. ENTRYPOINT ["/docker-entrypoint.sh"]

该脚本可以让用户用几种不同的方式和 PostgreSQL 交互。你可以很简单地启动 Postgres：

  1. $ docker run postgres

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

  1. $ docker run postgres postgres --help

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

  1. $ docker run --rm -it postgres bash

VOLUME

VOLUME 指令用于暴露任何数据库存储文件，配置文件，或容器创建的文件和目录。

:::tips 强烈建议使用 VOLUME 来管理镜像中的可变部分和用户可以改变的部分。 :::

USER

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

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

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

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

WORKDIR

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

Docker 镜像安全实践

Docker 镜像安全最佳实践速查表

Docker 安全要趁早

shifting_docker_security_left_2019.pdf

其它常见问题

镜像相关

如何批量清理临时镜像文件？

答：可以使用 docker image prune 命令。

如何查看镜像支持的环境变量？

答：可以使用 docker run IMAGE env 命令。

本地的镜像文件都存放在哪里？

答：与 Docker 相关的本地资源默认存放在 **/var/lib/docker/** 目录下，以 overlay2 文件系统为例，其中 containers 目录存放容器信息，image 目录存放镜像信息，overlay2 目录下存放具体的镜像层文件。

碰到网络问题，无法 docker pull 镜像，命令行指定 http_proxy 无效？

答：在 Docker 配置文件中添加 export http_proxy="http://<PROXY_HOST>:<PROXY_PORT>"，之后重启 Docker 服务即可。

容器相关

容器退出后，通过 docker container ls 命令查看不到，数据会丢失么？

答：容器退出后会处于终止（Exited）状态，此时可以通过 **docker container ls -a** 查看。其中的数据也不会丢失，还可以通过 docker start 命令来启动它。只有删除掉容器才会清除所有数据。

如何停止所有正在运行的容器？

  1. $ docker stop $(docker container ls -q)

如何批量清理已经停止的容器？

答：可以使用 docker container prune 命令。

如何获取某个容器的 PID 信息？

  1. $ docker inspect --format '{{ .State.Pid }}' <CONTAINER ID or NAME>

如何获取某个容器的 IP 地址？

  1. $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' <CONTAINER ID or NAME>

如何给容器指定一个固定 IP 地址，而不是每次重启容器 IP 地址都会变？

答：使用以下命令启动容器可以使容器 IP 固定不变

  1. $ docker network create -d bridge --subnet 172.25.0.0/16 my-net
  3. $ docker run --network=my-net --ip=172.25.3.3 -itd --name=my-container busybox

如何临时退出一个正在交互的容器的终端，而不终止它？

答：按 CTRL-p CTRL-q。如果按 CTRL-c 往往会让容器内应用进程终止，进而会终止容器。

使用 docker port 命令映射容器的端口时，系统报错 Error: No public port '80' published for xxx？

  • 创建镜像时 Dockerfile 要通过 EXPOSE 指定正确的开放端口；
  • 容器启动时指定 PublishAllPort = true。

可以在一个容器中同时运行多个应用进程么？

答：一般并不推荐在同一个容器内运行多个应用进程。如果有类似需求，可以通过一些额外的进程管理机制，比如 supervisord 来管理所运行的进程。可以参考：

配置相关

Docker 的配置文件放在哪里，如何修改配置？

答：使用 systemd 的系统（如 Ubuntu 16.04、Centos 等）的配置文件在 /etc/docker/daemon.json。

如何更改 Docker 的默认存储位置？

答：Docker 的默认存储位置是 /var/lib/docker，如果希望将 Docker 的本地文件存储到其他分区，可以使用 Linux 软连接的方式来完成，或者在启动 Docker Daemon 时通过 -g 参数指定，或者修改配置文件 /etc/docker/daemon.json 的 data-root 项 。可以使用 docker system info | grep "Root Dir" 查看当前使用的存储位置。

例如，如下操作将默认存储位置迁移到 /storage/docker：

  1. [root@s26 ~]# df -h
  2. Filesystem                    Size  Used Avail Use% Mounted on
  3. /dev/mapper/VolGroup-lv_root   50G  5.3G   42G  12% /
  4. tmpfs                          48G  228K   48G   1% /dev/shm
  5. /dev/sda1                     485M   40M  420M   9% /boot
  6. /dev/mapper/VolGroup-lv_home  222G  188M  210G   1% /home
  7. /dev/sdb2                     2.7T  323G  2.3T  13% /storage
  9. [root@s26 ~]# service docker stop
  10. [root@s26 ~]# cd /var/lib/
  11. [root@s26 lib]# mv docker /storage/
  12. [root@s26 lib]# ln -s /storage/docker/ docker
  14. [root@s26 lib]# ls -la docker
  15. lrwxrwxrwx. 1 root root 15 11月 17 13:43 docker -> /storage/docker
  17. [root@s26 lib]# service docker start

如何解决 Ubuntu 上生成的 Docker image 中内网 DNS 配置不正确？

答：Ubuntu 上默认启动了 dnsmasq，一个轻量级的 DNS 和 DHCP 服务器，所以在 /etc/resolv.conf 中看到的是 nameserver 127.0.1.1, 这里对应的是 dnsmasq 的地址而不是真实的内网 dns 地址，真实的地址由 dnsmasq 维护。故生成 docker image 时容器中的 /etc/resolv.conf 中也没有加载真实的地址，无法解析内网域名。可以通过以下方式之一解决：

  • 在 docker 配置文件 /etc/docker/daemon.json 添加真实内网 dns 地址
  • 关掉 dnsmasq，此时在 /etc/resolv.conf 可以看到真实内网 dns 地址
  • 生成 docker image 时指定 dns 配置

Docker 与虚拟化

Docker 与 LXC（Linux Container）有何不同？

答：LXC 利用 Linux 上相关技术实现了容器。Docker 则在如下的几个方面进行了改进：

  • 移植性：通过抽象容器配置，容器可以实现从一个平台移植到另一个平台；
  • 镜像系统：基于 OverlayFS 的镜像系统为容器的分发带来了很多的便利，同时共同的镜像层只需要存储一份，实现高效率的存储；
  • 版本管理：类似于 Git 的版本管理理念，用户可以更方便的创建、管理镜像文件；
  • 仓库系统：仓库系统大大降低了镜像的分发和管理的成本；
  • 周边工具：各种现有工具（配置管理、云平台）对 Docker 的支持，以及基于 Docker的 PaaS、CI 等系统，让 Docker 的应用更加方便和多样化。

Docker 与 Vagrant 有何不同？

答：两者的定位完全不同。

  • Vagrant 类似 Boot2Docker（一款运行 Docker 的最小内核），是一套虚拟机的管理环境。Vagrant 可以在多种系统上和虚拟机软件中运行，可以在 Windows，Mac 等非 Linux 平台上为 Docker 提供支持，自身具有较好的包装性和移植性。
  • 原生的 Docker 自身只能运行在 Linux 平台上，但启动和运行的性能都比虚拟机要快，往往更适合快速开发和部署应用的场景。

:::info 简单说：Vagrant 适合用来管理虚拟机，而 Docker 适合用来管理应用环境。 :::

开发环境中 Docker 和 Vagrant 该如何选择？

答：Docker 不是虚拟机，而是进程隔离，对于资源的消耗很少，但是目前需要 Linux 环境支持。Vagrant 是虚拟机上做的封装，虚拟机本身会消耗资源。

:::tips 如果本地使用的 Linux 环境，推荐都使用 Docker。 :::

如果本地使用的是 macOS 或者 Windows 环境，那就需要开虚拟机，单一开发环境下 Vagrant 更简单；多环境开发下推荐在 Vagrant 里面再使用 Docker 进行环境隔离。

其它

仓库（Repository）、注册服务器（Registry）、注册索引（Index） 有何关系？

答：首先，仓库是存放一组关联镜像的集合，比如同一个应用的不同版本的镜像。

注册服务器是存放实际的镜像文件的地方。注册索引则负责维护用户的账号、权限、搜索、标签等的管理。因此，注册服务器利用注册索引来实现认证等管理。

Docker 能在非 Linux 平台（比如 Windows 或 macOS ）上运行么？

答：完全可以。安装方法请查看 安装 Docker 一节。

如何将一台宿主主机的 Docker 环境迁移到另外一台宿主主机？

答：停止 Docker 服务。将整个 Docker 存储文件夹复制到另外一台宿主主机，然后调整另外一台宿主主机的配置即可。