docker-compose

项目地址： https://github.com/docker/compose

官方文档： https://docs.docker.com/compose/

许可证： Apache-2.0 ｜ 最新版本： v5.6.0

概述

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.6.0

独立的 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