RAG 项目中存储 API 密钥最推荐的做法是在开发环境使用本地环境变量文件，在生产环境使用云厂商的密钥管理服务。风险边界在于绝不能将包含密钥的文件提交到代码版本控制系统。
先说结论：避免硬编码的核心是将密钥与代码分离，开发阶段用环境变量，生产阶段用密钥管理服务。
- 先判断：确认当前密钥是否已提交到 Git 历史记录中
- 优先做：立即移除代码中的明文密钥并配置环境变量加载
- 再验证：通过代码扫描工具和 Git 日志确认无密钥残留
命令速用版
本地开发时创建 .env 文件并在 .gitignore 中排除，生产环境使用云平台命令行工具注入密钥。
# 创建本地环境变量文件
echo "OPENAI_API_KEY=your_key_here" > .env
# 确保 .env 不被提交到版本控制
echo ".env" >> .gitignore
# Python 代码中加载环境变量示例
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")为什么会这样
硬编码密钥会导致密钥随代码库公开泄露，一旦仓库权限失控或代码开源，攻击者可直接获取密钥。
代码版本控制系统会保留所有历史提交记录，即使后续删除了密钥文件，历史记录中仍可找回。密钥管理服务提供访问审计和自动轮换功能，能限制密钥的使用范围和生命周期。
分步处理
步骤 1：清理现有代码
搜索代码库中的所有密钥模式，替换为环境变量读取逻辑。检查 Git 历史记录，若已提交过密钥，需使用 git filter-repo 等工具清洗历史。
步骤 2：配置本地开发环境
在项目根目录创建 .env 文件存储密钥，确保该文件出现在 .gitignore 列表中。使用 python-dotenv 或 dotenv 库在应用启动时加载。
步骤 3：配置生产环境密钥管理
在云厂商的密钥管理服务中创建密钥条目。配置应用运行角色的 IAM 权限，仅允许读取特定密钥。
步骤 4：应用集成
修改代码通过云 SDK 动态获取密钥，而不是启动时读取固定值。设置密钥自动轮换策略，减少长期泄露风险。
怎么验证是否生效
使用 git log -p 搜索密钥特征字符串，确认历史记录中无明文。在运行环境中打印环境变量名称确认存在，但禁止打印密钥值。使用安全扫描工具如 GitLeaks 扫描仓库。
常见坑
将 .env 文件误提交到 GitHub 私有仓库，私有仓库转公开时密钥会立即泄露。在日志中打印包含密钥的配置对象，导致密钥写入日志系统。使用默认的服务账户密钥文件且未限制权限，导致密钥文件被下载即可滥用。
常见问题
密钥已经提交到 Git 历史怎么办
必须清洗 Git 历史记录，仅删除当前文件无效。
使用 git filter-repo 或 BFG Repo-Cleaner 工具移除历史中的敏感文件，随后强制推送并通知所有协作者重新克隆仓库，同时立即作废旧密钥。
生产环境可以直接用 .env 文件吗
不建议，生产环境应使用密钥管理服务。
.env 文件存在于磁盘上，容易被备份或误下载，缺乏访问审计和细粒度权限控制，云厂商密钥管理服务能提供更好的隔离和轮换机制。
如何确认密钥没有被泄露
监控密钥使用日志并设置异常告警。
检查云厂商控制台的 API 调用日志，关注非预期 IP 或高频调用，部分提供商支持密钥泄露扫描服务，可定期检测公开代码库中是否包含当前密钥。