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
如果发现标准输入的文件格式是
gzip
、bzip2
以及xz
的话,将会使其为上下文压缩包,直接将其展开,将里面视为上下文,并开始构建。
镜像构建上下文(Context)
Docker 在运行时分为 Docker 引擎
(也就是服务端守护进程)和客户端工具
。Docker 的引擎提供了一组 REST API
,被称为 Docker Remote API
,而如 docker
命令这样的客户端工具,则是通过这组 API
与 Docker 引擎
交互,从而完成各种功能。因此,虽然表面上我们好像是在本机执行各种 docker
功能,但实际上,一切都是使用的远程调用形式在服务端(Docker 引擎
)完成。也因为这种 C/S 设计,让我们操作远程服务器的 Docker 引擎变得轻而易举。[1]
当我们进行镜像构建的时候,并非所有定制都会通过 RUN
指令完成,经常会需要将一些本地文件复制进镜像,比如通过 COPY
指令、ADD
指令等。而 docker build
命令构建镜像,其实并非在本地构建,而是在服务端,也就是 Docker 引擎
中构建的。那么在这种客户端/服务端的架构中,如何才能让服务端获得本地文件呢?
这就引入了 上下文
的概念。当构建的时候,用户会指定构建镜像上下文的路径,docker build
命令得知这个路径后,会将路径下的所有内容打包,然后上传给 Docker 引擎
。这样 Docker 引擎
收到这个上下文包后,展开就会获得构建镜像所需的一切文件。
如果在 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
文件示例
FROM nginx |
FROM 指令
定制镜像,一定要以一个镜像为基础,在其上进行定制。
FROM
就是指定 基础镜像
,因此一个 Dockerfile
中 FROM
是必备的指令,并且必须是第一条指令。[1]
除了选择现有镜像为基础镜像外,Docker 还存在一个特殊的镜像,名为 scratch
。这个镜像是虚拟的概念,并不实际存在,它表示一个空白的镜像。
FROM scratch |
如果以 scratch
为基础镜像的话,意味着不以任何镜像为基础,接下来所写的指令将作为镜像第一层开始存在。
RUN 指令
RUN
指令是用来执行命令行命令的。由于命令行的强大能力,RUN
指令在定制镜像时是最常用的指令之一。[1] 其格式有两种:
- shell 格式:
RUN <命令>
,就像直接在命令行中输入的命令一样。上面写的Dockerfile
中的RUN
指令就是这种格式。 - exec 格式:
RUN ["可执行文件", "参数1", "参数2"]
,这更像是函数调用中的格式。
既然 RUN 就像 Shell 脚本一样可以执行命令,那么我们是否就可以像 Shell 脚本一样把每个命令对应一个 RUN 呢?比如这样:
FROM debian:stretch |
Dockerfile
中每一个指令都会建立一层,RUN
也不例外。每一个 RUN
的行为,就和我们手工建立镜像的过程一样:新建立一层,在其上执行这些命令,执行结束后,commit
这一层的修改,构成新的镜像。
每一个 RUN 都是启动一个容器、执行命令、然后提交存储层文件变更。当前的 RUN
指令和前后的 RUN
指令是不存在环境变量的共享及关联的
而上面的这种写法,创建了 7 层镜像。这是完全没有意义的,而且很多运行时不需要的东西,都被装进了镜像里,比如编译环境、更新的软件包等等。结果就是产生非常臃肿、非常多层的镜像,不仅仅增加了构建部署的时间,也很容易出错。
Union FS
是有最大层数限制的,比如 AUFS
,曾经是最大不得超过 42 层,现在是不得超过 127 层。
上面的 Dockerfile
正确的写法应该是这样:
FROM debian:stretch |
首先,之前所有的命令只有一个目的,就是编译、安装 redis 可执行文件。因此没有必要建立很多层,这只是一层的事情。因此,这里没有使用很多个 RUN
一一对应不同的命令,而是仅仅使用一个 RUN
指令,并使用 &&
将各个所需命令串联起来。将之前的 7 层,简化为了 1 层。在撰写 Dockerfile
的时候,要经常提醒自己,这并不是在写 Shell 脚本,而是在定义每一层该如何构建。
并且,这里为了格式化还进行了换行。Dockerfile
支持 Shell
类的行尾添加 \
的命令换行方式,以及行首 #
进行注释的格式。良好的格式,比如换行、缩进、注释等,会让维护、排障更为容易,这是一个比较好的习惯。
此外,还可以看到这一组命令的最后添加了清理工作的命令,删除了为了编译构建所需要的软件,清理了所有下载、展开的文件,并且还清理了 apt 缓存文件。这是很重要的一步,镜像是多层存储,每一层的东西并不会在下一层被删除,会一直跟随着镜像。因此镜像构建时,一定要确保每一层只添加真正需要添加的东西,任何无关的东西都应该清理掉。
COPY 复制文件指令
COPY
指令将构建上下文目录中的 <源路径>
的文件/目录复制到新的一层镜像内的 <目标路径>
位置。[2]
命令格式:
COPY [--chown=<user>:<group>] <源路径>... <目标路径>
COPY [--chown=<user>:<group>] ["<源路径1>",... "<目标路径>"]
<源路径>
可以是多个,甚至可以是通配符,其通配符规则要满足 Go
的 filepath.Match
规则,如:
COPY hom* /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
格式的话,实际的命令会被包装为 sh -c
的参数的形式进行执行。比如:
CMD echo $HOME |
在实际执行中,会将其变更为:
CMD [ "sh", "-c", "echo $HOME" ] |
其中主进程是 sh
。Docker 不是虚拟机,容器中的应用都应该以前台执行,而不是像虚拟机、物理机里面那样,用 systemd
去启动后台服务,容器内没有后台服务的概念。
比如以下指令:
CMD service nginx start |
容器执行后就会立即退出,对于容器而言,其启动程序就是容器应用进程,容器就是为了主进程而存在的,主进程退出,容器就失去了存在的意义,从而退出,其它辅助进程不是它需要关心的东西。
而使用 service nginx start
或 systemctl start nginx
等类似命令,被理解为 CMD [ "sh", "-c", "systemctl start nginx"]
,因此主进程实际上是 sh
, 那么当 systemctl start nginx
命令结束后,sh
也就结束了,sh
作为主进程退出了,自然就会令容器退出。
正确的做法是直接执行 nginx
可执行文件,并且要求以前台形式运行。比如:
CMD ["nginx", "-g", "daemon off;"] |
ENTRYPOINT 容器启动程序指令
ENTRYPOINT
的格式和 RUN
指令格式一样,分为 exec
格式和 shell
格式。 shell 格式和 exec 格式说明
ENTRYPOINT
的目的和 CMD
一样,都是在指定容器启动程序及参数。ENTRYPOINT
在容器启动时也可以替代,不过比 CMD
要略显繁琐,需要通过 docker run
的参数 --entrypoint
来指定。[4]
当指定了 ENTRYPOINT
后,CMD
(包括 Dockerfile
和 docker run
中的 CMD
)的含义就发生了改变,不再是直接的运行其命令,而是将 CMD
的内容作为参数传给 ENTRYPOINT
指令,即实际执行时,将变为:
<ENTRYPOINT> "<CMD>" |
ENV 设置环境变量指令
设置环境变量,无论是后面的其它指令,如 RUN
,还是运行时的应用,都可以直接使用这里定义的环境变量。
当使用生成的镜像运行容器时,使用 ENV
设置的环境变量将持久存在于容器内。 你可以使用 docker inspect
查看这些值,并使用 docker run --env <key>=<value>
修改它们
环境变量持久性可能会导致意想不到的副作用。 例如,设置
ENV DEBIAN_FRONTEND=noninteractive
会改变apt-get
的行为,并可能让使用镜像的用户感到困惑。
如果只在构建过程中需要环境变量,而不是在最终镜像中使用,可以使用ARG
,它不会在最终镜像中持久存在
ENV VERSION=1.0 DEBUG=on \ |
调用方式:
RUN echo $VERSION |
ARG 构建参数
格式:ARG <参数名>[=<默认值>]
构建参数和 ENV
的效果一样,都是设置环境变量。所不同的是,ARG
所设置的是构建环境的环境变量,在将来容器运行时是不会存在这些环境变量的。但是不要因此就使用 ARG 保存密码之类的信息,因为 docker history
还是可以看到所有值的。
Dockerfile
中的 ARG
指令是定义参数名称,以及定义其默认值。该默认值可以在构建命令 docker build
中用 --build-arg <参数名>=<值>
来覆盖。
ARG
指令有生效范围,如果在 FROM
指令之前指定,那么只能用于 FROM
指令中。
ARG DOCKER_USERNAME=library |
使用上述 Dockerfile
会发现无法输出 ${DOCKER_USERNAME}
变量的值,要想正常输出,你必须在 FROM
之后再次指定 ARG
只在 FROM 中生效 |
VOLUME 定义匿名卷指令
容器运行时应该尽量保持容器存储层不发生写操作,对于数据库类需要保存动态数据的应用,其数据库文件应该保存于卷(volume)中。为了防止运行时用户忘记将动态文件所保存目录挂载为卷,在 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
有关
WORKDIR /a |
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
来帮助判断,其 Dockerfile
的 HEALTHCHECK
可以这么写:
FROM nginx |
shell 格式和 exec 格式说明
在 Dockerfile 中,RUN
、CMD
、ENTRYPOINT
指令都支持 shell
格式和 exec
两种格式,格式分别如下
- shell 格式:
RUN <命令>
,就像直接在命令行中输入的命令一样。上面写的Dockerfile
中的RUN
指令就是这种格式。 - exec 格式:
RUN ["可执行文件", "参数1", "参数2"]
,这更像是函数调用中的格式。
此处演示两种格式的具体区别。
- 使用以下内容的 Dockerfile 构建镜像并运行,使用
shell
格式,假设镜像名称为centos7:dockerfile-cmd-shell
Dockerfile FROM centos:centos7.9.2009
CMD ping 127.0.0.1 - 使用以下内容的 Dockerfile 构建镜像并运行,使用
exec
格式,假设镜像名称为centos7:dockerfile-cmd-exec
Dockerfile FROM centos:centos7.9.2009
CMD [ "ping","127.0.0.1" ] - 运行以上 Dockerfile 构建出来的镜像,容器信息如下,镜像
dockerfile-cmd-exec
和dockerfile-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 - 分别查看 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 内容如下
FROM 1.6.67.11:5000/comm/php:7.3.18-fpm-alpine3.16 |
构建命令及报错如下
docker build -t comm/vas-php:20231101135333 -f ./php/Dockerfile . |
通常情况下,在镜像仓库不支持 HTTPS 的情况下,为了让 docker 客户端使用 HTTP 请求镜像仓库,需要在 docker 客户端的 docker 配置中配置以 HTTP 方式请求镜像仓库。要实现此配置,需要在(客户端) docker 服务配置文件 /etc/docker/daemon.json
(如果不存在则创建)中配置以下内容
{ |
配置后,重启 docker 生效。在 Dockerfile 中使用私有镜像仓库的情况下,此配置可能不能解决本示例中遇到的问题。那么问题原因有可能是因为 新版本 Docker 的 buildkit
特性,在此种情况下,可以选用以下方法之一解决 [7]
- 禁用
buildkit
特性。可以通过以下 2 种方式实现- 使用环境变量禁用此特性,关键参数
DOCKER_BUILDKIT=0
。具体执行方式如下DOCKER_BUILDKIT=0 docker build -t image_name .
- 通过 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"
],
...
}