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-shellDockerfile FROM centos:centos7.9.2009
CMD ping 127.0.0.1 - 使用以下内容的 Dockerfile 构建镜像并运行,使用
exec格式,假设镜像名称为centos7:dockerfile-cmd-execDockerfile 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"
],
...
}