容器与云原生 / 知识点
Docker Compose 配置与运维速查手册
手册条目
确认当前 Docker Compose CLI 版本及命令是否可用。
检查 Docker Compose 版本
用于确认当前终端是否已加载 Compose CLI、实际版本号以及自动化脚本应调用哪种命令。版本检查不读取项目配置,也不需要 Docker 守护进程正在运行。
基本语法
优先检查新版插件式命令;--short 只输出版本号,更适合脚本采集和版本比较。
docker compose version
docker compose version --short预期输出
Docker Compose version v<VERSION>
<VERSION><VERSION> 会随安装版本变化。第一行出现 Docker Compose version 表示子命令可用;第二行应只有版本号,不要在脚本中解析第一行的展示文本。
快速排障
同时检查 Docker CLI 路径、CLI 版本和 Compose 子命令,可快速区分“Docker 未安装”与“Compose 插件缺失”。
command -v docker
docker --version
docker compose version预期输出
<PATH>/docker
Docker version <DOCKER_VERSION>, build <ID>
Docker Compose version v<VERSION>若第一条无输出或提示 docker: command not found,先修复 Docker CLI 安装或 PATH。若 Docker 可用但第三条提示 docker: 'compose' is not a docker command,说明当前 CLI 未发现 Compose 插件,应安装或恢复插件,而不是反复重启业务容器。
风险与边界
不要把 docker --version 当作 Compose 版本,两者独立发布。脚本需要版本号时使用 docker compose version --short,并允许前导 v 差异;硬编码完整展示文本会在升级后导致误判。
旧环境可能只有 docker-compose version。它通常代表独立的旧式可执行文件,行为和升级路径可能与 docker compose 不同。生产脚本应统一一种调用方式,并在切换前完成配置解析和启动验证。
速查结论
看到完整版本或短版本号即可确认命令可用;只有 Docker CLI 版本、没有 Compose 输出,不能视为 Compose 已安装。
确认 Compose 默认识别的配置文件名称和实际加载位置。
查找 Docker Compose 配置文件
用于确认不带 -f 时可能被自动发现的配置文件,以及正在运行的 Compose 项目实际记录了哪些文件。重点防止在错误目录执行命令后误操作父目录中的另一套服务。
默认查找规则
推荐文件名为 compose.yaml,也识别 compose.yml;为兼容旧项目,还支持 docker-compose.yaml 和 docker-compose.yml。未指定文件时,Compose 会从当前工作目录向父目录查找;存在 compose.override.yaml 时,通常会与基础文件合并。
显式传入 -f,或设置 COMPOSE_FILE 后,应以显式文件列表及其顺序为准,不再依赖默认发现结果。
定位候选文件
下面的 Bash 脚本从当前目录向上查找常见文件名,输出首个候选的绝对路径,并立即验证其配置。它适合 Linux、macOS、WSL 和 Git Bash;同目录存在多个候选时,生产命令仍应显式使用 -f 消除歧义。
dir="$PWD"
names=(compose.yaml compose.yml docker-compose.yaml docker-compose.yml)
while :; do
for name in "${names[@]}"; do
if [[ -f "$dir/$name" ]]; then
file="$(cd "$dir" && pwd -P)/$name"
printf '%s\n' "$file"
docker compose -f "$file" config --quiet
exit $?
fi
done
[[ "$dir" == "/" ]] && break
dir="$(dirname "$dir")"
done
printf '未找到默认 Compose 配置文件\n' >&2
exit 1预期输出
<PATH>/compose.yaml命令退出码为 0 表示该文件能够被 Compose 解析;只有路径但随后出现 YAML、变量或字段错误,说明文件找到了但配置尚不可用。
查看运行项目的实际文件
项目已经启动时,docker compose ls 会列出 Compose 项目及其配置文件位置,可用于核对当前运行栈来自哪个目录。
docker compose ls预期输出
NAME STATUS CONFIG FILES
<PROJECT> running(2) <PATH>/compose.yaml<PROJECT>、容器数量和 <PATH> 会因环境不同而变化。若项目使用多个 -f 文件,CONFIG FILES 可能显示多个路径;没有运行中的 Compose 项目时只会看到表头或空结果。
风险与边界
触发条件是在错误目录执行 up、down、restart,而父目录恰好存在可识别的 Compose 文件。可能后果是创建、重建或停止错误项目。安全做法是先执行 pwd 和 docker compose config --quiet,生产操作固定写成 docker compose -f /绝对路径/compose.yaml <COMMAND>。
不要仅凭文件名判断生效内容。变量替换、覆盖文件和多个 -f 会改变最终模型;需要确认最终配置时运行 docker compose -f <PATH> config,再检查渲染后的服务、端口、挂载和镜像。
在启动前检查 YAML 语法、变量替换和服务配置是否有效。
启动前校验 Compose 配置
在执行 up、create 或部署流水线前,用 docker compose config --quiet 检查 Compose 文件能否被解析、环境变量能否完成替换,以及多文件合并后是否形成有效的配置模型。命令只做解析与校验,不会创建容器、网络或卷。
命令定位
默认在当前目录查找 compose.yaml、compose.yml 等 Compose 文件,并读取当前 Shell、.env 或 --env-file 指定文件中的变量。校验成功时通常不输出内容,退出码为 0;失败时在标准错误中给出文件、字段或变量相关信息,并返回非零退出码。
基本语法
docker compose config --quiet
status=$?
printf 'exit=%s\n' "$status"预期输出:
exit=0exit=0 表示配置模型已通过解析与校验;若前面出现错误且退出码非零,应先修复配置,不要继续执行 docker compose up。
高频用法
校验默认文件时使用 docker compose config -q。校验生产覆盖配置时使用 docker compose -f compose.yaml -f compose.prod.yaml config -q,文件按从左到右合并,后面的文件用于覆盖前面的定义。需要指定变量文件时使用 docker compose --env-file .env.prod config -q,避免误读当前目录中的开发变量。
对必填变量,建议在 YAML 中使用 ${IMAGE_TAG:?IMAGE_TAG is required}。变量缺失时校验会直接失败,而不是把空字符串带入镜像名、端口或路径。不要在最终校验中加入 --no-interpolate,该选项会跳过变量替换,可能掩盖真实的缺失变量问题。
风险与边界
该命令只能证明 Compose 模型可解析,不能证明镜像存在、仓库认证有效、宿主机端口空闲、挂载路径可访问、外部网络已创建或容器健康检查会通过。安全做法是先执行静态校验,再在目标环境执行 docker compose pull,最后在隔离或灰度环境启动服务验证运行条件。
多文件校验时,相对路径以第一个 -f 文件所在目录为基准。触发条件是从其他目录执行或调整文件顺序,可能导致构建上下文、绑定挂载和 env_file 指向错误位置;安全替代方案是使用明确路径,并保持基础文件始终位于第一个 -f 参数。
排障清单
- 出现
yaml解析错误:检查缩进、冒号、列表符号和未闭合引号,并确认没有 Tab 缩进。 - 出现变量未设置警告:核对 Shell、
.env与--env-file,对关键变量改用${VAR:?message}。 - 出现未知字段或类型错误:运行
docker compose version,确认实际使用的是 Compose v2 插件,并检查字段是否受当前版本支持。 - 多文件结果异常:去掉
--quiet执行同一组-f参数,直接查看最终合并配置后再定位覆盖来源。
速查结论:自动化流水线可将 docker compose config --quiet 的退出码作为启动前门禁,但仍需单独验证镜像、权限、端口和外部资源。
输出变量替换和多文件合并后的最终 Compose 配置。
查看合并后的最终 Compose 配置
当配置包含变量、多个 -f 文件、锚点或覆盖项时,直接阅读原始 YAML 容易误判实际生效值。docker compose config 会完成变量替换、文件合并和规范化,并输出 Compose 最终交给引擎处理的配置模型,但不会启动任何服务。
基本语法
docker compose -f compose.yaml -f compose.prod.yaml config预期结果:终端输出完成变量替换和多文件合并后的完整 Compose 模型;若解析或插值失败,命令返回非零退出码并打印错误。后面的文件覆盖前面的文件,没有显式指定 -f 时则使用当前项目自动发现的 Compose 文件。
主示例
下面的示例可直接复制运行,它创建一份基础配置和一份生产覆盖配置,再输出合并结果。
tmp_dir="$(mktemp -d)"
cat >"$tmp_dir/compose.yaml" <<'YAML'
services:
app:
image: acme/app:${IMAGE_TAG:?IMAGE_TAG is required}
environment:
LOG_LEVEL: info
YAML
cat >"$tmp_dir/compose.prod.yaml" <<'YAML'
services:
app:
environment:
LOG_LEVEL: warn
deploy:
replicas: 3
YAML
IMAGE_TAG=2026.08 docker compose -p demo \
-f "$tmp_dir/compose.yaml" \
-f "$tmp_dir/compose.prod.yaml" \
config预期输出关键片段:
name: demo
services:
app:
deploy:
replicas: 3
environment:
LOG_LEVEL: warn
image: acme/app:2026.08字段顺序以及自动补出的 networks 等内容可能随 Compose 插件版本不同而变化。读取时重点确认 image 已完成变量替换、LOG_LEVEL 已被后置文件覆盖、replicas 已进入最终服务定义。
常用参数
-f <FILE> 可重复指定,顺序决定覆盖方向;建议把基础文件放在前面,把环境或站点覆盖文件放在后面。--env-file <FILE> 指定插值变量来源;它不同于服务内的 env_file,前者用于渲染 Compose 文件,后者用于向容器注入环境变量。
--no-interpolate 保留 ${VAR} 原文,适合排查模板,不适合作为最终生效配置。--services、--profiles 等摘要选项适合快速列出对象,但不能替代完整 config 输出。需要固定项目名时可加 -p <PROJECT>,便于核对默认网络等派生名称。
风险与边界
执行完整 config 时,已经替换的密码、令牌或私有仓库凭据可能进入终端、CI 日志或重定向文件。触发条件是敏感值被直接写入 Compose 字段;可能后果是凭据泄漏。安全替代方案是使用 Docker secrets 或外部密钥系统,只在受控环境查看完整输出,流水线门禁优先使用 config --quiet。
最终配置只反映 Compose 模型,不代表运行时状态。它不会验证镜像能否拉取、端口是否冲突、绑定挂载是否存在、外部网络和卷是否已创建,也不会展示容器启动后由应用自行生成的配置。
排障清单
- 值与预期不同:确认
-f顺序,并检查是否有 Shell 变量覆盖.env或--env-file中的同名值。 - 路径指向错误:确认第一个 Compose 文件的位置;相对构建上下文和挂载路径以该基础文件为参照。
- 列表或映射合并异常:不要假设所有字段都采用同一种合并方式,直接在最终输出中核对目标字段。
- 输出缺少预期服务:检查实际执行目录、显式
-f参数、项目配置以及相关 profile 的启用方式。
速查结论:遇到“原文件看起来正确但运行结果不对”时,先看 docker compose config 的最终模型,再排查引擎和容器运行阶段。
查看当前 Compose 配置中定义的全部服务名称。
列出 Compose 服务
在启动、重建或指定单个服务前,使用 docker compose config --services 查看当前 Compose 配置解析后的服务名。命令会合并 -f 指定的文件、解析变量并输出服务名称,但不会创建或启动容器;结果每行一个名称,适合人工核对或交给脚本处理。:contentReference[oaicite:0]{index=0}
基本语法
在包含 compose.yaml 的目录执行:
docker compose config --services预期输出
web
db上例表示最终配置中有 web 和 db 两个服务。实际名称取决于 Compose 文件;不要依赖输出顺序判断服务启动顺序或依赖关系。
常用参数
-f <FILE>:指定 Compose 文件;可以重复使用,后面的文件会合并并覆盖前面的同名配置。--project-directory <DIR>:指定项目目录,影响配置中相对路径的解析。--services:仅打印服务名,不输出完整的规范化配置。
需要同时应用生产覆盖文件时,可使用 docker compose -f compose.yaml -f compose.prod.yaml config --services。多个文件的先后顺序不能颠倒,否则最终合并结果可能不同。:contentReference[oaicite:1]{index=1}
高频用法
确认部署脚本中的服务名是否存在时,先运行本命令,再执行 docker compose up -d <SERVICE>;可避免因拼写错误得到 no such service。
需要查看已经创建容器的服务,而不是配置中定义的全部服务时,改用 docker compose ps --services --all。config --services 只回答“配置里有哪些服务”,不反映容器是否运行、退出或尚未创建。:contentReference[oaicite:2]{index=2}
风险与边界
当 Compose 文件语法错误、必需环境变量缺失或引用文件不可读时,配置解析会失败,因此可能无法得到服务列表。不要用空输出直接判断“没有服务”,应同时检查标准错误和命令退出码。
该命令不会验证镜像能否拉取、端口是否冲突或容器能否健康启动。需要验证运行状态时使用 docker compose ps --all;需要检查完整合并结果时使用 docker compose config。
排障清单
- 报找不到配置文件:确认当前目录,或显式添加
-f <PATH>。 - 服务名与预期不一致:检查自动加载的覆盖文件,以及多个
-f的先后顺序。 - 变量解析失败:检查 shell 环境、项目目录下的
.env和 Compose 文件中的${VAR}。 - 只想看正在运行的服务:改用
docker compose ps --services。
速查:列配置定义用 config --services;列已创建容器对应的服务用 ps --services --all。
查看本机正在运行或已停止的 Compose 项目。
列出 Compose 项目
排查本机有哪些 Compose 应用仍在运行或保留了已停止容器时,使用 docker compose ls --all。默认的 docker compose ls 只列运行中的项目,增加 --all 后会把停止项目一并纳入;命令查询当前 Docker 上下文,不依赖当前目录中的 Compose 文件。:contentReference[oaicite:3]{index=3}
基本语法
docker compose ls --all预期输出
NAME STATUS CONFIG FILES
shop running(2) /srv/shop/compose.yaml
batch exited(1) /opt/batch/compose.yamlshop 有两个运行中的容器,batch 保留一个已退出容器;项目名、路径和容器数量属于动态值,实际输出会不同。:contentReference[oaicite:4]{index=4}
常用参数
-a, --all:在运行项目之外,同时显示停止的 Compose 项目。-q, --quiet:只输出项目名称,适合管道或循环处理。--format table|json:选择表格或 JSON 输出;自动化脚本优先使用 JSON,避免解析表格中的对齐空格。:contentReference[oaicite:5]{index=5}
只提取项目名时执行:
docker compose ls --all --quiet预期输出
shop
batch输出字段说明
NAME:Compose 项目名,可传给docker compose -p <NAME> ...定位同一项目。STATUS:项目内容器状态及数量汇总,例如running(2)或exited(1)。CONFIG FILES:创建该项目时关联的 Compose 文件路径,使用多个文件时可能显示多个路径。
项目名可能与当前目录名不同,后续排障应优先复制 NAME 列中的实际值,不要自行猜测。
风险与边界
docker compose ls --all 不会扫描磁盘寻找所有 compose.yaml,只显示当前 Docker 守护进程仍能识别的 Compose 项目。执行 docker compose stop 后容器仍保留,因此项目可作为停止项目被列出;执行 docker compose down 后容器和默认网络被移除,项目通常不再出现在列表中。:contentReference[oaicite:6]{index=6}
在远程 Docker 主机、多个 Docker Context 或 Docker Desktop 环境中,切换上下文会改变查询目标。若列表意外为空,先检查 docker context show 和 docker info,不要误判为没有 Compose 工作负载。
排障清单
- 看不到已停止项目:确认使用了
--all,并确认此前执行的是stop而不是down。 - 项目名称陌生:检查启动时是否使用
-p或设置COMPOSE_PROJECT_NAME。 - 路径已不存在但项目仍显示:资源可能仍保留,使用
docker compose -p <NAME> ps --all核对容器。 - 输出供脚本消费:使用
--format json或--quiet,不要解析表格列宽。
速查:查当前 Docker 上下文中的 Compose 项目用 docker compose ls --all;查某个项目的容器明细用 docker compose -p <NAME> ps --all。
创建并启动 Compose 项目中的所有启用服务。
启动全部服务
当需要按当前 Compose 配置创建并启动所有已启用服务,并在前台持续观察汇总日志时使用 docker compose up。命令会按依赖关系启动服务:缺失的容器会创建,配置或镜像发生变化时会按需重建;未激活 Profile 的服务不会被纳入本次启动。
基本语法
docker compose up预期输出(项目名、服务名和耗时会不同):
[+] Running 3/3
✔ Network <PROJECT>_default Created
✔ Container <PROJECT>-db-1 Created
✔ Container <PROJECT>-web-1 Created
Attaching to db-1, web-1
web-1 | Server listening on 0.0.0.0:<PORT>Running 3/3 表示本轮资源操作已完成;Attaching to 表示终端已连接各服务日志。命令不会立即返回,后续带 <SERVICE>-1 | 前缀的行是对应容器的标准输出。
高频用法
docker compose up --build 适合 Dockerfile、构建参数或本地源码需要重新进入镜像时;docker compose up --force-recreate 用于必须无条件替换容器的场景;docker compose up --remove-orphans 可清理已从当前配置移除的同项目容器;docker compose --profile <PROFILE> up 会额外启用指定 Profile 内的服务。
风险与边界
前台运行时按 Ctrl+C 会停止本次项目容器,而不只是退出日志界面;只想离开终端时应改用后台启动。使用 --force-recreate 会替换全部相关容器,可能造成短时中断;使用 --remove-orphans 会删除当前配置未声明的同项目容器。生产环境先用 docker compose config --services 核对服务范围,并确认数据写入命名卷或外部存储。
up 启动的是“当前已启用服务”,不是配置文件中的绝对全部服务。带 Profile 的服务只有在 Profile 被激活时才会启动;显式指定某个服务时,默认仍会启动其依赖,除非使用 --no-deps。
排障清单
配置解析失败时先运行 docker compose config;端口占用时检查报错中的宿主机端口并调整 ports;镜像或构建内容未更新时使用 docker compose pull 或 docker compose up --build;服务启动后立即退出时查看当前前台日志,或另开终端运行 docker compose ps -a 与 docker compose logs <SERVICE>。
以后台模式启动项目并立即返回终端。
后台启动服务
当需要启动 Compose 项目后立即取回终端,用于服务器常驻运行、继续执行部署脚本或稍后单独查看日志时,使用 docker compose up -d。它与前台 up 执行相同的创建和重建逻辑,但不会把当前终端附着到容器日志。
基本语法与验证
docker compose up -d
docker compose ps预期输出(名称、镜像、端口和时间会因项目而异):
[+] Running 3/3
✔ Network <PROJECT>_default Created
✔ Container <PROJECT>-db-1 Started
✔ Container <PROJECT>-web-1 Started
NAME IMAGE SERVICE STATUS PORTS
<PROJECT>-db-1 <IMAGE> db Up <TIME> 5432/tcp
<PROJECT>-web-1 <IMAGE> web Up <TIME> 0.0.0.0:<PORT>->8080/tcpStarted 只表示容器进程已被启动;docker compose ps 中的 Up 表示进程仍在运行。若服务配置了健康检查,还应确认状态出现 healthy,不能仅凭后台命令返回成功判断应用已经可用。
高频用法
docker compose up -d --build 在后台启动前重建镜像;docker compose up -d <SERVICE> 只更新指定服务及其依赖;docker compose up -d --wait --wait-timeout 60 会等待服务进入运行或健康状态,适合自动化部署;docker compose logs -f --tail=100 <SERVICE> 用于后台启动后持续跟踪最近日志。
风险与边界
使用 -d 后错误日志不会持续显示,服务可能在命令成功返回后进入退出、重启或不健康状态。安全做法是紧接着检查 docker compose ps -a,并读取异常服务日志。配置或镜像变化时,up -d 可能重建容器并造成短时连接中断;只更新单个无依赖变更的服务时,可评估使用 --no-deps <SERVICE>,但依赖版本不一致时不要这样做。
后台运行不会让容器脱离 Compose 项目管理。停止项目使用 docker compose stop,停止并删除项目容器与网络使用 docker compose down;后者在附加 -v 时还会删除声明的命名卷,存在数据丢失风险,除非已确认卷可重建或已有备份,否则不要使用。
排障清单
状态为 Exited 时运行 docker compose logs <SERVICE> 查找退出原因;状态为 Restarting 时检查启动命令、环境变量和依赖连接;状态为 unhealthy 时检查镜像中的健康检查命令及其超时;端口未暴露时核对 ports 与 docker compose ps 的 PORTS 列。旧版独立命令使用 docker-compose,而 --wait 依赖较新的 Docker Compose v2,参数不可用时先运行 docker compose version 确认版本。
只启动目标服务及其必要依赖,避免拉起整个项目。
启动指定服务
用于只拉起一个目标服务,并按 depends_on 声明自动创建和启动它需要的依赖,避免执行 docker compose up -d 时启动整个项目。
命令定位
在包含 compose.yaml、compose.yml、docker-compose.yaml 或 docker-compose.yml 的目录执行。命令末尾填写 Compose 配置中的服务名,例如 api,不是容器名或镜像名。可先运行 docker compose config --services 核对服务名。
基本语法
docker compose up [选项] 服务名...假设 api 通过 depends_on 声明了 db 和 redis,后台启动目标服务及这些依赖:
docker compose up -d api预期输出
[+] Running 3/3
✔ Container <PROJECT>-db-1 Healthy
✔ Container <PROJECT>-redis-1 Started
✔ Container <PROJECT>-api-1 Started<PROJECT> 通常取目录名或顶层 name 配置,实际容器顺序和状态文案可能不同。目标服务显示 Started 或 Running,表示容器已经启动;依赖是否真正可用还需结合健康检查确认。
常用参数
-d:在后台运行;不加时会持续附着到容器日志。--build:启动前重新构建镜像,适合 Dockerfile、依赖文件或构建上下文已经变化的场景。--no-deps:只处理目标服务,不启动其依赖;仅在依赖已经可用时使用。--force-recreate:即使配置未变化也重建容器,适合排除旧容器状态,但会产生短暂中断。
代码或镜像内容变化时可使用 docker compose up -d --build api。确认数据库、缓存等依赖已正常运行后,才考虑使用 docker compose up -d --no-deps api。
风险与边界
Compose 只启动 depends_on 明确声明的依赖,不会根据应用实际访问的主机名自动推断依赖。遗漏声明时,目标容器可能先启动后因连接失败而退出;应补充依赖关系,并让应用具备连接重试能力。
依赖容器处于 Started 不代表服务已经就绪。未配置健康检查时,应用可能在数据库初始化完成前发起连接。安全方案是为依赖设置 healthcheck,配合健康条件控制启动,或在应用侧实施有上限的重试。
目标服务的配置、镜像或挂载发生变化时,up 可能重建容器并造成短暂中断。生产环境应先运行 docker compose config 检查最终配置,避免在业务高峰期使用 --force-recreate。
排障清单
- 报
no such service:运行docker compose config --services,确认服务名及当前加载的配置文件。 - 容器已启动但应用不可用:运行
docker compose ps,再用docker compose logs --tail=100 api查看启动错误。 - 修改代码未生效:确认是否使用绑定挂载;代码位于镜像内时追加
--build。 - 拉起了不需要的容器:检查目标服务的
depends_on,必要时拆分配置或重新整理依赖关系。
兼容性
Compose v2 使用 docker compose。旧版 Compose v1 对应 docker-compose,多数参数相同,但新环境应优先使用持续维护的 Compose v2。
停止项目容器但保留容器、网络和数据卷。
停止服务
用于停止 Compose 项目的一个或多个容器,同时保留容器、网络和数据卷,便于之后使用 docker compose start 原地恢复。该命令不会删除已有资源。
命令定位
在项目 Compose 配置所在目录执行。未指定服务名时停止当前项目的全部服务;指定服务名时只停止列出的服务。服务名来自 Compose 配置中的 services,不是 docker ps 显示的容器名。
基本语法
docker compose stop [选项] [服务名...]停止 api 和 worker,并给进程最多 30 秒完成优雅退出:
docker compose stop -t 30 api worker预期输出
[+] Stopping 2/2
✔ Container <PROJECT>-worker-1 Stopped
✔ Container <PROJECT>-api-1 Stopped<PROJECT> 为实际 Compose 项目名,停止顺序和耗时可能不同。显示 Stopped 表示容器进程已经退出,但容器对象仍然存在;使用 docker compose ps -a 仍可查看这些容器。
常用参数
- 不带服务名:
docker compose stop,停止当前 Compose 项目的全部服务。 - 指定服务名:只停止目标服务,例如
docker compose stop api worker,不会自动停止它们依赖的数据库或缓存。 -t, --timeout <秒>:发送停止信号后等待指定时间,超时后再强制终止容器进程。
恢复已停止的容器使用 docker compose start api worker。如果 Compose 配置、镜像、环境变量或挂载已经变化,不要只执行 start,应改用 docker compose up -d api worker 重新评估并应用配置。
风险与边界
stop 会发送镜像配置的停止信号,通常为 SIGTERM;等待超时后可能使用 SIGKILL 强制结束。应用忽略信号或退出耗时较长时,过短的超时可能造成事务未提交、缓冲区未刷盘或任务处理中断。安全方案是先停止入口流量或任务消费,再按应用实际停机时间增大 -t。
不要把 stop 与 down 混用。docker compose down 会删除项目容器和默认网络;追加 -v 还会删除由 Compose 管理的数据卷,可能导致持久化数据丢失。只需暂时停机并保留现场时,应优先使用 stop。
停止某个应用服务不会自动停止其依赖,因此数据库、缓存等容器可能继续占用资源。这不是异常;需要停止整个项目时,应不带服务名执行 docker compose stop。
排障清单
- 停止后端口仍可访问:检查是否存在同镜像的非 Compose 容器,或是否有其他项目占用同一端口。
- 命令长时间等待:检查应用是否正确处理停止信号;优先修复信号处理或调整
-t,不要直接删除数据卷。 docker compose start后配置未更新:这是预期行为;使用docker compose up -d重新应用配置。- 误停全部服务:执行命令时在末尾明确填写服务名,并先用
docker compose config --services核对。
兼容性
Compose v2 使用 docker compose stop。旧版 Compose v1 使用 docker-compose stop,核心行为相近,但新环境应优先使用 Compose v2。
停止并删除 Compose 创建的容器和默认网络。
移除 Compose 项目
用于结束当前 Compose 项目并清理其容器与项目网络。默认执行 docker compose down 不删除命名卷、匿名卷、外部网络或镜像,适合开发环境收尾、重新创建容器,或部署前清除旧项目资源。
命令定位
在目标 compose.yaml 所在目录执行,Compose 会根据配置文件、项目名和当前目录定位资源。移除整个项目时不要附加服务名;存在多个配置文件或自定义项目名时,应继续使用启动时相同的 -f、-p 参数。
基本语法为 docker compose down [OPTIONS] [SERVICES]。项目级清理通常使用 docker compose down,而不是逐个执行 docker rm,这样可以同步移除 Compose 创建的默认网络。
高频用法
先列出项目资源,再停止并移除容器、默认网络以及已脱离当前配置的孤儿容器,最后确认项目中已无容器:
# 必须在正确的 Compose 项目目录执行
docker compose ps
docker compose down --remove-orphans
docker compose ps -a预期输出如下,<PROJECT>、镜像名和耗时会随实际项目变化:
NAME IMAGE COMMAND SERVICE CREATED STATUS
<PROJECT>-web-1 app:latest <CMD> web <TIME> ago Up <TIME>
<PROJECT>-db-1 postgres <CMD> db <TIME> ago Up <TIME>
[+] Running 3/3
✔ Container <PROJECT>-web-1 Removed
✔ Container <PROJECT>-db-1 Removed
✔ Network <PROJECT>_default Removed
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS最后一次 docker compose ps -a 只剩表头,表示该项目的 Compose 容器已经移除。若仍有数据行,先核对项目名、配置文件和残留容器是否属于另一个 Compose 项目。
常用参数
| 参数 | 什么时候用 | 影响 |
|---|---|---|
--remove-orphans |
配置中已删除或改名服务后清理旧容器 | 同时删除不再由当前配置声明的项目容器 |
-t, --timeout <秒> |
服务优雅退出需要更长时间 | 超时后容器可能被强制终止 |
-v, --volumes |
明确要清空项目数据卷 | 删除配置声明的命名卷和容器匿名卷 |
--rmi local |
清理没有自定义标签的本地服务镜像 | 下次启动可能重新构建或拉取 |
--rmi all |
确认服务镜像也不再需要 | 删除服务使用的镜像,影响后续启动速度 |
风险与边界
使用 -v 时,只要数据库、上传文件或缓存写在项目卷中,就可能造成不可恢复的数据丢失。安全做法是先确认卷名并完成备份,日常重建仅执行不带 -v 的 docker compose down。
使用 --rmi all 会删除服务镜像;离线环境或私有仓库不可用时,项目可能无法再次启动。更安全的替代方案是省略该参数,或仅使用 --rmi local 清理可重新构建的本地镜像。
项目名选错时,命令可能清理同目录之外的另一组同名资源。执行前用 docker compose ls 和 docker compose ps 核对项目;通过 -p <PROJECT> 启动过的项目,清理时必须使用相同项目名。外部网络和外部卷不会被 down 删除,需要单独管理。
排障清单
- 提示找不到配置文件:切换到配置目录,或显式传入
-f <PATH>/compose.yaml。 - 容器仍然存在:检查是否使用了不同的
-p、COMPOSE_PROJECT_NAME或配置文件组合。 - 网络无法删除:通常仍有非本项目容器连接,先用
docker network inspect <NETWORK>找出占用者。 - 服务停止过慢:检查应用是否正确处理终止信号,再按实际优雅退出时间设置
--timeout,不要直接把超时压到极短。
Docker Compose v2 使用 docker compose;旧版独立程序使用 docker-compose。两者参数大体相近,但自动化脚本应统一版本并先用 docker compose version 验证。
临时冻结或恢复容器进程而不重启服务。
暂停与恢复 Compose 服务
用于临时冻结一个或多个服务的容器进程,并在稍后从原执行位置继续运行。它不会重建容器,也不会重新加载配置,适合短时间阻止任务消费、稳定现场取证,或在不丢失进程状态的情况下暂停处理。
命令定位
docker compose pause [SERVICE...] 暂停指定服务;docker compose unpause [SERVICE...] 恢复指定服务。省略服务名会作用于当前项目全部可处理的服务,因此生产环境应优先点名目标服务,避免把数据库、网关和监控一起冻结。
暂停后容器仍然存在,文件系统、内存和网络配置也会保留,但容器内进程不再执行。恢复不是重启:进程号、内存状态和已打开资源通常延续暂停前状态。
高频用法
下面的 Bash 示例自动选择当前项目第一个运行中的服务,暂停后读取状态,再恢复并复查。项目至少需要有一个正在运行的 Compose 服务:
# 自动选取一个运行中服务,避免把示例写死为 web 或 worker
SERVICE="$(docker compose ps --services --status running | head -n 1)"
test -n "$SERVICE" || { echo "没有可暂停的运行中服务"; exit 1; }
docker compose pause "$SERVICE"
docker compose ps --format '{{.Service}} {{.State}}' "$SERVICE"
docker compose unpause "$SERVICE"
docker compose ps --format '{{.Service}} {{.State}}' "$SERVICE"预期输出如下,<PROJECT>、<SERVICE> 和进度格式可能因版本及项目而不同:
[+] Pausing 1/1
✔ Container <PROJECT>-<SERVICE>-1 Paused
<SERVICE> paused
[+] Unpausing 1/1
✔ Container <PROJECT>-<SERVICE>-1 Unpaused
<SERVICE> running状态由 paused 变为 running,说明容器没有被重新创建,而是从冻结状态恢复。若示例输出“没有可暂停的运行中服务”,先用 docker compose up -d 启动项目或显式选择其他正在运行的服务。
常用方式
| 目标 | 命令 | 读取结果 |
|---|---|---|
| 暂停单个服务 | docker compose pause worker |
该服务全部容器进入暂停状态 |
| 暂停多个服务 | docker compose pause api worker |
仅冻结列出的服务 |
| 暂停整个项目 | docker compose pause |
当前项目全部运行中服务被冻结 |
| 恢复单个服务 | docker compose unpause worker |
该服务容器恢复执行 |
| 查看暂停状态 | docker compose ps --status paused |
只列出处于暂停状态的项目容器 |
风险与边界
暂停对客户端不是“优雅维护”。触发条件是容器进程被冻结但端口和连接仍存在,可能后果是请求无响应、上游超时、健康检查告警、任务锁长时间占用,数据库或消息系统客户端还可能误判节点故障。安全替代方案是先摘除流量、停止任务投递,再暂停目标服务;预计停机较长时使用 docker compose stop。
暂停期间内存不会释放,不能用它解决宿主机内存压力。需要降低资源占用时,应停止非必要服务,或调整资源限制后重新创建容器。应用若依赖墙上时钟、租约、心跳或短超时,恢复后可能立即触发过期逻辑,应先在测试环境验证。
不要把 pause 当成配置刷新或故障自愈。配置、环境变量或镜像已经变化时,应使用 docker compose up -d 让 Compose 判断是否重建;进程已经异常时,应使用 restart 或结合日志定位根因。
排障清单
- 报错“container is not running”:用
docker compose ps -a检查容器是否已退出,退出容器不能通过unpause启动。 unpause后仍无响应:检查应用日志、依赖连接和超时状态;恢复只继续执行,不会修复应用内部故障。- 找不到服务:用
docker compose config --services核对服务名,不要使用容器名代替 Compose 服务名。 - 误暂停全部服务:立即执行
docker compose unpause,再逐项检查数据库、队列和网关是否恢复健康。 - 状态不明确:使用
docker compose ps --status paused和docker compose ps --status running分别核对。
Docker Compose v2 使用 docker compose pause 与 docker compose unpause。Linux 通常通过 cgroup 冻结进程;Windows 仅特定容器隔离模式支持暂停,因此跨平台脚本应先在目标环境验证。
检查容器运行状态、端口映射和健康状态。
查看 Docker Compose 服务状态
在 Compose 项目目录中运行 docker compose ps,确认服务容器是否运行、健康检查是否通过,以及宿主机端口映射。适合部署验收、重启后核对和故障初筛。
基本语法
docker compose ps预期输出
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
demo-web-1 nginx:alpine "/docker-entrypoint.…" web 2 minutes ago Up 2 minutes (healthy) 0.0.0.0:8080->80/tcp
demo-worker-1 demo-worker "python worker.py" worker 2 minutes ago Up 2 minutes先看 SERVICE 和 STATUS:Up 表示容器正在运行,healthy 表示已配置的健康检查通过。0.0.0.0:8080->80/tcp 表示宿主机 8080 端口转发到容器 80 端口。名称、时间和端口以实际环境为准。
常用参数与用法
-a或--all:包含已退出、已创建但未运行的容器;默认只显示运行中的容器。--status exited:筛选指定状态,可用值包括running、exited、restarting、paused和dead等。--format json:输出 JSON Lines,便于脚本读取Service、State、Health、ExitCode和Publishers。--no-trunc:显示完整命令和字段;--services只列服务名;-q只列容器 ID。
部署后先用默认命令检查运行态。发现服务缺失时执行 docker compose ps --all;批量找异常退出容器时用 docker compose ps --status exited;自动化采集时使用 docker compose ps --format json。
健康状态只有定义了 healthcheck 才会出现。未配置健康检查的容器显示 Up,并不代表应用接口、数据库连接或下游依赖一定正常。
风险与边界
在错误目录或使用错误项目名时,命令可能返回空列表或另一个项目的容器,导致误判。安全做法是显式指定文件和项目:docker compose -f <PATH>/compose.yaml -p <PROJECT> ps,并核对容器名前缀。
ps 只展示 Docker 记录的状态,不解释退出原因。容器显示 Up 但接口不可用时,应继续检查探活、端口监听、网络依赖和日志;显示 Exited 时先看退出码和启动日志,不要反复重启掩盖故障。
排障清单
- 无输出:确认当前目录、Compose 文件、项目名和 Docker daemon 连接。
- 服务未列出:加
--all,再检查 profile 是否启用、容器是否创建。 - 持续
Restarting:查看服务日志,检查启动命令、环境变量和依赖可达性。 unhealthy:检查健康检查命令、间隔、超时及容器内依赖。PORTS为空:服务可能仅开放容器网络端口,或未配置ports。
速查:默认输出看运行态,--all 找消失的容器,日志解释异常原因。
集中查看项目或指定服务的容器日志。
查看 Docker Compose 服务日志
使用 docker compose logs 集中读取当前 Compose 项目中一个或多个服务的标准输出和标准错误。适合定位启动失败、请求异常、依赖连接错误和容器重启原因。
基本语法
docker compose logs --tail 100 --timestamps --no-color web预期输出
web-1 | <TIME> INFO server started on 0.0.0.0:8080
web-1 | <TIME> INFO GET /health 200 3msweb 是 Compose 服务名。每行前缀表示日志来源容器;<TIME> 是实际 RFC 3339 时间戳,具体值会变化。先定位第一条错误,再结合前后日志判断触发请求、依赖异常和重启顺序。
常用参数与用法
-f或--follow:持续跟随新日志,按Ctrl+C退出,不会停止容器。-n <N>或--tail <N>:每个容器只显示末尾 N 行,避免一次拉取全部历史日志。--since 30m:只看最近 30 分钟;--until设置结束时间,也可使用 RFC 3339 时间。-t或--timestamps:显示时间戳,跨服务对齐事件时使用。--no-color:移除颜色控制字符,适合保存或粘贴;--index <N>只看某个副本。
查看整个项目近期日志可用 docker compose logs --since 10m --tail 200;只追踪关键服务可用 docker compose logs -f gateway app;复盘明确时间窗口时同时设置 --since、--until 和 --timestamps。
多服务日志按到达顺序汇总,不保证不同容器时钟完全一致。分析并发故障时,应使用时间戳、请求 ID 或追踪 ID 串联事件,不要只凭终端中的相邻行判断严格先后。
风险与边界
不带 --tail 读取大量历史日志,可能导致终端卡顿、传输增加并淹没关键错误。安全做法是先限定服务、时间和行数,再按需扩大范围。
日志可能包含令牌、Cookie、连接串或用户数据。复制到工单或外部平台前必须脱敏,只保留错误前后必要行,并删除认证头、密钥和个人信息。
命令只能读取 Docker 日志驱动可返回的内容。若配置为 none、使用不支持本地读取的远程日志方案,或旧日志已被轮转删除,输出可能为空或不完整,应改到对应日志平台查询。
排障清单
no such service:用docker compose config --services核对服务名、Compose 文件和 profile。- 没有日志:先用
docker compose ps --all确认容器已创建,再检查应用是否写入标准输出及日志驱动。 - 重复出现启动信息:容器可能处于重启循环,结合状态和退出码定位。
- 时间顺序混乱:加
--timestamps,并检查主机与容器时间同步。 - 输出难检索:关闭颜色、限定时间窗口后保存到受控文件,并限制权限、及时清理。
速查:先限定服务、时间和行数,再跟随日志;状态说明发生了什么,日志解释为什么。
实时跟踪服务日志并限制时间范围或输出行数。
持续跟踪 Docker Compose 日志
用于服务启动失败、接口报错或依赖异常时连续观察日志。优先同时限制时间窗口和历史行数,既能看到最近上下文,又避免首次读取大量旧日志;命令会持续等待新输出,按 Ctrl+C 只会停止查看,不会停止容器。
基本语法
docker compose logs [OPTIONS] [SERVICE...]不写服务名时汇总当前 Compose 项目的全部服务;指定一个或多个服务名时只查看目标服务。服务名来自 Compose 配置,可先用 docker compose config --services 确认。
高频用法
实时查看 web 最近 30 分钟内最多 200 行日志,并继续跟踪新输出:
docker compose logs --follow --since=30m --tail=200 web预期输出:
web-1 | <TIME> GET /health 200
web-1 | <TIME> GET /api/orders 500命令不会自动结束;后续日志会继续追加。<TIME>、容器序号和日志内容以实际环境为准。
只取 api 与 worker 各自最近 50 行,适合一次性收集现场:
docker compose logs --tail=50 api worker预期输出:
api-1 | <TIME> request completed status=200
worker-1 | <TIME> job <ID> completed读取最近 2 小时的数据库日志并显示时间戳,便于和监控告警对齐:
docker compose logs --since=2h --timestamps db预期输出:
db-1 | <TIME> database system is ready to accept connections常用参数与输出
-f, --follow:保持连接并输出新日志,适合复现问题时观察。--since=30m:仅显示指定时间之后的日志,可用相对时长或受支持的时间戳格式。-n, --tail=200:限制每个容器返回的末尾行数;all会读取全部可用日志。-t, --timestamps:显示日志时间戳,跨服务排查时更容易排序。--no-color:移除 ANSI 颜色,适合重定向到文件或交给文本工具处理。--no-log-prefix:隐藏服务与容器前缀;仅在单服务输出时使用,避免多服务日志无法区分来源。
默认前缀通常为 服务名-实例序号 | 日志正文。多副本服务会出现不同实例序号;同一时刻的多服务日志按到达客户端的顺序显示,不等同于严格的全局时间排序。
风险与边界
未设置 --tail 或 --since 且历史日志很大时,首次读取可能耗时并占用终端与网络;安全做法是先用较小的 --tail 获取现场,再逐步扩大范围。应用若把令牌、密码或个人数据写入日志,跟踪、复制或重定向都会扩大泄露范围,应先脱敏并限制文件权限。
日志为空不一定代表服务没有运行。应用可能只写文件而非标准输出,容器可能刚被重建,或 Docker 日志驱动未保留可读取记录。此时检查容器状态、应用日志路径和 Docker 日志驱动,不要反复无上限拉取。
排障清单
- 出现
no such service:运行docker compose config --services,确认当前目录、-f配置文件和服务名。 - 没有新输出:确认服务正在运行,并验证应用是否写入标准输出或标准错误。
- 日志过多:增加
--since、减小--tail,或只指定异常服务。 - 时间对不上:启用
--timestamps,同时核对主机、容器与日志平台的时区。 - 多副本难以定位:先用
docker compose ps找到实例,再结合服务副本和请求标识筛选。
兼容性
推荐 Docker Compose V2 的 docker compose。旧版 V1 使用 docker-compose,多数日志参数相近,但 V1 已不适合作为新环境基线;脚本中应先用 docker compose version 校验实际版本。
在已启动的服务容器内执行 Shell 或诊断命令。
进入运行中的 Docker Compose 容器
用于在已启动的服务容器内执行 Shell、查看进程、验证网络或读取配置。docker compose exec 不会创建新容器,命令直接在现有服务实例中运行,因此看到的是当前运行现场。
基本语法
docker compose exec [OPTIONS] SERVICE COMMAND [ARG...]SERVICE 是 Compose 服务名,不是容器名。目标容器必须处于运行状态;服务有多个副本时,默认进入第一个实例,可用 --index 指定。
高频用法
先执行一次无交互诊断,确认容器身份和当前工作目录:
docker compose exec web sh -lc 'printf "container=%s\n" "$HOSTNAME"; pwd'预期输出:
container=<CONTAINER_ID>
<PATH><CONTAINER_ID> 和 <PATH> 由镜像及 Compose 配置决定。该方式比直接开 Shell 更适合留存排障记录。
进入交互式 Shell;精简镜像通常只有 sh:
docker compose exec web sh预期结果:
<PATH> #出现容器内提示符即表示进入成功;输入 exit 返回宿主机。提示符可能是 $ 或 #,取决于容器用户权限。
在 CI 或管道中关闭伪终端,避免 the input device is not a TTY:
docker compose exec -T web sh -lc 'printf "ready\n"'预期输出:
ready检查容器内 DNS 解析。以下命令依赖镜像已包含 getent:
docker compose exec web getent hosts db预期输出:
<IP> db输出 <IP> 表示容器内 DNS 能解析服务名 db;没有输出或返回非零状态时,继续检查网络、服务名和容器状态。
常用参数
-T:禁用伪终端,适合 CI、重定向和管道;交互式 Shell 通常不要加。-u, --user <USER>:以指定用户执行,生产环境优先使用非 root 用户。-w, --workdir <PATH>:覆盖命令工作目录,目录必须已存在。-e, --env KEY=VALUE:仅为本次执行增加或覆盖环境变量。--index <N>:服务有多个副本时选择第 N 个容器实例。--privileged:扩大容器权限;仅在明确评估风险且普通诊断无法完成时临时使用。
风险与边界
以 root 身份修改文件、安装软件或删除数据时,可能立即影响线上进程;容器重建后,这些改动通常还会丢失,造成“临时修好但无法复现”。安全替代方案是先执行只读命令,必要变更写回 Dockerfile、Compose 配置或挂载卷,再通过重建部署验证。
启用 --privileged、访问宿主机挂载或在容器中操作 Docker Socket 时,可能获得接近宿主机级别的控制能力。除非已有审批和隔离措施,否则不要用于常规排障;优先使用最小权限用户、只读挂载和专用诊断镜像。
排障清单
- 出现
service ... is not running:先运行docker compose ps,启动目标服务后重试。 - 出现
executable file not found:镜像可能没有bash或诊断工具,改用sh,不要直接在生产容器内安装临时软件。 - 出现 TTY 错误:自动化环境加
-T;需要交互时移除-T。 - 服务有多个副本但现场不一致:结合
docker compose ps,使用--index <N>进入指定实例。 - 用户或目录错误:使用
--user、--workdir明确上下文,并先确认目标用户和目录存在。 - 命令执行后状态仍异常:检查修改是否只发生在单个实例,或是否会被健康检查、重启策略和容器重建覆盖。
兼容性
推荐 Docker Compose V2 的 docker compose exec。旧版 V1 使用 docker-compose exec;参数大体相近,但脚本仍应按实际版本验证。Distroless 或 scratch 镜像可能完全没有 Shell,此时不能靠 exec ... sh 进入,应使用应用自带诊断接口、旁路调试容器或重新构建含受控调试能力的镜像。
基于服务配置创建临时容器执行迁移、测试或管理命令。
运行一次性命令
需要执行迁移、测试、脚本或管理命令,又不想改动服务的长期启动命令时,使用 docker compose run。它会按指定服务的镜像、网络、环境变量和卷创建新容器,并用本次命令覆盖服务的 command。
命令定位
语法为 docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]。SERVICE 是 Compose 文件中的服务名,不是容器名。该命令不会进入正在运行的服务容器;要在现有容器内执行命令,应使用 docker compose exec SERVICE COMMAND。
主示例
创建可直接运行的 compose.yaml:
services:
toolbox:
image: alpine:3.20
working_dir: /work
volumes:
- .:/work执行一次性任务,并在退出后删除临时容器:
docker compose run --rm toolbox sh -lc 'printf "one-off-ok\n"'预期输出:
one-off-ok首次执行可能先显示镜像拉取进度;最终输出 one-off-ok 且退出码为 0 即成功。--rm 只删除临时容器,不会删除绑定目录、命名卷或数据库数据。
常用参数与用法
迁移常用 docker compose run --rm web python manage.py migrate;CI 测试可加 -T 关闭伪终端;不启动依赖时加 --no-deps;确实需要服务端口时加 --service-ports,或用 -p <HOST_PORT>:<CONTAINER_PORT> 显式发布。
-e KEY=VALUE 临时覆盖环境变量,-u USER 指定用户,-w <PATH> 覆盖工作目录,--build 在运行前构建镜像。--entrypoint 会绕过镜像原入口逻辑,仅应在明确需要或诊断时使用。
风险与边界
run 默认不发布服务端口,临时启动 Web 进程后主机可能无法访问;安全做法是仅在需要时发布端口,并先确认没有冲突。一次性容器仍可访问挂载卷和外部数据库,误执行迁移、清理或写入脚本可能造成持久化数据变更;生产环境应先备份、核对目标环境,并避免并发执行迁移。
反复省略 --rm 会留下停止容器。不要直接执行范围过大的清理命令;先用 docker compose ps -a 确认对象,再删除明确的容器。
排障清单
出现 no such service 时运行 docker compose config --services 核对服务名。命令不存在时检查镜像内容、PATH 和工作目录。CI 报 TTY 错误时加 -T;端口不可访问时检查是否遗漏端口发布;依赖失败时查看 docker compose logs <SERVICE>。
Compose v2 使用 docker compose,旧版 v1 使用 docker-compose。新项目应优先使用 v2,并通过 docker compose version 核对环境。
重启指定服务或整个项目中的现有容器。
重启服务
容器进程异常、连接需要重建,或只需让现有服务停止后重新启动时,使用 docker compose restart。它可处理指定服务或整个项目中的容器,但不会重新构建镜像,也不会应用修改后的 Compose 配置和环境变量。
基本语法
语法为 docker compose restart [OPTIONS] [SERVICE...]。不写服务名会重启项目内全部服务;写多个服务名则只处理这些服务。-t, --timeout <SECONDS> 设置停止等待时间,--no-deps 用于不希望 Compose 连带处理依赖关系的场景。
主示例
前提是当前目录存在 Compose 文件,且 worker 服务已经创建:
docker compose restart -t 10 worker
docker compose ps --status running --services预期输出示例:
[+] Restarting 1/1
✔ Container <PROJECT>-worker-1 Started
worker<PROJECT> 会随目录名或 --project-name 改变,进度文字也可能因版本略有差异。验证重点是 worker 出现在运行服务列表中;命令成功只表示容器已启动,不代表应用健康检查一定通过。
高频用法与配置边界
重启单个服务用 docker compose restart api,多个服务用 docker compose restart api worker,整个项目用 docker compose restart。需要更多优雅退出时间时使用 docker compose restart -t 60 api,适合仍在处理请求、写文件或刷新缓存的进程。
修改 compose.yaml、.env、端口、卷或环境变量后,不要用 restart 期待配置生效。通常改用 docker compose up -d 让 Compose 检测差异并重建必要容器;需要重新构建镜像时使用 docker compose up -d --build;只有明确需要无条件重建时才加 --force-recreate。
风险与边界
重启会产生短暂中断,单副本服务在停止到启动期间不可用;生产环境应先确认流量切换、健康检查和上游重试策略。--timeout 过短时,进程可能来不及优雅退出并被强制终止,造成事务回滚、缓存丢失或文件写入不完整;应根据应用关闭耗时设置足够等待时间。
restart 不会拉取新镜像,也不会修复错误配置。若容器持续退出,重复重启只会形成故障循环并增加日志,应先定位退出原因。
排障清单
提示 no such service 时运行 docker compose config --services。重启后立即退出时查看 docker compose ps -a 和 docker compose logs --tail=100 <SERVICE>,重点检查退出码、缺失变量、端口冲突和依赖不可达。配置修改未生效时使用 docker compose up -d --force-recreate <SERVICE>。容器显示运行但业务不可用时继续检查健康状态、监听地址和应用日志。
Compose v2 使用 docker compose restart,旧版 v1 使用 docker-compose restart。生产脚本应通过 docker compose version 固定并验证运行环境。
忽略配置差异检测并重新创建服务容器。
强制重建容器
当服务容器状态可疑、启动参数未按预期生效,或需要无条件替换现有容器时,使用 docker compose up --force-recreate。它会重新创建目标服务容器,即使 Compose 判断配置和镜像没有变化;默认不会重新构建镜像,也不会删除命名卷。
基本语法
docker compose up -d --force-recreate [SERVICE...]-d 让服务后台运行;省略服务名会处理项目中的全部服务,指定服务名则缩小影响范围。预期输出
[+] Running 1/1
✔ Container <PROJECT>-web-1 Recreated<PROJECT> 由 Compose 项目名决定,终端中的计数、耗时和容器名可能不同;看到 Recreated 表示旧容器已被替换。
高频用法
- 全部服务强制重建:
docker compose up -d --force-recreate - 只重建
web:docker compose up -d --force-recreate web - 同时重建镜像:
docker compose up -d --build --force-recreate web - 连匿名卷一起更新:
docker compose up -d --force-recreate --renew-anon-volumes web
需要尽量避免依赖服务被联动启动时,可加 --no-deps;仅在确认依赖当前状态可用时使用。
验证结果
docker compose ps web预期输出
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
<PROJECT>-web-1 <IMAGE> "<COMMAND>" web <TIME> ago Up <TIME> <PORTS>重点检查 CREATED 是否刚更新、STATUS 是否为 Up 或 healthy。<IMAGE>、<COMMAND>、<TIME>、<PORTS> 取决于实际项目。
风险与边界
强制重建会停止并替换现有容器,触发条件是命令命中正在运行的服务;可能造成连接中断、短时不可用和未落盘进程数据丢失。生产环境应先确认健康检查、维护窗口和回滚镜像,并优先只指定单个服务。
使用 --renew-anon-volumes 时,匿名卷会被新卷替换,卷内未备份数据可能丢失。需要持久化的数据应改用命名卷并先备份。--force-recreate 本身不会刷新构建缓存;镜像内容可疑时加 --build,必要时先执行 docker compose build --no-cache <SERVICE>。
排障清单
- 容器未变化:确认当前目录、
-f文件和项目名是否正确,再运行docker compose config --services。 - 新容器立即退出:运行
docker compose logs --tail=100 <SERVICE>,检查入口命令、环境变量和依赖连接。 - 端口占用:先用
docker compose ps找旧容器,再检查宿主机端口冲突;不要直接删除不明进程。 - 数据未刷新:区分镜像层、绑定挂载、命名卷和匿名卷,按实际数据来源选择重建镜像或更新卷。
根据 Compose 中的 build 配置构建一个或多个服务镜像。
构建服务镜像
当 Compose 服务声明了 build,并且 Dockerfile、依赖文件或构建参数发生变化时,使用 docker compose build 生成一个或多个服务镜像。该命令只负责构建,不会启动、重建或替换正在运行的容器。
基本语法
docker compose build [OPTIONS] [SERVICE...]省略服务名会构建所有带 build 配置的服务;指定服务名可减少耗时和缓存扰动。服务只有 image、没有 build 时,不会从 Dockerfile 构建。
主示例
docker compose build --pull web预期输出
[+] Building <TIME> (<N>/<N>) FINISHED
=> [web internal] load build definition from Dockerfile
=> [web internal] load metadata for <BASE_IMAGE>
=> [web] exporting to image
=> => naming to <IMAGE_NAME><TIME>、<N>、基础镜像和最终镜像名由构建环境与 Compose 配置决定。最后出现 exporting to image 且命令退出码为 0,表示镜像已成功写入本地镜像存储;--pull 会尝试获取更新的基础镜像。
常用参数
--no-cache:不复用 Dockerfile 指令缓存,适合缓存疑似污染时使用。--pull:尝试拉取更新的基础镜像;它不等同于清空全部构建缓存。--build-arg KEY=VALUE:覆盖 Dockerfile 中声明的ARG,适合非敏感构建参数。--with-dependencies:同时构建目标服务依赖且也声明了build的服务。
需要查看完整构建步骤时,可使用 Compose 全局参数 docker compose --progress plain build web,便于定位具体失败层。
构建后运行
docker compose up -d --no-deps web预期输出
[+] Running 1/1
✔ Container <PROJECT>-web-1 Recreated首次启动时状态可能显示 Created 或 Started;已有容器使用了新镜像时通常显示 Recreated。需要一次完成构建和启动时,可直接使用 docker compose up -d --build web。
风险与边界
--no-cache 会使所有构建层重新执行,触发条件是显式开启该参数;可能显著增加时间、网络流量和镜像仓库压力。安全替代是先使用普通缓存构建并加 --pull,只有确认缓存异常后再无缓存重建。
不要通过 --build-arg 传入密码、令牌或私钥。构建参数可能出现在日志、缓存元数据或镜像历史中;敏感值应使用 BuildKit secret,并确保 Dockerfile 通过 secret mount 读取。构建成功也不代表服务可运行,仍需执行 docker compose up 并检查健康状态与应用日志。
排障清单
- 提示找不到 Dockerfile:检查
build.context、build.dockerfile相对路径,并运行docker compose config查看解析结果。 - 基础镜像拉取失败:先执行
docker login <REGISTRY>,再检查代理、DNS、证书和仓库权限。 - 修改未生效:确认文件位于构建上下文内且未被
.dockerignore排除;必要时使用--no-cache --pull。 - 磁盘不足:运行
docker system df评估占用,确认无用缓存后再定向清理,避免直接执行会误删资源的全局清理命令。
兼容性
本文使用 Compose v2 的 docker compose 语法。旧版独立程序通常写作 docker-compose;部分 BuildKit 参数、输出格式和构建能力会随 Docker Engine、Docker Desktop 与 builder 版本不同。