📚 课程目录第1章环境变量差异

第1章环境变量差异：默认值、生产覆盖、敏感信息加密

Agent 在原型阶段通常使用硬编码或低安全级别的环境变量，而生产环境必须满足覆盖策略、密钥管理与合规审计。本章围绕“默认值—生产覆盖—加密保护”这条主线，拆解变量生命周期的配置差异，并给出可复现的实现流程与调试方法。

1.1 核心差异

差异维度	原型环境	生产环境
默认值来源	代码常量、本地 `.env` 文件	配置管理中心（Vault / AWS Secrets Manager）
覆盖机制	进程启动时按文件 → shell 变量 → 命令行参数顺序覆盖	同顺序，但每个来源都有校验与审计
敏感信息	明文存储，日志可能泄露	加密存储，运行时解密，日志脱敏
密钥轮换	手动修改，无通知	自动轮换，版本管理，失效期强制更新

1.2 环境变量加载流程

标准加载顺序确保默认值能被安全覆盖，生产环境在第三步增加加密解密环节：

读取默认值 — 从代码常量或 .env.default 加载。
环境级覆盖 — 根据 AGENT_ENV 选择 .env.development / .env.production。
解密覆盖 （生产） — 对以 SECRET_ 为前缀的变量执行解密。
运行时注入 — Docker / K8s Secret 或系统环境变量最终覆盖。
启动校验 — 检查必填变量是否存在且格式正确，缺漏则启动失败。

  关键原则： 原型阶段允许变量缺失时使用兜底默认值；生产阶段必须显式定义所有敏感变量，缺失即报错。

1.3 配置文件与命令示例

.env 文件（原型）

# 默认值，可被覆盖
AGENT_NAME=MyDevAgent
AGENT_PORT=8080
SECRET_API_KEY=dev_abc123

生产覆盖文件（.env.production）

# 仅包含非敏感值，敏感值由加密源注入
AGENT_PORT=443
AGENT_LOG_LEVEL=warn
# SECRET_API_KEY 加密后通过 sops 传递

使用 sops 加密敏感变量

# 加密
sops --encrypt --age age1... --in-place .env.secret

# 解密并传递给 Agent
sops exec-file .env.secret "source {} && ./run_agent"

启动时设置环境变量（命令行）

AGENT_PORT=8888 AGENT_LOG_LEVEL=debug python agent.py

调试技巧： 在 Agent 启动早期打印加载的变量名（不打印值）以验证覆盖顺序：

import os; print([k for k in os.environ if k.startswith('AGENT_')])

1.4 部署步骤

Step 1： 将原型 .env 中的敏感键抽出，放到加密存储（Vault / Kubernetes Secret）。
Step 2： 修改 CI/CD 流水线，在构建阶段注入非敏感变量，在运行阶段挂载加密 Secret。
Step 3： 配置启动脚本，执行环境变量解密与校验（参考以下 shell 片段）。
Step 4： 启用日志脱敏，避免加密前的明文出现在日志中。

#!/bin/bash
# deploy_prod.sh - 生产部署入口
set -euo pipefail

export AGENT_ENV=production
. .env.production

# 解密 secret 并 source
sops exec-file .env.secret "source {}"

# 校验必填变量
vars=(SECRET_API_KEY AGENT_PORT)
for v in "${vars[@]}"; do
  if [ -z "${!v:-}" ]; then
    echo "ERROR: Missing required env var: $v"
    exit 1
  fi
done

exec python agent.py

1.5 常见错误与优化

错误	后果	优化方案
默认值中写入生产密钥	泄露风险	默认值只放占位符，生产密钥由加密源注入
覆盖顺序错误	使用错误配置	严格遵循文件 → shell → 命令行的优先级，并记录加载来源
加密前打印变量	明文落入日志	使用 `envsubst` 替代 `export` 后立即脱敏
密钥未轮换	长期暴露	结合 Vault 设置 TTL，自动轮换并通知 Agent 重载

生产警告： 切勿在 Dockerfile 中使用 ENV 硬编码敏感变量；改用 --secret 构建参数和运行时 --env-file 传递。

1.6 环境变量差异流程总览

上图展示了环境变量从原型默认值到生产加密校验的完整路径。关键差异在于生产阶段增加“加密存储”与“启动校验”两个强制环节，从而消除明文泄漏风险并保证配置完整性。