Docker Compose

描述	Docker Compose
用法	`docker compose`

选项

选项	默认	描述
`--all-resources`		包含所有资源，即使未被服务使用
`--ansi`	`auto`	控制何时打印 ANSI 控制字符（"never"\|"always"\|"auto"）
`--compatibility`		在向后兼容模式下运行 compose
`--dry-run`		在空运行模式下执行命令
`--env-file`		指定备用环境文件
`-f, --file`		Compose 配置文件
`--parallel`	`-1`	控制最大并行度，-1 表示无限制
`--profile`		指定要启用的配置文件
`--progress`	`auto`	设置进度输出的类型 (auto, tty, plain, json, quiet)
`--project-directory`		指定一个备用工作目录（默认值：第一个指定的 Compose 文件的路径）
`-p, --project-name`		项目名称

示例

使用 `-f` 来指定一个或多个 Compose 文件的名称和路径

使用 -f 标志来指定 Compose 配置文件的位置。

指定多个 Compose 文件

您可以提供多个 -f 配置文件。当您提供多个文件时，Compose 会将它们合并为一个配置。Compose 按照您提供文件的顺序构建配置。后续的文件会覆盖并添加到其前置文件的配置中。

例如，考虑这个命令行：

$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db

docker-compose.yml 文件可能会指定一个 webapp 服务。

services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"

如果 docker-compose.admin.yml 也指定了相同的服务，任何匹配的字段都会覆盖先前文件中的内容。新值将添加到 webapp 服务配置中。

services:
  webapp:
    build: .
    environment:
      - DEBUG=1

当您使用多个 Compose 文件时，文件中的所有路径都相对于通过 -f 指定的第一个配置文件。您可以使用 --project-directory 选项来覆盖此基本路径。

使用 -f 和 - (连字符) 作为文件名以从标准输入读取配置。当使用标准输入时，配置中的所有路径都相对于当前工作目录。

-f 标志是可选的。如果您在命令行中未提供此标志，Compose 会遍历工作目录及其父目录以查找 compose.yaml 或 docker-compose.yaml 文件。

指定单个 Compose 文件的路径

您可以使用 -f 标志来指定不在当前目录中的 Compose 文件路径，可以通过命令行或者在 shell 或环境文件中设置 COMPOSE_FILE 环境变量来实现。

有关在命令行使用 -f 选项的示例，假设您正在运行 Compose Rails 示例，并且在名为 sandbox/rails 的目录中有一个 compose.yaml 文件。您可以像 docker compose pull 这样使用命令，通过使用 -f 标志从任何位置获取 db 服务的 postgres 镜像，如下所示：

$ docker compose -f ~/sandbox/rails/compose.yaml pull db

使用 `-p` 指定项目名称

每个配置都有一个项目名称。Compose 使用以下机制设置项目名称，按优先级顺序排列：

-p 命令行标志
COMPOSE_PROJECT_NAME 环境变量
配置文件中的顶层 name: 变量（或使用 -f 指定的一系列配置文件中的最后一个 name:）
项目目录的 basename，其中包含配置文件（或使用 -f 指定的第一个配置文件）
如果未指定配置文件，则为当前目录的basename 项目名称只能包含小写字母、十进制数字、连字符和下划线，并且必须以小写字母或十进制数字开头。如果项目目录或当前目录的basename违反此约束，则必须使用其他机制之一。

$ docker compose -p my_project ps -a
NAME                 SERVICE    STATUS     PORTS
my_project_demo_1    demo       running

$ docker compose -p my_project logs
demo_1  | PING localhost (127.0.0.1): 56 data bytes
demo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms

使用 --profile 来指定一个或多个活动配置文件调用 docker compose --profile frontend up 会启动带有配置文件 frontend 的服务以及未指定任何配置文件的服务。您也可以启用多个配置文件，例如使用 docker compose --profile frontend --profile debug up 会启用配置文件 frontend 和 debug。

配置文件也可以通过 COMPOSE_PROFILES 环境变量进行设置。

配置并行度

使用 --parallel 指定并发引擎调用的最大并行度。调用 docker compose --parallel 1 pull 会逐个拉取 Compose 文件中定义的可拉取镜像。这也可以用于控制构建并发。

并行度也可以通过 COMPOSE_PARALLEL_LIMIT 环境变量进行设置。

设置环境变量

您可以为各种 docker compose 选项设置环境变量，包括 -f、-p 和 --profiles 标志。

设置 COMPOSE_FILE 环境变量等同于传递 -f 标志， COMPOSE_PROJECT_NAME 环境变量与 -p 标志作用相同， COMPOSE_PROFILES 环境变量等同于 --profiles 标志而 COMPOSE_PARALLEL_LIMIT 与 --parallel 标志作用相同。

如果在命令行中显式设置了标志，则相关的环境变量将被忽略。

将 COMPOSE_IGNORE_ORPHANS 环境变量设置为 true 可阻止 docker compose 检测该项目的孤立容器。

将 COMPOSE_MENU 环境变量设置为 false 可以在以附加模式运行 docker compose up 时禁用辅助菜单。或者，您也可以运行 docker compose up --menu=false 来禁用辅助菜单。

使用 Dry Run 模式测试您的命令

使用 --dry-run 标志可以在不改变应用程序堆栈状态的情况下测试命令。 Dry Run 模式会显示 Compose 在执行命令时应用的所有步骤，例如：

$ docker compose --dry-run up --build -d
[+] Pulling 1/1
 ✔ DRY-RUN MODE -  db Pulled                                                                                                                                                                                                               0.9s
[+] Running 10/8
 ✔ DRY-RUN MODE -    build service backend                                                                                                                                                                                                 0.0s
 ✔ DRY-RUN MODE -  ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd                                                                                                                                                   0.0s
 ✔ DRY-RUN MODE -  ==> ==> naming to nginx-golang-mysql-backend                                                                                                                                                                            0.0s
 ✔ DRY-RUN MODE -  Network nginx-golang-mysql_default                                    Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Healthy                                                                                                                                           0.5s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started

从上面的示例中，您可以看到第一步是拉取由 db 服务定义的镜像，然后构建 backend 服务。接下来，创建容器。db 服务启动，backend 和 proxy 服务会等待 db 服务变为健康状态后再启动。

试运行模式适用于几乎所有命令。您不能将试运行模式用于不会更改 Compose 堆栈状态的命令，例如 ps、ls、logs。

子命令

命令	描述
`docker compose alpha`	实验性命令
`docker compose build`	构建或重新构建服务
`docker compose config`	以规范格式解析、解析和渲染 compose 文件
`docker compose cp`	在服务容器和本地文件系统之间复制文件/文件夹
`docker compose create`	为服务创建容器
`docker compose down`	停止并移除容器、网络
`docker compose events`	从容器接收实时事件
`docker compose exec`	在运行中的容器内执行命令
`docker compose images`	列出已创建容器使用的镜像
`docker compose kill`	强制停止服务容器
`docker compose logs`	查看容器的输出
`docker compose ls`	列出运行中的 compose 项目
`docker compose pause`	暂停服务
`docker compose port`	打印端口绑定的公共端口
`docker compose ps`	列出容器
`docker compose pull`	拉取服务镜像
`docker compose push`	推送服务镜像
`docker compose restart`	重启服务容器
`docker compose rm`	移除已停止的服务容器
`docker compose run`	在服务上运行一次性命令
`docker compose start`	启动服务
`docker compose stop`	停止服务
`docker compose top`	显示正在运行的进程
`docker compose unpause`	恢复服务
`docker compose up`	创建并启动容器
`docker compose version`	显示 Docker Compose 版本信息
`docker compose wait`	阻塞直到所有（或指定的）服务的容器停止。
`docker compose watch`	监视服务的构建上下文，并在文件更新时重新构建/刷新容器