Docker Compose 模块化多环境配置规范指南：示例搭建Kibana 9.4.2
- [Docker Compose 模块化多环境配置规范指南](#Docker Compose 模块化多环境配置规范指南)
-
- 示例：kibana_V9.4.2
-
- 目录结构规范
- 配置文件详解与完整注释
-
- [1. 全局公共环境配置：`dev/.env`](#1. 全局公共环境配置：
dev/.env) - [2. 服务私有环境配置：`dev/kibana_V9.4.2/.env`](#2. 服务私有环境配置：
dev/kibana_V9.4.2/.env) - [3. 服务编排配置：dev/kibana_V9.4.2/docker-compose.yml](#3. 服务编排配置：dev/kibana_V9.4.2/docker-compose.yml)
- [4. Kibana 核心配置文件：dev/kibana_V9.4.2/volumes/kibana.yml](#4. Kibana 核心配置文件：dev/kibana_V9.4.2/volumes/kibana.yml)
- [5. 服务启动](#5. 服务启动)
- [6. 浏览器访问](#6. 浏览器访问)
- [1. 全局公共环境配置：`dev/.env`](#1. 全局公共环境配置：
Docker Compose 模块化多环境配置规范指南
服务的版本、端口、密码，以及项目的环境，网络这些要怎么放置？
标准的规范做法是双层配置隔离：
-
根目录公共
.env：仅保留全局通用变量（ENV、COMPOSE_PROJECT_NAME、NETWORK_NAME等）。 -
服务私有
.env：与服务的docker-compose.yml同级放置，仅维护该服务独有的参数（如版本、密码、端口、JVM 配置等）。
示例：kibana_V9.4.2
目录结构规范
以下为标准的工程目录结构。不同环境（如 dev / test / prod）通过顶层文件夹进行物理隔离，.env 按照双层变量隔离的方式：
text
dev/
├── .env # 全局公共环境配置文件（仅定义共享基础设施变量）
└── kibana_V9.4.2/ # 独立服务单元
├── .env # 服务私有环境配置文件（仅定义服务专属变量）
├── docker-compose.yml # Docker Compose 编排文件
└── volumes/ # 持久化数据与日志挂载目录配置文件详解与完整注释
1. 全局公共环境配置：dev/.env
位于环境根目录下，仅保留跨服务共享的基础网络 与项目标识参数。
bash
# =========================================================
# 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/242. 服务私有环境配置：dev/kibana_V9.4.2/.env
bash
# =========================================================
# Kibana 服务专属环境配置文件
# 作用：管理 Kibana 独享的版本、服务令牌凭证及暴露端口
# 位置：与服务自身的 docker-compose.yml 同级
# =========================================================
############################################################
# Kibana 配置
############################################################
# 镜像版本（例如：9.4.2 / 8.17.0）
KIBANA_VERSION=9.4.2
# Kibana Web 界面访问端口（宿主机访问端口，容器内部默认端口：5601）
KIBANA_PORT=56013. 服务编排配置：dev/kibana_V9.4.2/docker-compose.yml
bash
# =========================================================
# Kibana Docker Compose 配置
#
# 目录结构：
# dev/
# ├── .env
# └── kibana_V${KIBANA_VERSION}(例如：kibana_V9.4.2)/
# ├── .env
# ├── docker-compose.yml
# └── volumes/
# ├── kibana.yml # Kibana 核心配置文件
# ├── data/ # Kibana 持久化数据
# └── logs/ # Kibana 运行日志
#
# 说明：
#
# 1. 环境配置
# 全局基础参数（ENV、NETWORK等）由根目录公共 .env 管理；
# Kibana 专属参数（版本、端口等）由服务同级 .env 管理。
#
# 2. 存储与依赖
# Kibana 依赖 Elasticsearch 作为后端服务，
# 在同一 Docker 网络中通过服务名 `elasticsearch:9200` 进行通信。
#
# 3. 持久化目录与配置
# Kibana 的数据、日志及核心配置文件统一存放于
# kibana_V${KIBANA_VERSION}/volumes/ 目录下。
#
# 4. 路径规则
# 所有宿主机挂载目录均采用相对路径，
# 相对路径以当前 docker-compose.yml 所在目录为基准。
# 例如 ./volumes/data 对应：
# <当前环境>/kibana_V${KIBANA_VERSION}/volumes/data。
#
# 5. 环境隔离
# 挂载路径不使用 ${ENV} 拼接。
# 不同环境通过上层目录进行隔离，例如：
# dev/kibana_V${KIBANA_VERSION}、test/kibana_V${KIBANA_VERSION}。
#
# 6. 数据迁移
# kibana_V${KIBANA_VERSION}/ 目录包含 Compose 配置及 Kibana
# 持久化数据，可作为当前环境的整体备份和迁移单元。
#
# 7. 镜像配置
# Kibana 的所有核心参数（含令牌、密钥与汉化）均通过
# 挂载 kibana.yml 统一管理，不再使用环境变量传递。
#
# =========================================================
############################################################
# 网络配置
############################################################
networks:
# Compose 内部网络名称。
env_network:
# 使用 Docker Bridge 网络。
driver: bridge
# Docker 实际网络名称，由上层公共 .env 管理。
name: ${NETWORK_NAME}
# 自定义网络地址范围。
ipam:
config:
- subnet: ${NETWORK_SUBNET}
############################################################
# 服务配置
############################################################
services:
##########################################################
# Kibana
##########################################################
kibana:
# Kibana 镜像及版本。
# 版本由私有 .env 中的 KIBANA_VERSION 管理。
image: kibana:${KIBANA_VERSION}
# 容器名称（自动拼接版本与环境）。
# 例如：kibana_dev_V9.4.2
container_name: kibana_${ENV}_V${KIBANA_VERSION}
# 加入当前环境的 Docker 网络。
networks:
- env_network
# 端口映射。
#
# HTTP：
# 宿主机 ${KIBANA_PORT} -> 容器 5601
ports:
- "${KIBANA_PORT}:5601"
########################################################
# 持久化目录与配置文件挂载
########################################################
#
# 所有宿主机挂载目录均采用相对路径。
#
# 相对路径以当前 docker-compose.yml 所在目录为基准。
#
# 当前 Compose 文件路径示例：
#
# <当前环境>/kibana_V${KIBANA_VERSION}/docker-compose.yml
#
# 因此：
#
# ./volumes/kibana.yml
# ./volumes/data
# ./volumes/logs
#
# 分别对应：
#
# <当前环境>/kibana_V${KIBANA_VERSION}/volumes/kibana.yml
# <当前环境>/kibana_V${KIBANA_VERSION}/volumes/data
# <当前环境>/kibana_V${KIBANA_VERSION}/volumes/logs
#
# 不使用 ${ENV} 拼接挂载路径，
# 环境隔离由上层目录完成。
#
########################################################
volumes:
# Kibana 核心配置文件。
#
# 宿主机：
# ./volumes/kibana.yml
#
# 容器：
# /usr/share/kibana/config/kibana.yml
#
# 统一托管服务令牌、加密密钥及汉化等核心参数。
- ./volumes/kibana.yml:/usr/share/kibana/config/kibana.yml
# Kibana 核心持久化数据。
#
# 宿主机：
# ./volumes/data
#
# 容器：
# /usr/share/kibana/data
#
# 保存 Kibana 内部 UI 状态、报表导出缓存及插件配置数据。
- ./volumes/data:/usr/share/kibana/data
# Kibana 运行日志。
#
# 宿主机：
# ./volumes/logs
#
# 容器：
# /usr/share/kibana/logs
#
# 保存 Kibana系统的运行日志与异常 StackTrace。
- ./volumes/logs:/usr/share/kibana/logs
########################################################
# 健康检查
########################################################
healthcheck:
# 检查 Kibana HTTP API 返回状态。
test:
[
"CMD-SHELL",
"curl -s -I http://localhost:5601/api/status | grep -q 'HTTP/1.1 200 OK' || exit 1"
]
# 每 10 秒检查一次。
interval: 10s
# 单次健康检查最大执行时间。
timeout: 5s
# 连续失败 30 次后标记为 unhealthy。
retries: 30
# 启动阶段给予 120 秒宽限时间。
start_period: 120s
# 容器异常退出后自动重启。
restart: unless-stopped
########################################################
# 容器标签
########################################################
labels:
# 当前环境。
env: ${ENV}
# Kibana 版本。
version: ${KIBANA_VERSION}
# 服务名称（自动拼接环境与版本号）。
service: kibana_${ENV:-dev}_V${KIBANA_VERSION}4. Kibana 核心配置文件：dev/kibana_V9.4.2/volumes/kibana.yml
# =========================================================
# Kibana 核心配置文件
#
# 说明：
# 集中管理 Kibana 的所有服务参数、连接凭证、
# 加密密钥以及界面语言汉化。
# =========================================================
# 服务监听地址。
server.host: "0.0.0.0"
# 服务监听端口（容器内部默认端口）。
server.port: 5601
# Elasticsearch 后端服务地址（通过 Docker 同一网络中的容器服务名连接）。
elasticsearch.hosts: ["http://elasticsearch:9200"]
# Elasticsearch 服务账号令牌（用于集群身份认证）。
elasticsearch.serviceAccountToken: "AAEAAWVsYXN0aWMva2liYW5hL2tpYmFuYS10b2tlbjptbTYxV0YteFRwV3FiZm1ramgyUlV3"
# X-Pack 加密保存对象密钥（用于 Fleet 插件及常规加密对象）。
xpack.encryptedSavedObjects.encryptionKey: "y0+QgRnrJi0s4aoH7n/cFIj2XRakGJHszbsL5Q/W7VU="
# 界面语言汉化配置（支持 zh-CN 中文界面）。
i18n.locale: "zh-CN"配置属性说明：
-
elasticsearch.serviceAccountToken ：从 Elasticsearch/Kibana 8.x/9.x 开始，官方出于安全性考虑，禁止 Kibana 使用超级管理员账户
elastic作为其连接凭证 。因为elastic账户缺乏对 Kibana 内部系统索引（System Indices）的写入权限。在最新的 ES/Kibana 体系中，Kibana 必须使用服务账号 Token（Service Account Token）或内置的
kibana_system账号来连接 Elasticsearch。生成 Kibana 服务账号 Token，确保你的 Elasticsearch 容器处于运行状态，在命令行中执行以下命令生成专用的 Service Token：
docker exec -it elasticsearch_dev_V9.4.2 elasticsearch-service-tokens create elastic/kibana kibana-token运行后，终端会输出一行长 Token 字符串（例如：AAEAAWVsYXN0aWMva2liYW5hL2tpYmFuYS10b2tlbj...），请复制这个 Token。
-
xpack.encryptedSavedObjects.encryptionKey ：在高版本（如 8.x/9.x）的 Kibana 中，如果启用了 Fleet 或安全相关功能，必须配置
xpack.encryptedSavedObjects.encryptionKey，否则相关插件无法加密存储敏感数据。如这个报错FleetEncryptedSavedObjectEncryptionKeyRequired: Agent binary source needs encrypted saved object api key to be set说明 Kibana 的认证已经成功了（前面的security_exception已解决），但是在启动 Fleet 插件时，系统检测到缺少加密密钥（Encryption Key） 。通常选择 Base64 并设置长度为 32 bytes（或生成的 Base64 长度在 44 个字符左右），即可完美满足 Kibana 的加密要求。在线网址：https://secretkeygenerator.com/
5. 服务启动
在 kibana_V9.4.2/ 目录下执行命令时，显式同时加载父级和当前目录的 .env 文件：
bash
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）：
- 项目名称统一 ：由于公共配置文件中统一指定了固定的
COMPOSE_PROJECT_NAME（例如dev），Docker Compose 会将该项目下的所有服务（如容器 A、容器 B 等）归入同一个逻辑项目集中管理。 - 局部文件读取 ：当在某个独立的服务子目录下执行部署命令时，Docker Compose 仅会加载当前目录下 的
docker-compose.yml配置文件。 - 识别为孤儿容器 ：Compose 在检查全局项目状态时，发现该项目下存在其他已经在运行、但未定义在当前
docker-compose.yml文件中的容器，因此将其标记为"孤儿容器（orphan containers）"并发出提醒。
- 项目名称统一 ：由于公共配置文件中统一指定了固定的
-
影响说明
- 无负面影响 ：这仅是 Docker Compose 的正常提示信息，不会影响当前服务的启动与运行，也不会自动删除或干预其他正在运行的容器。
- 符合预期：将多个组件放在同一个大项目名下属于合理的管理方式，只要已运行的其他服务仍需继续提供服务，完全忽略此警告即可。
6. 浏览器访问
这里用到的就是 Elasticsearch 时候的用户名和密码。
