Docker多阶段构建中构建阶段向最终阶段传递密钥问题

你忽略的核心问题 #

1. 多阶段构建环境完全隔离：build阶段的环境变量无法自动传递到最终阶段。你在build阶段设置的ENV_SECRET_1，到第二个FROM alpine阶段时完全不可见，所以SECRET_1=$ENV_SECRET_1会被解析为空值。
2. Shell变量未提前设置：docker-compose.yml中的${SECRET_1}会读取当前Shell环境的变量，你没有在执行docker compose前设置这个变量，所以Compose会提示变量未设置，默认使用空字符串。
3. RUN命令的环境变量仅临时有效：build阶段的RUN export ENV_SECRET_1=1只是在当前RUN的Shell进程中生效，执行完毕后就会消失，不会影响后续构建步骤或其他阶段。

修正后的基础示例 #

方法1：通过ARG跨阶段传递（仅用于非敏感数据，不推荐传密钥） #

如果只是验证变量传递逻辑，可在最终阶段显式声明ARG：

FROM alpine AS build
ARG SECRET_1
# 模拟从Vault拉取密钥（实际需调用Vault API）
RUN echo "获取到密钥: $SECRET_1"

FROM alpine
# 必须在当前阶段重新声明ARG才能引用
ARG SECRET_1
ENV SECRET_1=$SECRET_1
CMD sleep infinity

方法2：提前设置Shell变量或使用.env文件 #

执行docker compose前，先在Shell中设置变量：

export SECRET_1="你的实际密钥"
docker compose up -d --build

或者创建.env文件：

SECRET_1="你的实际密钥"

docker-compose.yml可简化为：

services:
  main:
    image: my_var_test
    build:
      context: .
      dockerfile: Dockerfile
      args:
        SECRET_1: ${SECRET_1}

针对Vault密钥注入的最优实践 #

注意：绝对不要在构建阶段注入密钥——构建阶段的密钥会残留镜像层中，可通过镜像历史恢复，严重泄露敏感信息。以下是安全的运行时注入方案：

1. Vault Agent Sidecar模式 #

部署Vault Agent作为Sidecar容器，负责从Vault拉取密钥并同步到共享卷，主容器从卷中读取密钥：

• Agent会自动刷新密钥，无需应用修改代码
• 主容器无需直接与Vault交互，适配第三方镜像
• 可通过AppRole/Kubernetes Auth自动获取Vault Token，避免硬编码

2. 启动脚本注入环境变量 #

编写启动脚本，在应用启动前从Vault拉取密钥并注入环境：

#!/bin/sh
# 从Vault API拉取密钥（需提前配置Vault地址和Token）
SECRET_1=$(curl -s -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/secret/data/myapp | jq -r '.data.data.secret1')
export SECRET_1

# 启动原应用（替换为第三方镜像的启动命令）
exec "$@"

在docker-compose.yml中挂载脚本并指定入口：

services:
  main:
    image: third-party-webapp
    entrypoint: ["/bin/sh", "/app/entrypoint.sh"]
    volumes:
      - ./entrypoint.sh:/app/entrypoint.sh
    environment:
      VAULT_ADDR: "https://你的Vault地址"
      VAULT_TOKEN: "${VAULT_TOKEN}" # 建议用AppRole动态获取，不要硬编码

3. Docker Secrets（Swarm模式） #

将Vault中的密钥同步到Docker Secrets，在Swarm服务中挂载Secrets到容器内的文件路径，应用从文件读取密钥：

• Secrets存储在Docker加密存储中，比环境变量更安全
• 可通过工具自动同步Vault密钥到Docker Secrets

4. Consul Template + Vault Agent #

用Consul Template渲染包含密钥的配置文件，由Vault Agent自动更新，应用读取配置文件：

• 适合需要将密钥写入配置文件的应用
• 支持动态刷新配置，无需重启应用

安全要点 #

• 最小化Vault Token权限：仅授予应用所需密钥路径的读取权限
• 避免硬编码Token：使用AppRole、Kubernetes Auth等自动认证方式
• 不要将密钥写入镜像：所有密钥注入操作都应在运行时完成

内容的提问来源于stack exchange，提问作者Jason