目录

• 命令对象与格式

• 通用选项

• 命令详解

  • docker compose build

  • docker compose up

  • docker compose stop

  • docker compose start

  • docker compose restart

  • docker compose down

  • docker compose convert

  • docker compose exec

  • docker compose images

  • docker compose ps

  • docker compose ls

  • docker compose kill

  • docker compose logs

  • docker compose pause

  • docker compose unpause

  • docker compose port

  • docker compose pull

  • docker compose push

  • docker compose rm

  • docker compose run

  • docker-compose scale

  • docker compose top

  • docker compose version

docker compose常用命令

参考：https://yeasy.gitbook.io/docker_practice/compose/commands#up*https://docs.docker.com/compose/reference/

命令对象与格式

对Docker Compose来说，大部分命令的对象既可以是项目（project）本身，也可以是项目中的一个或多个服务（service）。一般来说，如果没有显示指定，命令针对的对象都是当前项目（docker-compose.yml文件所在目录），这意味着项目中的所有服务都会受到此命令的影响。

例如，使用docker compose ps可以列出「当前项目」下所有的服务（️ 图片）。

docker compose 命令的基本格式：

docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]

可以使用docker compose [COMMAND] --help来查看命令的帮助文档：

$ docker compose --help

Define and run multi-container applications with Docker.

Usage:
  docker compose [-f <arg>...] [--profile <name>...] [options] [COMMAND] [ARGS...]
  docker compose -h|--help

Options:
  -f, --file FILE             Specify an alternate compose file
                              (default: docker-compose.yml)
  -p, --project-name NAME     Specify an alternate project name
                              (default: directory name)
  --profile NAME              Specify a profile to enable
  --verbose                   Show more output
  --log-level LEVEL           DEPRECATED and not working from 2.0 - Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --no-ansi                   Do not print ANSI control characters
  -v, --version               Print version and exit
  -H, --host HOST             Daemon socket to connect to

  --tls                       Use TLS; implied by --tlsverify
  --tlscacert CA_PATH         Trust certs signed only by this CA
  --tlscert CLIENT_CERT_PATH  Path to TLS certificate file
  --tlskey TLS_KEY_PATH       Path to TLS key file
  --tlsverify                 Use TLS and verify the remote
  --skip-hostname-check       Don't check the daemon's hostname against the
                              name specified in the client certificate
  --project-directory PATH    Specify an alternate working directory
                              (default: the path of the Compose file)
  --compatibility             If set, Compose will attempt to convert deploy
                              keys in v3 files to their non-Swarm equivalent

Commands:
  build              Build or rebuild services
  bundle             Generate a Docker bundle from the Compose file
  config             Validate and view the Compose file
  create             Create services
  down               Stop and remove containers, networks, images, and volumes
  events             Receive real time events from containers
  exec               Execute a command in a running container
  help               Get help on a command
  images             List images
  kill               Kill containers
  logs               View output from containers
  pause              Pause services
  port               Print the public port for a port binding
  ps                 List containers
  pull               Pull service images
  push               Push service images
  restart            Restart services
  rm                 Remove stopped containers
  run                Run a one-off command
  scale              Set number of containers for a service
  start              Start services
  stop               Stop services
  top                Display the running processes
  unpause            Unpause services
  up                 Create and start containers
  version            Show the Docker Compose version information

通用选项

docker compose的子命令有几个通用的选项：

• -f, --file FILE：指定要使用的 Compose 模板文件，默认为工作目录下的 docker-compose.yml，可以多次指定，相同的配置以最后一个为准。注意大部分命令都依赖于Compose 模板文件。

• -p, --project-name NAME：指定项目名称，默认是将工作目录的名称作为项目名。项目名会影响最终生成的服务容器名（项目名-服务名-1），详见 COMPOSE_PROJECT_NAME环境变量。

• –profile NAME：激活指定的profile，那么只有该profile对应的服务以及没有指定profile的服务会启动。详见 Using profiles with Compose 和 COMPOSE_PROFILES 环境变量.

• –project-directory PATH：指定工作目录，默认为Compose模板文件所在目录。

Tip：-f 和 -p 选项还支持指定一些与其相关的环境变量。比如，COMPOSE_FILE 环境变量与 -f 选项相关，而COMPOSE_PROJECT_NAME 环境变量与 -p 选项相关。

此外，你也可以在一个 .env 文件中设置这些环境变量（而不是在命令行）。

命令详解

docker compose build

格式：docker compose build [SERVICE...]

（重新）构建docker-compose.yml文件中的服务，生成镜像。

在docker-compose.yml文件中，一个服务既可以基于image元素引用现有的镜像，也可以基于build元素根据某个DockerfileBash 代码块docker build的事情。

但无论是哪种，所生成的镜像名都默认为项目名_服务名。如果build和image元素同时存在，那么将先根据image尝试拉取镜像，如果拉取失败才根据build构建镜像，构建出来的镜像名与image相同【详见】。

如果一个服务是使用build元素构建的，那么一旦你更改了这个服务的Dockerfile，就需要运行docker compose build重新构建它，以保证之后up时运行的服务容器是最新的。

选项：

• –force-rm：总是删除构建过程中的临时容器。

• –no-cache：镜像构建过程中不使用 cache。

• –pull：始终先尝试通过 pull 来获取最新版本的镜像。

docker compose up

格式： docker compose up [options] [SERVICE...]

这是最重要且最常用的一个命令，大部分时候都可以直接通过该命令来启动一个项目。

它将自动完成 构建镜像、（重新）创建服务、按依赖顺序启动任何关联的服务 等一系列操作。

除非服务已经正在运行，否则所有相关联的服务都将被自动启动。

默认情况下，docker compose up 启动的容器都在前台，控制台将实时打印所有容器的输出信息（以不同的颜色标识不同的服务），可以很方便进行调试。当按下 Ctrl+C 时，所有容器都会被停止。

如果使用 docker compose up -d，则所有服务将在后台启动。一般生产环境下推荐使用该选项。

默认情况下，如果某个服务容器已存在，但是docker-compose.yml中该服务的相关配置已经变更了，那么docker compose up 将尝试停止容器，然后重新创建相应的服务（配置未变更的服务不会重新创建），以保证所有服务总是能匹配 docker-compose.yml 中的最新内容。

如果用户不希望已存在的容器被重新创建（即使配置已经变更），可以使用 docker compose up --no-recreate。这样，就只会创建那些不存在的服务容器，而忽略已存在的服务容器。

如果用户只想启动某个服务而不想启动该服务所依赖的其他服务，可以使用 docker compose up --no-deps -d <SERVICE_NAME> 来单独启动这一个服务。

需要注意的是，如果某个服务容器是通过build元素进行构建的，并且该服务对应的镜像已经存在，那么即使Dockerfile文件内容已经变更，docker compose up也不会重新构建该服务，此时你需要先执行docker compose build构建镜像，再执行docker compose up。

docker compose build && docker compose up

选项：

• -d：在后台运行服务容器。

• –no-deps：不启动服务所依赖的其他服务（由depends_on元素指定）。

• –no-color：不使用颜色来区分不同服务的控制台输出。

• –force-recreate：总是重新创建容器，不能与 --no-recreate 同时使用。

• –no-recreate：如果容器已经存在了，则不重新创建，不能与 --force-recreate 同时使用。

• –no-build：不进行服务镜像的构建，即使该服务镜像不存在。

• -t, --timeout TIMEOUT：停止容器时的超时时间（默认为 10 秒）。

• –scale：设置某个服务要启动的容器数量，用于快速扩容/缩容，例如 --scale='web=3' 将为web服务启动3个容器副本，并且会覆盖docker-compose.yml中原有的 scales设置。

docker compose stop

格式：docker compose stop [options] [SERVICE...]

停止项目中的所有服务容器。稍后可以通过 docker compose start再次启动。

选项：

• -t, --timeout TIMEOUT：停止容器时的超时时间（默认为 10 秒）

docker compose start

格式：docker compose start [SERVICE...]

启动项目中的所有服务容器。

docker compose restart

格式：docker compose restart [options] [SERVICE...]

重启项目中的所有服务容器。

不同于docker compose up的是，即使docker-compose.yml中的内容已经变更，此命令也不会重新创建服务容器。如果你要更改此行为，请参见 restart 或 restart_policy。

选项：

• -t, --timeout TIMEOUT 指定重启前停止容器的超时（默认为 10 秒）。

docker compose down

此命令将会『停止并删除』docker-compose.yml中定义的所有服务容器和网络，但保留数据卷。

默认情况下，删除的内容只包括：

• docker-compose.yml中定义的服务容器（in the services section）。

• docker-compose.yml中定义的网络（in the networks section）。

• 如果使用了默认网络，也会删除默认网络。

但是，在docker-compose.yml之外定义的网络和数据卷永远不会被删除。

默认情况下，也不会删除匿名卷。但由于它们没有稳定的名称，因此之后再次up时也不会自动安装它们了。对于需要在两次更新之间持久化的数据，请使用 显式的路径映射绑定 或 命名卷。

docker compose convert

将docker-compose.yml文件转换成与平台兼容的更规范的文件格式。

可以借助这个命令来验证 docker-compose.yml 文件格式是否正确，若错误则会显示错误原因。

docker compose exec

格式：docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]

此命令和3.4 进入/退出容器类似，只不过它针对的是服务，可在指定的服务容器中执行命令。例如：

docker compose exec web /bin/bash

docker compose images

格式：docker compose images [SERVICE...]

列出所有已创建的服务容器的镜像信息。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-eK6zlvIY-1661012224861)(image/image_T-oAlvj3G-.png)]

docker compose ps

格式：docker-compose ps [options] [SERVICE...]

列出当前项目下的所有容器（包括已停止的）。

选项：

• -q：只打印容器的 ID。

• –filter=‘status=running’：只显示运行中的容器。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-mi6jWcBM-1661012224862)(image/image_VO4MgZbWlc.png)]

docker compose ls

格式： docker compose ls [options] [PROJECT...]

列出Docker上正在运行的所有项目，该信息与当前所在的项目无关。

选项：

• –all , -a：同时显示已停止的项目。

$ docker compose ls
NAME                STATUS              CONFIG FILES
docker-demo         running(3)          /Users/oneice/IdeaProjects/docker-demo/docker-compose.yml

docker compose kill

格式： docker compose kill [options] [SERVICE...]

通过发送 SIGKILL 信号来强制停止服务容器（kill -9）。

支持通过 -s 参数来指定发送的信号，例如使用如下命令发送 SIGINT 信号（Ctrl+C）：

docker-compose kill -s SIGINT

See also：kill根据PID杀死指定的进程、SIGINT SIGTERM SIGKILL区别

docker compose logs

格式：docker compose logs [options] [SERVICE...]

查看当前项目下所有服务容器的日志输出。默认情况下，docker compose logs将对不同的服务输出使用不同的颜色来区分。可以通过 --no-color 来关闭颜色。

该命令在调试问题的时候十分有用。

docker compose pause

格式：docker compose pause [SERVICE...]

暂停当前项目下一个或多个服务容器。稍后可以通过docker compose unpause解除暂停。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-OHQJh4Ic-1661012224862)(image/image_NuEuOaKFK6.png)]

docker compose unpause

格式：docker compose unpause [SERVICE...]

恢复当前项目下处于暂停状态的服务。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-HW0r94g3-1661012224862)(image/image_duFivrh4BR.png)]

docker compose port

格式： docker compose port [options] SERVICE PRIVATE_PORT

打印某个服务容器的内部端口所映射的公共端口（宿主机端口）。

选项：

• –protocol=proto：指定端口协议，tcp（默认值）或者 udp。

• –index=index：如果同一服务存在多个容器副本，可用此选项指定容器的序号（默认为 1）。

$ docker compose port mysql 3306              
0.0.0.0:3307

$ docker compose port redis 6379 
0.0.0.0:6380

docker compose pull

格式：docker compose pull [options] [SERVICE...]

拉取当前项目下所有服务依赖的镜像（不包括build元素所构建的服务）。

选项：

• –ignore-pull-failures： 忽略拉取镜像过程中的错误。

docker compose push

格式：docker compose push [SERVICE...]

对于使用build元素构建的服务，我们可以用此命令将其镜像推送到 Docker 镜像仓库。

选项：

• –ignore-push-failures：忽略推送镜像过程中的错误。

services:
  service1:
    build: .
    image: localhost:5000/yourimage  # goes to local registry
 
  service2:
    build: .
    image: your-dockerid/yourimage  # goes to your repository on Docker Hub

docker compose rm

格式：docker-compose rm [options] [SERVICE...]

删除所有已停止的服务容器。推荐先执行 docker compose stop 命令来停止容器。

选项：

• -f, --force：强制直接删除，包括非停止状态的容器。一般尽量不要使用该选项。

• -v：同时删除容器所挂载的匿名数据卷。

$ docker compose rm                      
? Going to remove docker-demo_web_1, docker-demo_mysql_1, docker-demo_redis_1 Yes
[+] Running 3/0
 ⠿ Container docker-demo_redis_1  Removed                                                                                                                         0.0s
 ⠿ Container docker-demo_web_1    Removed                                                                                                                         0.0s
 ⠿ Container docker-demo_mysql_1  Removed                                                                                                                         0.0s

docker compose run

格式：docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...] SERVICE [COMMAND] [ARGS...]

此命令的行为和3.1 创建并启动容器相似，它总是为某个服务创建并启动一个全新的容器。

例如，以下命令为web服务创建并启动一个容器，然后执行 /bin/bash命令：

$ docker compose run web /bin/bash

此命令一定会创建一个新的容器，其配置由docker-compose.yml中的web服务所定义，包括数据卷、网络、依赖关系、环境变量等详细信息。

此命令和docker compose up有两个重要区别：

• 此命令可以重写服务的启动命令（docker-compose.yml中定义的command元素）。

  例如，如果 web 服务的启动命令是 /bin/bash（由command元素指定），那么docker compose run web python app.py 将会把启动命令重写为python app.py。

• 此命令不会自动创建docker-compose.yml中配置的任何端口映射，以避免端口冲突。

  如果确实想为服务创建端口并将其映射到宿主机，请指定 --service-ports 选项：

  $ docker compose run --service-ports web python manage.py shell
  

  或者，可以使用 --publish 或 -p 选项手动指定端口映射，就像使用3.1 创建并启动容器时一样：

  $ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
  

默认情况下，如果存在依赖关系（由depends_on元素指定），则所有被依赖的服务将会被自动启动，除非这些服务已经在运行中。如果不希望 run 命令启动依赖的其他容器，请使用 --no-deps 选项：

$ docker compose run --no-deps web python manage.py shell

如果你只想创建一次的容器，在容器停止后自动删除它，可以使用 --rm选项：

$ docker compose run --rm web python manage.py db upgrade

这将运行一个数据库升级脚本，并在运行完成时删除容器（即使在服务配置中指定了restart policy）。

选项：

• -d：在后台运行容器。

• –name NAME：为容器指定一个名字，默认为项目名-服务名-uuid。

• –entrypoint CMD：覆盖默认的容器启动命令。

• -e KEY=VAL：设置环境变量，可以多次指定此选项来设置多个环境变量。

• -u, --user=“”：指定运行容器的用户名或者 uid。

• –no-deps：不启动所其他的其他服务容器。

• –rm：容器运行完成时自动删除容器。

• -p, --publish=[]：手动映射容器端口到宿主机，和3.1 创建并启动容器一样。

• –service-ports：使docker-compose.yml中配置的端口映射生效，默认忽略。

• -T：不分配伪 TTY，意味着依赖 TTY 的命令将无法运行。

docker-compose scale

注：该命令已经过时，可使用docker compose up附带 选项代替。

格式：docker-compose scale [options] [SERVICE=NUM...]

设置指定服务所运行的容器个数（通过 SERVICE=NUM 的形式来设置容器数量），实现快速扩容/缩容。

例如，以下命令将为 web 服务启动3个容器，为 db 服务启动2容器：

$ docker-compose scale web=3 db=2
# $ docker compose up --scale='web=3' --scale='db=2'

当指定的容器数多于该服务当前实际运行的容器数，将创建并启动新的容器；反之，将停止多余的容器。

需要注意的是，如果你在docker-compose.yml中使用ports元素进行了端口映射，那么此命令必然报错端口冲突。解决办法是，① 要么使用随机端口映射（例如ports: ["8080"]），然后在容器运行后使用docker compose ps查看实际映射的端口。② 要么服务自身不暴露端口，而是添加一个nginx容器作为统一入口，基于Docker内嵌的DNS路由到目标服务的容器实例上【详见】。

选项：

• -t, --timeout TIMEOUT：停止容器时候的超时（默认为 10 秒）。

docker compose top

格式：docker compose top [SERVICES...]

查看当前项目下各个服务容器内运行的进程。

$ docker compose top    
docker-demo_mysql_1
UID   PID     PPID    C    STIME   TTY   TIME       CMD
999   56939   56903   1    02:41   ?     00:00:14   mysqld   

docker-demo_redis_1
UID   PID     PPID    C    STIME   TTY   TIME       CMD
999   56867   56839   0    02:41   ?     00:00:03   redis-server *:6379   

docker-demo_web_1
UID    PID     PPID    C    STIME   TTY   TIME       CMD
root   57098   57071   2    02:41   ?     00:00:21   java -jar docker-demo.jar

docker compose version

格式： docker compose version

打印 Docker Compose 版本信息，该信息与当前所在的项目无关。

$ docker compose version
Docker Compose version v2.6.0