Dockerfile 简介

Dockerfile 是一个文本文件,其内包含了一条条的 指令(Instruction),每一条指令构建一层,因此每一条指令的内容,就是描述该层应当如何构建。

docker build 命令

docker build 命令使用 Dockerfile 进行镜像构建。其格式为:

docker build [选项] <上下文路径/URL/->

docker build 命令常用选项

选项 说明 示例
-t, --tag 给新构建的镜像一个新的标签,格式为:name:tag docker build -t nginx:v3 .
-f, --file string Dockerfile的路径(文件名),默认为 上下文(Context)目录/Dockerfile

上下文路径 格式

上下文路径可以是以下方式

  • 本地路径

  • Git repo 进行构建

    docker build -t hello-world https://github.com/docker-library/hello-world.git#master:amd64/hello-world

    这行命令指定了构建所需的 Git repo,并且指定分支为 master,构建目录为 /amd64/hello-world/,然后 Docker 就会自己去 git clone 这个项目、切换到指定分支、并进入到指定目录后开始构建。

  • 用给定的 tar 压缩包构建

    docker build http://server/context.tar.gz

    如果所给出的 URL 不是个 Git repo,而是个 tar 压缩包,那么 Docker 引擎会下载这个包,并自动解压缩,以其作为上下文,开始构建。

  • 从标准输入中读取 Dockerfile 进行构建

    docker build - < Dockerfile

    cat Dockerfile | docker build -

    如果标准输入传入的是文本文件,则将其视为 Dockerfile,并开始构建。这种形式由于直接从标准输入中读取 Dockerfile 的内容,它没有上下文,因此不可以像其他方法那样可以将本地文件 COPY 进镜像之类的事情。

  • 从标准输入中读取上下文压缩包进行构建

    docker build - < context.tar.gz

    如果发现标准输入的文件格式是 gzipbzip2 以及 xz 的话,将会使其为上下文压缩包,直接将其展开,将里面视为上下文,并开始构建。

镜像构建上下文(Context)

Docker 在运行时分为 Docker 引擎(也就是服务端守护进程)和客户端工具。Docker 的引擎提供了一组 REST API,被称为 Docker Remote API,而如 docker 命令这样的客户端工具,则是通过这组 APIDocker 引擎 交互,从而完成各种功能。因此,虽然表面上我们好像是在本机执行各种 docker 功能,但实际上,一切都是使用的远程调用形式在服务端(Docker 引擎)完成。也因为这种 C/S 设计,让我们操作远程服务器的 Docker 引擎变得轻而易举。[1]

当我们进行镜像构建的时候,并非所有定制都会通过 RUN 指令完成,经常会需要将一些本地文件复制进镜像,比如通过 COPY 指令、ADD 指令等。而 docker build 命令构建镜像,其实并非在本地构建,而是在服务端,也就是 Docker 引擎 中构建的。那么在这种客户端/服务端的架构中,如何才能让服务端获得本地文件呢?

这就引入了 上下文 的概念。当构建的时候,用户会指定构建镜像上下文的路径,docker build 命令得知这个路径后,会将路径下的所有内容打包,然后上传给 Docker 引擎。这样 Docker 引擎 收到这个上下文包后,展开就会获得构建镜像所需的一切文件。

如果在 Dockerfile 中这么写:

Dockerfile
COPY ./package.json /app/

这并不是要复制执行 docker build 命令所在的目录下的 package.json,也不是复制 Dockerfile 所在目录下的 package.json,而是复制 上下文(context) 目录下的 package.json

因此,COPY 这类指令中的源文件的路径都是相对路径。

一般来说,应该会将 Dockerfile 置于一个空目录下,或者项目根目录下。如果该目录下没有所需文件,那么应该把所需文件复制一份过来。如果目录下有些东西确实不希望构建时传给 Docker 引擎,那么可以用 .gitignore 一样的语法写一个 .dockerignore,该文件是用于剔除不需要作为上下文传递给 Docker 引擎 的。

默认情况下,如果不额外指定 Dockerfile 的话,会将上下文目录下的名为 Dockerfile 的文件作为 Dockerfile

这只是默认行为,实际上 Dockerfile 的文件名并不要求必须为 Dockerfile,而且并不要求必须位于上下文目录中,比如可以用 -f ../Dockerfile.php 参数指定某个文件作为 Dockerfile
当然,一般大家习惯性的会使用默认的文件名 Dockerfile,以及会将其置于镜像构建上下文目录中

Dockerfile 指令详解

Dockerfile 文件示例

Dockerfile
FROM nginx
RUN echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html

FROM 指令

定制镜像,一定要以一个镜像为基础,在其上进行定制。

FROM 就是指定 基础镜像,因此一个 DockerfileFROM必备的指令,并且必须是第一条指令[1]

除了选择现有镜像为基础镜像外,Docker 还存在一个特殊的镜像,名为 scratch。这个镜像是虚拟的概念,并不实际存在,它表示一个空白的镜像。

Dockerfile
FROM scratch

如果以 scratch 为基础镜像的话,意味着不以任何镜像为基础,接下来所写的指令将作为镜像第一层开始存在。

RUN 指令

RUN 指令是用来执行命令行命令的。由于命令行的强大能力,RUN 指令在定制镜像时是最常用的指令之一。[1] 其格式有两种:

  • shell 格式:RUN <命令>,就像直接在命令行中输入的命令一样。上面写的 Dockerfile 中的 RUN 指令就是这种格式。
  • exec 格式:RUN ["可执行文件", "参数1", "参数2"],这更像是函数调用中的格式。

shell 格式和 exec 格式说明

既然 RUN 就像 Shell 脚本一样可以执行命令,那么我们是否就可以像 Shell 脚本一样把每个命令对应一个 RUN 呢?比如这样:

Dockerfile
FROM debian:stretch

RUN apt-get update
RUN apt-get install -y gcc libc6-dev make wget
RUN wget -O redis.tar.gz "http://download.redis.io/releases/redis-5.0.3.tar.gz"
RUN mkdir -p /usr/src/redis
RUN tar -xzf redis.tar.gz -C /usr/src/redis --strip-components=1
RUN make -C /usr/src/redis
RUN make -C /usr/src/redis install

Dockerfile 中每一个指令都会建立一层,RUN 也不例外。每一个 RUN 的行为,就和我们手工建立镜像的过程一样:新建立一层,在其上执行这些命令,执行结束后,commit 这一层的修改,构成新的镜像。
每一个 RUN 都是启动一个容器、执行命令、然后提交存储层文件变更。当前的 RUN 指令和前后的 RUN 指令是不存在环境变量的共享及关联的

而上面的这种写法,创建了 7 层镜像。这是完全没有意义的,而且很多运行时不需要的东西,都被装进了镜像里,比如编译环境、更新的软件包等等。结果就是产生非常臃肿、非常多层的镜像,不仅仅增加了构建部署的时间,也很容易出错。

Union FS 是有最大层数限制的,比如 AUFS,曾经是最大不得超过 42 层,现在是不得超过 127 层。

上面的 Dockerfile 正确的写法应该是这样:

Dockerfile
FROM debian:stretch

RUN set -x; buildDeps='gcc libc6-dev make wget' \
&& apt-get update \
&& apt-get install -y $buildDeps \
&& wget -O redis.tar.gz "http://download.redis.io/releases/redis-5.0.3.tar.gz" \
&& mkdir -p /usr/src/redis \
&& tar -xzf redis.tar.gz -C /usr/src/redis --strip-components=1 \
&& make -C /usr/src/redis \
&& make -C /usr/src/redis install \
&& rm -rf /var/lib/apt/lists/* \
&& rm redis.tar.gz \
&& rm -r /usr/src/redis \
&& apt-get purge -y --auto-remove $buildDeps

首先,之前所有的命令只有一个目的,就是编译、安装 redis 可执行文件。因此没有必要建立很多层,这只是一层的事情。因此,这里没有使用很多个 RUN 一一对应不同的命令,而是仅仅使用一个 RUN 指令,并使用 && 将各个所需命令串联起来。将之前的 7 层,简化为了 1 层。在撰写 Dockerfile 的时候,要经常提醒自己,这并不是在写 Shell 脚本,而是在定义每一层该如何构建。

并且,这里为了格式化还进行了换行。Dockerfile 支持 Shell 类的行尾添加 \ 的命令换行方式,以及行首 # 进行注释的格式。良好的格式,比如换行、缩进、注释等,会让维护、排障更为容易,这是一个比较好的习惯。

此外,还可以看到这一组命令的最后添加了清理工作的命令,删除了为了编译构建所需要的软件,清理了所有下载、展开的文件,并且还清理了 apt 缓存文件。这是很重要的一步,镜像是多层存储,每一层的东西并不会在下一层被删除,会一直跟随着镜像。因此镜像构建时,一定要确保每一层只添加真正需要添加的东西,任何无关的东西都应该清理掉。

COPY 复制文件指令

COPY 指令将构建上下文目录中的 <源路径> 的文件/目录复制到新的一层镜像内的 <目标路径> 位置。[2]

命令格式:

  • COPY [--chown=<user>:<group>] <源路径>... <目标路径>
  • COPY [--chown=<user>:<group>] ["<源路径1>",... "<目标路径>"]

<源路径> 可以是多个,甚至可以是通配符,其通配符规则要满足 Gofilepath.Match 规则,如:

COPY hom* /mydir/
COPY hom?.txt /mydir/

如果源路径为文件夹,复制的时候不是直接复制该文件夹,而是将文件夹中的内容复制到目标路径。

<目标路径> 可以是容器内的绝对路径,也可以是相对于工作目录的相对路径(工作目录可以用 WORKDIR 指令来指定)。目标路径不需要事先创建,如果目录不存在会在复制文件前先行创建缺失目录。

使用 COPY 指令,源文件的各种元数据都会保留。比如读、写、执行权限、文件变更时间等。

COPY 指令其他选项:

选项 说明 示例
--from 从其他镜像或构件阶段拷贝文件 COPY --from=0 /go/app . 多阶段构建 [6] 中,从第1阶段的镜像中复制文件
COPY --from=step1 /go/app . 多阶段构建中,从名为 step1 的镜像中复制

CMD 容器启动指令

镜像启动时默认执行的指令,在启动容器时,容器后面跟其他指令,会替换默认指令

CMD 指令[3]的格式和 RUN 相似,也是两种格式:

  • shell 格式:CMD <命令>
  • exec 格式:CMD ["可执行文件", "参数1", "参数2"...]
  • 参数列表格式:CMD ["参数1", "参数2"...]。在指定了 ENTRYPOINT 指令后,用 CMD 指定具体的参数。

shell 格式和 exec 格式说明

如果使用 shell 格式的话,实际的命令会被包装为 sh -c 的参数的形式进行执行。比如:

Dockerfile
CMD echo $HOME

在实际执行中,会将其变更为:

Dockerfile
CMD [ "sh", "-c", "echo $HOME" ]

其中主进程是 sh 。Docker 不是虚拟机,容器中的应用都应该以前台执行,而不是像虚拟机、物理机里面那样,用 systemd 去启动后台服务,容器内没有后台服务的概念。

比如以下指令:

Dockerfile
CMD service nginx start

容器执行后就会立即退出,对于容器而言,其启动程序就是容器应用进程,容器就是为了主进程而存在的,主进程退出,容器就失去了存在的意义,从而退出,其它辅助进程不是它需要关心的东西。

而使用 service nginx startsystemctl start nginx 等类似命令,被理解为 CMD [ "sh", "-c", "systemctl start nginx"],因此主进程实际上是 sh, 那么当 systemctl start nginx 命令结束后,sh 也就结束了,sh 作为主进程退出了,自然就会令容器退出。

正确的做法是直接执行 nginx 可执行文件,并且要求以前台形式运行。比如:

Dockerfile
CMD ["nginx", "-g", "daemon off;"]

ENTRYPOINT 容器启动程序指令

ENTRYPOINT 的格式和 RUN 指令格式一样,分为 exec 格式和 shell 格式。 shell 格式和 exec 格式说明

ENTRYPOINT 的目的和 CMD 一样,都是在指定容器启动程序及参数。ENTRYPOINT 在容器启动时也可以替代,不过比 CMD 要略显繁琐,需要通过 docker run 的参数 --entrypoint 来指定。[4]

当指定了 ENTRYPOINT 后,CMD (包括 Dockerfiledocker run 中的 CMD)的含义就发生了改变,不再是直接的运行其命令,而是将 CMD 的内容作为参数传给 ENTRYPOINT 指令,即实际执行时,将变为:

<ENTRYPOINT> "<CMD>"

ENV 设置环境变量指令

设置环境变量,无论是后面的其它指令,如 RUN,还是运行时的应用,都可以直接使用这里定义的环境变量。

当使用生成的镜像运行容器时,使用 ENV 设置的环境变量将持久存在于容器内。 你可以使用 docker inspect 查看这些值,并使用 docker run --env <key>=<value> 修改它们

环境变量持久性可能会导致意想不到的副作用。 例如,设置 ENV DEBIAN_FRONTEND=noninteractive 会改变 apt-get 的行为,并可能让使用镜像的用户感到困惑。
如果只在构建过程中需要环境变量,而不是在最终镜像中使用,可以使用 ARG,它不会在最终镜像中持久存在

Dockerfile
ENV VERSION=1.0 DEBUG=on \
NAME="Happy Feet"

调用方式:

Dockerfile
RUN echo $VERSION

ARG 构建参数

格式:ARG <参数名>[=<默认值>]

构建参数和 ENV 的效果一样,都是设置环境变量。所不同的是,ARG 所设置的是构建环境的环境变量,在将来容器运行时是不会存在这些环境变量的。但是不要因此就使用 ARG 保存密码之类的信息,因为 docker history 还是可以看到所有值的。

Dockerfile 中的 ARG 指令是定义参数名称,以及定义其默认值。该默认值可以在构建命令 docker build 中用 --build-arg <参数名>=<值> 来覆盖。

ARG 指令有生效范围,如果在 FROM 指令之前指定,那么只能用于 FROM 指令中。

Dockerfile
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

RUN set -x ; echo ${DOCKER_USERNAME}

使用上述 Dockerfile 会发现无法输出 ${DOCKER_USERNAME} 变量的值,要想正常输出,你必须在 FROM 之后再次指定 ARG

Dockerfile
# 只在 FROM 中生效
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

# 要想在 FROM 之后使用,必须再次指定
ARG DOCKER_USERNAME=library

RUN set -x ; echo ${DOCKER_USERNAME}

VOLUME 定义匿名卷指令

容器运行时应该尽量保持容器存储层不发生写操作,对于数据库类需要保存动态数据的应用,其数据库文件应该保存于卷(volume)中。为了防止运行时用户忘记将动态文件所保存目录挂载为卷,在 Dockerfile 中,我们可以事先指定某些目录挂载为匿名卷,这样在运行时如果用户不指定挂载,其应用也可以正常运行,不会向容器存储层写入大量数据。

Dockerfile
VOLUME /data

这里的 /data 目录就会在容器运行时自动挂载为匿名卷,任何向 /data 中写入的信息都不会记录进容器存储层,从而保证了容器存储层的无状态化。当然,运行容器时可以覆盖这个挂载设置。比如:

docker run -d -v mydata:/data xxxx

在这行命令中,就使用了 mydata 这个命名卷挂载到了 /data 这个位置,替代了 Dockerfile 中定义的匿名卷的挂载配置。

EXPOSE 暴露端口指令

格式为 EXPOSE <端口1> [<端口2>...]

EXPOSE 指令是声明容器运行时提供服务的端口,这只是一个声明,在容器运行时并不会因为这个声明,应用就会开启这个端口的服务。在 Dockerfile 中写入这样的声明有两个好处:

  • 一个是帮助镜像使用者理解这个镜像服务的守护端口,以方便配置映射;
  • 另一个用处则是在运行时使用随机端口映射时,也就是 docker run -P 时,会自动随机映射 EXPOSE 的端口。

要将 EXPOSE 和在运行时使用 -p <宿主端口>:<容器端口> 区分开来。-p,是映射宿主端口和容器端口,换句话说,就是将容器的对应端口服务公开给外界访问,而 EXPOSE 仅仅是声明容器打算使用什么端口而已,并不会自动在宿主进行端口映射。

WORKDIR 指定工作目录指令

格式为 WORKDIR <工作目录路径>

使用 WORKDIR 指令可以来指定工作目录(或者称为当前目录),以后各层的当前目录就被改为指定的目录,如该目录不存在,WORKDIR 会帮你建立目录。

如果 WORKDIR 指令使用的是相对路径,那么所切换的路径与之前的 WORKDIR 有关

Dockerfile
WORKDIR /a
WORKDIR b
WORKDIR c

RUN pwd

RUN pwd 的工作目录为 /a/b/c。

USER 指定当前用户指令

格式:USER <用户名>[:<用户组>]

USER 指令和 WORKDIR 相似,都是改变环境状态并影响以后的层。WORKDIR 是改变工作目录,USER 则是改变之后层的执行 RUN, CMD 以及 ENTRYPOINT 这类命令的身份。 USER 只是帮助你切换到指定用户而已,这个用户必须是事先建立好的,否则无法切换。

HEALTHCHECK 健康状态检查命令

格式:
HEALTHCHECK [选项] CMD <命令>:设置检查容器健康状况的命令 [5]
HEALTHCHECK NONE:如果基础镜像有健康检查指令,使用这行可以屏蔽掉其健康检查指令

HEALTHCHECK 支持下列选项:

选项 说明 示例
--interval=<30s> 两次健康检查的间隔,默认为 30 秒
--timeout=<30s> 健康检查命令运行超时时间,如果超过这个时间,本次健康检查就被视为失败,默认 30 秒;
--retries=<次数> 当连续失败指定次数后,则将容器状态视为 unhealthy,默认 3 次。

当在一个镜像指定了 HEALTHCHECK 指令后,用其启动容器,初始状态会为 starting,在 HEALTHCHECK 指令检查成功后变为 healthy,如果连续一定次数失败,则会变为 unhealthy

CMD, ENTRYPOINT 一样,HEALTHCHECK 只可以出现一次,如果写了多个,只有最后一个生效。

HEALTHCHECK [选项] CMD 后面的命令,格式和 ENTRYPOINT 一样,分为 shell 格式,和 exec 格式。命令的返回值决定了该次健康检查的成功与否:

  • 0:成功;
  • 1:失败;
  • 2:保留,不要使用这个值。

假设我们有个镜像是个最简单的 Web 服务,我们希望增加健康检查来判断其 Web 服务是否在正常工作,我们可以用 curl 来帮助判断,其 DockerfileHEALTHCHECK 可以这么写:

Dockerfile
FROM nginx
RUN yum install -y curl && yum clean all
HEALTHCHECK --interval=5s --timeout=3s CMD \
curl -fs http://localhost/ || exit 1

shell 格式和 exec 格式说明

在 Dockerfile 中,RUNCMDENTRYPOINT 指令都支持 shell 格式和 exec 两种格式,格式分别如下

  • shell 格式:RUN <命令>,就像直接在命令行中输入的命令一样。上面写的 Dockerfile 中的 RUN 指令就是这种格式。
  • exec 格式:RUN ["可执行文件", "参数1", "参数2"],这更像是函数调用中的格式。

此处演示两种格式的具体区别。

  1. 使用以下内容的 Dockerfile 构建镜像并运行,使用 shell 格式,假设镜像名称为 centos7:dockerfile-cmd-shell
    Dockerfile
    FROM centos:centos7.9.2009

    CMD ping 127.0.0.1
  2. 使用以下内容的 Dockerfile 构建镜像并运行,使用 exec 格式,假设镜像名称为 centos7:dockerfile-cmd-exec
    Dockerfile
    FROM centos:centos7.9.2009

    CMD [ "ping","127.0.0.1" ]
  3. 运行以上 Dockerfile 构建出来的镜像,容器信息如下,镜像 dockerfile-cmd-execdockerfile-cmd-shell 分别使用 exec 格式和 shell 格式
    $ docker ps 
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
    f2168d2dba94 centos7:dockerfile-cmd-exec "ping 127.0.0.1" 5 minutes ago Up 5 minutes funny_rubin
    70738995509f centos7:dockerfile-cmd-shell "/bin/sh -c 'ping 12…" 16 minutes ago Up 16 minutes magical_cannon

  4. 分别查看 2 个容器的 docker inspect 输出信息中的运行的进程信息
    $ docker inspect f2168d2dba94
    [
    {
    "Id": "f2168d2dba94d549bf70185d9d41e52d482be6f56a7c0d392f625e3721d1c07e",
    "Created": "2023-05-12T03:15:15.860200728Z",
    "Path": "ping",
    "Args": [
    "127.0.0.1"
    ],
    ...

    $ docker inspect 70738995509f
    [
    {
    "Id": "70738995509f12b0f4099c765cea3d2655076865f2a380b9cb7b1763bac58808",
    "Created": "2023-05-12T03:05:10.112279195Z",
    "Path": "/bin/sh",
    "Args": [
    "-c",
    "ping 127.0.0.1"
    ],
    ...
    由此可见,shell 格式的命令,在容器运行时会先启动 shell,然后在 shell 中执行命令。exec 格式则在容器启动时直接执行命令,未使用 shell 启动。

常见错误

http: server gave HTTP response to HTTPS client

在 Dockerfile 中使用私有仓库中的基础镜像,在构建镜像的过程中拉取镜像报错,关键 Dockerfile 内容如下

Dockerfile
FROM 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16
WORKDIR /home/www

构建命令及报错如下

# docker build -t comm/vas-php:20231101135333 -f ./php/Dockerfile .
[+] Building 0.4s (3/3) FINISHED
=> [internal] load .dockerignore 0.3s
=> => transferring context: 2B 0.0s
=> [internal] load build definition from Dockerfile 0.4s
=> => transferring dockerfile: 1.47kB 0.0s
=> ERROR [internal] load metadata for 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16 0.0s
------
> [internal] load metadata for 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16:
------
Dockerfile:1
--------------------
1 | >>> FROM 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16
2 | WORKDIR /home/www
3 | COPY ./php/www.conf /usr/local/etc/php-fpm.d/
--------------------
ERROR: failed to solve: 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16: failed to do request: Head "https://1.6.67.11:5000/v2/comm/php/manifests/7.3.18-fpm-alpine3.16": http: server gave HTTP response to HTTPS client

通常情况下,在镜像仓库不支持 HTTPS 的情况下,为了让 docker 客户端使用 HTTP 请求镜像仓库,需要在 docker 客户端的 docker 配置中配置以 HTTP 方式请求镜像仓库。要实现此配置,需要在(客户端) docker 服务配置文件 /etc/docker/daemon.json(如果不存在则创建)中配置以下内容

/etc/docker/daemon.json
{
"insecure-registries": ["1.6.67.11:5000"]
}

配置后,重启 docker 生效。在 Dockerfile 中使用私有镜像仓库的情况下,此配置可能不能解决本示例中遇到的问题。那么问题原因有可能是因为 新版本 Docker 的 buildkit 特性,在此种情况下,可以选用以下方法之一解决 [7]

  • 禁用 buildkit 特性。可以通过以下 2 种方式实现
    1. 使用环境变量禁用此特性,关键参数 DOCKER_BUILDKIT=0。具体执行方式如下
      DOCKER_BUILDKIT=0 docker build -t image_name .
    2. 通过 docker 配置文件 /etc/docker/daemon.json,具体配置如下,注意其中的 insecure-registries 配置,无需指定协议
      /etc/docker/daemon.json
      {
      ...
      "features": {
      "buildkit": false
      },
      "insecure-registries": [
      "hostname:18443",
      "hostname:8083"
      ],
      ...
      }
  • 启用 buildkit 特性的情况下配置 insecure-registries在启用 buildkit 特性的情况下,insecure-registries 中的镜像仓库地址指定协议
    /etc/docker/daemon.json
    {
    ...
    "features": {
    "buildkit": true
    },
    "insecure-registries": [
    "http://hostname:18443",
    "http://hostname:8083"
    ],
    ...
    }

参考链接

docker 从入门到实践

脚注