本附录是笔者对 Docker 官方文档中 Best practices for writing Dockerfiles 的理解与翻译。
通过 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
中各种指令的最佳编写方式给出建议。
尽可能使用当前官方仓库作为你构建镜像的基础。推荐使用 Alpine 镜像,因为它被严格控制并保持最小尺寸(目前小于 5 MB),但它仍然是一个完整的发行版。
你可以给镜像添加标签来帮助组织镜像、记录许可信息、辅助自动化构建等。每个标签一行,由 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。关于查询标签信息,参考 Managing labels on objects。
为了保持 Dockerfile
文件的可读性,可理解性,以及可维护性,建议将长的或复杂的 RUN
指令用反斜杠 \
分割成多行。
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:14.04
RUN apt-get update
RUN apt-get install -y curl
构建镜像后,所有的层都在 Docker 的缓存中。假设你后来又修改了其中的 apt-get install
添加了一个包:
FROM ubuntu:14.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 ["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
的工作方式十分熟悉。
EXPOSE
指令用于指定容器将要监听的端口。因此,你应该为你的应用程序使用常见的端口。例如,提供 Apache
web 服务的镜像应该使用 EXPOSE 80
,而提供 MongoDB
服务的镜像使用 EXPOSE 27017
。
对于外部访问,用户可以在执行 docker run
时使用一个标志来指示如何将指定的端口映射到所选择的端口。
为了方便新程序运行,你可以使用 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
指令来自动的改变容器中的软件版本。
虽然 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
。
ENTRYPOINT
的最佳用处是设置镜像的主命令,允许将镜像当成命令本身来运行(用 CMD
提供默认选项)。
例如,下面的示例镜像提供了命令行工具 s3cmd
:
ENTRYPOINT ["s3cmd"]
CMD ["--help"]
现在直接运行该镜像创建的容器会显示命令帮助:
$ docker run s3cmd
或者提供正确的参数来执行某个命令:
$ docker run s3cmd ls s3://mybucket
这样镜像名可以当成命令行的参考。
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
VOLUME
指令用于暴露任何数据库存储文件,配置文件,或容器创建的文件和目录。强烈建议使用 VOLUME
来管理镜像中的可变部分和用户可以改变的部分。
如果某个服务不需要特权执行,建议使用 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
中使用绝对路径。另外,你应该使用 WORKDIR
来替代类似于 RUN cd ... && do-something
的指令,后者难以阅读、排错和维护。
这些官方仓库的 Dockerfile 都是参考典范:https://github.com/docker-library/docs