Docker Compose搭建本地开发环境完全指南

你是否曾经因为环境配置问题而浪费了大量时间？"在我电脑上能跑"这句话是否已成为团队内部的魔咒？Docker Compose 来拯救你了！本文将带你彻底掌握如何用 Docker Compose 构建一致、可靠且易于分享的本地开发环境。

Docker Compose是什么？

Docker Compose 是一个用于定义和运行多容器 Docker 应用的工具。通过 Compose，你可以使用 YAML 文件来配置应用的服务，然后用一个命令就能创建并启动所有服务。

它就像是一位出色的乐队指挥，协调多个容器之间的配合，让它们形成一个完整的应用系统。

Docker Compose工作流

为什么需要Docker Compose？

想象一下，你正在开发一个典型的Web应用，可能需要：

• 前端应用服务器
• 后端API服务
• 数据库（MySQL/PostgreSQL）
• 缓存服务（Redis）
• 消息队列（RabbitMQ/Kafka）

手动启动和配置这些服务将会是一场噩梦。而使用Docker Compose，你只需一个命令 docker-compose up，就能启动整个应用栈。

优势显而易见：

• 简化配置：所有环境参数都在YAML文件中定义
• 一致性：所有开发者使用完全相同的环境配置
• 隔离性：不同项目的环境互不干扰
• 可扩展性：轻松添加新的服务组件
• 快速重建：环境出问题时，一键重建

安装Docker Compose

大多数Docker Desktop安装已经包含了Docker Compose。要验证是否已安装，请运行：

docker-compose --version

如果未安装，可以按照操作系统进行安装：

Linux

# 下载当前稳定版本
sudo curl -L "https://github.com/docker/compose/releases/download/v2.21.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 添加可执行权限
sudo chmod +x /usr/local/bin/docker-compose

macOS & Windows

Docker Desktop已内置Docker Compose，无需额外安装。

Docker Compose核心概念与语法

docker-compose.yml文件

Docker Compose配置的核心是docker-compose.yml文件，它定义了应用的所有服务及其配置。

一个简单的例子：

version: '3'

services:
  web:
    build: ./web
    ports:
      - "8000:8000"
    volumes:
      - ./web:/code
    depends_on:
      - db
  
  db:
    image: postgres:13
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_USER=user
      - POSTGRES_DB=mydb

volumes:
  postgres_data:

核心组成部分

version

指定docker-compose文件格式的版本。最新项目应使用'3'或更高版本。

services

定义构成应用的所有服务（容器）。每个服务可以独立配置。

volumes

定义可以挂载到容器中的命名卷。

networks

定义服务可以连接的网络。

常用配置选项

build

指定构建镜像的上下文路径：

build: ./dir  # 简单形式
# 或
build:
  context: ./dir  # 包含Dockerfile的目录
  dockerfile: Dockerfile-dev  # 自定义Dockerfile名称
  args:  # 构建参数
    VERSION: '1.0'

image

指定要使用的镜像：

image: nginx:latest

ports

暴露端口，格式为"主机端口:容器端口"：

ports:
  - "8000:8000"  # 固定端口映射
  - "127.0.0.1:8001:8001"  # 绑定到特定IP
  - "9000-9100:9000-9100"  # 端口范围映射

volumes

挂载路径或命名卷，使数据持久化：

volumes:
  - ./app:/app  # 主机路径:容器路径
  - data:/var/lib/data  # 命名卷:容器路径
  - /var/run/docker.sock:/var/run/docker.sock  # 特殊文件挂载

environment

设置环境变量：

environment:
  - NODE_ENV=development
  - DEBUG=true
  # 或
  NODE_ENV: development
  DEBUG: true

depends_on

指定服务依赖，确保按顺序启动：

depends_on:
  - db
  - redis

注意

depends_on只保证容器启动顺序，不保证应用程序在容器内是否已就绪。对于需要等待依赖服务就绪的情况，应考虑使用等待脚本或健康检查。

networks

指定服务连接的网络：

networks:
  - frontend
  - backend

restart

定义容器的重启策略：

restart: always  # 总是重启
# 其他选项: "no", "on-failure", "unless-stopped"

实战案例：全栈开发环境

让我们创建一个完整的全栈开发环境，包含前端（React）、后端（Node.js）和数据库（MongoDB）。

目录结构：

project/
│
├── docker-compose.yml
├── frontend/
│   ├── Dockerfile
│   └── ...
├── backend/
│   ├── Dockerfile
│   └── ...
└── .env

docker-compose.yml

version: '3'

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - REACT_APP_API_URL=http://localhost:4000
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "4000:4000"
    volumes:
      - ./backend:/app
      - /app/node_modules
    environment:
      - MONGODB_URI=mongodb://mongo:27017/myapp
      - PORT=4000
    depends_on:
      - mongo

  mongo:
    image: mongo:4.4
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

frontend/Dockerfile

FROM node:16-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

backend/Dockerfile

FROM node:16-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 4000

CMD ["npm", "run", "dev"]

Docker Compose命令详解

基本命令

# 启动所有服务
docker-compose up

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

# 构建/重建服务
docker-compose build

# 停止服务
docker-compose stop

# 停止并移除容器、网络、卷
docker-compose down

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs

# 查看特定服务日志
docker-compose logs service_name

# 在服务中执行命令
docker-compose exec service_name command

高级用法

# 仅启动特定服务及其依赖
docker-compose up -d service_name

# 重建并强制重新创建容器
docker-compose up -d --build --force-recreate

# 扩展服务实例数量
docker-compose up -d --scale service=3

# 使用特定的Compose文件
docker-compose -f custom-compose.yml up

# 使用多个Compose文件（组合配置）
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up

开发技巧与最佳实践

1. 使用环境变量

创建.env文件存储敏感配置：

DB_PASSWORD=secret
API_KEY=abcdef123456

在docker-compose.yml中引用这些变量：

environment:
  - DB_PASSWORD=${DB_PASSWORD}

2. 开发环境挂载代码卷

为了实现代码热重载，将源代码目录挂载到容器中：

volumes:
  - ./src:/app/src

注意避免挂载node_modules目录：

volumes:
  - ./:/app
  - /app/node_modules  # 匿名卷，保留容器内的node_modules

3. 使用profiles分组服务

对于不总是需要运行的服务，使用profiles标签：

services:
  app:
    # ...
  
  test-db:
    profiles: ["test"]
    # ...

启动时指定profile：

docker-compose --profile test up

4. 组织多环境配置

对于不同环境（开发、测试、生产），使用多个Compose文件：

• docker-compose.yml：基础配置
• docker-compose.override.yml：默认覆盖（开发环境）
• docker-compose.prod.yml：生产环境特定配置

启动生产配置：

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

5. 健康检查

确保依赖服务完全准备好：

services:
  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  
  app:
    depends_on:
      db:
        condition: service_healthy

故障排除指南

常见问题和解决方案

1. 端口已被占用

   错误信息：Bind for 0.0.0.0:3000 failed: port is already allocated

   解决方案：

   • 更改宿主机端口映射
   • 找到并停止占用端口的进程

2. 容器无法连接到其他服务

   问题：服务之间无法通过服务名连接

   解决方案：

   • 确保服务在同一网络中
   • 使用服务名而非localhost
   • 检查防火墙设置

3. 卷挂载问题

   问题：容器内看不到挂载的文件

   解决方案：

   • 检查路径是否正确
   • 使用绝对路径替代相对路径
   • 检查文件权限

4. 环境变量未生效

   解决方案：

   • 确认.env文件位置正确
   • 检查变量引用语法
   • 重新构建容器

调试技巧

1. 查看详细日志

docker-compose logs --tail=100 --follow service_name

2. 检查容器配置

docker inspect container_name

3. 进入容器排查

docker-compose exec service_name sh

总结

Docker Compose 是构建开发环境的理想工具，它使环境配置变成了代码，可以版本控制、共享和快速重建。通过本指南，你应该已经掌握了：

• Docker Compose 的基本概念和配置语法
• 如何构建完整的多服务开发环境
• 常用的命令和最佳实践
• 疑难问题的解决方法

下一步，尝试将你现有的项目Docker化，并创建一个docker-compose.yml文件。你会惊讶于你的开发流程变得多么顺畅！

记住："配置即代码，一次定义，随处运行！"