Docker Compose 命令完全指南：从构建到运维

在容器化应用的生命周期中，Docker Compose 是连接"开发"与"部署"的桥梁。它通过一个声明式的 docker-compose.yml 文件，将多容器应用的定义、配置与运行环境统一管理，极大地简化了微服务架构的本地测试与生产发布。

然而，仅有配置文件还不够，真正掌控应用命运的是一系列精心设计的 docker-compose 子命令。build、up、down、restart、ps、logs、exec 构成了日常操作的核心七巧板。掌握它们，就等同于拥有了容器编排的"控制台"。

本文将深入剖析这七个核心命令，并结合进阶选项与实战场景，帮助你从"会用"走向"精通"。

一、命令执行环境与权限说明

在进入详解之前，先解决一个常见问题：为什么许多命令前带有 sudo？

Docker 守护进程默认以 root 用户运行，因此普通用户直接执行 docker-compose 可能遇到权限错误。解决方式有两种：

每次添加 sudo（不推荐，易遗忘且影响脚本自动化）。
将当前用户加入 docker 组 （推荐）：
bash 复制代码
```
sudo usermod -aG docker $USER
newgrp docker  # 刷新组权限
```
此后，所有 docker-compose 命令均可去掉 sudo。

本文后续所有命令示例均省略 sudo，请根据自身环境按需添加。

二、核心命令详解

1. `docker-compose build` ------ 构建或重建镜像

作用：根据 docker-compose.yml 中定义的 build 配置，构建服务的 Docker 镜像。

基本用法：

bash 复制代码

docker-compose build [SERVICE...]

常用选项：

选项	说明
`--no-cache`	构建时不使用缓存，强制重新下载所有层
`--pull`	尝试拉取基础镜像的最新版本
`--build-arg key=val`	传递构建参数（对应 Dockerfile 的 ARG）
`--parallel`	并行构建多个服务（提升速度）

实战案例：

bash 复制代码

# 构建所有服务
docker-compose build

# 仅构建 web 和 worker 服务，并忽略缓存
docker-compose build --no-cache web worker

# 带构建参数构建
docker-compose build --build-arg ENV=production api

场景与技巧：

在开发过程中，频繁修改代码后，需重新构建镜像再启动，可结合 up --build（见下文）一步到位。
生产环境中建议使用 --pull 确保基础镜像安全补丁最新。
若 docker-compose.yml 中服务未定义 build 字段，则此命令无效果。

2. `docker-compose up` ------ 启动并运行整个应用

作用：创建并启动所有服务的容器，输出整合后的日志到终端。这是最常用的启动命令。

基本用法：

bash 复制代码

docker-compose up [SERVICE...]

常用选项：

选项	说明
`-d, --detach`	后台运行容器（不占用终端）
`--build`	启动前先重新构建镜像
`--scale SERVICE=NUM`	设置服务副本数量（需配合 `--scale`）
`--force-recreate`	强制重新创建容器（即使配置未变）
`--no-recreate`	如果容器已存在则不重新创建
`--remove-orphans`	删除未在 compose 文件中定义的服务容器
`--timeout, -t`	停止超时时间（默认10秒）

实战案例：

bash 复制代码

# 前台运行，日志打印到终端（Ctrl+C 会停止所有容器）
docker-compose up

# 后台启动所有服务
docker-compose up -d

# 启动时自动重新构建并扩展 web 服务为 3 个实例
docker-compose up -d --build --scale web=3

# 仅启动 db 和 redis 服务
docker-compose up -d db redis

场景与技巧：

开发环境推荐不加 -d，方便实时查看日志；生产环境务必使用 -d。
首次启动时，Compose 会先创建网络、卷，再拉取镜像或构建，最后启动容器。
若修改了 docker-compose.yml，再次 up 会自动识别变更并重建受影响的容器（增量更新）。

3. `docker-compose down` ------ 停止并移除容器、网络等资源

作用：停止所有运行中的容器，并删除它们，同时移除默认创建的网络（除非网络被声明为 external）。可选是否删除卷或镜像。

基本用法：

bash 复制代码

docker-compose down [OPTIONS]

常用选项：

选项	说明
`--volumes, -v`	删除服务所使用的匿名卷（命名卷不受影响）
`--rmi [local/all]`	删除镜像：`local` 仅删除无标签的镜像，`all` 删除所有服务镜像
`--remove-orphans`	移除未在 compose 文件中定义的服务容器
`--timeout, -t`	超时时间（默认10秒）

实战案例：

bash 复制代码

# 标准停止并清理（保留卷和镜像）
docker-compose down

# 完全清理：停止容器 + 删除匿名卷 + 删除所有服务镜像
docker-compose down -v --rmi all

# 仅停止容器并移除孤儿容器
docker-compose down --remove-orphans

场景与技巧：

执行 down 后，容器状态丢失，下次 up 会全新创建。
若只想停止而不删除容器，应使用 stop（见下文扩展）。
对生产环境慎用 down，通常使用 restart 或滚动更新代替。

4. `docker-compose restart` ------ 重启服务容器

作用：重启一个或多个服务的容器，容器 ID 保持不变，但内部进程会重新启动。

基本用法：

bash 复制代码

docker-compose restart [SERVICE...]

常用选项：

--timeout, -t：指定停止超时时间（秒），默认10秒。

实战案例：

bash 复制代码

# 重启所有服务
docker-compose restart

# 重启 web 和 worker 服务，并设置超时 30 秒
docker-compose restart --timeout 30 web worker

场景与技巧：

当修改环境变量或配置文件（未涉及镜像重建）时，restart 比 down && up 更快速。
注意：重启不会重新创建容器，因此网络和卷挂载保持不变。
若依赖镜像更新，需使用 up --build 代替。

5. `docker-compose ps` ------ 查看服务状态

作用：列出当前 Compose 项目中所有容器的状态信息，包括名称、命令、状态、端口映射等。

基本用法：

bash 复制代码

docker-compose ps [SERVICE...]

常用选项：

-a, --all：显示所有容器（包括已停止的）。
-q, --quiet：仅输出容器 ID（用于脚本）。

实战案例：

bash 复制代码

# 默认显示运行中的容器
docker-compose ps

# 显示所有容器（包括已退出）
docker-compose ps -a

# 仅获取 web 服务的容器 ID
docker-compose ps -q web

场景与技巧：

该命令是快速确认服务健康状态的首选工具。
输出中的 State 列常见值：Up（正常运行）、Exit（已退出）、Restarting（重启中）。
如果容器健康检查（HEALTHCHECK）失败，状态可能仍显示 Up，需结合 logs 排查。

6. `docker-compose logs` ------ 查看容器输出日志

作用：获取一个或多个服务的日志输出，支持实时跟踪。

基本用法：

bash 复制代码

docker-compose logs [SERVICE...]

常用选项：

选项	说明
`-f, --follow`	实时跟踪日志输出（类似 `tail -f`）
`--tail NUM`	显示最近 NUM 行，默认为所有
`--since TIME`	显示指定时间之后的日志（如 `2023-01-01T00:00:00`）
`--until TIME`	显示指定时间之前的日志
`--timestamps, -t`	显示时间戳
`--no-color`	禁用彩色输出

实战案例：

bash 复制代码

# 查看所有服务的最新 100 行并持续跟踪
docker-compose logs -f --tail=100

# 仅查看 web 服务的错误日志（假设输出含 ERROR）
docker-compose logs web | grep ERROR

# 查看从 10 分钟前开始的日志
docker-compose logs --since 10m

# 结合时间戳导出日志到文件
docker-compose logs -t > app.log

场景与技巧：

日志是故障诊断的核心依据。使用 -f 可在 up 未加 -d 时替代终端输出。
若日志量巨大，建议配合 grep、awk 等工具过滤。
Compose 默认日志驱动为 json-file，若改为 syslog 或 gelf，则 logs 命令可能失效。

7. `docker-compose exec` ------ 在运行中的容器内执行命令

作用：在指定服务的容器中执行一条命令（类似 docker exec），常用于调试、运维操作。

基本用法：

bash 复制代码

docker-compose exec [OPTIONS] SERVICE COMMAND [ARGS...]

常用选项：

选项	说明
`-d, --detach`	后台执行命令（不阻塞）
`--index INDEX`	指定副本容器索引（默认 1），适用于 `--scale` 多实例
`-e KEY=VAL`	设置环境变量
`--user, -u`	以指定用户执行命令
`--workdir, -w`	设置工作目录

实战案例：

bash 复制代码

# 进入 web 服务的容器，启动 bash 交互式 shell
docker-compose exec web bash

# 在 db 服务中执行数据库备份命令
docker-compose exec db mysqldump -u root -p mydb > backup.sql

# 以 root 用户执行命令并指定工作目录
docker-compose exec --user root --workdir /app web ls -la

# 在多个副本中，针对第二个副本执行
docker-compose exec --index 2 web env

场景与技巧：

此命令是"容器内调试"的利器，无需 ssh 进入宿主机。
注意：exec 不会进入新终端，若需交互式 shell，必须指定 bash、sh 等。
若容器未运行（状态非 Up），则无法执行命令。
为避免权限问题，可使用 --user 切换用户。

三、扩展命令速览（常用补充）

除了上述七个核心命令，以下命令同样值得掌握：

命令	说明
`docker-compose start`	启动已存在但处于停止状态的容器（不重新创建）
`docker-compose stop`	停止容器但保留其文件系统和网络配置
`docker-compose pause`	暂停容器进程（冻结状态）
`docker-compose unpause`	恢复暂停的容器
`docker-compose pull`	拉取服务所需镜像（不启动）
`docker-compose push`	将本地构建的镜像推送到仓库
`docker-compose run`	临时启动一次性容器执行命令（常用于迁移、初始化）
`docker-compose config`	验证并查看合并后的 Compose 配置

这些命令与核心命令配合，可覆盖容器全生命周期管理。

四、实战工作流与最佳实践

开发阶段

日常启动 ：docker-compose up -d（后台运行，不干扰编码）
代码变更 ：docker-compose build web（仅重建修改的服务）+ docker-compose up -d --no-deps web（只重启 web，不重启依赖）
查看日志 ：docker-compose logs -f web（实时追踪）
调试容器 ：docker-compose exec web /bin/sh

CI/CD 管道

构建阶段 ：docker-compose -f docker-compose.ci.yml build --parallel
测试阶段 ：docker-compose up -d && docker-compose run tester && docker-compose down -v
部署阶段 ：docker-compose pull（拉取生产镜像）+ docker-compose up -d --no-build

生产环境

更新应用 ：先 docker-compose build 或 pull，再 docker-compose up -d --force-recreate（滚动更新）。
监控与排查 ：定期 docker-compose ps，结合 logs --tail=100 快速定位异常。
应急回滚 ：docker-compose down 后再 up 旧版本镜像（需提前 tag）。

五、常见问题与排障指南

Q1：执行 up 时提示 Cannot start service ...，端口已被占用？

A：修改 docker-compose.yml 中的 ports 映射，或使用 docker-compose down 清理占用端口的旧容器。

Q2：exec 无法进入容器，报错 Error: No such container？

A：确认服务名称正确，且容器处于运行状态（ps 查看）；若存在多副本，需指定 --index。

Q3：logs 不显示任何内容，但容器确实有日志输出？

A：检查日志驱动是否设置为 json-file（默认），若为 none 或 syslog，则需调整配置。

Q4：down 后重新 up，数据丢失怎么办？

A：确保数据库等有状态服务使用了命名卷（volumes 声明），而非匿名卷。down -v 会删除匿名卷，但不会删除命名卷。

Q5：如何在不停止容器的情况下重新加载配置（如 nginx）？

A：使用 docker-compose exec nginx nginx -s reload 发送信号，或者 kill -HUP 主进程。

六、命令对比速查表

命令	是否会重建容器	是否保留卷	是否删除网络	适用场景
`up`	是（若无容器则创建）	是	否（创建新网络）	首次启动或更新
`down`	是（删除容器）	默认保留，`-v` 删除匿名卷	是（默认网络）	彻底清理环境
`restart`	否（复用容器）	是	否	快速重启服务
`stop`	否（容器停止）	是	否	临时暂停
`start`	否（启动停止的容器）	是	否	恢复停止的容器

七、总结

Docker Compose 的命令体系如同指挥家的手势，精准地控制着容器交响乐的每一个节奏。build 是谱曲，up 是开场，down 是落幕，而 ps、logs、exec 则是幕后的监听与调试。掌握它们，你便能从繁琐的容器管理中抽身，专注于应用本身。

核心要点回顾：

build + up -d 是最常用的启动组合，配合 --build 可实现一键重建。
down -v 可彻底清理，但务必注意数据卷的保护。
logs -f 与 exec 是问题定位的双刃剑。
生产环境优先使用 restart 和 up --force-recreate 进行滚动更新，避免停服。

最后，请牢记：命令是工具，场景是灵魂。根据开发、测试、生产的不同需求，灵活组合这些命令，才能最大化 Docker Compose 的威力。

Docker Compose 命令完全指南：从构建到运维