6.1 常用命令速查

6.1 常用命令速查

本节摘要：本节把 Compose 常用命令按六个功能域整理成速查表：启动停止、查看状态、进入执行、日志、镜像构建、其他。每个命令配一句"何时用"和常用选项，并给出 ps 输出示例等真实形态。这里的命令写法统一使用新版 docker compose 空格形式，老版连字符写法语义一致，照抄时注意换算。

学习目标

• 能为每个功能域说出至少两个代表命令及使用时机
• 能正确选择 up 的 -d、--build、--scale 选项组合
• 能读懂 ps 输出，从状态列判断容器是否正常
• 能区分 exec 与 run 的适用场景
• 能熟练用 config 命令在启动前验证文件

一、启动停止组：应用的开关

这一组命令负责应用的启动、停止与清理，是日常使用频率最高的四个命令。

docker compose up 构建并按需创建、启动所有服务。不加 -d 时前台运行，日志直接打满终端，关掉终端容器随之停止；加 -d 转入后台。何时用：启动应用，或修改配置后让新配置生效。常用组合：

docker compose up -d            # 后台启动全部服务
docker compose up --build       # 启动前强制重新构建镜像
docker compose up --scale web=3 # 把 web 服务扩展到 3 个副本
​

前台与后台的选择有一个简单标准：需要盯着日志调试时用前台，up 不带 -d，日志实时滚动，Ctrl+C 退出即停；服务稳定后一律 -d 后台。另一个实用组合是 up -d 加 --wait，让命令等待所有服务健康检查通过后才返回，写自动化脚本时用它判断"应用是否就绪"，比轮询 ps 输出可靠得多。

docker compose down 停止并删除容器和项目网络。何时用：彻底清理项目。两个危险选项要格外小心：down -v 连命名卷一起删，数据没了；down --rmi all 连镜像一起删，下次启动要重新拉取。

docker compose stop 停止全部或指定服务，容器保留。何时用：临时停用，下午还要继续。docker compose start 启动已存在的容器，不读配置、不建容器。何时用：唤醒 stop 过的服务。docker compose restart 先停后启。何时用：不改配置的纯重启。注意 start、stop、restart 都可以在后面跟服务名限定范围，比如 docker compose restart web db。

二、查看状态组：应用的体检

docker compose ps 列出项目内所有容器及其状态，输出包含容器名、命令、状态、端口四列：

      Name                    Command               State           Ports
--------------------------------------------------------------------------------
myapp_db_1        docker-entrypoint.sh mysqld      Up      3306/tcp, 33060/tcp
myapp_web_1       /docker-entrypoint.sh ngin ...   Up      0.0.0.0:80->80/tcp, 443/tcp
​

State 列是重点：Up 表示运行中，Exited 表示退出，Restarting 表示在重启循环里。看到 Restarting 要立刻查日志。何时用：确认应用是否全部就位，部署后第一件事。

ps 输出的其他列也值得会读：Name 列的容器名按"项目名_服务名_序号"生成，myapp_web_1 一眼能看出属于哪个项目哪个服务；Command 列显示容器启动命令，和预期不一致说明 entrypoint 或 command 配置有意外；Ports 列的 0.0.0.0:80->80/tcp 表示宿主机所有网卡的 80 端口映射到容器 80 端口，只带 3306/tcp 不带箭头前缀的说明端口只是容器内暴露、没映射到宿主机。ps 加 -a 参数可以连已停止的容器一起列出，排查"容器去哪了"时先跑 ps -a。

docker compose top 显示各服务容器内的进程列表，何时用：想知道容器里到底跑了哪些进程。docker compose port web 80 打印 web 服务 80 端口映射到宿主机的实际端口，何时用：端口用了自动分配，或者记不清映射关系时。docker compose images 列出项目使用的镜像及大小，何时用：检查镜像版本是否符合预期。docker compose events 实时输出项目事件流，何时用：调试启动过程中发生了什么，事件比日志更底层，它的 --filter 参数可以只关注指定服务的事件，减少无关噪声。

三、进入执行组：伸手进容器

docker compose exec 在运行中的容器里执行命令，这是调试最常用的命令：

docker compose exec web bash                 # 进入 web 容器的 bash
docker compose exec -it db mysql -u root -p  # 打开 db 容器的 MySQL 客户端
​

-it 组合表示交互式加伪终端，跑 shell 和交互式客户端时必须带。何时用：容器在跑，需要进去看文件、跑命令、连数据库。注意 exec 要求容器必须处于运行状态，容器挂了会直接报错。exec 默认以容器的默认用户执行命令，需要临时切换用户时加 --user 参数，比如 --user root 排查权限问题。

docker compose run 则是在一个全新的一次性容器里执行命令，常用于跑迁移、初始化等任务：

docker compose run --rm web python manage.py migrate
​

--rm 让命令结束后自动删除容器，不留垃圾。何时用：容器没在跑、或不想污染现有容器状态时。exec 与 run 的区别一句话：exec 进现成的容器，run 开一次性的新容器。

docker compose create 只创建容器不启动，何时用：想先建好容器、检查配置，稍后再 start 的场景，CI 流水线的预创建阶段也会用到。

四、日志组：排错的第一现场

docker compose logs 查看服务日志，何时用：容器起不来、请求报错、一切异常排查的开场动作：

docker compose logs web              # 查看 web 服务全部日志
docker compose logs -f web           # 实时跟踪，类似 tail -f
docker compose logs --tail=100 web   # 只看最后 100 行
​

-f 适合调试期挂住跟踪，--tail 适合容器重启后捞最后几行。还有两个时间相关参数值得记：--since 只看指定时间之后的日志，比如 --since 30m 表示最近半小时，适合配合"刚刚出了问题"的现场；--timestamps 给每行加时间戳，分析多服务日志顺序时很有用。logs 也可以一次跟多个服务：docker compose logs -f web db 会按时间顺序混合输出两个服务的日志，配合 --timestamps 能还原完整时间线，排查跨服务调用问题时比单看一个服务高效得多。日志默认只保留最近内容，要看历史日志需要服务配好日志轮转与持久化，做法见 6.3 节。

五、镜像构建组：造镜像与拉镜像

docker compose build 构建项目里所有需要构建的服务镜像：

docker compose build            # 构建全部
docker compose build web        # 只构建 web
docker compose build --no-cache web   # 禁用缓存从头构建
​

--no-cache 何时用：Dockerfile 改了但构建缓存没失效，或者怀疑缓存里藏着旧层。docker compose pull 只拉取镜像不启动，何时用：部署前预拉镜像，减少启动等待。多服务里个别镜像拉取失败时，pull 加 --ignore-pull-failures 可以跳过失败项继续拉其余的，先把能拿到的拿到手。docker compose push 把本地构建的镜像推到仓库，何时用：CI 流程里构建完推送，供服务器拉取。

六、其他：验证与扩展

docker compose config 验证并展开 Compose 文件，何时用：启动前的第一道检查。它会把文件里的 ${变量} 全部展开、合并继承，输出最终生效的完整配置，语法错误在这里报得比 up 清晰得多：

docker compose config
docker compose config --services   # 只列出服务名
​

docker compose scale 是旧版命令，新版用 up --scale 代替，语法 docker compose scale web=3 仍可用。何时用：临时扩容给某个服务加副本，用完再缩回来。最后别忘了两个元命令：docker compose version 查看版本号，docker compose --help 或子命令加 --help 查看完整选项——任何速查表都可能过时，帮助命令不会。

命令分类图

命令选择流程

分组速查总表

⚠️ exec 与 run 别混用：exec 进的是现有容器，改了文件会影响运行中的服务；run 开的是隔离的一次性容器，改了什么都不会碰现有实例。想试脚本又怕搞坏现场，用 run --rm。

💡 每条命令的完整选项问 --help：docker compose up --help 会列出全部选项和默认值，比任何速查表都全。本节表格只收录高频选项，记不清时先查帮助，再决定。

一节小结

• up 是核心命令：-d 后台、--build 强制构建、--scale 扩副本，改配置后用 up 而非 restart
• down 的两个危险选项：-v 删卷等于删数据，--rmi all 删镜像，用前确认
• ps 看 State 列：Restarting 是重启循环的警报，立刻查 logs
• exec 进现成容器，run 开一次性容器：调试用 exec，跑任务用 run --rm
• logs 是排错第一现场：-f 跟踪、--tail 捞尾部、--since 按时间过滤
• config 是语法守门员：启动前先 config 验证，变量展开、错误定位都比 up 清晰
• 帮助命令永远可用：命令加 --help 即可查看全部选项，速查表记不全的靠它兜底

命令手册收好，接下来把目光放远——6.2 节列出去哪找官方文档、模板库和社区，让学习不停在这一本书上。