Docker Compose 与多服务编排：从单容器到本地开发环境

Docker Compose 与多服务编排：从单容器到本地开发环境

一、本地开发的"环境地狱"：依赖太多，启动太复杂

微服务架构下，本地开发一个功能可能需要启动多个服务：API 网关、用户服务、订单服务、Redis 缓存、MySQL 数据库、RabbitMQ 消息队列。手动启动这些服务需要记住每个服务的端口、环境变量和启动顺序，新人入职第一周可能都在搭建开发环境。

Docker Compose 通过声明式配置将多服务编排自动化，一条docker compose up命令即可启动完整的本地开发环境。但 Compose 的使用远不止"启动容器"——服务依赖、健康检查、数据持久化、网络隔离等细节，决定了本地开发环境的稳定性和易用性。

二、多服务编排的核心机制

Docker Compose 的核心概念是服务（Service）、网络（Network）和卷（Volume）。服务间通过 depends_on 和 healthcheck 确保启动顺序和就绪状态。

flowchart TD A[API Gateway :8080] --> B[User Service :8081] A --> C[Order Service :8082] B --> D[Redis :6379] C --> D B --> E[MySQL :3306] C --> E C --> F[RabbitMQ :5672] subgraph 依赖关系 E -->|depends_on + healthy| B E -->|depends_on + healthy| C D -->|depends_on + healthy| B D -->|depends_on + healthy| C end subgraph 数据持久化 G[mysql-data Volume] H[redis-data Volume] H --> D G --> E end

三、工程化实现

3.1 完整的 Compose 配置

# docker-compose.yml version: '3.8' services: # 基础设施层：先启动 mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-dev_root_pass} MYSQL_DATABASE: app_db MYSQL_USER: app_user MYSQL_PASSWORD: ${MYSQL_PASSWORD:-dev_pass} ports: - "3306:3306" volumes: - mysql-data:/var/lib/mysql - ./init-scripts/mysql:/docker-entrypoint-initdb.d healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 5s timeout: 3s retries: 10 networks: - backend redis: image: redis:7-alpine command: redis-server --appendonly yes --maxmemory 256mb ports: - "6379:6379" volumes: - redis-data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 3s retries: 5 networks: - backend rabbitmq: image: rabbitmq:3-management-alpine environment: RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-guest} RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASS:-guest} ports: - "5672:5672" - "15672:15672" # 管理界面 healthcheck: test: ["CMD", "rabbitmq-diagnostics", "check_running"] interval: 10s timeout: 5s retries: 5 networks: - backend # 应用层：依赖基础设施就绪 user-service: build: context: ./services/user-service dockerfile: Dockerfile.dev environment: DB_HOST: mysql DB_PORT: 3306 DB_NAME: app_db DB_USER: app_user DB_PASSWORD: ${MYSQL_PASSWORD:-dev_pass} REDIS_HOST: redis REDIS_PORT: 6379 ports: - "8081:8080" volumes: - ./services/user-service/src:/app/src # 热重载 depends_on: mysql: condition: service_healthy redis: condition: service_healthy networks: - backend healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/health"] interval: 10s timeout: 5s retries: 3 order-service: build: context: ./services/order-service dockerfile: Dockerfile.dev environment: DB_HOST: mysql DB_PORT: 3306 DB_NAME: app_db DB_USER: app_user DB_PASSWORD: ${MYSQL_PASSWORD:-dev_pass} REDIS_HOST: redis REDIS_PORT: 6379 RABBITMQ_HOST: rabbitmq RABBITMQ_PORT: 5672 ports: - "8082:8080" volumes: - ./services/order-service/src:/app/src depends_on: mysql: condition: service_healthy redis: condition: service_healthy rabbitmq: condition: service_healthy networks: - backend api-gateway: build: context: ./services/api-gateway dockerfile: Dockerfile.dev environment: USER_SERVICE_URL: http://user-service:8080 ORDER_SERVICE_URL: http://order-service:8080 ports: - "8080:8080" volumes: - ./services/api-gateway/src:/app/src depends_on: user-service: condition: service_healthy order-service: condition: service_healthy networks: - backend volumes: mysql-data: redis-data: networks: backend: driver: bridge

3.2 开发用 Dockerfile

# services/user-service/Dockerfile.dev FROM node:20-alpine WORKDIR /app # 先复制依赖文件，利用缓存层 COPY package.json package-lock.json ./ RUN npm ci # 复制源码（开发模式通过 volume 挂载，构建时不需要） COPY . . # 开发模式：使用热重载 CMD ["npm", "run", "dev"]

3.3 便捷脚本

#!/bin/bash # dev.sh - 本地开发快捷命令 case "$1" in up) # 启动所有服务（后台运行） docker compose up -d echo "等待服务就绪..." sleep 10 docker compose ps ;; down) # 停止所有服务，保留数据 docker compose down ;; clean) # 停止并删除数据（慎用） docker compose down -v echo "所有数据已清除" ;; logs) # 查看指定服务日志 docker compose logs -f "${2:-}" ;; rebuild) # 重新构建指定服务 docker compose build "${2:-}" && docker compose up -d "${2:-}" ;; shell) # 进入指定服务容器 docker compose exec "${2:-api-gateway}" sh ;; db) # 连接 MySQL docker compose exec mysql mysql -uapp_user -pdev_pass app_db ;; redis) # 连接 Redis CLI docker compose exec redis redis-cli ;; *) echo "Usage: $0 {up|down|clean|logs|rebuild|shell|db|redis}" echo " up [service] 启动所有/指定服务" echo " down 停止所有服务" echo " clean 停止并清除数据" echo " logs [service] 查看日志" echo " rebuild [service] 重新构建服务" echo " shell [service] 进入容器" echo " db 连接 MySQL" echo " redis 连接 Redis" ;; esac

四、Docker Compose 的 Trade-offs

性能开销：每个容器都有虚拟化开销，在低配开发机上运行 6-8 个容器可能导致内存不足。建议对基础设施服务（MySQL、Redis）使用轻量级镜像（Alpine），对应用服务启用热重载避免频繁重建。

数据持久化的风险：Volume 数据在docker compose down时保留，但docker compose down -v会删除。建议在 README 中明确标注数据清除命令的风险，避免开发者误删数据库。

网络隔离的复杂性：默认 bridge 网络下，服务间通过服务名访问（如 mysql:3306），但宿主机无法通过服务名访问。需要使用 localhost + 映射端口。建议在开发文档中列出所有服务的访问地址。

多项目冲突：多个项目使用相同的端口（如 3306、6379）会冲突。建议使用环境变量动态分配端口，或使用 Compose 的 project name 隔离不同项目。

五、总结

Docker Compose 将本地开发环境从"手动搭建"推进到"一键启动"，通过声明式配置管理服务依赖、健康检查和数据持久化。落地路线上，建议先搭建最小可用环境（数据库 + 缓存 + 1 个服务），再逐步添加其他服务。关键原则：健康检查确保启动顺序，Volume 持久化开发数据，热重载提升开发效率，便捷脚本降低使用门槛。