Docker Compose 命令大全：常用功能速查 – wiki基地

---

Docker Compose 命令大全：常用功能速查与深度解析

Docker Compose 是 Docker 官方提供的一个工具，用于定义和运行多容器 Docker 应用程序。通过一个 YAML 文件 (docker-compose.yml) 来配置应用的服务，然后通过简单的命令即可创建并启动所有服务。这极大地简化了复杂应用的部署和管理。

掌握 Docker Compose 的核心命令是高效开发和部署多容器应用的关键。本文旨在提供一份详尽的 Docker Compose 命令参考，覆盖最常用的功能，并提供速查和深度解析，帮助开发者快速定位所需命令并理解其背后原理。

请注意：自 Docker Engine 1.18 版本起，docker-compose 工具被集成到 Docker CLI 中，成为 docker compose 命令。本文将主要使用 docker compose 新语法，但其功能和 V1 版本 (docker-compose) 大体相同。

1. 前言：为什么需要 Docker Compose 命令？

在没有 Docker Compose 的情况下，启动一个包含 Web 服务器、数据库、缓存的微服务应用，你需要手动执行一系列 docker run 命令，分别启动每个容器，并手动配置它们之间的网络、卷等。这不仅繁琐，而且容易出错。

Docker Compose 通过一个声明式的 YAML 文件描述整个应用栈，包括服务（容器）、网络、卷等。而 Docker Compose 命令就是操作这个 YAML 文件所描述的应用栈的接口。你可以用一个命令启动整个应用，用另一个命令停止它，再用一个命令重建它，大大提高了效率和可重复性。

这份命令大全将是你在日常开发和部署工作中不可或缺的参考。

2. 环境准备：使用 Docker Compose

在使用 Docker Compose 命令之前，你需要确保以下几点：

• Docker Engine 安装： 确保你的系统上已经安装了 Docker。
• Docker Compose 安装：
  • 如果你使用的是较新版本的 Docker Desktop 或 Docker Engine (1.18+)，docker compose 命令可能已内置。
  • 如果需要独立安装 V2 版本，可以参考 Docker 官方文档进行安装。
  • 如果你仍在使用旧版本的 docker-compose (V1)，命令语法基本一致，只需将 docker compose 替换为 docker-compose。本文以 docker compose 为主。
• docker-compose.yml 文件： 你需要一个有效的 docker-compose.yml 文件来定义你的应用栈。本文的所有命令都假设你在包含 docker-compose.yml 文件的目录下执行，或者通过 -f 选项指定文件路径。

3. 全局选项与参数

在使用 docker compose 命令时，有些选项是全局性的，可以放在 docker compose 和具体命令之间。这些选项通常用于指定要使用的 Compose 文件、项目名称或设置其他环境参数。

语法:

bash
docker compose [全局选项] COMMAND [命令选项] [服务...] [命令参数]

常用全局选项:

• -f, --file FILE: 指定一个或多个 Compose 文件路径。如果指定了多个文件，它们的配置会合并，后面的文件会覆盖前面文件的相同配置。
  • 示例: docker compose -f docker-compose.yml -f docker-compose.override.yml up
• -p, --project-name NAME: 指定项目名称。项目名称用于隔离不同 Compose 应用的网络、卷和容器名称（通常前缀是 <projectname>_<service>_<index>）。默认情况下，项目名称是当前目录的名称。
  • 示例: docker compose -p myapp_staging up
• --env-file FILE: 读取环境变量文件。Compose 文件中可以使用 ${VAR} 或 $VAR 语法引用环境变量。
  • 示例: docker compose --env-file .env up
• --verbose: 显示更详细的输出信息，用于调试。
• --no-ansi: 禁用 ANSI 控制符输出，用于在不支持 ANSI 的终端或脚本中使用。
• --profile NAME: 启用指定的 profile。在 docker-compose.yml 中，服务可以关联到特定的 profile，只在指定 profile 激活时才启动。
  • 示例: docker compose --profile debug up

服务参数:

很多命令都支持在命令后面指定一个或多个服务名称。这样命令只会作用于指定的这些服务及其依赖的服务。
* 示例: docker compose up web db (只启动 web 和 db 服务及其依赖)
* 示例: docker compose logs web (只查看 web 服务的日志)

4. 常用 Docker Compose 命令速查与详解

接下来，我们将详细介绍最常用和重要的 Docker Compose 命令。

4.1 docker compose up – 启动应用栈

用途: 构建、（重新）创建、启动并关联定义在 Compose 文件中的服务。这是最常用的命令，用于启动整个应用或指定的某个/某几个服务。

语法:

bash
docker compose [全局选项] up [命令选项] [服务...]

详细描述:

up 命令会执行以下步骤（取决于选项）：
1. 查找 docker-compose.yml 文件。
2. 构建或拉取每个服务的镜像（如果需要）。
3. 创建并启动服务的容器。
4. 为容器创建网络和卷（如果需要）。
5. 将容器连接到指定的网络。
6. （默认情况下）会将容器的标准输出连接到当前终端，显示日志。

常用命令选项:

• -d, --detach: 在后台运行容器，并退出终端。这是生产环境或长期运行应用的标准模式。
  • 示例: docker compose up -d
• --build: 在启动前强制重新构建服务镜像。即使镜像没有更改，也会执行构建过程。
  • 示例: docker compose up --build
• --no-build: 不构建镜像，如果镜像不存在则会报错。用于确保只使用已有的镜像。
  • 示例: docker compose up --no-build
• --force-recreate: 强制重新创建容器，即使其配置或镜像没有变化。会先停止并移除现有容器，再创建新的。
  • 示例: docker compose up --force-recreate
• --no-recreate: 如果容器已经存在且处于运行状态，则不做任何操作。
  • 示例: docker compose up --no-recreate
• --no-deps: 不启动服务所依赖的服务。只启动指定的顶级服务。
  • 示例: docker compose up --no-deps web (只启动 web，不启动 web 依赖的 db)
• --abort-on-container-exit: 任何容器退出时，停止所有容器。对于运行测试或一次性任务很有用。
• --attach SERVICE: 连接到指定的服务的输出。可以指定多个服务，或使用通配符。默认连接所有服务。
• --remove-orphans: 移除那些在 Compose 文件中不再定义但属于该项目的容器。这发生在更新 Compose 文件移除某个服务后。
  • 示例: docker compose up --remove-orphans
• --scale SERVICE=NUM: 启动时覆盖服务的容器数量。
  • 示例: docker compose up --scale web=3 worker=2 (启动 web 3个实例，worker 2个实例)
• --wait: 等待服务达到稳定状态后退出。稳定状态通常指容器健康检查通过，或者容器已停止（如果定义了 restart: “no” 或 “on-failure” 且已完成）。

示例:

• 启动当前目录下 docker-compose.yml 定义的所有服务，并在前台显示日志：
  bash
docker compose up
• 在后台启动所有服务：
  bash
docker compose up -d
• 强制重建 web 和 api 服务的镜像后，启动所有服务（如果容器存在则强制重建）：
  bash
docker compose up --build --force-recreate web api
• 启动所有服务，并移除不再在 docker-compose.yml 中定义的属于该项目的旧容器：
  bash
docker compose up -d --remove-orphans

注意:
* up 命令是幂等的，多次执行 docker compose up -d 通常不会创建新的容器，除非配置或镜像发生了变化。
* 默认情况下，如果镜像不存在，up 会尝试构建或拉取。使用 --no-build 或 --no-pull 可以改变此行为。

4.2 docker compose down – 停止并移除应用栈

用途: 停止并移除 docker compose up 命令创建的容器、网络、卷和镜像。

语法:

bash
docker compose [全局选项] down [命令选项]

详细描述:

down 命令会执行以下步骤：
1. 停止属于该项目的所有正在运行的容器。
2. 移除这些容器。
3. 移除由 Compose 自动创建的默认网络。
4. 移除匿名数据卷（取决于选项）。
5. 移除镜像（取决于选项）。

常用命令选项:

• --volumes, -v: 移除匿名数据卷以及 Compose 文件中指定了 name 或驱动不是 local 的命名卷。谨慎使用，这会删除数据！
  • 示例: docker compose down --volumes
• --rmi type: 移除镜像。type 可以是 local (只移除没有自定义标签的镜像) 或 all (移除所有Compose文件引用的镜像，包括带自定义标签的)。
  • 示例: docker compose down --rmi all
• --timeout SECONDS: 停止容器的超时时间（秒），默认 10 秒。
  • 示例: docker compose down --timeout 60

示例:

• 停止并移除所有容器和默认网络：
  bash
docker compose down
• 停止并移除所有容器、默认网络以及匿名卷：
  bash
docker compose down --volumes
• 停止并移除所有容器、默认网络，并移除 Compose 文件中引用的所有镜像：
  bash
docker compose down --rmi all

注意:
* down 命令是 up 命令的逆过程，用于清理资源。
* 默认情况下，命名卷（在 volumes 顶级键下定义并引用的卷）不会被移除，以防止数据丢失。使用 --volumes 选项时要格外小心，特别是对于数据库卷。

4.3 docker compose build – 构建服务镜像

用途: 构建 Compose 文件中定义的服务镜像。这个命令只执行构建过程，不会启动容器。

语法:

bash
docker compose [全局选项] build [命令选项] [服务...]

详细描述:

对于 Compose 文件中 build 关键字定义的服务，此命令会根据 Dockerfile 构建新的镜像。对于 image 关键字定义的服务，此命令不做任何操作（除非同时使用了 build 和 image，build 优先）。

常用命令选项:

• --no-cache: 构建镜像时不使用缓存。每次都从头构建。
  • 示例: docker compose build --no-cache
• --pull: 总是尝试拉取更新的基础镜像。
• --progress string: 设置构建进度显示类型 (auto, plain, tty)。默认 auto。
• --build-arg key=val: 设置构建时的变量。
  • 示例: docker compose build --build-arg VERSION=1.2.3 web

示例:

• 构建 Compose 文件中所有服务的镜像：
  bash
docker compose build
• 构建 web 服务的镜像，不使用构建缓存：
  bash
docker compose build --no-cache web

注意:
* 通常情况下，docker compose up --build 足够满足需求，因为它会在启动前自动构建。但如果你只想构建镜像而不启动服务，或者想在 CI/CD 流程中分开构建和部署，build 命令就很有用。

4.4 docker compose start – 启动已停止的服务

用途: 启动之前通过 stop 或 down 命令停止的、但尚未移除的服务容器。

语法:

bash
docker compose [全局选项] start [服务...]

详细描述:

此命令不会创建新容器，也不会重建镜像。它只会启动处于停止状态的现有容器。

示例:

• 启动所有已停止的服务：
  bash
docker compose start
• 启动 web 和 worker 服务（如果它们已停止）：
  bash
docker compose start web worker

注意:
* 如果服务容器不存在，此命令会报错。要创建和启动容器，请使用 docker compose up。

4.5 docker compose stop – 停止运行中的服务

用途: 优雅地停止运行中的服务容器。

语法:

bash
docker compose [全局选项] stop [命令选项] [服务...]

详细描述:

此命令会向容器发送 SIGTERM 信号，等待容器中的进程自行终止。如果在指定的超时时间内进程未能终止，会强制发送 SIGKILL 信号。容器会被停止，但不会被移除。

常用命令选项:

• --timeout SECONDS: 停止容器的超时时间（秒），默认 10 秒。
  • 示例: docker compose stop --timeout 60

示例:

• 停止所有运行中的服务：
  bash
docker compose stop
• 停止 web 服务：
  bash
docker compose stop web

注意:
* 停止后的容器可以使用 docker compose start 重新启动。要停止并移除容器，请使用 docker compose down。

4.6 docker compose restart – 重启服务

用途: 重启运行中的服务容器。

语法:

bash
docker compose [全局选项] restart [命令选项] [服务...]

详细描述:

此命令会先停止（发送 SIGTERM，超时后 SIGKILL）指定的容器，然后立即重新启动它们。

常用命令选项:

• --timeout SECONDS: 重启时停止容器的超时时间（秒），默认 10 秒。

示例:

• 重启所有服务：
  bash
docker compose restart
• 重启 web 和 nginx 服务：
  bash
docker compose restart web nginx

4.7 docker compose exec – 在容器中执行命令

用途: 在指定服务的运行中容器内执行任意命令。

语法:

bash
docker compose [全局选项] exec [命令选项] SERVICE COMMAND [参数...]

详细描述:

这是调试和维护运行中容器的强大工具。你可以使用它进入容器内部 shell、执行数据库迁移、运行诊断脚本等。

常用命令选项:

• -d, --detach: 在后台执行命令。
• -it: 分配一个伪 TTY 并保持标准输入打开，用于交互式会话（例如进入容器 shell）。这是最常用的选项组合。
• -e KEY=VALUE: 设置环境变量，只对当前执行的命令生效。
• -u USER: 指定执行命令的用户。
• --index index: 如果服务有多个实例（例如使用 --scale 或 deploy 模式），指定要执行命令的实例索引（从 1 开始）。

示例:

• 在 web 服务容器中执行 ls -l /app 命令：
  bash
docker compose exec web ls -l /app
• 进入 web 服务的 bash shell（最常用方式）：
  bash
docker compose exec -it web bash
• 在 db 服务容器中以 postgres 用户执行 psql 命令连接到数据库：
  bash
docker compose exec -it db psql -U postgres
• 在 worker 服务的第二个实例中执行一个命令：
  bash
docker compose exec --index 2 worker my_command

注意:
* exec 命令要求目标容器必须处于运行状态。
* 与 docker compose run 不同，exec 在现有容器中执行命令，不会创建新容器。

4.8 docker compose run – 运行一次性命令

用途: 在指定服务的环境中运行一个一次性命令。

语法:

bash
docker compose [全局选项] run [命令选项] SERVICE COMMAND [参数...]

详细描述:

run 命令会创建一个新的容器，该容器基于指定服务的镜像和配置（网络、卷等），但会覆盖启动命令为你在命令行中提供的 COMMAND。当命令执行完毕，容器默认会停止（使用 --rm 选项可以自动移除）。它不会与 docker compose up 启动的主应用生命周期绑定。

常用命令选项:

• --rm: 命令执行完毕后自动移除容器。对于一次性任务非常有用，避免留下大量停止的容器。强烈推荐使用此选项。
  • 示例: docker compose run --rm web python manage.py migrate
• -d, --detach: 在后台运行容器，并退出终端。
• -it: 分配一个伪 TTY 并保持标准输入打开，用于交互式命令（如 shell）。
• -e KEY=VALUE: 设置环境变量。
• -u USER: 指定执行命令的用户。
• --entrypoint COMMAND: 覆盖服务的 Entrypoint。
• --name NAME: 为一次性容器指定一个自定义名称。
• --no-deps: 不启动服务所依赖的服务。

示例:

• 在 web 服务环境中运行数据库迁移命令，并在完成后移除容器：
  bash
docker compose run --rm web python manage.py migrate
• 在 web 服务环境中启动一个交互式 shell（并完成后移除容器）：
  bash
docker compose run --rm -it web bash
• 在 worker 服务环境中运行一个后台处理任务：
  bash
docker compose run -d worker process_queue

注意:
* run 创建的是一个新容器，这与 exec 在现有容器中执行命令有本质区别。
* run 容器默认不会在项目网络中公开端口，除非在命令行中显式使用 -p 选项。
* run --rm -it service bash 是一个非常有用的组合，用于临时进入服务环境进行调试。

4.9 docker compose logs – 查看服务日志

用途: 查看服务容器的标准化输出日志。

语法:

bash
docker compose [全局选项] logs [命令选项] [服务...]

详细描述:

此命令从运行中的容器中抓取标准输出 (stdout) 和标准错误 (stderr)。

常用命令选项:

• -f, --follow: 持续输出新的日志（跟踪模式）。
  • 示例: docker compose logs -f web
• -t, --timestamps: 在每行日志前加上时间戳。
  • 示例: docker compose logs -t
• --tail number: 只显示日志的最后 N 行。
  • 示例: docker compose logs --tail 100 web
• --no-log-prefix: 不显示日志的来源（服务名称）。

示例:

• 显示所有服务的历史日志和新日志：
  bash
docker compose logs -f
• 显示 web 服务的最后 50 行日志：
  bash
docker compose logs --tail 50 web
• 显示 nginx 和 api 服务的带时间戳日志：
  bash
docker compose logs -t nginx api

4.10 docker compose ps – 列出服务容器

用途: 列出 Compose 文件中定义的服务及其运行状态。

语法:

bash
docker compose [全局选项] ps [命令选项] [服务...]

详细描述:

此命令会显示项目中每个服务容器的名称、命令、状态、端口映射等信息。

常用命令选项:

• -a, --all: 显示所有容器，包括停止的。默认只显示运行中的。
• --services: 只列出服务名称，每行一个。
• -q, --quiet: 只列出容器 ID。
• --format format: 格式化输出 (json, table)。

示例:

• 列出所有运行中的服务容器：
  bash
docker compose ps
• 列出所有服务容器（包括停止的）：
  bash
docker compose ps -a
• 只列出服务名称：
  bash
docker compose ps --services

4.11 docker compose config – 验证和查看配置

用途: 验证 Compose 文件的有效性，并显示合并后的配置。

语法:

bash
docker compose [全局选项] config [命令选项]

详细描述:

这个命令非常有助于调试 docker-compose.yml 文件。它可以检查 YAML 语法的正确性，并显示 Compose 解析、合并（如果使用了多个文件）和应用了环境变量后的最终配置。

常用命令选项:

• -q, --quiet: 只检查配置是否有效，不输出具体配置。如果配置无效则返回非零退出码。用于脚本中检查。
  • 示例: docker compose config -q
• --services: 只列出服务名称。
• --volumes: 只列出卷名称。
• --networks: 只列出网络名称。
• --hash: 打印配置文件的配置哈希，可以用来判断配置是否发生了变化。
• --format format: 格式化输出 (json, yaml)。

示例:

• 验证 docker-compose.yml 文件并显示最终配置：
  bash
docker compose config
• 只检查配置文件是否有效：
  bash
docker compose config -q
• 显示所有服务名称：
  bash
docker compose config --services

4.12 docker compose rm – 移除停止的服务容器

用途: 移除已停止的服务容器。

语法:

bash
docker compose [全局选项] rm [命令选项] [服务...]

详细描述:

此命令会移除通过 Compose 创建但目前处于停止状态的容器。默认情况下，它不会移除卷或网络。

常用命令选项:

• -f, --force: 强制移除容器，即使它们仍在运行。不建议在非交互式脚本中使用，除非非常确定。
  • 示例: docker compose rm -f
• -v: 移除与容器关联的匿名卷。
  • 示例: docker compose rm -v web

示例:

• 移除所有已停止的服务容器（会提示确认）：
  bash
docker compose rm
• 强制移除所有容器（包括运行中的，不提示）：
  bash
docker compose rm -f
• 移除 web 服务已停止的容器及其关联的匿名卷：
  bash
docker compose rm -v web

注意:
* docker compose down 通常是更常用的命令，因为它会先停止容器再移除，并且可以清理网络、卷和镜像。rm 更多用于清理单独停止的容器。

4.13 docker compose pull – 拉取服务镜像

用途: 拉取 Compose 文件中指定的镜像（使用 image 关键字）。

语法:

bash
docker compose [全局选项] pull [命令选项] [服务...]

详细描述:

对于 Compose 文件中使用 image 关键字指定了镜像的服务，此命令会从镜像仓库拉取最新的或指定的镜像版本。对于使用 build 关键字的服务，此命令无效。

常用命令选项:

• --ignore-pull-failures: 忽略拉取失败的错误，继续尝试拉取其他服务镜像。
• --include-deps: 也拉取依赖服务的镜像。

示例:

• 拉取所有服务所需的镜像：
  bash
docker compose pull
• 拉取 web 和 redis 服务的镜像：
  bash
docker compose pull web redis

4.14 docker compose top – 查看服务容器进程

用途: 显示服务容器中运行的进程。

语法:

bash
docker compose [全局选项] top [服务...]

详细描述:

类似于系统中的 top 命令或 Docker CLI 的 docker top 命令，显示指定服务容器内的进程信息。

示例:

• 显示所有运行中服务容器的进程：
  bash
docker compose top
• 显示 web 服务容器的进程：
  bash
docker compose top web

4.15 docker compose images – 列出 Compose 使用的镜像

用途: 列出 Compose 文件中使用的镜像。

语法:

bash
docker compose [全局选项] images

详细描述:

显示项目中每个服务对应的镜像仓库、标签、镜像ID、大小等信息。

示例:

• 列出项目中所有服务使用的镜像：
  bash
docker compose images

4.16 docker compose version – 显示版本信息

用途: 显示 Docker Compose 版本信息。

语法:

bash
docker compose version

示例:

• 显示 Docker Compose 版本：
  bash
docker compose version

5. 高级用法与注意事项

• 使用多个 Compose 文件: 通过 -f 选项指定多个文件，可以实现配置的分层和覆盖。例如，一个基础的 docker-compose.yml 定义应用结构，一个 docker-compose.dev.yml 添加开发环境特有的配置（如端口映射、卷挂载），一个 docker-compose.prod.yml 添加生产环境配置（如副本数、网络模式）。
  • docker compose -f docker-compose.yml -f docker-compose.dev.yml up
• 环境变量: Compose 文件支持使用环境变量，可以在文件中引用 ${VAR}。这些变量可以来自 .env 文件、Shell 环境变量或通过 --env-file 选项指定的文件。
• 项目名称的隔离: 使用 -p 或设置 COMPOSE_PROJECT_NAME 环境变量来明确项目名称，可以避免不同 Compose 应用之间的资源冲突。
• 服务间的依赖: Compose 会自动解析服务间的 depends_on 依赖关系，并确保依赖的服务先启动。
• 健康检查 (healthcheck): 在 docker-compose.yml 中定义服务的健康检查，可以配合 docker compose up --wait 选项，确保应用完全健康后再认为启动成功。

6. 总结

Docker Compose 及其命令是管理多容器 Docker 应用的强大工具集。通过这份命令大全，你应该能够快速查找并理解大部分日常开发和部署所需的命令。

• 使用 docker compose up 启动你的整个应用栈。
• 使用 docker compose down 清理资源。
• 使用 docker compose build 构建镜像。
• 使用 docker compose ps 查看应用状态。
• 使用 docker compose logs 查看日志。
• 使用 docker compose exec 在运行中容器内执行命令（调试）。
• 使用 docker compose run 运行一次性任务（数据库迁移、脚本）。
• 使用 docker compose config 验证和查看配置。

熟练掌握这些命令将极大地提升你使用 Docker 的效率和体验。记住，总有更多的选项和功能等待你去探索，官方文档永远是获取最权威和最新信息的最佳来源。祝你使用 Docker Compose 愉快！

---