Codex / Cursor / OpenAI API Key 怎么安全管理？

用 Codex、Cursor、Claude Code、OpenAI API 写代码时，最容易被忽略的不是模型怎么调用，而是 API Key、`.env`、SSH 私钥和 Git Token 放在哪里。很多新手不是被黑客“攻破”的，而是自己把密钥提交到 Git、发到截图、贴给 AI 或留在远程 VPS 的日志里。

🧑‍💻 这篇文章适合谁

• 正在用 Codex、Cursor、OpenAI API、Claude Code 或 GitHub Copilot 写代码的人。
• 项目里已经有 `.env`，但不确定能不能提交到 Git 的小白。
• 把开发环境放到海外 VPS、VS Code Remote 或 Cursor Remote 的用户。
• 准备把项目部署到 Vercel、Cloudflare、GitHub Actions、Docker 或 systemd 的开发者。
• 已经误提交过 API Key，想知道下一步该怎么补救的人。

如果你还在搭 AI 开发网络环境，可以先看 稳定 AI 网络环境指南；如果已经准备把 Codex / Cursor 放到 VPS 上，再配合 海外 VPS 远程开发机指南 一起读。

✅ 先给结论：新手照这 6 条做

只要你先做到这 6 条，已经能避开 80% 的 API Key 泄露事故。后面再按本地、Git、AI 工具、远程 VPS 和部署平台逐步补齐。

🔐 哪些东西算敏感信息

新手常把“密码”当敏感信息，却忽略 API Key、Token、连接串和截图。实际开发里，下面这些都要当敏感信息处理。

🧭 API Key 安全的基本原则

API Key 的安全目标不是“永远不出错”，而是让错误更难发生，发生后影响范围更小、恢复更快。

• 项目代码和密钥分离：代码进 Git，密钥进环境变量或 Secret 管理。
• 本地、远程 VPS、CI/CD、生产部署使用不同密钥，避免一处泄露拖垮所有环境。
• 能限制权限、额度、项目或组织范围时，就不要使用过大的主账号权限。
• 多人协作时不要共享个人 Key；每个人使用自己的凭据，团队环境使用专门的部署凭据。
• 排查问题时只暴露错误码、请求路径和脱敏后的配置，不暴露完整 Header、Cookie、Token。

尤其是 OpenAI API 这类按量计费服务，泄露后不仅是账号风险，还可能产生真实费用。密钥一旦离开你的控制范围，就别再侥幸继续用。

📁 本地项目怎么放 .env

最适合小白的方案是：真实密钥放 `.env`，仓库只提交 `.env.example`。这样别人拉取项目后知道需要哪些变量，但看不到你的真实 Key。

  # AI / API secrets
.env
.env.*
!.env.example

# Local-only runtime files
*.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

仓库里可以保留一个模板文件，变量名写清楚，真实值留空。

  # .env.example
# 只放变量名和说明，不放真实密钥
OPENAI_API_KEY=
OPENAI_PROJECT_ID=

# 其他服务按项目需要增加
DATABASE_URL=
GITHUB_TOKEN=

代码里读取环境变量，而不是写死真实密钥：

  // Node.js / Astro / Next.js 示例
const apiKey = process.env.OPENAI_API_KEY;

if (!apiKey) {
  throw new Error("OPENAI_API_KEY is not configured");
}

临时排查时，也可以只给当前终端会话设置环境变量。这个方式适合测试命令，不适合长期生产部署。

  # Linux / macOS / VPS：仅当前终端会话生效
export OPENAI_API_KEY="your_openai_api_key_here"

# Windows PowerShell：仅当前窗口生效
$env:OPENAI_API_KEY="your_openai_api_key_here"

🧪 提交前怎么检查 Git

每次提交 AI 项目之前，先花 30 秒看一眼暂存区。很多泄露都是因为 `git add .` 之后没有看 diff。

  # 看这次准备提交哪些文件
git status --short
git diff --cached --name-only

# 提交前看暂存区完整 diff，确认没有 Key、Token、Cookie
git diff --cached

# Linux / macOS / Git Bash：检查是否已经有 .env 被 Git 跟踪
git ls-files | grep -E '(^|/)\.env(\.|$)'

# Windows PowerShell：检查是否已经有 .env 被 Git 跟踪
git ls-files | Select-String -Pattern '(^|/)\.env(\.|$)'

# 搜索常见敏感变量名，正式项目建议接入 secret scanning
rg -n "OPENAI_API_KEY|ANTHROPIC_API_KEY|GITHUB_TOKEN|DATABASE_URL|sk-" .

如果发现 `.env` 已经被 Git 跟踪，先移出索引，再确认 `.gitignore` 已经生效。

  # 如果 .env 已经被 Git 跟踪，先把它从 Git 索引移除
# 这不会删除你本地的 .env 文件
git rm --cached .env

# 确认 .gitignore 已经包含 .env 规则后再提交
git status --short
git commit -m "Remove env file from git tracking"

注意：如果真实 Key 已经进入过 Git 提交，单纯 `git rm --cached .env` 不够。你还需要先轮换 Key，并按公开仓库、私有仓库、是否推送远端来决定是否清理历史。

🤖 Codex / Cursor 使用时怎么避免泄露

AI 编程工具能读代码、改文件、运行命令，效率很高；但也意味着你要更清楚哪些内容不能放进上下文。

• 不要把完整 API Key 粘给 Codex、Cursor、聊天窗口或工单。
• 不要让 AI “帮我打印所有环境变量”“帮我上传日志”，除非你能确认日志已经脱敏。
• 让 AI 改配置时，要求它使用变量名和占位符，例如 `OPENAI_API_KEY=your_key_here`。
• 提交前自己看 `git diff`，不要完全依赖 AI 判断有没有敏感信息。
• 如果工具支持忽略文件或上下文排除，把 `.env`、私钥、日志、备份文件加入忽略列表。

一个实用习惯是：让 AI 看到 `.env.example`，不要让它看到 `.env`。它知道项目需要什么变量，但不需要知道真实值。

🖥️ 远程 VPS 开发机怎么存密钥

把 Codex / Cursor 放到海外 VPS 上跑时，密钥风险会变成两层：仓库不能泄露，服务器本身也不能被轻易读取。至少先做好文件权限和目录隔离。

  # VPS 上创建项目级 .env 后，收紧权限
chmod 600 .env

# SSH 私钥也要收紧权限
chmod 600 ~/.ssh/id_ed25519
chmod 700 ~/.ssh

• 每个项目单独 `.env`，不要把所有 Key 都塞进 `~/.bashrc`。
• 不要长期使用 root 用户写代码，创建普通开发用户更稳。
• 不要把数据库、Redis、管理面板暴露在公网，只开放必要端口。
• 多人共用 VPS 时，不要共用同一套 API Key 和 SSH 私钥。
• 备份代码和配置时，不要把明文 `.env` 直接同步到公共网盘或公开仓库。

如果项目用 systemd 管理，可以把环境变量放进受限权限的 EnvironmentFile：

  # /etc/my-app/my-app.env
OPENAI_API_KEY=your_openai_api_key_here
DATABASE_URL=postgres://...

# systemd service 片段
[Service]
EnvironmentFile=/etc/my-app/my-app.env
WorkingDirectory=/opt/my-app
ExecStart=/usr/bin/node server.js

如果项目用 Docker Compose，可以用 `env_file`，但 `.env` 仍然必须被 `.gitignore` 忽略。

  # docker-compose.yml
services:
  app:
    image: my-app:latest
    env_file:
      - .env
    ports:
      - "3000:3000"

# 注意：.env 仍然必须在 .gitignore 里

🚀 CI/CD 和生产部署怎么处理

CI/CD 和生产部署里最忌讳把 Key 写进仓库配置文件。GitHub Actions、Vercel、Cloudflare Pages、Netlify 这类平台都有自己的环境变量或 Secrets 功能。

• GitHub Actions：把 Key 放到 Repository Secrets 或 Environment Secrets，再在 workflow 里读取。
• Vercel / Netlify / Cloudflare：在项目设置里配置环境变量，区分 development、preview、production。
• Docker 镜像：不要把 `.env` 打进镜像层；构建参数和运行时环境变量要分清。
• 生产环境：尽量使用单独的生产 Key，并限制调用范围、额度和可访问项目。

有前端页面时要特别小心：只要变量被打包进浏览器端代码，就可能被用户看到。真正私密的 API Key 应该在后端、Serverless Function、VPS 服务端或平台 Secret 中使用。

🧯 如果已经泄露了怎么办

密钥泄露时，顺序很重要：不要先花半小时美化提交记录，先让泄露的 Key 失效。

如果泄露发生在公开 GitHub 仓库，还要检查 fork、Actions 日志、部署日志、Release 包和构建产物。已经进入公开历史的敏感信息，按 GitHub 官方“移除敏感数据”流程处理，不要只靠删除最新文件。

🧰 推荐工具与适用场景

不同阶段适合不同工具。个人练手不用一上来就引入复杂 Secret 平台；团队和生产环境也不应该只靠一个 `.env` 文件硬撑。

如果你只是一个人做小项目，先把 `.env`、`.env.example`、`.gitignore` 和提交前检查做好。等项目进入多人协作、生产部署或客户代码阶段，再引入 GitHub Secrets、平台环境变量和专门的 Secret 管理工具。

⚠️ 常见错误做法

📋 提交前检查清单

每次提交 AI 项目前，按下面清单过一遍。它不高级，但很管用。

• 仓库里只有 `.env.example`，没有真实 `.env`。
• `git status --short` 里没有 `.env`、私钥、日志、截图、备份压缩包。
• `git diff --cached` 没有 `sk-`、`OPENAI_API_KEY` 的真实值、Cookie、Token、连接串。
• AI 工具生成的代码只读取环境变量，没有把 Key 写死在源码里。
• 远程 VPS 上 `.env` 权限收紧，项目之间没有乱共用 Key。
• CI/CD 使用平台 Secrets，不在 workflow、Dockerfile、Compose 文件里写真实 Key。
• 如果 Key 曾经公开，已经先轮换或吊销，不继续使用旧 Key。

🧭 站内下一步推荐

📚 资料来源

• OpenAI API Key 安全最佳实践：用于核对 API Key 不共享、不暴露、按场景分开管理和轮换的安全口径。
• OpenAI Codex CLI 官方文档：用于核对 Codex CLI 的官方入口和终端使用边界。
• GitHub Secret Scanning 文档：用于核对 GitHub 仓库密钥扫描能力。
• GitHub 移除仓库敏感数据文档：用于核对敏感信息进入 Git 历史后的处理流程。
• GitHub 忽略文件文档：用于核对 `.gitignore` 的基础行为。