Docker Compose build 和 image 在 VPS 上的区别
了解 Compose 中 image 与 build 的真实行为:image 只使用或拉取镜像,build 才读取 Dockerfile;解释修改 Dockerfile 后 docker compose up 不重建的原因及修复方法。
Docker Compose build 与 image:简要说明
在 Docker Compose 文件中,image:用于指定要使用的镜像,包括本地镜像、标签或摘要引用;build:则告诉 Compose 如何从源代码构建镜像。只设置 image: 时,Compose 会根据 pull_policy 使用或拉取该镜像。只设置 build: 时,Compose 会使用配置的构建器构建镜像,并为其分配一个由项目名称和服务名称派生的名称。两者同时设置时,pull_policy决定 Compose 是拉取还是构建镜像;执行构建时,Compose 会使用 image: 中的名称为结果添加标签。这也是构建镜像后使用自选名称推送镜像的方式。构建器可以在本地运行,也可以在远程 Docker 主机上运行。
区别就是这些。下面的内容说明它在服务器上的实际运行方式。本文假定 Docker Engine 和 Compose 插件已安装;在 VPS 上运行 Docker介绍了这部分内容。
三种完整形式
使用已发布的标签;如果该标签不存在,则根据默认的拉取策略拉取它。整个过程不会使用 Dockerfile。
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"根据项目目录中的 Dockerfile 构建。构建过程也可以拉取镜像,并下载 Dockerfile 所需的依赖项。
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"构建结果并使用 docker compose build 为其添加标签;如果未明确指定拉取策略,up 会在构建前尝试拉取此镜像。然后,docker compose push 可以将完全相同的标签推送到镜像仓库。
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context 是发送给构建器的目录。dockerfile 相对于该上下文目录解析,因此使用 dockerfile: docker/prod.Dockerfile 配置 context: . 是正常且正确的。运行 docker compose images 可查看每个服务容器所使用的镜像名称和镜像 ID;检查 Compose 文件,确认服务是否使用 image:、build: 或两者。
为什么修改 Dockerfile 后,运行 docker compose up 仍不会重新构建?
因为普通的 up 会复用现有镜像,除非您明确要求构建,或配置要求构建的策略。
当 Compose 启动一个只有 build: 配置段的服务时,只要现有镜像可用,它就会使用该镜像。它不会读取您的 Dockerfile,不会比较源文件,也不会检查任何时间戳。如果同时配置了 image: 和 build:,且没有显式指定 pull_policy,Compose 会先尝试拉取镜像;只有在镜像在镜像仓库或平台缓存中不可用时,才会构建。镜像只要存在,就会被视为足够可用。
因此,您修改 app.py,运行 docker compose up -d,看到 Compose 报告容器正在运行,但实际提供的仍是旧代码。整个过程没有失败,因此也不会产生警告。判断依据是 Compose 在容器名称旁输出的状态词:如果 Compose 替换了容器,会报告 recreated 或 started;如果 Compose 决定保留容器不变,则会报告 running。
通过两项检查即可确认。docker compose images 会输出每个容器正在使用的镜像 ID,因此请在部署前记录该 ID,并在部署后进行比较。docker image ls 包含 CREATED 列,但缓存构建和可复现时间戳意味着,单凭该日期无法证明是否使用最新源代码完成了构建。
哪些标志会强制重新构建
docker compose up -d --build会先执行构建,然后重新创建镜像已更改的容器。这是大多数人需要的标志。docker compose build web只构建一个服务,不启动任何服务。将其与docker compose up --no-deps -d web一起使用,可以只替换该容器,同时让堆栈中的其他服务继续运行。docker compose build --no-cache web会绕过缓存层,重新构建该服务。docker compose build --pull会尝试拉取FROM中基础镜像的较新版本。因此,像node:22这样的可变标签会使用当前内容,而不是使用你在 3 月下载的副本。docker compose up -d --force-recreate会强制重新创建容器,即使配置和镜像都没有更改。该标志本身不会请求构建,但如果镜像缺失,或拉取策略要求构建,up仍可能执行构建。你本来需要--build,却使用了这个标志,是常见的误区。
你也可以将此决策写入文件。按照 Compose 规范的定义,pull_policy: build 表示 Compose 会构建镜像;如果镜像已存在,还会重新构建。每次执行 up 都会产生构建开销。在笔记本电脑上通常需要这样做,但在服务器上很少需要。
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: build还需要了解另一个交互行为。docker compose pull 也会尝试拉取包含 build 部分的服务所使用的镜像。如果拉取失败,它会提示必须改为构建镜像。传入 --ignore-buildable 可静默跳过这些服务。
构建缓存如何决定部署时间
当 Dockerfile 指令及其输入未发生变化时,构建器会检查该指令是否有可复用的缓存结果。对于 COPY,输入包括文件内容和元数据,但不包括修改时间。一旦某一层未命中缓存,依赖该层的后续步骤也会重新构建。
这条规则决定部署耗时是几秒还是几分钟。按变化频率从低到高排列 Dockerfile:先放很少变化的内容,最后放每次提交都会变化的内容。
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci 位于 COPY . . 之前,因此编辑源文件后,安装层仍可使用缓存,构建会从复制步骤继续。交换这两行后,即使只修改一个字符,也会重新安装所有依赖,因为 COPY . . 会使 npm ci 所依赖的层失效。同样的结构也适用于 pip install -r requirements.txt 和 go mod download。
当您怀疑某个过时的层掩盖了修复时,应使用 --no-cache。但不应默认使用它,因为它会丢弃 Dockerfile 排序原本用于实现的缓存复用。
镜像设置的一项内容可以被 Compose 覆盖:Dockerfile 中的 CMD 决定镜像默认运行的内容,而服务中的 command: 键会替换它。命令与入口点如何交互 在这里很重要,因为 Compose 覆盖配置可能让刚构建的镜像表现得与旧镜像完全相同。
构建上下文和 .dockerignore
context: . 会将项目目录提供给构建器。未设置排除项时,其中包括 .git 以及您可能放在源代码旁边的任何数据目录。不过,BuildKit 会跳过未使用的文件,并增量传输变更。如果项目没有任何变化,但构建仍在传输上下文步骤暂停,这说明上下文过大。
在上下文根目录创建 .dockerignore 文件,可以从传输内容中排除路径。其语法接近 .gitignore。
.git
node_modules
*.log
data/
.env这样做有两个好处。首先,传输内容会变小,从而减少传输这些文件所需的时间。其次,COPY . . 无法再将 .env 复制到镜像中;任何拉取该镜像的人都可以从中读出这些内容。
会随时间变慢的典型情况是绑定挂载。命名卷位于项目目录之外,但像 ./data:/var/lib/postgresql/data 这样的绑定挂载位于构建上下文内。因此,随着数据库增长,构建会逐周变慢。在 .dockerignore 中添加一行即可解决问题。绑定挂载与命名卷的比较介绍了更广泛的权衡。
构建参数也存在类似但较小的风险。通过 args: 传入的值可能保留在镜像历史或来源证明元数据中,因此应在其中放置版本号,绝不要放置令牌。预定义的代理参数默认不会写入构建缓存和 docker history,除非在 Dockerfile 中显式引用。Compose 中的环境文件和密钥介绍了凭据应放置的位置。
应在 VPS 上构建,还是在其他位置构建后拉取?
在承载网络流量的服务器上构建通常是默认选择,因为路径最短:git pull,然后 docker compose up -d --build。对于尚未被其他人依赖的小型服务器,这没有问题。但以下两个可测量的原因,以及一个只会在糟糕情况下暴露的问题,会让这种做法不再合适。
内存。 构建会让编译器和打包工具与在线应用运行在同一台服务器上,而它们通常是整个技术栈中最耗内存的部分。JavaScript 打包工具或 Rust 编译过程可能耗尽 1 GB VPS 可用的内存。内存耗尽时,内核会根据内存使用量、分配上下文和 oom_score_adj 计算的 badness 分数选择 OOM 终止目标;它不会简单地终止占用内存最多的进程。构建可能因 Killed 停止,并以退出状态 137 退出;也可能是数据库被终止,导致网站在部署过程中途宕机。dmesg -T | grep -i oom 会在内核日志中搜索 OOM 消息;访问该日志需要相应权限。
磁盘。 构建会留下镜像层和构建缓存。docker system df 可显示它们占用的磁盘空间;BuildKit 的定期垃圾回收会根据配置的策略回收缓存。使用 docker image prune 回收悬空镜像,使用 docker builder prune 回收缓存层。磁盘空间耗尽影响的不只是构建。数据库也会停止写入,而这种故障造成的损失远高于部署变慢。
可复现性。 如果不推送或导出镜像,那么在服务器上构建的镜像只存在于该服务器上。如果旧镜像已不可用,回滚就意味着检出旧提交并重新构建;但无法保证这次构建会生成原来的结果,因为基础镜像标签可能已移动,软件包镜像也可能随之变化。在其他位置构建并推送标签后,回滚只需修改配置:让 image: 指向之前的标签,然后运行 docker compose up -d。
更可靠的方案很简单。持续集成系统负责构建并推送 registry.example.com/acme/web:<git-sha>,VPS 上的 Compose 文件使用 image:,且完全不包含 build: 键。这样部署只需执行两个命令,几乎不占用内存。
docker compose pull
docker compose up -d在服务器上运行 docker login registry.example.com,以保存拉取私有标签所需的凭据。
保留用于开发的构建部分,不要删除。将其放在一个由您自行命名的文件中。
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --build将该文件命名为 compose.dev.yaml,不要命名为 compose.override.yaml。只要覆盖文件存在,Compose 就会自动加载它,因此如果误将覆盖文件复制到服务器,服务器会再次悄悄执行构建。组合多个 Compose 文件介绍了合并过程如何处理各个键。
在其他环境构建时的架构陷阱
单个平台镜像包含其构建目标 CPU 架构。在 Apple Silicon 笔记本电脑上构建 ARM 镜像并推送,然后在 x86_64 VPS 上使用该镜像时,如果 Docker 使用了不兼容的缓存镜像且未明确指定平台,Docker 会在创建容器时发出警告。没有仿真支持时,进程会因 exec format error 失败。该错误看起来像二进制文件损坏,但实际并非如此。请明确指定目标平台进行构建:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .如果您的笔记本电脑使用 x86 架构,而您运行的是 ARM VPS,而不是 x86 VPS,也会发生相反的架构不匹配。让 CI 在部署目标所使用的架构上完成构建,可以避免这一问题。多平台镜像也能解决此问题:Docker 拉取镜像时会选择匹配的变体。
部署后检查事项
docker compose images输出每个正在运行的容器所使用的镜像及标签。镜像 ID 发生变化,才能证明新构建已投入运行。docker compose config输出变量替换后的合并文件。这样可以在运行任何命令前,确认 Compose 最终使用的镜像名称。docker compose logs -f web在切换后的前 30 秒内持续监控容器。如果容器反复启动并退出,只有在其重启策略要求时才会自动重启;请检查日志以确定原因。docker image ls显示 CREATED 列。还应检查构建输出和已部署镜像 ID,因为创建时间戳本身无法证明是否执行了重新构建。
如果您仍在组装这些检查所针对的文件,请参阅 VPS 上 Compose 文件的基础知识,了解相关配置项;Compose 命令速查表列出了其余子命令。
FAQ
我可以在同一个服务中同时使用 build 和 image 吗?
可以。这是自行构建项目的常见配置。Compose 根据 build: 部分进行构建时,会使用 image: 的值为结果添加标签;如果未显式设置 pull_policy,up 会先尝试拉取镜像。该标签就是 docker compose push 推送到镜像仓库的标签,也是另一台机器拉取的标签。如果没有 image: 键,Compose 仍会构建,但会根据项目名和服务名命名镜像,并警告缺少该属性会导致镜像无法推送。
为什么 docker compose up 没有应用我的 Dockerfile 修改?
因为普通的 up 会复用现有镜像,除非您请求构建,或配置了要求构建的策略。它不会比较该镜像与 Dockerfile 或源文件,因此不会自行判断是否需要重新构建。请运行 docker compose up -d --build;或者先运行 docker compose build web,再运行 docker compose up --no-deps -d web,以替换单个服务。在服务上设置 pull_policy: build 后,每次 up 都会重新构建,适合开发机。
--build 和 --force-recreate 有什么区别?
--build 会重新构建镜像,然后重新创建镜像已发生变化的容器。--force-recreate 会强制重新创建容器,即使配置和镜像都没有变化;它本身不会请求构建。如果修改了源代码或 Dockerfile,应使用 --build 标志。--force-recreate 用于重置容器本身,例如在保留同一镜像的同时清除其可写层。
我应该在 VPS 上构建 Docker 镜像,还是在其他位置构建?
在其他位置构建,然后在该服务器同时承载网络流量后拉取标签。构建过程会与应用争用内存。内存耗尽时,内核会根据可调整的 OOM 分数选择要终止的进程,可能终止构建过程或数据库。构建还会在磁盘上留下缓存,但 BuildKit 会根据其垃圾回收策略自动回收缓存。对于没有用户的小型项目,直接在服务器上构建没有问题。如果保留 build: 部分,并将其放在仅用于开发的 Compose 文件中,之后迁移的成本也很低。
如何防止 Docker 构建缓存占满磁盘?
运行 docker system df,查看镜像和构建缓存分别占用多少空间。docker builder prune 会删除缓存层,docker image prune 会删除早期构建留下的悬空镜像。分别添加 -a 后,会删除所有未使用的构建缓存,或删除所有未被容器引用的镜像;但这不保证下一次构建会完全从零开始。不要在服务器上安排 docker system prune -af --volumes,因为它会删除已停止的容器和未使用的匿名卷,维护期间可能导致匿名卷中的数据库数据丢失。