Docker Compose 模块化多环境配置规范指南：示例搭建Alf Tengine MD2DOC 1.1.1

Docker Compose 模块化多环境配置规范指南：示例搭建Alf Tengine MD2DOC 1.1.1

• [Docker Compose 模块化多环境配置规范指南](#Docker Compose 模块化多环境配置规范指南)
• • 示例：alf_tengine_md2doc_V1.1.1
  • • 目录结构规范
    • 配置文件详解与完整注释
    • • [1. 全局公共环境配置：`dev/.env`](#1. 全局公共环境配置：dev/.env)
      • [2. 服务私有环境配置：`dev/alf_tengine_md2doc_V1.1.1/.env`](#2. 服务私有环境配置：dev/alf_tengine_md2doc_V1.1.1/.env)
      • [3. 服务编排配置：dev/alf_tengine_md2doc_V1.1.1/docker-compose.yml](#3. 服务编排配置：dev/alf_tengine_md2doc_V1.1.1/docker-compose.yml)
      • [5. 生成默认模板文件](#5. 生成默认模板文件)
      • [6. 服务启动](#6. 服务启动)
      • [7. 浏览器访问](#7. 浏览器访问)

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

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

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

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

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

---

示例：alf_tengine_md2doc_V1.1.1

---

目录结构规范

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

dev/
├── .env                               # 全局公共环境配置文件（仅定义共享基础设施变量）
└── alf_tengine_md2doc_V1.1.1/         # 独立服务单元
    ├── .env                           # 服务私有环境配置文件（仅定义服务专属变量）
    ├── docker-compose.yml             # Docker Compose 编排文件
    └── volumes/                       # 持久化数据与日志挂载目录
       ├── configs/     # 系统配置文件 (/app/config/application-default.yaml)
       ├── templates/   # Word 样式模板文件 (/app/reference.docx)        
       └── logs/        # 应用运行日志 (/logs)

---

配置文件详解与完整注释

---

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/alf_tengine_md2doc_V1.1.1/.env

位于服务目录下，包含与 Elasticsearch 强绑定的个性化参数。

# =========================================================
# Alf Tengine MD2DOC MD2DOC 服务专属环境配置文件
# 作用：管理 Alfresco Tengine MD2DOC 独享的版本、宿主机端口及 JVM 运行内存配置
# 位置：与服务自身的 docker-compose.yml 同级
# Git 官网地址：https://github.com/aborroy/alf-tengine-md2doc
# =========================================================

############################################################
# Alfresco Tengine MD2DOC 配置
############################################################

# 镜像版本（例如：1.1.1 / 1.0.0）
MD2DOC_VERSION=1.1.1

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

# JVM 运行与内存优化参数
JAVA_OPTS=-Xms256m -Xmx512m

---

3. 服务编排配置：dev/alf_tengine_md2doc_V1.1.1/docker-compose.yml

# =========================================================
# Alf Tengine MD2DOC Docker Compose 配置
#
# 目录结构：
#    dev/
#    ├── .env
#    └── alf_tengine_md2doc_V${MD2DOC_VERSION}(例如：alf_tengine_md2doc_V1.0.0)/
#        ├── .env
#        ├── docker-compose.yml
#        └── volumes/
#            ├── configs/     # 系统配置文件 (/app/config/application-default.yaml)
#            ├── templates/   # Word 样式模板文件 (/app/reference.docx)
#            └── logs/        # 应用运行日志 (/logs)
#
# 说明：
#
#    1. 环境配置
#       全局基础参数（ENV、NETWORK等）由根目录公共 .env 管理；
#       MD2DOC 基础环境（版本、端口及 JVM 参数）由服务同级 .env 管理。
#
#    2. 应用配置与模板
#       所有的业务参数统一由 ./volumes/configs/application-default.yaml 管理，
#       排版样式由 ./volumes/templates/reference.docx 进行覆盖。
#
#    3. 路径规则
#       所有宿主机挂载目录均采用相对路径，
#       相对路径以当前 docker-compose.yml 所在目录为基准。
#       例如 ./volumes/configs 对应：
#       <当前环境>/alf_tengine_md2doc_V${MD2DOC_VERSION}/volumes/configs。
#
#    4. 环境隔离
#       挂载路径不使用 ${ENV} 拼接。
#       不同环境通过上层目录进行隔离，例如：
#       dev/alf_tengine_md2doc_V${MD2DOC_VERSION}、test/alf_tengine_md2doc_V${MD2DOC_VERSION}。
#
#    5. 数据迁移
#       alf_tengine_md2doc_V${MD2DOC_VERSION}/ 目录包含 Compose 配置及 MD2DOC
#       持久化数据，可作为当前环境的整体备份和迁移单元。
#
# =========================================================


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

networks:

  # Compose 内部网络名称。
  env_network:

    # 使用 Docker Bridge 网络。
    driver: bridge

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

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


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

services:

  ##########################################################
  # Alfresco Tengine MD2DOC
  ################################################          

  transform-md2doc:

    # 使用 angelborroy/alf-tengine-md2doc 镜像
    image: angelborroy/alf-tengine-md2doc:${MD2DOC_VERSION}

    # 容器名称（自动拼接环境与版本号）。
    # 例如：alf_tengine_md2doc_dev_V1.0.0
    container_name: alf_tengine_md2doc_${ENV}_V${MD2DOC_VERSION}

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

    # 端口映射。
    #
    # MD2DOC：
    #    宿主机 ${MD2DOC_PORT} -> 容器 8090
    ports:
      - "${MD2DOC_PORT}:8090"

    # MD2DOC 运行参数（参照官方文档设置基础变量）。
    environment:
      - SERVER_PORT=8090
      - JAVA_OPTS=${JAVA_OPTS}


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

    volumes:

      # MD2DOC 应用系统配置文件（Spring Boot 会自动优先加载此路径下的配置）。
      #
      # 宿主机：
      #    ./volumes/configs/application-default.yaml
      #
      # 容器：
      #    /app/config/application-default.yaml:ro
      - ./volumes/configs/application-default.yaml:/app/config/application-default.yaml:ro

      # Word 转换样式模版文件。
      #
      # 宿主机：
      #    ./volumes/templates/reference.docx
      #
      # 容器：
      #    /app/reference.docx:ro
      - ./volumes/templates/reference.docx:/app/reference.docx:ro

      # MD2DOC 应用运行日志目录。
      #
      # 宿主机：
      #    ./volumes/logs
      #
      # 容器：
      #    /logs
      - ./volumes/logs:/logs


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

    healthcheck:

      # 使用 Actuator 检查 HTTP 健康状态。
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health"]

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

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

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

      # 启动阶段给予 60 秒宽限时间（包含 JVM 启动与相关组件初始化）。
      start_period: 60s


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


    ########################################################     
    # 资源限制
    ########################################################     

    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '2.0'
        reservations:
          memory: 512M
          cpus: '0.5'


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

    labels:

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

      # MD2DOC 版本。
      version: ${MD2DOC_VERSION}

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

---

5. 生成默认模板文件

alf-tengine-md2doc GitHub 官网 ：https://github.com/jgm/pandoc/

官方自带的默认是空白的，维护标题，列表等样式不方便，因此不推荐使用

建议自定义DOCX样式

pandoc GitHub 官网 ：https://github.com/jgm/pandoc/

选择 releases 版本

这里下载 Windows 的 ZIP 包即可，解压就能使用

解压后的目录如下

可以使用下面的命令生成，在当前目录生成样式文件

pandoc -o reference.docx --print-default-data-file reference.docx

预览效果如下

---

6. 服务启动

在 alf_tengine_md2doc_V1.1.1/ 目录下执行命令时，显式同时加载父级和当前目录的 .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 的正常提示信息，不会影响当前服务的启动与运行，也不会自动删除或干预其他正在运行的容器。
  • 符合预期：将多个组件放在同一个大项目名下属于合理的管理方式，只要已运行的其他服务仍需继续提供服务，完全忽略此警告即可。

---

7. 浏览器访问

---