Docker Compose 本地多服务环境实战：MySQL、Redis、Nginx 一键启动

本地开发环境最怕“服务多、启动乱、配置散”。一个后端项目可能同时依赖 MySQL、Redis、Nginx、消息队列和应用服务。手动启动不仅麻烦，还容易出现端口冲突、环境变量不一致、数据目录丢失等问题。

Docker Compose 的价值在于把多服务环境写成一份可版本化配置。团队成员拉下仓库后，用同一份 compose.yaml 启动服务，网络、端口、数据卷和依赖关系都清楚可见。

摘要

本文用 App + MySQL + Redis + Nginx 的组合，演示 Compose 本地开发环境的核心配置：服务定义、端口映射、内部网络、数据卷、环境变量、健康检查和排查命令。重点是让开发环境可重复启动、可定位问题、可持续维护。

适合人群

适合正在维护 Web 项目、本地联调环境、后端依赖服务、团队开发脚手架的开发者。你需要本机已经安装 Docker，并能正常运行 docker compose 命令。

目录

1. 项目结构怎么放
2. 写一份 compose.yaml
3. 服务网络和数据卷怎么理解
4. 启动顺序与健康检查
5. 常见问题排查
6. 团队使用建议

一、项目结构怎么放

推荐把 Compose 配置放在项目根目录，数据库和 Nginx 配置单独建目录：

my-project/
  app/
  nginx/
    conf.d/
  mysql/
    conf.d/
  compose.yaml
  .env

.env 可以放本地开发变量，比如端口、数据库名、密码。生产密码不要提交到仓库，开发环境也尽量提供 .env.example 作为模板。

二、写一份 compose.yaml

下面是一份最小可用示例，包含应用、MySQL、Redis 和 Nginx。为了便于理解，示例保留了常见配置项。

services:
  app:
    build: ./app
    container_name: demo_app
    ports:
      - "8080:8080"
    environment:
      APP_ENV: local
      DB_HOST: mysql
      REDIS_HOST: redis
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - backend

  mysql:
    image: mysql:8.0
    container_name: demo_mysql
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: root123
      MYSQL_DATABASE: appdb
      MYSQL_USER: app
      MYSQL_PASSWORD: app123
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 3s
      retries: 10
    networks:
      - backend

  redis:
    image: redis:7-alpine
    container_name: demo_redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 10
    networks:
      - backend

  nginx:
    image: nginx:1.25-alpine
    container_name: demo_nginx
    ports:
      - "80:80"
    depends_on:
      - app
    networks:
      - backend

volumes:
  mysql_data:
  redis_data:

networks:
  backend:
    driver: bridge

服务之间访问时，使用服务名作为主机名。例如应用访问 MySQL，主机写 mysql；访问 Redis，主机写 redis。不要在容器内部写 localhost 访问其它服务，因为容器里的 localhost 指向它自己。

三、服务网络和数据卷怎么理解

Compose 默认会为项目创建网络。放在同一个网络里的服务，可以通过服务名互相访问。端口映射则是“宿主机访问容器”的入口，例如 8080:8080 表示本机 8080 转到容器 8080。

数据卷用于持久化数据。MySQL 的数据目录挂到 mysql_data，容器删除后数据仍然保留。开发时这很方便，但如果你想重置数据库，就需要明确清理对应数据卷。

四、启动顺序与健康检查

depends_on 可以声明服务依赖，但只控制启动顺序，不代表依赖服务已经可以处理请求。数据库启动到可连接之间通常有一段等待时间，所以更稳妥的做法是配合 healthcheck。

常用命令如下：

docker compose up -d
docker compose ps
docker compose logs -f app
docker compose config
docker compose restart app
docker compose down

docker compose config 很适合排查配置合并后的最终结果；logs 适合看服务启动失败原因；ps 可以看端口和健康状态。

五、常见问题排查

1. 端口冲突

如果本机 80、3306、6379 已经被占用，可以改宿主机端口，例如 3307:3306。容器之间通信仍然使用服务名和容器端口。

2. 数据库连接失败

先确认应用里的 DB_HOST 是 mysql，不是 localhost。再看 MySQL 是否 healthy，最后检查账号、密码和数据库名。

3. 改了配置但没有生效

修改环境变量或镜像构建配置后，可能需要重新创建容器。先看 docker compose config 输出是否符合预期，再重启对应服务。

4. 数据卷导致旧数据残留

数据库密码、初始化脚本、库名改了，但数据卷里已有旧数据，初始化不会重新跑。需要明确备份后再清理数据卷。

六、团队使用建议

• 把 compose.yaml 和 .env.example 放进仓库；
• 不要提交真实密码和个人本地路径；
• 端口映射尽量统一，避免每个人自己改；
• 给数据库、缓存这类服务配置健康检查；
• 在 README 里写清楚启动、查看日志、重置数据的方法。

七、资料依据

本文写作时参考了 Docker 官方 Compose 文档中关于 Compose 文件、services、networks、volumes、depends_on、healthcheck 和常用命令的说明。本文示例为原创整理，实际项目可按服务数量和语言栈调整。

八、总结

Docker Compose 很适合把本地多服务开发环境标准化。用服务名解决容器间访问，用数据卷保存数据库和缓存数据，用健康检查控制依赖可用性，再配合日志和配置检查命令排查问题。把这些写进仓库后，团队协作会少很多“环境不一致”的消耗。