Dockerfile

时间 2019-11-20

原文原文链接

Dockerfile 最佳实践

来自官方映像的 6 个 Dockerfile 技巧 - 技术翻译 - 开源中国社区 https://www.oschina.net/translate/6-dockerfile-tips-official-images php

本文是 Docker 官方文档 docs/archive:v1.1 中 Best practices for writing Dockerfiles 的理解和翻译。包含了 Docker 官方对编写 Dockerfile 的最佳实践和建议。这些建议是为了让你写出高效易用的 Dockerfile。Docker 官方强烈建议你听从这些建议（实际上，若是你是在建立官方镜像，你必须得听从这些建议）。python

阅读该文档须要你已经会经过Dockerfile构建镜像，并了解Dockerfile中各条指令的用途。nginx

通常性的指南和建议

容器应该是短暂的

经过 Dockerfile 定义的镜像所产生的容器应该尽量短暂（生命周期短）。“短暂”，意味着能够中止和销毁容器，而且建立一个新容器并部署好所需的设置和配置工做量应该是极小的。git

使用 .dockerignore 文件

通常最好的方法是将 Dockerfile 放置在一个单独地空目录下。而后，将构建镜像所须要的文件添加到目录下。为了提升构建的效率，你也能够在目录下建立一个 .dockerignore 文件来指定要忽略的文件和目录。.dockerignore 文件的排除模式语法和 Git 的 .gitignore 文件相似。github

避免安装没必要要的包

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

一个容器只运行一个进程

在大多数状况下，你应该保证在一个容器中只运行一个进程。将多个应用解耦到不一样容器中，能够保证应用的横向扩展性和重用容器。若是你一个服务依赖于另外一个服务，能够利用容器连接（link）。web

镜像层数尽量少

你须要在 Dockerfile 可读性（也包括长期的可维护性）和减小层数之间作一个平衡。明智并谨慎地考虑你所使用的层数。sql

将多行参数排序

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

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

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

构建缓存

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

可是，若是你想在构建的过程当中使用缓存，你得明白何时会，何时不会找到匹配的镜像。Docker 遵循的基本规则以下：

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

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

Dockerfile 指令

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

FROM

只要有可能，请使用当前官方仓库做为构建你镜像的基础。咱们推荐使用Debian image，由于它被严格控制并保持最小尺寸（当前小于 150 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=""  # Set multiple labels on one line LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"  # 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。

RUN

一如往常，保持你的 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: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.0*。若是以前的镜像使用的是更旧的版本，指定新的版本会致使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、Rails…)，你可能会执行相似于CMD ["apache2","-DFOREGROUND"]形式的命令。实际上，咱们建议任何服务镜像都使用这种形式的命令。

多数状况下，CMD都须要一个交互式的 shell(bash,python,perl,etc)，例如，CMD ["perl","-de0"],CMD ["php","-a"]。使用这种形式意味着，当你执行相似docker run -it python时，你会进入一个准备好的 shell 中。CMD应该在极少的状况下才能以CMD ["param","param"]的形式与ENTRYPOINT协同使用，除非你和你的预期用户都对ENTRYPOINT的工做方式十分熟悉。

EXPOSE

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

对于外部访问，镜像用户能够在执行docker run时使用一个标志来指示如何将指定的端口映射到所选择的端口。对于容器连接，Docker 提供环境变量从接收容器回溯到源容器（例如，MYSQL_PORT_3306_TCP）。

ENV

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

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

最后，ENV也能用于设置常见的版本号，以便维护 version bumps，参考下面的示例：

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

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

若是你的Dockerfiles有多个步骤须要使用上下文中不一样的文件。单独COPY每一个文件，而不是一次性COPY完。这将保证每一个步骤的构建缓存只在特定的文件变化时失效。

例如：

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

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

为了让镜像尽可能小，最好不要使用ADD指令从远程 URL 获取包，而是使用curl和wget。这样你能够在文件提取完以后删掉再也不须要的文件，能够避免在镜像中额外添加一层。（译者注：ADD指令不能和其余指令合并，因此前者ADD指令会单独产生一层镜像。然后者能够将获取、提取、安装、删除合并到同一条RUN指令中，只有一层镜像。）好比，你应该尽可能避免下面这种用法：

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的自动提取（tar）功能的文件或目录，你应该坚持使用COPY。

ENTRYPOINT

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指令用于暴露任何数据库存储区域，配置文件，或容器建立的文件和目录。强烈建议使用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

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

ONBUILD

ONBUILD中的命令会在当前镜像的子镜像构建时执行。能够把ONBUILD命令当成父镜像的Dockerfile传递给子镜像的Dockerfile的指令。

在子镜像的构建过程当中，Docker 会在执行Dockerfile中的任何指令以前，先执行父镜像经过ONBUILD传递的指令。

当从给定镜像构建新镜像时，ONBUILD指令颇有用。例如，你可能会在一个语言栈镜像中使用ONBUILD，语言栈镜像用于在Dockerfile中构建用户使用相应语言编写的任意软件，正如 Ruby 的ONBUILD变体

使用ONBUILD构建的镜像应用一个单独的标签，例如：ruby:1.9-onbuild或ruby:2.0-onbuild。

在ONBUILD中使用ADD或COPY时要格外当心。若是新的构建上下文中缺乏对应的资源，“onbuild”镜像会灾难性地失败。添加一个单独的标签，容许Dockerfile的做者作出选择，将有助于缓解这种状况。

官方仓库示例

这些官方仓库的Dockerfile都是参考典范：