项目地址: https://github.com/docker/compose
官方文档: https://docs.docker.com/compose/
许可证: Apache-2.0
包管理器: Docker Compose v2+ 插件(
docker-compose-plugin/ Docker Desktop 自带)/ 源码(最新 v5.7.1,截至 2026-11)版本: v5.7.1(2026-11-11,GitHub Releases;上一版 v5.7.0 为 2026-11-02 的功能版,v5.7.1 是紧随其后的补丁修复)
概述
Docker Compose 是定义和运行多容器 Docker 应用的工具。它用单个 YAML 文件(默认 compose.yaml)描述应用的服务、网络与卷,再用一条命令统一构建、启动、停止和查看。Compose 是 Compose Specification 的参考实现,旧的 2.x / 3.x 文件格式已并入统一规范,不再需要顶层 version: 字段。它面向单机(单 Docker 引擎)编排,是开发环境与单服务器部署的常用方案。
主要能力:
- 声明式编排:在
compose.yaml中定义services/networks/volumes,配置即代码 - 生命周期管理:
up/down/ps/logs/exec统一管理全部容器 - 与 Dockerfile 协作:
build从源码构建镜像,image直接拉取现成镜像 - 配置注入:
environment/env_file/.env配合变量插值 - 启动顺序控制:
depends_on+healthcheck等待依赖就绪 - 分组开关:
profiles按场景启用调试或工具类服务 - 多文件叠加:
-f base.yaml -f override.yaml按环境分层覆盖
环境准备
Compose v2+ 以插件形式随 Docker CLI 提供,命令为 docker compose(空格,区别于已停止维护的旧版 docker-compose)。
Docker Desktop(Windows / macOS)
- 安装 Docker Desktop 即自带 Compose 插件与 Docker Engine,无需单独安装。
- 启动 Docker Desktop 后,终端即可使用
docker compose。
Linux(Docker Engine + compose 插件)
# Debian / Ubuntu
sudo apt-get update
sudo apt-get install docker-compose-plugin
# RHEL / CentOS / Fedora(dnf 或 yum)
sudo dnf install docker-compose-plugin
# 或
sudo yum install docker-compose-plugin
验证
docker compose version
# 预期输出:Docker Compose version v5.7.1
独立的
docker-compose(v1,Python 实现)已停止维护,请使用 v2+ 的docker compose子命令。
核心 API/命令
compose.yaml 顶层结构
name: myapp # 项目名,默认取所在目录名
services: # 必填:服务(容器)集合
web:
image: nginx:1.27
networks: # 可选:自定义网络
frontend:
volumes: # 可选:命名卷,供多个服务复用
db-data:
services:每个条目定义一个容器及其运行时配置networks:定义服务之间通信的网络,默认自动创建default网络volumes:定义命名卷;跨服务复用的卷必须在此声明configs/secrets:挂载配置文件与敏感数据(可选)
服务常用字段
services:
web:
image: nginx:1.27 # 直接使用现成镜像
# build: . # 或从 Dockerfile 构建(二选一)
ports:
- "8080:80" # 短语法 HOST:CONTAINER
volumes:
- ./html:/usr/share/nginx/html # bind mount(宿主机目录)
- static:/app/static # named volume(需顶层声明)
environment:
APP_ENV: production
env_file:
- .env
depends_on:
db:
condition: service_healthy
restart: unless-stopped
build 段可指定上下文、Dockerfile、构建参数与多阶段目标:
services:
api:
build:
context: ./api
dockerfile: Dockerfile
args:
NODE_ENV: production
target: builder
健康检查
services:
db:
image: postgres:18
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 10s
retries: 5
start_period: 30s
test:探活命令,CMD直接执行,CMD-SHELL经 shell 执行interval/timeout/retries/start_period:探测间隔、超时、重试次数、启动宽限期disable: true或test: ["NONE"]可关闭健康检查
依赖与启动顺序
- 短语法
depends_on: [db]只保证启动先后,不等待依赖就绪。 - 长语法
condition支持三种条件:
services:
web:
depends_on:
db:
condition: service_healthy # 等待 db 健康
restart: true # db 重启时 web 一并重启
redis:
condition: service_started # 仅等待启动
migrate:
condition: service_completed_successfully # 等待一次性任务成功退出
profiles 分组
services:
app:
image: myapp # 无 profile,默认始终启动
phpmyadmin:
image: phpmyadmin
profiles: [debug] # 仅激活 debug 时才启动
docker compose --profile debug up -d
COMPOSE_PROFILES=debug docker compose up -d
docker compose --profile "*" up -d # 启用全部 profile
环境变量与 .env
.env默认位于项目目录(与compose.yaml同级)。- 插值语法:
${VAR}、${VAR:-default}(空则取默认)、${VAR:?err}(缺失即报错);$$转义为字面$。 - 优先级(高到低):shell 环境变量 →
--env-file指定文件 →.env文件。 - 服务级
environment的取值优先级高于env_file。
services:
web:
image: "webapp:${TAG:-latest}"
docker compose --env-file .env.prod config --environment
常用命令
docker compose up -d # 构建并后台启动全部服务
docker compose up -d --build # 强制重建镜像后再启动
docker compose down # 停止并删除容器与网络
docker compose down -v # 同时删除命名卷(数据会丢失)
docker compose ps # 查看容器状态
docker compose logs -f web # 跟踪指定服务日志
docker compose exec web sh # 在运行中的容器内执行命令
docker compose run --rm web sh # 一次性运行(不占用已发布端口)
docker compose build # 构建 / 重建镜像
docker compose pull # 拉取服务镜像
docker compose config # 渲染并校验最终配置
docker compose restart web # 重启服务
docker compose stop / start # 停止 / 启动
docker compose cp ./x.txt web:/tmp/ # 在容器与宿主间复制文件
docker compose watch # 监听变更并同步 / 重建
典型工作流
场景一:从零编排 Web + 数据库
# 目录结构
# myapp/
# ├── compose.yaml
# ├── .env
# └── api/Dockerfile
# 1. 构建并启动
docker compose up -d --build
# 2. 校验最终配置与状态
docker compose config
docker compose ps
# 3. 观察日志
docker compose logs -f api
# 4. 进入容器调试
docker compose exec db psql -U postgres
# 5. 清理(含数据卷)
docker compose down -v
场景二:多文件分环境叠加
# 基础文件 + 生产覆盖文件
docker compose -f compose.yaml -f compose.production.yaml up -d
# 仅重建并替换单个服务,不重启其依赖
docker compose build web
docker compose up --no-deps -d web
最佳实践
- 生产环境移除源码 bind mount,使用镜像内已构建的代码。
- 为长驻服务设置
restart: unless-stopped或always,减少停机。 - 为被依赖服务配置
healthcheck,并用depends_on.condition: service_healthy等待就绪。 - 用
deploy.resources.limits限制cpus与memory。 - 为日志配置
max-size/max-file轮转,避免磁盘被写满。 - 密码、令牌等敏感数据用
secrets或env_file,不要硬编码进compose.yaml。 - 固定镜像 tag(含摘要更佳),避免
latest漂移导致环境不一致。 - 用
profiles区分核心服务与调试 / 运维工具服务。 - 在 CI 中运行
docker compose config校验语法与插值。
services:
web:
deploy:
resources:
limits:
cpus: "0.50"
memory: 512M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
常见问题
| 问题 | 解决 |
|---|---|
提示 docker: 'compose' is not a docker command |
安装 compose 插件(v2+),并确认使用 docker compose(空格)而非旧版 docker-compose |
Bind for 0.0.0.0:8080 failed: port is already allocated |
宿主端口已被其它进程/容器占用 |
depends_on 后应用仍连接失败 |
短语法不等待就绪,改用 condition: service_healthy 并配置 healthcheck |
down 后数据库数据丢失 |
down -v 会删除命名卷;日常清理不要加 -v,或先备份卷 |
| 修改代码后容器未更新 | 用 up -d --build 重建,或使用 docker compose watch |
.env 中的变量未生效 |
确认 .env 与 compose.yaml 同目录;检查是否被 shell 同名变量覆盖 |
顶层 version 出现告警 |
Compose Specification 已弃用 version:,删除该字段 |
| Windows 下路径挂载失败 | 使用绝对路径或 ${PWD},并在 Docker Desktop 中开启文件共享 |
| 容器日志占满磁盘 | 配置 logging.options.max-size / max-file 做轮转 |
profiles 服务未启动 |
启动时加 --profile <名> 或设置 COMPOSE_PROFILES |
| 资源限制未生效 | 使用 deploy.resources.limits,而非旧版的 mem_limit / cpus |
AI 使用建议
推荐工作流
- 先写
compose.yaml骨架(name/services/networks/volumes),再逐服务补充字段。 - 被依赖服务先加
healthcheck,再用depends_on.condition串联启动顺序。 - 每次改动后运行
docker compose config校验,再执行up -d。 - 敏感配置放入
.env/env_file,不写进版本库。
关键模式与常见陷阱
- 端口语义:
ports是发布到宿主机的映射;expose仅声明内部端口,不对外发布。 - 卷类型:
./path:/x为 bind mount,单独/x为匿名卷,命名卷需在顶层volumes声明。 - 插值时机:
compose.yaml中的${VAR}由 Compose 解析;容器内需用$$VAR交给 shell。 - 就绪 vs 运行:
depends_on只保证容器运行,健康检查才保证服务可用。 - 多文件合并:后指定的
-f文件覆盖前者;config可查看合并后的最终结果。
如何选择方案
| 场景 | 推荐方案 |
|---|---|
| 单机多容器开发或小规模生产 | Docker Compose |
| 多节点集群 / 自动扩缩容 | Kubernetes 或 Swarm |
| 仅运行单个容器 | docker run |
| 需要密钥托管与集中管理 | Compose secrets 或外部密钥管理服务 |
相关技能
- geoserver-cloud — GeoServer 云原生微服务,本地开发或单机部署可用 Compose 编排。
- billionmail — 自托管邮件营销平台,官方推荐以
docker compose部署。 - ruoyi-cloud — Java 微服务脚手架,常用 Compose 编排 Nacos、MySQL 等依赖中间件。