Docker Compose 模块化多环境配置规范指南

服务的版本、端口、密码，以及项目的环境，网络这些要怎么放置？

标准的规范做法是双层配置隔离：

• 根目录公共 .env：仅保留全局通用变量（ENV、COMPOSE_PROJECT_NAME、NETWORK_NAME 等）。

• 服务私有 .env：与服务的 docker-compose.yml 同级放置，仅维护该服务独有的参数（如版本、密码、端口、JVM 配置等）。

---

示例：mysql_V9.7.0

---

目录结构规范

以下为标准的工程目录结构。不同环境（如 dev / test / prod）通过顶层文件夹进行物理隔离，.env 按照双层变量隔离的方式：

dev/
├── .env                               # 全局公共环境配置文件（仅定义共享基础设施变量）
└── mysql_V9.7.0/                      # 独立服务单元
    ├── .env                           # 服务私有环境配置文件（仅定义服务专属变量）
    ├── docker-compose.yml             # Docker Compose 编排文件
    └── volumes/                       # 持久化数据与日志挂载目录

---

配置文件详解与完整注释

---

1. 全局公共环境配置：dev/.env

# =========================================================
# Docker Compose 全局公共环境配置文件
# 作用：管理跨服务的全局基础设施配置（如网络、环境标识等）
# =========================================================

############################################################
# 环境基础配置
############################################################

# 当前运行环境标识
# 可选值：dev（开发）、test（测试）、prod（生产）
ENV=dev

# Docker Compose 全局项目名称（影响容器默认命名前缀）
COMPOSE_PROJECT_NAME=dev

############################################################
# Docker 公共网络配置
############################################################

# 跨服务通信的 Docker 共享网络名称
NETWORK_NAME=network-${ENV}

# 自定义 Docker bridge 网络子网掩码（确保网段不与宿主机冲突）
NETWORK_SUBNET=10.10.0.0/24

---

2. 服务私有环境配置：dev/mysql_V9.7.0/.env

# =========================================================
# MySQL 服务专属环境配置文件
# 作用：管理 MySQL 独享的版本、账号密码及暴露端口
# 位置：与服务自身的 docker-compose.yml 同级
# =========================================================

############################################################
# MySQL 配置
############################################################

# 镜像版本（例如：9.7.0 / 8.4.7）
MYSQL_VERSION=9.7.0

# root 用户初始化密码
MYSQL_ROOT_PASSWORD=Pass@8520

# 暴露端口配置（宿主机访问端口，容器内部默认端口：3306）
MYSQL_PORT=3306

---

3. 服务编排配置：dev/mysql_V9.7.0/docker-compose.yml

# =========================================================
# MySQL Docker Compose 配置
#
# 目录结构：
#   dev/
#   ├── .env
#   └── mysql_V${MYSQL_VERSION}(例如：mysql_V9.7.0)/
#       ├── .env
#       ├── docker-compose.yml
#       └── volumes/
#           ├── data/        # MySQL 数据文件（/var/lib/mysql）
#           ├── conf/        # MySQL 自定义配置（/etc/mysql/conf.d）
#           └── logs/        # MySQL 运行与慢查询日志
#
# 说明：
#
#   1. 环境配置
#      全局基础参数（ENV、NETWORK等）由根目录公共 .env 管理；
#      MySQL 专属参数（版本、密码、端口等）由服务同级 .env 管理。
#
#   2. 持久化目录
#      MySQL 的数据、配置与日志统一存放于
#      mysql_V${MYSQL_VERSION}/volumes/ 目录下。
#
#   3. 路径规则
#      所有宿主机挂载目录均采用相对路径，
#      相对路径以当前 docker-compose.yml 所在目录为基准。
#      例如 ./volumes/data 对应：
#      <当前环境>/mysql_V${MYSQL_VERSION}/volumes/data。
#
#   4. 环境隔离
#      挂载路径不使用 ${ENV} 拼接。
#      不同环境通过上层目录进行隔离，例如：
#      dev/mysql_V${MYSQL_VERSION}、test/mysql_V${MYSQL_VERSION}。
#
#   5. 数据迁移
#      mysql_V${MYSQL_VERSION}/ 目录包含 Compose 配置及 MySQL
#      持久化数据，可作为当前环境的整体备份和迁移单元。
#
#   6. 镜像配置
#      MySQL 挂载 /etc/mysql/conf.d 目录添加自定义配置（如 my.cnf 追加片段），
#      避免直接覆盖容器主配置文件。
#
# =========================================================


############################################################
# 网络配置
############################################################

networks:

  # Compose 内部网络名称。
  env_network:

    # 使用 Docker Bridge 网络。
    driver: bridge

    # Docker 实际网络名称，由上层公共 .env 管理。
    name: ${NETWORK_NAME}

    # 自定义网络地址范围。
    ipam:
      config:
        - subnet: ${NETWORK_SUBNET}


############################################################
# 服务配置
############################################################

services:

  ##########################################################
  # MySQL
  ##########################################################

  mysql:

    # MySQL 镜像及版本。
    # 版本由私有 .env 中的 MYSQL_VERSION 管理。
    image: mysql:${MYSQL_VERSION}

    # 容器名称（自动拼接环境与版本号）。
    # 例如：mysql_dev_V8.4.7
    container_name: mysql_${ENV}_V${MYSQL_VERSION}

    # 加入当前环境的 Docker 网络。
    networks:
      - env_network

    # 端口映射。
    #
    # MySQL：
    #   宿主机 ${MYSQL_PORT} -> 容器 3306
    ports:
      - "${MYSQL_PORT}:3306"

    # MySQL 运行参数。
    environment:

      # root 用户初始化密码。
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}


    ########################################################
    # 持久化目录
    ########################################################
    #
    # 所有宿主机挂载目录均采用相对路径。
    #
    # 相对路径以当前 docker-compose.yml 所在目录为基准。
    #
    # 当前 Compose 文件路径示例：
    #
    #   <当前环境>/mysql_V${MYSQL_VERSION}/docker-compose.yml
    #
    # 因此：
    #
    #   ./volumes/data
    #   ./volumes/conf
    #   ./volumes/logs
    #
    # 分别对应：
    #
    #   <当前环境>/mysql_V${MYSQL_VERSION}/volumes/data
    #   <当前环境>/mysql_V${MYSQL_VERSION}/volumes/conf
    #   <当前环境>/mysql_V${MYSQL_VERSION}/volumes/logs
    #
    # 不使用 ${ENV} 拼接挂载路径，
    # 环境隔离由上层目录完成。
    #
    ########################################################

    volumes:

      # MySQL 核心数据库文件。
      #
      # 宿主机：
      #   ./volumes/data
      #
      # 容器：
      #   /var/lib/mysql
      #
      # 保存表结构、InnoDB 数据文件及系统元数据。
      - ./volumes/data:/var/lib/mysql

      # MySQL 自定义配置文件。
      #
      # 宿主机：
      #   ./volumes/conf
      #
      # 容器：
      #   /etc/mysql/conf.d
      #
      # 用于放置自定义的 .cnf 配置追加项（如编码、连接数、慢查询日志配置等）。
      - ./volumes/conf:/etc/mysql/conf.d

      # MySQL 运行与慢查询日志目录。
      #
      # 宿主机：
      #   ./volumes/logs
      #
      # 容器：
      #   /var/log/mysql
      - ./volumes/logs:/var/log/mysql


    ########################################################
    # 健康检查
    ########################################################

    healthcheck:

      # 使用 mysqladmin ping 命令检查数据库引擎连通性。
      test:
        [
          "CMD-SHELL",
          "mysqladmin ping -h localhost -u root -p${MYSQL_ROOT_PASSWORD} || exit 1"
        ]

      # 每 10 秒检查一次。
      interval: 10s

      # 单次健康检查最大执行时间。
      timeout: 5s

      # 连续失败 10 次后标记为 unhealthy。
      retries: 10

      # 启动阶段给予 30 秒宽限时间（数据库初始化与恢复需要时间）。
      start_period: 30s


    # 容器异常退出后自动重启。
    restart: unless-stopped


    ########################################################
    # 容器标签
    ########################################################

    labels:

      # 当前环境。
      env: ${ENV}

      # MySQL 版本。
      version: ${MYSQL_VERSION}

      # 服务名称（自动拼接环境与版本号）。
      service: mysql_${ENV:-dev}_V${MYSQL_VERSION}

---

4. 服务启动

在 mysql_V9.7.0/ 目录下执行命令时，显式同时加载父级和当前目录的 .env 文件：

docker compose --env-file ../.env --env-file .env up -d

注意：必须同时写上 --env-file ../.env 和 --env-file .env，这样 Compose 才能在语法解析阶段同时获取到父级的 ENV、NETWORK_NAME 以及子级的 ES_VERSION。

出现这个警告是因为 Docker Compose 在同一个项目名称（Project Name）下检测到了不属于当前 docker-compose.yml 文件定义的其他容器。

• 警告原因分析

  出现该警告的核心原因在于多个子服务共享了同一个 Docker Compose 项目名称（Project Name）：

  1. 项目名称统一：由于公共配置文件中统一指定了固定的 COMPOSE_PROJECT_NAME（例如 dev），Docker Compose 会将该项目下的所有服务（如容器 A、容器 B 等）归入同一个逻辑项目集中管理。
  2. 局部文件读取：当在某个独立的服务子目录下执行部署命令时，Docker Compose 仅会加载当前目录下的 docker-compose.yml 配置文件。
  3. 识别为孤儿容器：Compose 在检查全局项目状态时，发现该项目下存在其他已经在运行、但未定义在当前 docker-compose.yml 文件中的容器，因此将其标记为“孤儿容器（orphan containers）”并发出提醒。

• 影响说明

  • 无负面影响：这仅是 Docker Compose 的正常提示信息，不会影响当前服务的启动与运行，也不会自动删除或干预其他正在运行的容器。
  • 符合预期：将多个组件放在同一个大项目名下属于合理的管理方式，只要已运行的其他服务仍需继续提供服务，完全忽略此警告即可。

---

5. 连接访问

---