> For the complete documentation index, see [llms.txt](https://camelgemonion.gitbook.io/docker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://camelgemonion.gitbook.io/docker/dockerfile-zui-jia-shi-jian.md). # Dockerfile最佳实践 Dockerfile包含一组指令集合。Docker镜像由每一条指令生成的只读层构成。镜像层是栈式的，并且每一层都基于上一层的变化。 ``` FROM ubuntu:18.04 COPY . /app RUN make /app CMD python /app/app.py ``` * `FROM` 创建一个基于ubuntu:18.04的镜像层 * `COPY` 将当前目录下面的文件拷贝到镜像中 * `RUN` 运行make指令构建应用 * `CMD` 指定容器需要运行的命令 当使用Docker镜像生成一个docker容器时，会在容器的最上层添加一个可写层，这个可写层称为容器层。在容器中对文件的增删改都会写入容器层。 ## 构建上下文 docker镜像的构建上下文与Dockerfile文件的位置无关。如果在构建镜像时，Dockerfile正好处于构建上下文之中，且文件的名字为Dockerfile，则可以在构建镜像时省略Dockerfile的指定。 例如： ``` docker build -t camelgem/test . ``` 如果Dockerfile不在当前的构建上下文路径中，且Dockerfile文件的名字不为Dockerfile，则必须使用-f选项指定Dockerfile的路径和名称。 ``` docker build -f MyDockerfile -t camelgem/test . ``` 构建镜像时，不要将不需要的文件一起打包到镜像中，这些无用的文件增加镜像的大小以及镜像构建的速度。 当构建镜像时，终端会输出一条信息，提示当前构建镜像的构建上下文有多大。 ``` Sending build context to Docker daemon 187.8MB ``` ## 通过管道来构建镜像 除了通过创建Dockerfile文件来构建镜像以外，我们也可以使用管道来临时构建镜像。 例如下面的示例： ``` echo -e 'FROM busybox\nRUN echo "hello world"' | docker build - docker build -< /number ``` Docker使用/bin/sh -c解释器来执行这些命令，命令执行的成功与否取决于管道中最后一条命令执行的退出状态码。上面的例子中，即使wget命令执行失败了，此构建步骤也会成功并生成新的镜像。 如果希望命令在任何一个阶段出现错误都会失败，可以使用set -o pipefail && 来确保一个非预期的错误不会导致构建的意外成功。见下面示例： ``` RUN set -o pipefail && wget -O - https://some.site | wc -l > /number ``` {% hint style="info" %} 并不是所有shell都支持 -o pipefail选项。在这种情况下，可以考虑使用RUN指令来明确运行一个支持次选项的shell。 例如 RUN \["/bin/bash", "-c", "set -o pipefail && wget -O - | wc -l > /number"] {% endhint %} ### CMD CMD指令应用于运行镜像像中带有参数的软件。CMD应该始终使用CMD \["executable"、"param1"、"param 2"...]的形式。因此，如果镜像用于运行一个服务，如Apache和Rails，我么将运行类似CMD \["Apache2"，"-DFOREGROUND"]。事实上，对于任何基于服务的镜像，都建议使用这种形式的指令。 在大部分情况下，CMD应该被提供一个交互shell，例如bash，python和perl。例如，CMD \["perl", "de0"], CMD \["python"], 或者CMD \["php", "-a"]。使用这种形式意味着当我们执行某些命令例如docker run -it python时，我们将进入一个可用的shell终端。 CMD应该尽可能少的以 CMD\["param1"、"param2"]的形式与ENTRYPOINT一起使用，除非用户已经非常熟悉ENTRYPOINT的工作原理。 ### EXPOSE EXPOSE指令指示容器侦听连接的端口。因此，我们应该让我们的应用使用常见的传统端口。例如，包含 Apache Web 服务器的镜像将使用EXPOSE 80，而包含MongoDB的镜像将使用EXPOSE 27017等。 对于外部访问，用户可以执行带有flag的docker run，指示如何将指定端口映射到自己选择的端口。对于容器链接，Docker为从接收容器返回源的路径（即MYSQL\_PORT\_3306\_TCP）提供环境变量。 ### ENV 可以使用ENV来为容器中安装的软件更新环境变量，ENV=/usr/local/nginx/bin:$PATH，确保CMD \["nginx"]能正常运行。 ENV也可以用于为需要容器化的应用提供需要的环境变量，例如Postgre’s PGDATA。 ENV还可以用于设置通过的版本号，以便版本号更容器维护，见下面的例子： ``` ENV PG_MAJOR=9.3 ENV PG_VERSION=9.3.4 RUN curl -SL https://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgress && … ENV PATH=/usr/local/postgres-$PG_MAJOR/bin:$PATH ``` Dockerfile中设置的ENV变量值，也可以在命令行指定新的值来覆盖老的值，见示例： ``` FROM perl ENV name=camelgem RUN echo $name ``` �输出 ``` CACHED [1/2] FROM docker.io/library/perl 0.0s => [2/2] RUN echo camelgem ``` 通过命令行修改ENV设置的值 ``` docker % docker run -e name=kobe -it perl /bin/sh # echo $name kobe # 值变为kobe ``` 每一个ENV行会创建一个新的间接层，就是RUN指令那样。这意味着即使在后面的层unset 环境变量，它也依然会持久的保存在该层中，不会被丢弃。见下面示例： ``` FROM alpine ENV ADMIN_USER="mark" RUN echo $ADMIN_USER > ./mark RUN unset ADMIN_USER ``` ``` $ docker run --rm test sh -c 'echo $ADMIN_USER' mark ``` 为了防止这种情况，并真正取消设置环境变量，使用带有shell命令的 RUN 命令，将变量的设置、使用和取消设置为单个层。我们可以将命令使用;或&&分隔。如果使用第二种方法，并且其中一个命令执行失败，则docker build也会失败。这通常是个好主意。使用\作为Linux Dockerfile的行继续字符，可提高可读性。我们还可以将所有命令放入外壳脚本中，并让 RUN 命令运行该shell脚本。 ``` FROM alpine RUN export ADMIN_USER="mark" \ && echo $ADMIN_USER > ./mark \ && unset ADMIN_USER CMD sh ``` ``` $ docker run --rm test sh -c 'echo $ADMIN_USER' ``` ### ADD或COPY ADD和COPY功能非常类似，通常来说，优先使用COPY。这是因为COPY比ADD更加透明。COPY只支持基本的将本地文件拷贝到容器中，而ADD拥有其他的一些特性，例如本地解压缩包或支持远端URL。ADD最佳使用方式是将本地的压缩文件解压到容器镜像中。 如果需要拷贝多个文件到容器镜像中，使用COPY指令单独拷贝它们，不要使用单个COPY指令拷贝多个文件。这样当后续文件内容修改以后，只确保每一个构建步骤中的缓存失效，这样更加高效。 例如： ``` COPY requirements.txt /tmp/ RUN pip install --requirement /tmp/requirements.txt COPY . /tmp/ ``` ### ENTRYPOINT ENTRYPOINT的最佳使用方式是作为镜像的主命令。允许镜像指定里面指令的命令，并且以CMD中指定的参数作为默认参数。 见下面示例： ``` ENTRYPOINT ["s3cmd"] CMD ["--help"] ``` 现在镜像可以像下面这样显示命令的使用帮助： ``` $ docker run s3cmd ``` 或使用正确的参数执行命令： ``` $ docker run s3cmd ls s3://mybucket ``` 这很有用，因为镜像名称可以作为对二进制文件的引用，如上面的命令所示。 ENTRYPOINT指令还可以与helper脚本结合使用，允许它以类似于上述命令的方式运行，即使启动工具可能需要多个步骤。 例如，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 "$@" ``` 帮助脚本被拷贝容器镜像中，并通过ENTRYPOINT执行： ``` COPY ./docker-entrypoint.sh / ENTRYPOINT ["/docker-entrypoint.sh"] CMD ["postgres"] ``` 脚本为我们提供了简单的交互，可以像下面这样启动容器 ``` $ docker run postgres ``` 或者传递参数给它： ``` $ docker run postgres postgres --help ``` 最后，也可以被用来启动一个不同的工具，比如Bash ``` $ docker run --rm -it postgres bash ``` ### VOLUME 应使用卷OLUME指令来暴露docker容器创建的任何数据库存储区域、配置存储或文件/文件夹。强烈建议将VOLUME用于镜像的任何可变和/或用户服务部分。 ### USER 如果一个应用不需要使用特权用户来运行，则可以使用USER来切换用户。在切换前，在Dockerfile中使用RUN指令来生成一个用户： ``` RUN groupadd -r postgres && useradd --no-log-init -r -g postgres postgres ``` {% hint style="info" %} 镜像中的用户和组被分配一个不确定的UID/GID，因为无论镜像重新构建与否，都会分配“下一个”UID/GID。因此，有必要的话，我们应该指定一个明确的UID/GID。 {% endhint %} ### WORKDIR 为了清晰度和可靠性，我们应该始终使用WORKDIR绝对路径进行工作。此外，我们应该使用WORKDIR，而不是像RUN cd..&&之类的指令，这些指令很难读取、不利于排除故障和维护。 ### ONBUILD ONBUILD指令会在当前镜像构建完成以后被执行。ONBUILD会在使用当前镜像的子镜像中被执行。可以认为ONBUILD指令是父Dockerfile提供给子Dockerfile的指令。 ONBUILD会在任何子Dockerfile指令之前被执行。 ONBUILD对于那些将要使用FROM来指定一个镜像的镜像非常有用。例如，我们可以使用ONBUILD在Dockerfile中来构建一个基于特定语言的软件。 在ONBUILD中使用COPY或ADD指令时，需要特别注意，如果子镜像中的构建上下文中不存在COPY或ADD指令中指定的文件或目录，则构建会执行失败。