21. Compose 常用命令与配置

本节目标：掌握 docker compose 的高频命令，搞懂 build、restart、ports、volumes 这些配置项的写法和适用场景，能独立调一个 Compose 项目。

命令全景

Compose 的命令都是 docker compose <子命令> 形式，记忆负担不大。先把最常用的几个列出来：

命令	作用
`docker compose up`	拉起整套服务
`docker compose down`	停止并删除容器、网络
`docker compose ps`	查看当前项目下的容器
`docker compose logs`	查看服务日志
`docker compose exec`	进入运行中的容器执行命令
`docker compose build`	重新构建服务镜像
`docker compose start`	启动已存在的容器（不重建）
`docker compose stop`	停止容器（不删除）
`docker compose restart`	重启容器
`docker compose pull`	拉取服务镜像的最新版

下面挨个说用法和容易踩的坑。

up：拉起整套环境

docker compose up 是用得最多的命令。它干的事比看起来多：读文件、建网络、建卷、拉镜像、起容器，一条龙。

# 前台跑，日志直接打印到终端，Ctrl+C 停止
docker compose up

# 后台跑，推荐
docker compose up -d

# 如果服务配了 build，强制重新构建镜像
docker compose up -d --build

Tip

改了 Dockerfile 或代码后，直接 docker compose up -d 不一定会重新构建。加 --build 才会强制重建用 build 定义的服务。这是个高频踩坑点：改了代码没生效，多半是镜像没重建。

只起某个服务也行，会自动带上它的依赖：

docker compose up -d mysql

down：拆掉环境

down 是 up 的反操作，停容器、删容器、删网络。

# 默认只删容器和网络，保留卷
docker compose down

# 连命名卷一起删（数据没了，慎用）
docker compose down --volumes

# 连镜像一起删
docker compose down --rmi all

Warning

--volumes 会删掉你定义的命名卷，数据库数据会全没。除非你确定要重来，否则别加这个参数。我之前手抖加过一次，半天的测试数据全没了。

ps 与 logs：看状态和日志

docker compose ps 只看当前项目的容器，比全局 docker ps 干净：

$ docker compose ps
NAME                IMAGE           STATUS         PORTS
app-app-1           node:22-alpine  Up 2 minutes   0.0.0.0:3000->3000/tcp
app-mysql-1         mysql:8.0       Up 2 minutes   3306/tcp

docker compose logs 看日志，默认把所有服务日志混在一起，每行前缀带服务名方便区分：

# 跟进所有服务日志
docker compose logs -f

# 只看某个服务
docker compose logs -f app

Tip

混合日志看启动顺序问题特别有用。比如应用先起来去连还没就绪的数据库，会直接报错。logs -f 能一眼看出谁先谁后。

exec：进容器执行命令

和 docker exec 类似，但不用记容器名，用服务名就行：

# 进 mysql 服务的 shell
docker compose exec mysql bash

# 在 app 服务里跑一条命令
docker compose exec app yarn test

服务名是你在 compose.yaml 里定义的那个，Compose 会自动找到对应的运行中容器。

build：单独构建镜像

如果服务用 build 而不是 image，docker compose build 会触发构建：

# 构建所有用 build 的服务
docker compose build

# 构建指定服务
docker compose build app

# 不用缓存，从头构建
docker compose build --no-cache

build 字段两种写法：

services:
  app:
    # 简写：指向 Dockerfile 所在目录
    build: .

    # 完整写法：可指定 Dockerfile 名和参数
    build:
      context: .
      dockerfile: Dockerfile.prod
      args:
        VERSION: 1.2

Note

如果既写了 build 又写了 image，构建出来的镜像会打上 image 指定的标签，方便后续推送。

start / stop / restart：轻量操作

这三个命令和 up/down 的区别在于：它们不创建也不删除，只在已有容器上操作。

docker compose stop        # 停止所有服务
docker compose start       # 启动已停止的服务
docker compose restart     # 重启
docker compose restart mysql  # 只重启 mysql

适合「暂时停下来，待会还要接着用」的场景，容器和卷都保留。

restart 策略配置

服务级别的 restart 字段控制容器挂了怎么办，和 docker run --restart 一致：

services:
  app:
    image: my-app
    restart: unless-stopped

几个取值：

no：默认，挂了就挂了，不重启。
always：总是重启，包括手动 stop 后守护进程重启也会拉起来。
unless-stopped：类似 always，但手动 stop 的不会被守护进程重启时拉起。
on-failure：只在非零退出码时重启，可加最大次数 on-failure:3。

Tip

本地开发常用 unless-stopped，机器重启后服务自动回来，又不会和你手动停止的意图冲突。生产环境配合健康检查用 on-failure 更精细。

ports：端口映射两种写法

端口映射有短语法和长语法。短语法最常用：

ports:
  - 3000:3000       # 宿主机 3000 -> 容器 3000
  - 8080:80         # 宿主机 8080 -> 容器 80
  - 443             # 只指定容器端口，宿主机随机分配

长语法更明确，能控制协议和绑定地址：

ports:
  - target: 80          # 容器端口
    published: 8080     # 宿主机端口
    protocol: tcp       # tcp 或 udp
    mode: host          # host 或 ingress（Swarm 用）

Warning

短语法 8080:80 里，左边是宿主机端口，右边是容器端口，别记反了。我见过有人把数据库 3306 映射成 3306:33060，怎么都连不上，排查半天。

volumes：卷映射两种写法

卷映射同样有短长两种语法。短语法用冒号分隔：

volumes:
  # 命名卷：卷名:容器路径
  - todo-mysql-data:/var/lib/mysql

  # bind mount：宿主路径:容器路径
  - ./:/app

  # 只读挂载，加 :ro
  - ./config/nginx.conf:/etc/nginx/nginx.conf:ro

长语法能控制读写权限和传播方式：

volumes:
  - type: volume            # volume 或 bind 或 tmpfs
    source: todo-mysql-data
    target: /var/lib/mysql
    read_only: false
  - type: bind
    source: ./config
    target: /etc/config
    read_only: true

命名卷和 bind mount 的区别前面章节讲过，这里复习一下：

命名卷：Docker 托管，跨容器复用，适合数据库等持久化数据。
bind mount：直接挂宿主机目录，适合开发时热重载代码。

Note

用了命名卷，记得在顶层 volumes: 里声明，否则 Compose 不会自动创建。bind mount 不用声明，因为它指向的就是宿主机已有路径。

常用配置速查表

把这一章讲到的字段汇总一下，方便查阅：

字段	作用	示例
`image`	指定镜像	`image: nginx:alpine`
`build`	现场构建	`build: .`
`command`	覆盖启动命令	`command: ["python", "app.py"]`
`ports`	端口映射	`- 3000:3000`
`volumes`	挂载卷或目录	`- ./code:/app`
`environment`	环境变量	`MYSQL_HOST: mysql`
`restart`	重启策略	`unless-stopped`
`working_dir`	工作目录	`/app`
`container_name`	固定容器名	`my-app`（一般别指定）
`hostname`	容器内主机名	`app-1`

Tip

container_name 能固定容器名，但会破坏 Compose 的多副本扩展能力。除非有特殊需求（比如其他工具要按名字找容器），否则让它自动生成 <项目名>-<服务名>-1 就好。

小结

这一章把 Compose 的高频命令和核心配置项过了一遍。记住几个关键点：

up -d --build 是改代码后的标准动作。
down 默认不删卷，加 --volumes 才删。
restart 用 unless-stopped 最省心。
端口和卷都有短长两种语法，短语法够日常用。

下一章进入进阶：环境变量、依赖顺序、健康检查这些让 Compose 真正「聪明」起来的机制。