Docker Compose 模块化多环境配置规范指南：示例搭建kkFileView 4.1.0

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

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

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

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

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

示例：kkfileview_V4.1.0

目录结构规范

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

dev/ ├── .env # 全局公共环境配置文件（仅定义共享基础设施变量） └── kkfileview_V4.1.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/kkfileview_V4.1.0/.env

# =========================================================# kkFileView 服务专属环境配置文件# 作用：管理 kkFileView 独享的版本、端口及服务配置# 位置：与服务自身的 docker-compose.yml 同级# =========================================================############################################################# kkFileView 配置############################################################# 镜像版本（常用稳定版本：4.1.0）KKFILEVIEW_VERSION=4.1.0# 暴露端口配置（宿主机访问端口，容器内部默认端口：8012）KKFILEVIEW_PORT=8012

3. 服务编排配置：dev/kkfileview_V4.1.0/docker-compose.yml

# =========================================================# kkFileView Docker Compose 配置## 目录结构：# dev/# ├── .env# └── kkfileview_V${KKFILEVIEW_VERSION}(例如：kkfileview_V4.1.0)/# ├── .env# ├── docker-compose.yml# └── volumes/# ├── data/ # kkFileView 基础数据与预览缓存# └── fonts/ # kkFileView 自定义字体目录（存放微软雅黑、宋体等）## 说明：## 1. 环境配置# 全局基础参数（ENV、NETWORK等）由根目录公共 .env 管理；# kkFileView 专属参数（版本、端口等）由服务同级 .env 管理。## 2. 持久化目录# kkFileView 的数据与字体目录统一存放于# kkfileview_V${KKFILEVIEW_VERSION}/volumes/ 目录下。## 3. 路径规则# 所有宿主机挂载目录均采用相对路径，# 相对路径以当前 docker-compose.yml 所在目录为基准。# 例如 ./volumes/data 对应：# <当前环境>/kkfileview_V${KKFILEVIEW_VERSION}/volumes/data。## 4. 环境隔离# 挂载路径不使用 ${ENV} 拼接。# 不同环境通过上层目录进行隔离，例如：# dev/kkfileview_V${KKFILEVIEW_VERSION}、test/kkfileview_V${KKFILEVIEW_VERSION}。## 5. 数据迁移# kkfileview_V${KKFILEVIEW_VERSION}/ 目录包含 Compose 配置及 kkFileView# 持久化数据，可作为当前环境的整体备份和迁移单元。## 6. 镜像配置# kkFileView 的默认配置文件由 Docker 镜像提供，# 不直接挂载整个配置目录，避免覆盖镜像内部默认配置。## =========================================================############################################################# 网络配置############################################################networks:# Compose 内部网络名称。env_network:# 使用 Docker Bridge 网络。driver:bridge# Docker 实际网络名称，由上层公共 .env 管理。name:${NETWORK_NAME}# 自定义网络地址范围。ipam:config:-subnet:${NETWORK_SUBNET}############################################################# 服务配置############################################################services:########################################################### kkFileView##########################################################kkfileview:# kkFileView 镜像及版本。# 版本由私有 .env 中的 KKFILEVIEW_VERSION 管理。image:keking/kkfileview:${KKFILEVIEW_VERSION}# 容器名称（自动拼接环境与版本号）。# 例如：kkfileview_dev_V4.1.0container_name:kkfileview_${ENV}_V${KKFILEVIEW_VERSION}# 加入当前环境的 Docker 网络。networks:-env_network# 端口映射。## HTTP：# 宿主机 ${KKFILEVIEW_PORT} -> 容器 8012ports:-"${KKFILEVIEW_PORT}:8012"######################################################### 持久化目录########################################################## 所有宿主机挂载目录均采用相对路径。## 相对路径以当前 docker-compose.yml 所在目录为基准。## 当前 Compose 文件路径示例：## <当前环境>/kkfileview_V${KKFILEVIEW_VERSION}/docker-compose.yml## 因此：## ./volumes/data# ./volumes/fonts## 分别对应：## <当前环境>/kkfileview_V${KKFILEVIEW_VERSION}/volumes/data# <当前环境>/kkfileview_V${KKFILEVIEW_VERSION}/volumes/fonts## 不使用 ${ENV} 拼接挂载路径，# 环境隔离由上层目录完成。#########################################################volumes:# kkFileView 基础数据与预览缓存目录。## 宿主机：# ./volumes/data## 容器：# /opt/kkFileView/data## 保存转换缓存文件及运行生成的临时数据。-./volumes/data:/opt/kkFileView/data# kkFileView 自定义字体目录。## 宿主机：# ./volumes/fonts## 容器：# /usr/share/fonts## 存放中文字体（如微软雅黑 msyh.ttc、宋体 simsun.ttc 等），解决 Office 预览乱码问题。-./volumes/fonts:/usr/share/fonts######################################################### 健康检查########################################################healthcheck:# 检查 kkFileView 服务 HTTP 响应状态。test:["CMD-SHELL","curl -sf http://localhost:8012/ >/dev/null || exit 1"]# 每 10 秒检查一次。interval:10s# 单次健康检查最大执行时间。timeout:5s# 连续失败 10 次后标记为 unhealthy。retries:10# 启动阶段给予 60 秒宽限时间（Office 转换组件初始化需时）。start_period:60s# 容器异常退出后自动重启。restart:unless-stopped######################################################### 容器标签########################################################labels:# 当前环境。env:${ENV}# kkFileView 版本。version:${KKFILEVIEW_VERSION}# 服务名称（自动拼接环境与版本号）。service:kkfileview_${ENV:-dev}_V${KKFILEVIEW_VERSION}

4. 服务启动

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

dockercompose --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. 浏览器访问

http://localhost:8012/