整理日期：2026-05-21 | Docker Compose v2.x
目录
基础命令
命令对照表
| 命令 |
说明 |
典型用法 |
docker compose up |
创建并启动容器 |
启动整个应用 |
docker compose down |
停止并移除容器 |
关闭整个应用 |
docker compose start |
启动已存在的容器 |
恢复已停止的服务 |
docker compose stop |
停止运行中的容器 |
暂停服务 |
docker compose restart |
重启容器 |
重启服务 |
docker compose ps |
列出容器 |
查看服务状态 |
docker compose logs |
查看日志 |
调试问题 |
docker compose exec |
在容器中执行命令 |
进入容器操作 |
命令语法结构
docker compose [OPTIONS] COMMAND
| 选项 |
说明 |
-f, --file |
指定 Compose 文件路径 |
-p, --project-name |
指定项目名称 |
--ansi |
控制 ANSI 输出 (never/auto/always) |
--no-ansi |
不使用 ANSI 颜色 |
-v, --verbose |
详细输出模式 |
--log-level |
日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
快速查询流程图
┌─────────────────────────────────────────────────────┐
│ Docker Compose 工作流程 │
├─────────────────────────────────────────────────────┤
│ │
│ 编写 docker-compose.yml │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ docker compose │ up ──→ 创建并启动 │
│ │ config │ validate ──→ 验证配置 │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ 服务运行中 │ ps ──→ 查看状态 │
│ │ │ logs ──→ 查看日志 │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ down / stop │ ──→ 停止并清理 │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
服务管理
启动与停止
| 命令 |
说明 |
示例 |
up |
创建并启动容器 |
docker compose up -d |
down |
停止并移除容器、网络 |
docker compose down |
start |
启动已存在的服务 |
docker compose start |
stop |
停止服务 |
docker compose stop |
restart |
重启服务 |
docker compose restart |
pause |
暂停服务 |
docker compose pause web |
unpause |
恢复暂停的服务 |
docker compose unpause web |
启动/停止指定服务
| 命令 |
说明 |
示例 |
up SERVICE |
仅启动指定服务 |
docker compose up -d web |
up SERVICE1 SERVICE2 |
启动多个指定服务 |
docker compose up -d web db |
stop SERVICE |
仅停止指定服务 |
docker compose stop web |
stop SERVICE1 SERVICE2 |
停止多个指定服务 |
docker compose stop web db |
start SERVICE |
仅启动指定服务 |
docker compose start web |
restart SERVICE |
仅重启指定服务 |
docker compose restart web |
pause SERVICE |
仅暂停指定服务 |
docker compose pause web |
unpause SERVICE |
仅恢复指定服务 |
docker compose unpause web |
rm SERVICE |
删除指定服务容器 |
docker compose rm web |
logs SERVICE |
仅查看指定服务日志 |
docker compose logs -f web |
ps SERVICE |
仅查看指定服务状态 |
docker compose ps web |
指定服务操作流程图
┌─────────────────────────────────────────────────────────────┐
│ 指定服务操作示例 │
├─────────────────────────────────────────────────────────────┤
│ │
│ docker-compose.yml 示例: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ services: │ │
│ │ web: # web 服务 │ │
│ │ db: # db 服务 │ │
│ │ redis: # redis 服务 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 常用操作: │
│ │
│ 启动单个服务 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ docker compose up -d web │ │
│ │ # 仅启动 web 服务，依赖的 db/redis 也会自动启动 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 启动多个指定服务 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ docker compose up -d web db │ │
│ │ # 仅启动 web 和 db，不启动 redis │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 停止指定服务 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ docker compose stop web │ │
│ │ # 仅停止 web 服务，其他服务继续运行 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 重启指定服务 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ docker compose restart web │ │
│ │ # 仅重启 web 服务 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 查看指定服务日志 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ docker compose logs -f web │ │
│ │ # 仅查看 web 服务日志 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
up 命令选项
| 选项 |
说明 |
示例 |
-d, --detach |
后台运行 |
docker compose up -d |
--build |
启动前构建镜像 |
docker compose up --build |
--no-build |
不构建镜像 |
docker compose up --no-build |
--scale |
设置服务副本数 |
docker compose up --scale web=3 |
-t, --timeout |
超时秒数 |
docker compose up -t 10 |
--no-log-prefix |
不显示日志前缀 |
docker compose up --no-log-prefix |
服务状态流转图
┌────────────────────────────────────────────────────────┐
│ 服务生命周期 │
├────────────────────────────────────────────────────────┤
│ │
│ [不存在] │
│ │ │
│ │ up / start │
│ ▼ │
│ ┌─────────┐ │
│ │ Running │ ──→ pause ──→ [Paused] │
│ └─────────┘ ▲ │
│ │ │ │
│ │ unpause │ │
│ ▼ │ │
│ [Running] │ │
│ │ │
│ │ stop / restart │
│ ▼ │
│ [Stopped] ◄──────────────────────────────────────────┘
│ │ │
│ │ down │
│ ▼ │
│ [不存在] │
│ │
└────────────────────────────────────────────────────────┘
构建相关
构建命令对照表
| 命令 |
说明 |
示例 |
build |
构建服务镜像 |
docker compose build |
build --no-cache |
不使用缓存构建 |
docker compose build --no-cache |
build --pull |
总是拉取基础镜像 |
docker compose build --pull |
build 选项
| 选项 |
说明 |
--no-cache |
不使用 Docker 缓存 |
--pull |
始终拉取基础镜像的最新版本 |
--progress |
设置进度输出类型 (auto, plain, tty) |
-o, --build-arg |
设置构建参数 (key=value) |
--ssh |
设置 SSH 认证 |
构建流程图
┌─────────────────────────────────────────────────────────┐
│ 镜像构建流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ docker-compose.yml │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 读取 Dockerfile │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 执行 FROM 指令 (拉取基础镜像) │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 执行 RUN/COPY/ADD 等指令 │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 执行 CMD/ENTRYPOINT │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ▼ │
│ [镜像构建完成] │
│ │
└─────────────────────────────────────────────────────────┘
运行与执行
run 命令
| 命令 |
说明 |
示例 |
run |
运行一个一次性容器 |
docker compose run web bash |
run --rm |
容器停止后自动删除 |
docker compose run --rm web |
run -e |
设置环境变量 |
docker compose run -e VAR=value web |
run --no-deps |
不启动依赖服务 |
docker compose run --no-deps web |
exec 命令
| 命令 |
说明 |
示例 |
exec SERVICE CMD |
在容器中执行命令 |
docker compose exec web ls |
exec -i |
交互模式 |
docker compose exec -i web bash |
exec -t |
分配伪终端 |
docker compose exec -t web bash |
exec -d |
后台运行 |
docker compose exec -d web python app.py |
exec -e |
设置环境变量 |
docker compose exec -e VAR=value web env |
操作对比表
| 特性 |
run |
exec |
| 用途 |
创建新容器执行一次性任务 |
在已运行容器中执行命令 |
| 默认行为 |
会创建新容器 |
操作已存在的容器 |
--rm 选项 |
可在停止后删除容器 |
不适用 |
| 服务依赖 |
可以选择忽略依赖 |
必须服务已运行 |
命令执行流程图
┌─────────────────────────────────────────────────────────────┐
│ run vs exec 执行流程对比 │
├─────────────────────────────────────────────────────────────┤
│ │
│ docker compose run │
│ │ │
│ ├──[创建新容器]────┐ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────┐ │
│ │ │ 执行命令 │ │
│ │ └────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ [容器停止] ──[rm]──► [容器删除] │
│ │
│ docker compose exec │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ 已存在容器 │ ◄── 必须服务已在运行 │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ 执行命令 │ │
│ └────────────┘ │
│ │ │
│ ▼ │
│ [容器继续运行] │
│ │
└─────────────────────────────────────────────────────────────┘
日志与监控
logs 命令选项
| 选项 |
说明 |
示例 |
logs |
查看所有服务日志 |
docker compose logs |
logs -f |
实时跟踪日志 |
docker compose logs -f |
logs --tail |
显示最后 N 行 |
docker compose logs --tail 100 |
logs --since |
显示指定时间后的日志 |
docker compose logs --since "10m" |
logs -t |
显示时间戳 |
docker compose logs -t |
ps 命令选项
| 选项 |
说明 |
示例 |
ps |
列出容器 |
docker compose ps |
ps --all |
显示所有容器(含停止) |
docker compose ps --all |
ps -q |
仅显示容器 ID |
docker compose ps -q |
ps --format |
自定义输出格式 |
docker compose ps --format json |
监控命令对照表
| 命令 |
说明 |
docker compose ps |
查看服务状态 |
docker compose logs |
查看日志 |
docker compose top |
查看进程 |
docker compose port |
查看端口映射 |
docker compose images |
查看使用的镜像 |
top 命令输出示例
┌────────────────────────────────────────────────────────┐
│ 容器进程信息 │
├────────────────────────────────────────────────────────┤
│ │
│ NAME PID USER CMD │
│ ──────────────────────────────────────────────────── │
│ app-web-1 1234 root python app.py │
│ app-web-1 1235 root python app.py │
│ app-db-1 5678 postgres postgres │
│ │
└────────────────────────────────────────────────────────┘
编排与伸缩
scale/replicas 命令
| 命令 |
说明 |
示例 |
up --scale |
设置服务副本数 |
docker compose up -d --scale web=3 |
up --scale web=3 |
web 服务启动 3 个副本 |
docker compose up -d --scale web=3 |
伸缩操作对照表
| 操作 |
命令 |
说明 |
| 启动时伸缩 |
up --scale SERVICE=N |
启动时设置副本数 |
| 动态伸缩 |
docker compose up -d --scale web=5 |
运行时调整副本 |
| 查看副本 |
ps |
确认多副本运行 |
| 缩减 |
up --scale web=1 |
缩减到单副本 |
负载均衡架构图
┌─────────────────────────────────────────────────────────────┐
│ 服务伸缩架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ 负载均衡器 │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ web-1 │ │ web-2 │ │ web-3 │ │
│ │ :8080 │ │ :8080 │ │ :8080 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ docker compose up -d --scale web=3 │
│ │
│ 副本数由 --scale 参数控制 │
│ │
└─────────────────────────────────────────────────────────────┘
配置与检查
config 命令
| 命令 |
说明 |
示例 |
config |
验证并显示合并后的配置 |
docker compose config |
config --services |
列出所有服务名 |
docker compose config --services |
config --volumes |
列出所有卷 |
docker compose config --volumes |
config --hash |
显示服务配置哈希 |
docker compose config --hash |
config 输出结构
┌────────────────────────────────────────────────────────┐
│ docker compose config 输出 │
├────────────────────────────────────────────────────────┤
│ │
│ services: │
│ web: │
│ image: nginx:latest │
│ ports: │
│ - "80:80" │
│ volumes: │
│ - ./html:/usr/share/nginx/html │
│ db: │
│ image: postgres:15 │
│ environment: │
│ POSTGRES_PASSWORD: secret │
│ volumes: │
│ - db-data:/var/lib/postgresql/data │
│ │
│ volumes: │
│ db-data: │
│ │
└────────────────────────────────────────────────────────┘
检查命令对照表
| 命令 |
说明 |
config |
验证配置文件 |
config --services |
列出服务 |
config --volumes |
列出卷 |
ls |
列出项目 |
version |
显示版本 |
help |
显示帮助 |
环境变量优先级图
┌─────────────────────────────────────────────────────────────┐
│ 环境变量优先级 (从高到低) │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 命令行选项 (-e VAR=value) [最高优先级] │
│ │ │
│ ▼ │
│ 2. .env 文件中的变量 │
│ │ │
│ ▼ │
│ 3. shell 环境变量 │
│ │ │
│ ▼ │
│ 4. docker-compose.yml 中定义 │
│ │ │
│ ▼ │
│ 5. Dockerfile 中的 ENV 指令 [最低优先级] │
│ │
│ ⚠️ compose 文件中的变量会覆盖 Dockerfile 中的变量 │
│ │
└─────────────────────────────────────────────────────────────┘
元数据查询（容器 Labels）
Docker Compose 启动容器时会自动注入 com.docker.compose.* 标准化 Labels，可通过 docker inspect 读取，用于回溯配置文件位置与服务归属。
标准 Labels 字段
| 字段 |
含义 |
com.docker.compose.project.working_dir |
docker-compose.yml 所在目录的宿主机绝对路径 |
com.docker.compose.project.config_files |
docker-compose.yml 完整文件路径（含文件名） |
com.docker.compose.service |
容器对应的服务名（如 oceanbase） |
查询单个容器的 working_dir
docker inspect oceanbase --format '{{ (index .Config.Labels "com.docker.compose.project.working_dir") }}'
# 输出：/home/ubuntu/docker/oceanbase
一键列出所有 Compose 容器及其工作目录
⚠️ docker ps --format 模板里 .Labels 实际是字符串而非 map，无法用 index 访问。最稳妥的写法是回退到 docker inspect：
# 方法 1：用 inspect 逐个容器查（推荐，字段类型正确）
docker inspect --format '{{.Name}} {{index .Config.Labels "com.docker.compose.project.working_dir"}}' $(docker ps -aq) 2>/dev/null
# 方法 2：用 ps + awk 解析拼接后的 Labels 字符串
docker ps -a --format '{{.Names}} {{.Labels}}' \
| awk '/com.docker.compose.project.working_dir=/ {print $1}'
验证配置文件真实性
# 检查 docker-compose.yml 是否存在于元数据记录的路径
ls -l $(docker inspect oceanbase --format '{{index .Config.Labels "com.docker.compose.project.working_dir"}}')/docker-compose.yml
重要特性
- 仅创建时写入：
up 首次启动时写入，start 不会更新；移动 docker-compose.yml 后需 down && up 重建容器才能更新
- 始终是宿主机路径：与容器内
WORKDIR 无关
- 100% 由 Compose 维护：与
--name 自定义容器名无关，重命名不失效
- 持久化存储：保存在
/var/lib/docker/containers/ 下的 JSON 中，rm 容器后才会消失
docker run vs docker compose up 对比
| 启动方式 |
是否包含 com.docker.compose.* Labels |
原因 |
docker compose up |
✅ 是 |
Compose 显式注入标准化元数据 |
docker run |
❌ 否 |
无 Compose 介入，需手动 --label 添加 |
其他命令
健康检查命令
| 命令 |
说明 |
docker compose ls |
列出所有 Compose 项目 |
docker compose cp |
复制文件/目录 |
docker compose create |
创建容器(不启动) |
docker compose rm |
删除已停止的容器 |
docker compose kill |
强制停止容器 |
docker compose events |
获取实时事件流 |
导入导出命令
| 命令 |
说明 |
示例 |
cp |
复制文件 |
docker compose cp app:/data ./backup |
export |
导出容器文件系统 |
docker compose export web -o backup.tar |
import |
导入文件系统为镜像 |
docker compose import backup.tar myimage |
完整命令速查表
┌─────────────────────────────────────────────────────────────┐
│ 命令速查 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 启动类 │
│ ├─ up 创建并启动所有服务 │
│ ├─ start 启动已存在的服务 │
│ ├─ run 运行一个一次性容器 │
│ └─ create 仅创建容器不启动 │
│ │
│ 停止类 │
│ ├─ down 停止并移除容器和网络 │
│ ├─ stop 停止服务(不删除) │
│ ├─ pause 暂停服务 │
│ ├─ kill 强制停止服务 │
│ └─ rm 删除已停止的容器 │
│ │
│ 查看类 │
│ ├─ ps 列出容器 │
│ ├─ logs 查看日志 │
│ ├─ top 查看进程 │
│ ├─ port 查看端口映射 │
│ ├─ config 查看配置 │
│ ├─ events 查看事件 │
│ └─ ls 列出项目 │
│ │
│ 操作类 │
│ ├─ exec 在容器中执行命令 │
│ ├─ build 构建镜像 │
│ ├─ pull 拉取镜像 │
│ ├─ push 推送镜像 │
│ ├─ restart 重启服务 │
│ └─ unpause 恢复暂停 │
│ │
│ 文件类 │
│ ├─ cp 复制文件 │
│ ├─ export 导出容器 │
│ └─ import 导入镜像 │
│ │
└─────────────────────────────────────────────────────────────┘
常用选项速查
全局选项
| 选项 |
说明 |
-f, --file FILE |
指定 Compose 文件 |
-p, --project-name NAME |
指定项目名称 |
--ansi never|auto|always |
ANSI 控制 |
-v, --verbose |
详细输出 |
--log-level LEVEL |
日志级别 |
up 常用选项
| 选项 |
说明 |
-d |
后台运行 |
--build |
启动前构建 |
--no-build |
不构建 |
--scale SERVICE=N |
设置副本数 |
-t, --timeout N |
超时秒数 |
--remove-orphans |
移除孤立容器 |
logs 常用选项
| 选项 |
说明 |
-f, --follow |
实时跟踪 |
--tail N |
显示最后 N 行 |
--since TIME |
显示指定时间后 |
-t, --timestamps |
显示时间戳 |
exec 常用选项
| 选项 |
说明 |
-i, --interactive |
交互模式 |
-t, --tty |
分配伪终端 |
-e, --env KEY=VAL |
设置环境变量 |
-d, --detach |
后台执行 |
-w, --workdir DIR |
工作目录 |
常见使用场景
场景 1: 开发环境启动
# 启动所有服务(后台)
docker compose up -d
# 重新构建并启动
docker compose up --build -d
# 查看日志
docker compose logs -f
场景 2: 故障排查
# 查看所有服务状态
docker compose ps -a
# 查看服务日志
docker compose logs -f web
# 进入容器调试
docker compose exec -it web bash
场景 3: 生产部署
# 拉取最新镜像
docker compose pull
# 构建
docker compose build
# 滚动更新
docker compose up -d --remove-orphans
# 查看状态
docker compose ps
📝 提示: 使用 docker compose [command] --help 查看详细帮助信息
浙公网安备 33010602011771号