好的，docker-compose 是 Docker 生态中用于定义和运行多容器 Docker 应用程序的核心工具。它非常强大且极其常用，绝对值得一份详细的教程。

docker compose 通过一个 文件（docker-compose.yml）来配置应用服务，然后使用一个简单的命令，就可以从该配置中创建并启动所有服务。

这是一份从入门到实践的详细 docker-compose 使用教程。

1. 为什么需要 docker-compose？

想象一下，你有一个 Web 应用，它至少需要三个组件：

1. 一个 Web 服务器（如 Nginx）
2. 一个应用服务器（如 Python/Node.js）
3. 一个数据库（如 PostgreSQL）

使用 Docker，你需要为每个组件单独运行 docker run ... 命令，并手动管理它们之间的网络连接（--link 或创建 docker network）、数据卷（-v）和环境变量（-e）。这个过程非常繁琐且容易出错。

docker-compose 允许你在一个 文件中声明式地定义所有这些服务、网络和卷，然后用一个命令管理它们的整个生命周期（启动、停止、重建）。

2. 安装

在现代 Docker 安装中（例如通过 Docker Desktop for Mac/Windows/Linux 或在 Linux 上使用官方安装脚本），docker compose (V2) 通常已经包含在内。

1. 验证安装：

xxxxxxxxxx
2
1
docker compose version
2
# 输出: Docker Compose version v2.x.x

\2. (如果未安装) 在 Linux 上安装：

如果你的 docker 版本较旧，或安装时未包含该插件，可以手动安装：

方法一 (推荐)：使用 Docker 的 apt/yum 仓库

xxxxxxxxxx
7
1
# Debian/Ubuntu
2
sudo apt-get update
3
sudo apt-get install docker-compose-plugin
4
5
# CentOS/RHEL/Fedora
6
sudo dnf install docker-compose-plugin
7
# (或 sudo yum install docker-compose-plugin)

方法二：手动下载 (备用)

xxxxxxxxxx
6
1
# 检查最新版本: https://github.com/docker/compose/releases
2
DOCKER_COMPOSE_VERSION="v2.23.0" # 示例版本
3
DEST_DIR="/usr/libexec/docker/cli-plugins"
4
sudo mkdir -p $DEST_DIR
5
sudo curl -SL "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-x86_64" -o $DEST_DIR/docker-compose
6
sudo chmod +x $DEST_DIR/docker-compose

3. 核心文件：docker-compose.yml

docker-compose 的所有魔力都在这个 文件中。它有几个顶层关键字段：

• services: (必需) 定义你的应用包含的各个服务（容器）。
• volumes: 定义 "命名卷"，用于数据持久化。
• networks: 定义 "自定义网络"，用于服务间通信。
• configs / secrets: 用于管理配置和敏感数据。

docker-compose.yml 结构详解

我们将重点讲解最核心的 services 部分。

x
1
# 顶层的 'version' 字段在 V2 中已不再是必需的
2
# version: '3.8' 
3
4
services:
5
  
6
  # ---------------------------------
7
  # 服务 1: Web 服务器 (例如 Nginx)
8
  # "web" 是你自定义的服务名
9
  # ---------------------------------
10
  web:
11
    # 方式一: 直接使用 Docker Hub 上的镜像
12
    image: "nginx:latest"
13
14
    # 方式二: 从本地 Dockerfile 构建
15
    # build:
16
    #   context: .  # Dockerfile 所在的目录
17
    #   dockerfile: Dockerfile  # Dockerfile 的文件名 (可省略, 默认即为 Dockerfile)
18
19
    # 端口映射 (格式: 宿主机:容器)
20
    # 将宿主机的 8080 端口映射到容器的 80 端口
21
    ports:
22
      - "8080:80"
23
24
    # 卷挂载 (数据持久化或配置文件)
25
    volumes:
26
      # 方式一: 命名卷 (推荐用于数据)
27
      # "nginx-data" 是在下面顶层 `volumes:` 中定义的命名卷
28
      - nginx-data:/usr/share/nginx/html
29
      
30
      # 方式二: 绑定挂载 (Bind Mount) (推荐用于配置文件/代码)
31
      # 将宿主机的 ./nginx.conf 挂载到容器的 /etc/nginx/nginx.conf
32
      - ./nginx.conf:/etc/nginx/nginx.conf:ro  # "ro" 表示只读 (readonly)
33
34
    # 环境变量
35
    environment:
36
      - NGINX_HOST=example.com
37
      - NGINX_PORT=80
38
      
39
    # 方式二: 从 .env 文件读取环境变量 (最佳实践)
40
    env_file:
41
      - ./.env.web
42
43
    # 网络配置
44
    # 将此服务连接到 "app-network" 网络
45
    networks:
46
      - app-network
47
48
    # 启动依赖
49
    # 确保 "db" 和 "api" 服务启动后, 再启动 "web"
50
    depends_on:
51
      - db
52
      - api
53
54
  # ---------------------------------
55
  # 服务 2: 数据库 (例如 MySQL)
56
  # ---------------------------------
57
  db:
58
    image: "mysql:8.0"
59
    
60
    # 确保数据库数据持久化
61
    volumes:
62
      - db-data:/var/lib/mysql
63
      
64
    # 最佳实践: 密码等敏感信息应放在 .env 文件中
65
    environment:
66
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
67
      - MYSQL_DATABASE=${MYSQL_DATABASE}
68
      
69
    networks:
70
      - app-network
71
      
72
    # 健康检查 (高级):
73
    # `depends_on` 只等待容器启动, 而 `healthcheck` 能等待服务真正可用
74
    healthcheck:
75
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
76
      interval: 10s
77
      timeout: 5s
78
      retries: 5
79
80
  # ---------------------------------
81
  # 服务 3: 应用 API (示例)
82
  # ---------------------------------
83
  api:
84
    build: ./api  # 假设 api 代码和 Dockerfile 在 ./api 目录下
85
    networks:
86
      - app-network
87
    environment:
88
      - DB_HOST=db  # <-- 关键点: 可以直接使用服务名 "db" 作为主机名
89
      - DB_USER=root
90
      - DB_PASSWORD=${MYSQL_ROOT_PASSWORD}
91
92
# ---------------------------------
93
# 顶层定义: 命名卷
94
# ---------------------------------
95
volumes:
96
  nginx-data:
97
  db-data:
98
99
# ---------------------------------
100
# 顶层定义: 自定义网络
101
# ---------------------------------
102
networks:
103
  app-network:
104
    driver: bridge # 默认即为 bridge

4. 核心概念：服务发现

在上面的例子中，api 服务如何连接到 db 服务？

• environment: - DB_HOST=db

当所有服务都连接到同一个自定义网络（app-network）时，Docker 会自动提供 DNS 服务发现。这意味着 api 容器内可以直接通过服务名 db 作为主机名 (Hostname) 来访问 db 容器的 IP 地址。

这解决了容器 IP 地址不固定的问题，是 docker-compose 的核心优势之一。

5. 核心概念：使用 .env 文件

永远不要把密码、API 密钥等敏感信息硬编码到 docker-compose.yml 文件中（因为你可能需要把这个文件提交到 Git）。

最佳实践是使用 .env 文件。docker compose 会自动加载与 docker-compose.yml 同目录下的 .env 文件。

1. 创建 .env 文件 (并将其添加到 .gitignore)：

xxxxxxxxxx
3
1
# .env
2
MYSQL_ROOT_PASSWORD=my-super-secret-password
3
MYSQL_DATABASE=my_app_db

2. 在 docker-compose.yml 中引用：

xxxxxxxxxx
7
1
services:
2
  db:
3
    image: mysql:8.0
4
    environment:
5
      # ${...} 语法会从 .env 文件或宿主机环境变量中读取
6
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
7
      - MYSQL_DATABASE=${MYSQL_DATABASE}

6. 核心命令（常用操作）

假设你已经在 docker-compose.yml 所在的目录中。

6.1. 启动应用 (创建并运行)

docker compose up

• 前台启动： docker compose up

  (日志会直接输出到当前终端，Ctrl+C 会停止并关闭所有服务)

• 后台启动 (最常用)： docker compose up -d (-d = detached)

  (在后台启动并运行所有服务)

• 强制重建镜像： docker compose up -d --build

  (如果你的 Dockerfile 或代码有更改，使用此命令在启动前重新构建镜像)

6.2. 停止并移除应用

docker compose down

• 这会停止并移除所有相关的容器和网络。

• 重要： 默认情况下，docker compose down 不会删除 volumes: (命名卷)！这是为了保护你的数据。

• 停止并删除命名卷： docker compose down -v (-v = volumes)

  (这个命令会彻底清除所有，包括数据库数据，请谨慎使用！)

6.3. 临时停止/启动 (不移除)

docker compose stop

• 停止正在运行的服务 (容器依然存在)。

docker compose start

• 启动已停止的服务。

docker compose restart

• 重启所有服务。

6.4. 查看状态与日志

docker compose ps

• 列出当前 docker-compose.yml 管理的所有容器及其状态 (Up/Down)。

docker compose logs

• 查看所有服务的日志。
• 实时跟踪日志： docker compose logs -f (-f = follow)
• 查看特定服务的日志： docker compose logs -f web (只看 web 服务的日志)

6.5. 在运行的容器中执行命令

docker compose exec

• 这是调试的利器，等同于 docker exec。

• 获取 db 服务的 shell：

   

  x
  1
  docker compose exec db 
  

  (进入容器后，你可以像在 Linux 中一样执行命令，例如 mysql -u root -p)

• 在 api 服务中运行数据库迁移 (示例)：

   

  1
  docker compose exec api python manage.py db upgrade
  

6.6. 更新镜像

docker compose pull

• 拉取 docker-compose.yml 中定义的所有镜像的最新版本（例如 nginx:latest）。

docker compose build

• （如果使用 build:）重新构建本地的镜像。

docker compose up -d 最后使用该命令重新创建并启动最新版容器

7.volumes详解

3
1
volumes:
2
  nginx-data:
3
  db-data:

是 docker-compose.yml 文件中的 "顶层卷声明" (Top-Level Volume Declaration)。

它的作用是告诉 docker compose：“请为我创建并管理两个命名卷 (Named Volumes)，一个叫 nginx-data，另一个叫 db-data。”

下面是详细的解释，包括它为什么存在以及如何工作。

7.1. 🤔 为什么需要 volumes？(The Problem)

容器是“短暂”的 (Ephemeral)。

当你运行 docker compose up -d，它会创建容器。当你运行 docker compose down 来停止和移除应用时，这些容器会被彻底销毁。

• 如果你的数据库 (db) 将数据文件写在容器的 /var/lib/mysql 目录中...
• 如果你的 Nginx (web) 允许用户上传图片到容器的 /usr/share/nginx/html/uploads 目录中...

...那么在 docker compose down 之后，所有这些数据都会永久丢失。

7.2. 💡 volumes 如何解决问题？(The Solution)

命名卷 (Named Volumes) 就是 Docker 官方推荐的数据持久化方案。

一个“命名卷”是：

1. 一个由 Docker 在宿主机（你的电脑或服务器）上创建和管理的特殊存储区域。
2. 它有一个唯一的名称（比如 db-data）。
3. 它的生命周期与容器无关。

7.3. 🧩 docker-compose 中的两部分

docker-compose 中使用 volumes 分为两步：

第 1 部分：顶层 volumes: (你问的)

5
1
# docker-compose.yml (文件末尾)
2
3
volumes:     # <--- 这是“顶层卷声明”
4
  nginx-data:  # <--- 声明一个叫 "nginx-data" 的命名卷
5
  db-data:     # <--- 声明一个叫 "db-data" 的命名卷

• 做什么： 这是在定义“数据桶”。它告诉 docker compose：“我需要这两个数据桶，请你帮我创建它们。”
• 何时创建： 当你第一次运行 docker compose up -d 时，Docker 会检查这两个卷是否存在。如果不存在，它会自动创建它们。
• 存在哪里： 它们被创建在 Docker 的内部存储目录中（在 Linux 上通常是 /var/lib/docker/volumes/），你不需要关心具体路径，只需要记住它们的名字。

第 2 部分：服务级 volumes: (如何使用)

光声明了“数据桶”还不够，你必须告诉服务（容器）如何去使用它们。这在 services: 内部完成。

22
1
# docker-compose.yml (文件上部)
2
3
services:
4
  
5
  db:
6
    image: mysql:8.0
7
    volumes:    # <--- 这是“服务级卷挂载”
8
      # 格式: [命名卷名称]:[容器内路径]
9
      - db-data:/var/lib/mysql
10
11
  web:
12
    image: nginx:latest
13
    volumes:
14
      - nginx-data:/usr/share/nginx/html
15
16
# ... (省略其他配置) ...
17
18
# -----------------------------------
19
# 这里是第 1 部分的“顶层卷声明”
20
volumes:
21
  nginx-data:
22
  db-data:

工作流程解释 (db 服务)：

1. docker compose 看到 db 服务需要挂载一个叫 db-data 的卷。
2. 它去顶层的 volumes: 声明里查找，发现 db-data 已经被定义了。
3. 当启动 db 容器时，Docker 会把这个持久化的 db-data 卷（在宿主机上）“挂载”到容器内部的 /var/lib/mysql 路径上。

结果：

当 db 容器内的 MySQL 进程向 /var/lib/mysql 写入数据时，这些数据实际上被直接写入到了宿主机上的 db-data 卷中。

7.4. ✨ 带来的好处 (Benefits)

使用这种方式，你可以获得：

1. 数据持久化：

   当你运行 docker compose down 时，db 容器被销毁，但 db-data 卷依然存在，里面的数据完好无损。

2. 平滑升级：

   下一次你运行 docker compose up -d（比如为了升级 MySQL 镜像），docker compose 会创建一个新的 db 容器，并把现有的 db-data 卷重新挂载到新容器的 /var/lib/mysql 目录。你的所有数据都还在。

3. 数据与容器解耦：

   你的数据（db-data）和你的应用逻辑（db 容器）的生命周期是分开的，这在运维中至关重要。

8. 实战演练：部署 WordPress (Web + 数据库)

这是一个经典的 docker-compose 示例。

1. 创建项目目录：

xxxxxxxxxx
2
1
mkdir my-wordpress
2
cd my-wordpress

2. 创建 .env 文件 (用于数据库密码)：

xxxxxxxxxx
3
1
# .env
2
DB_ROOT_PASSWORD=somestrongpassword
3
DB_PASSWORD=wordpress_password

3. 创建 docker-compose.yml 文件：

xxxxxxxxxx
46
1
# docker-compose.yml
2
version: '3.8'
3
4
services:
5
  
6
  # 服务 1: 数据库
7
  db:
8
    image: mysql:8.0
9
    container_name: wordpress-db  # (可选) 自定义容器名
10
    environment:
11
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
12
      MYSQL_DATABASE: wordpress
13
      MYSQL_USER: wordpress
14
      MYSQL_PASSWORD: ${DB_PASSWORD}
15
    volumes:
16
      - db-data:/var/lib/mysql
17
    networks:
18
      - wp-net
19
20
  # 服务 2: WordPress 应用
21
  wordpress:
22
    image: wordpress:latest
23
    container_name: wordpress-app
24
    depends_on:
25
      - db
26
    ports:
27
      # 将宿主机的 8000 端口映射到容器的 80 端口
28
      - "8000:80"
29
    environment:
30
      WORDPRESS_DB_HOST: db  # <-- 关键: 使用服务名 "db"
31
      WORDPRESS_DB_USER: wordpress
32
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
33
      WORDPRESS_DB_NAME: wordpress
34
    volumes:
35
      # (可选) 挂载 wp-content 以便保留插件和主题
36
      - wp-content:/var/www/html/wp-content
37
    networks:
38
      - wp-net
39
40
# 顶层定义
41
volumes:
42
  db-data:
43
  wp-content:
44
45
networks:
46
  wp-net:

4. 启动应用：

xxxxxxxxxx
1
1
docker compose up -d

5. 访问：

等待一两分钟让 WordPress 和数据库完成初始化。

在浏览器中打开 http://<你的服务器IP>:8000，你将看到 WordPress 的安装界面。

6. 清理：

当你测试完毕，可以运行：

xxxxxxxxxx
5
1
# 停止并移除容器/网络 (保留数据卷)
2
docker compose down
3
4
# (如果确定不要数据了) 彻底清除
5
docker compose down -v