envsubst + bash Docker镜像文档

镜像概述

本镜像整合了envsubst工具与bash shell，提供轻量级解决方案，用于在容器化环境中高效处理环境变量替换及执行bash脚本。基于轻量级基础镜像构建，体积小巧，启动快速，适用于各类需要动态配置文件生成或环境变量预处理的场景。

核心功能与特性

• 环境变量替换：集成envsubst工具，支持将文本文件中的$VARIABLE或${VARIABLE}格式占位符替换为实际环境变量值
• 完整bash支持：包含标准bash shell，支持复杂条件判断、循环、函数等bash语法特性，可执行复杂shell脚本
• 轻量级设计：基于精简基础镜像（如Alpine或Debian Slim），镜像体积小，资源占用低，部署高效

适用场景

• 配置文件模板处理：动态生成包含环境变量的配置文件（如Nginx配置、应用配置文件、INI/JSON/YAML格式配置）
• 容器启动预处理：在应用容器启动前，通过环境变量替换生成最终配置文件
• 环境变量驱动的脚本执行：运行依赖环境变量的bash脚本，实现动态逻辑处理
• CI/CD流程中的配置生成：在持续集成/部署流程中，根据不同环境参数生成对应配置文件

使用方法与配置说明

基本用法（Docker Run）

1. 环境变量替换示例

将本地模板文件中的环境变量替换为实际值：

# 准备模板文件 input.template（内容示例："Hello, $NAME!"）
# 执行替换并输出到output.txt
docker run --rm \
  -v $(pwd):/workspace \          # 挂载当前目录到容器内/workspace
  -e NAME="World" \               # 设置环境变量NAME
  my-envsubst-bash-image \        # 镜像名称
  envsubst < /workspace/input.template > /workspace/output.txt

2. 指定替换变量列表

仅替换指定的环境变量（避免替换模板中其他未定义的变量）：

docker run --rm \
  -v $(pwd):/workspace \
  -e NAME="World" -e AGE=30 \
  my-envsubst-bash-image \
  envsubst '$NAME' < /workspace/input.template > /workspace/output.txt
# 仅替换$NAME，保留$AGE占位符

3. 执行bash脚本

运行包含环境变量逻辑的bash脚本：

# 准备脚本文件 script.sh（内容示例：
# #!/bin/bash
# echo "Name: $NAME, Age: ${AGE:-20}"
# ）
docker run --rm \
  -v $(pwd):/workspace \
  -e NAME="Alice" \
  my-envsubst-bash-image \
  bash /workspace/script.sh
# 输出：Name: Alice, Age: 20（AGE未定义时使用默认值20）

Docker Compose示例

在容器启动前生成配置文件：

version: '3'
services:
  app:
    image: my-app-image
    depends_on:
      config-generator:
        condition: service_completed_successfully
    volumes:
      - ./config:/app/config  # 挂载生成的配置文件

  config-generator:
    image: my-envsubst-bash-image
    volumes:
      - ./templates:/templates
      - ./config:/output
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=admin
    command: bash -c "envsubst < /templates/app.config.template > /output/app.config"

配置参数说明

envsubst工具参数

环境变量传递

• 通过-e VAR=value（Docker Run）或environment字段（Docker Compose）传递环境变量
• 支持读取系统环境变量：使用--env-file .env加载.env文件中的环境变量
• 容器内可访问的环境变量均可用作替换源

注意事项

• 挂载文件时确保容器内路径权限正确（建议使用-u $(id -u):$(id -g)指定用户ID，避免权限问题）
• 模板文件中避免使用$符号的非环境变量场景（如需保留$，可使用\$转义）
• 复杂脚本建议通过挂载文件执行，避免在command中直接编写长命令
• 基础镜像选择（如Alpine）可能影响部分bash特性支持，复杂脚本建议使用基于Debian Slim的版本