Python API Key防泄露：环境变量与Git忽略配置实践

脚本专家

API Key 是调用 AI 服务的访问凭证，一旦泄露，别人就能借用你的额度发起请求。Python 项目中，Key 泄露的常见原因包括：写死在源码中并提交到 Git、打印到终端或日志、放进前端代码、截图时未遮挡、错误信息中返回给用户。所以安全处理要同时覆盖代码、日志、仓库和部署环境。

一、从源码中移除硬编码 Key

很多初学者习惯这样：

2. from openai import OpenAI
4. client = OpenAI(
5.     api_key='sk-your-real-key',
6.     base_url='https://your-api-domain.com/v1',
7. )

复制代码

这样的代码一旦上传 GitHub、分享给同事或打包发布，真实 Key 就暴露了。更稳妥的方式是从环境变量读取：

2. import os
3. from openai import OpenAI
5. client = OpenAI(
6.     api_key=os.getenv('API_KEY'),
7.     base_url=os.getenv('BASE_URL'),
8. )

复制代码

业务代码中不再出现真实凭证，Key 的保存范围被转移到运行环境。

二、用 .env 管理本地配置

本地开发推荐 python-dotenv。安装：

2. pip install python-dotenv

复制代码

然后在项目根目录创建 .env：

2. API_KEY=replace-with-your-key
3. BASE_URL=https://your-api-domain.com/v1
4. MODEL=your-model-name

复制代码

Python 启动时加载：

2. import os
3. from dotenv import load_dotenv
5. load_dotenv()
7. api_key = os.getenv('API_KEY')
8. base_url = os.getenv('BASE_URL')
9. model = os.getenv('MODEL')

复制代码

注意：.env 只适合放在本地开发机或受保护的部署环境，不能提交到公开仓库。

三、用 .gitignore 拦截 .env

在项目根目录创建或修改 .gitignore，加入：

2. .env
3. .env.*
4. !.env.example

复制代码

同时提供一个脱敏模板 .env.example：

2. API_KEY=replace-with-your-key
3. BASE_URL=https://example.com/v1
4. MODEL=your-model-name

复制代码

这样协作者知道需要配置哪些项目，拿到的却不是真实 Key。

四、日志中只显示脱敏结果

不要在日志里直接打印整个 Key：

2. print(f'api_key={api_key}')

复制代码

可以写一个脱敏函数：

2. def mask_secret(value: str, prefix: int = 4, suffix: int = 3) -> str:
3.     if not value:
4.         return '<empty>'
5.     if len(value) <= prefix + suffix:
6.         return '***'
7.     return value[:prefix] + '***' + value[-suffix:]

复制代码

调用时：

2. print(mask_secret(api_key))

复制代码

也可以只记录配置是否已设置：

2. print({
3.     'api_key_configured': bool(api_key),
4.     'model': model,
5. })

复制代码

五、前端不能保存服务端 Key

浏览器中的 JavaScript、页面源码、网络请求都可能被用户完全看到。所以不要在前端写：

2. const apiKey = 'your-real-key';

复制代码

正确结构是“浏览器前端 → 自己的后端 → AI API”。后端保存 Key，前端只调用自己的业务接口。纯本地脚本可以把 Key 放在本地环境变量中；公开网页则绝不能把服务端 Key 直接交给浏览器。

六、启动时检查配置，但不打印配置

可以在启动阶段检查必需配置：

2. def validate_config(api_key: str, base_url: str, model: str):
3.     missing = []
4.     if not api_key:
5.         missing.append('API_KEY')
6.     if not base_url:
7.         missing.append('BASE_URL')
8.     if not model:
9.         missing.append('MODEL')
10.     if missing:
11.         raise ValueError('缺少配置：' + ', '.join(missing))

复制代码

这个检查能尽早暴露问题，但不要顺手把完整配置打印出来。

七、Key 泄露后的应急处理

怀疑 Key 已泄露时，按以下顺序处理：

1. 立即禁用或删除旧 Key
2. 创建新 Key 并替换本地和部署环境配置
3. 检查 Git 提交记录和日志
4. 查看异常请求和用量变化
5. 清理公开文件中的敏感内容

注意：只删除当前文件不够。如果 Key 曾经提交到 Git，历史提交里可能仍然存在，需要同步清理或轮换。

八、提交前做一次凭证扫描

可以在命令行搜索常见凭证模式：

2. git grep -n -E 'sk-[A-Za-z0-9_-]{10,}|API_KEY=|Bearer [A-Za-z0-9._-]+' -- . ':!*.lock'

复制代码

这不是完整安全扫描，但能发现一部分明显问题。正式项目可以接入密钥扫描工具，并把扫描放到提交钩子或 CI 流程中。

九、个人开发者最小安全清单

- Key 不写死在源码中
- .env 不提交到仓库，同时提供脱敏 .env.example
- 日志不打印完整凭证
- 前端不保存服务端 Key
- 不把 Key 放入截图和文章
- 发现泄露后立即轮换
- 定期查看异常用量

对于 Python AI 项目，把这些基础动作做到位，就能明显降低凭证泄露风险，也让项目更适合后续部署和维护。

热心网友2

楼主总结得很全面，尤其“环境变量读取 + .env 本地管理 + .gitignore 拦截”这套组合是新手最容易忽略的。我补充一个实际踩过的坑：`.gitignore` 里写了 `.env` 之后，如果之前已经提交过，一定要用 `git rm --cached .env` 把它从暂存区移除，否则仍然会留在版本管理里。另外那个脱敏函数很实用，我直接拿去用了，谢谢分享。

热心网友2

很实用的总结，尤其是“日志脱敏”和“提交前扫描”这两点，很多新手容易忽略。我补充一个小细节：用 `git grep` 扫描的时候，建议也把 `.env` 加进 `.gitignore` 之后，再检查一下有没有文件被 `git add` 过，有时候因为加了 `-f` 或者规则没写对，Key 还是会被提交进去。另外，如果用的是 GitHub，可以开启他的 Secret Scanning 功能，仓库历史里的 Key 也能帮你报警，算是最后一道保险。

热心网友2

这篇帖子写得太实用了，尤其是“Key 泄露后的应急处理”和“提交前做一次凭证扫描”这两部分，对经常在 GitHub 上开源项目的人来说简直是救命提醒。我之前就吃过亏，把 key 提交到 public 仓库后才发现，虽然立刻删了文件，但历史记录里还能翻出来，最后只能轮换密钥。 另外还想补充一点，如果项目用的是 Git 后端的代码托管平台（比如 GitHub、GitLab），建议再开启平台的 secret scanning 功能，配合帖子里的 `.gitignore` 和本地扫描，基本就能把大部分泄露风险堵住了。感谢楼主整理得这么清晰！