boxboat/config-merge

Config Merge

镜像概述和主要用途

Config Merge 是一个运行在Docker容器中的工具，用于合并JSON、TOML、YAML格式的配置文件，并支持环境变量替换。通过该工具可以轻松处理多环境配置文件的合并与定制，适用于需要动态生成配置的场景。

核心功能和特性

• 多格式文件合并：支持合并.json、.js、.toml、.yaml、.yml格式文件
• JSONPatch补丁：支持应用以.patch.json、.patch.toml等为后缀的JSONPatch补丁文件
• 环境变量替换：支持解析.env和.sh文件中的环境变量，并进行变量替换
• 灵活输出格式：可指定输出为json、toml或yaml格式（默认yaml）
• 合并算法：基于lodash merge函数，支持递归合并数组和对象

使用场景和适用范围

• 多环境配置管理（如开发、测试、生产环境配置合并）
• Docker Compose/Swarm配置动态生成
• 需要根据环境变量动态调整的配置文件生成
• 多来源配置文件的整合与定制

使用方法和配置说明

基本使用

拉取镜像

bash
docker pull boxboat/config-merge

查看帮助

bash
docker run --rm boxboat/config-merge -h

参数说明

• -f, --format：输出格式，可选json|toml|yaml，默认yaml
• -n, --inline：开始使用内联表示法的深度，默认10，设为0禁用
• -h, --help：显示帮助信息

文件处理规则

• .env和.sh文件：会被加载为环境变量，用于变量替换
• .json, .js, .toml, .yaml, .yml文件：会被合并处理
• .patch.json, .patch.js, .patch.toml, .patch.yaml, .patch.yml文件：会作为JSONPatch应用

工作目录

容器的工作目录为/home/node，需要合并的文件/目录需挂载到此目录。

部署示例

示例1：生成Docker Compose配置

以下示例展示如何合并本地配置文件，生成适用于本地测试的Docker Compose配置：

bash
docker_compose_config=$(
    docker run --rm \
    -v "$(pwd)/test/docker-compose/:/home/node/" \
    boxboat/config-merge \
    local.env docker-compose.yml docker-compose-local.patch.yml docker-compose-local.yml
)

# 使用生成的配置启动Docker Compose
docker-compose -f - -p nginx-local up <<EOF
$docker_compose_config
EOF

# 部署到Swarm
docker stack deploy -c - nginx-local <<EOF
$docker_compose_config
EOF

示例2：使用通配符

支持通配符匹配文件，但需在docker run命令中对通配符进行转义，以便在容器内展开：

bash
docker_compose_config=$(
    docker run --rm \
    -v "$(pwd)/test/docker-compose/:/home/node/" \
    boxboat/config-merge \
    "*.env" docker-compose.yml "*-local*"
)

合并规则

扩展名为.json、.js、.toml、.yaml、.yml的文件将按顺序合并，合并算法基于lodash merge函数，规则如下：

• 解析为undefined的源属性在目标值存在时会被跳过
• 数组和纯对象属性会递归合并
• 其他对象和值类型通过赋值覆盖
• 源文件从左到右应用，后续源文件会覆盖先前源文件的属性赋值

补丁功能

扩展名为.patch.json、.patch.js、.patch.toml、.patch.yaml、.patch.yml的文件将作为JSON Patch应用于合并后的配置。

环境变量替换

.env和.sh文件会被加载到环境中，环境变量替换使用https://github.com/a8m/envsubst%E5%AE%9E%E7%8E%B0%EF%BC%8C%E6%94%AF%E6%8C%81%E4%BB%A5%E4%B8%8B%E8%A1%A8%E8%BE%BE%E5%BC%8F%EF%BC%9A