Claude Code 密钥管理指南：从 .env 到生产轮换

API key、数据库 URL、OAuth client secret、云端部署凭证，都是应用上线必须面对的配置。但它们一旦被随手复制，就可能长期留在 Git 历史、CI 日志、截图、工单、README 或文章草稿里。使用 Claude Code 处理调试、部署和文档时，第一条规则是：Claude Code 可以帮助你建立安全机制，但不应该看到、打印、保存或复用真实密钥值。

密钥管理不是把密码放进某个“保险箱”就结束。它包括把配置从代码中分离，区分本地、开发、预发和生产环境，限制权限，启动时验证配置，日志中脱敏，并在事故发生前就能完成轮换。The Twelve-Factor App 的 Config 原则仍然是起点：配置应该来自环境，而不是写死在仓库里。现实项目还需要 .gitignore、.env.example、配置校验、CI/CD secrets、云端 Secret Manager 和可执行的轮换清单。

flowchart LR
  Dev["Local .env"] --> Loader["Validated config loader"]
  CI["CI/CD secrets"] --> Deploy["Deployment runtime"]
  Store["AWS / GCP / Azure secret store"] --> Deploy
  Deploy --> App["Application process"]
  App --> Logs["Redacted logs"]

1. 先决定什么放在哪里

初学者最容易把所有环境变量都当成同一类配置。判断方式很简单：如果某个值泄露后，别人可以花钱、发邮件、读取数据、写入数据、部署代码或冒充用户，它就是密钥。公开的 base URL、功能开关名称、OAuth client ID 通常不是同等级别，因为它们单独不能授予权限。

场景	示例	本地开发	生产环境
邮件和 API 集成	SendGrid API key、Stripe secret key、GitHub token	在.env中使用测试 key	从 CI/CD secrets 或密钥库注入
数据库	DATABASE_URL、用户名、密码	只连接本地或开发数据库	拆分读写权限并定期换密码
云端部署	AWS/GCP/Azure 凭证	避免本地长期访问 key	使用 OIDC 或部署专用 role
OAuth 与 Webhook	OAUTH_CLIENT_SECRET、webhook signing secret	为本地单独创建应用	生产 secret 不进仓库

重点是环境隔离。不要在本地复用生产 Stripe key，不要让 CI 使用拥有整个组织权限的个人 GitHub token，也不要给部署凭证开管理员权限。最小权限原则就是：只给完成任务所需的权限，只给对应环境，最好还要有期限。

2. 仓库只提交形状，不提交值

.env适合本地开发，但绝不能提交。仓库应该提交.env.example，说明变量名、格式、来源和用途。团队 onboarding 时可以配合阅读环境变量管理指南，减少“这个 key 去哪里拿”的重复沟通。

# Local secrets
.env
.env.*
!.env.example
!.env.test.example

# Logs and generated output that may contain tokens
npm-debug.log*
yarn-debug.log*
coverage/
dist/

# .env.example - placeholders only, never real values
NODE_ENV=development
APP_BASE_URL=http://localhost:3000

# Use a local database user, not production credentials.
DATABASE_URL=postgres://app_user:replace-me@localhost:5432/app_dev

# Use test/sandbox keys for local development.
SENDGRID_API_KEY=SG.xxxxxx
STRIPE_SECRET_KEY=sk_test_xxxxxx
GITHUB_TOKEN=ghp_xxxxxx

# OAuth secrets must be separated by environment.
OAUTH_CLIENT_ID=local-client-id
OAUTH_CLIENT_SECRET=replace-me

# Deployment reads these from CI or a cloud secret store.
AWS_REGION=ap-northeast-1
DEPLOY_ROLE_ARN=arn:aws:iam::123456789012:role/app-deploy-dev

让 Claude Code 参与时，要明确边界：可以读取.env.example、部署配置、package scripts 和变量名；不能打开.env，不能把真实值贴进对话，也不能把凭证写入文档。如果实现需要真实值，应由你在本地、CI 设置页或云端密钥库中填写，Claude Code 只需要知道变量名。

3. Node.js 启动时校验，日志中统一脱敏

缺失或格式错误的密钥应该让应用启动失败，而不是运行到一半才报错。下面的 Node.js 配置加载器使用dotenv和envalid做校验，并提供redactConfig给日志、健康检查和支持排障使用。

import { config as loadDotenv } from "dotenv";
import { cleanEnv, str, url } from "envalid";

const envFile = process.env.NODE_ENV === "test" ? ".env.test" : ".env";
loadDotenv({ path: envFile });

const secretKeyPattern = /(KEY|TOKEN|SECRET|PASSWORD|DATABASE_URL|PRIVATE)/i;

const env = cleanEnv(process.env, {
  NODE_ENV: str({
    choices: ["development", "test", "staging", "production"],
    default: "development",
  }),
  APP_BASE_URL: url({ default: "http://localhost:3000" }),
  DATABASE_URL: url(),
  SENDGRID_API_KEY: str(),
  STRIPE_SECRET_KEY: str(),
  GITHUB_TOKEN: str(),
  OAUTH_CLIENT_ID: str(),
  OAUTH_CLIENT_SECRET: str(),
  AWS_REGION: str({ default: "ap-northeast-1" }),
  DEPLOY_ROLE_ARN: str(),
});

export function appConfig() {
  return Object.freeze({
    nodeEnv: env.NODE_ENV,
    appBaseUrl: env.APP_BASE_URL,
    databaseUrl: env.DATABASE_URL,
    sendgridApiKey: env.SENDGRID_API_KEY,
    stripeSecretKey: env.STRIPE_SECRET_KEY,
    githubToken: env.GITHUB_TOKEN,
    oauthClientId: env.OAUTH_CLIENT_ID,
    oauthClientSecret: env.OAUTH_CLIENT_SECRET,
    awsRegion: env.AWS_REGION,
    deployRoleArn: env.DEPLOY_ROLE_ARN,
  });
}

export function redactValue(key, value) {
  if (!secretKeyPattern.test(key)) return value;
  if (!value) return "<empty>";
  const text = String(value);
  if (text.length <= 8) return "<redacted>";
  return `${text.slice(0, 4)}...${text.slice(-4)}`;
}

export function redactConfig(config) {
  return Object.fromEntries(
    Object.entries(config).map(([key, value]) => [key, redactValue(key, value)]),
  );
}

if (process.argv[1] === new URL(import.meta.url).pathname) {
  console.log(redactConfig(appConfig()));
}

常见事故是为了排查问题临时写下console.log(process.env)，然后把 CI 日志贴到工单或聊天里。Claude Code 如果被要求总结原始日志，也可能把密钥再次写进测试、文档或文章。因此先脱敏，再提问。截图也一样，上传到任何地方前都要裁剪或打码。

4. 给 Claude Code 明确权限边界

Claude Code 通常不需要真实密钥。它需要的是变量名、格式、已经脱敏的错误信息，以及每个权限的目的。安全、部署、排障任务开始前，可以直接复制这段边界提示。

You may inspect .env.example, package.json, deployment manifests, and secret names.
Do not open, print, summarize, store, or copy .env, CI/CD secret values, cloud credentials, production dumps, or screenshots containing tokens.
When you need a value, ask me to set it outside chat and confirm only the variable name.
If a secret appears in command output, stop, redact it, and report which file or command exposed it.
Before changing permissions, explain the least-privilege scope and ask for approval.
Do not paste real secrets into prompts, logs, documentation, code comments, tests, tickets, or articles.

命令权限也要收紧。printenv、cat .env、会显示云凭证的 CLI、完整 CI 日志、截图抓取，都应要求人工确认。即使没有真实值，Claude Code 也可以根据.env.example、类型定义、脱敏错误和官方文档完成大部分修改。

5. 合理使用 CI/CD secrets 和云端密钥库

实际项目中，本地用.env，流水线用 CI/CD secrets，生产运行时用云端密钥库，是比较稳妥的分层。AWS 可用AWS Secrets Manager，Google Cloud 可用Secret Manager，Azure 可用Key Vault。GitHub 仓库还应启用secret scanning，尽早发现误提交的 token。

name: deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    env:
      NODE_ENV: production
      AWS_REGION: ap-northeast-1
    steps:
      - uses: actions/checkout@v4
      - name: Validate required secret names
        run: test -n "${{ secrets.DEPLOY_ROLE_ARN }}" && test -n "${{ secrets.DATABASE_URL }}"
      - name: Deploy without echoing secrets
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          DEPLOY_ROLE_ARN: ${{ secrets.DEPLOY_ROLE_ARN }}
        run: npm run deploy

CI 中最大的陷阱是“先 echo 看看”。GitHub Actions 会遮蔽很多精确匹配的 secret，但对派生字符串、编码后的 URL、JSON 包装值、截图和未注册的值并不总是可靠。让 Claude Code 输出变量名和验证步骤，不要输出值；如果它要求contents: write或更大的云权限，要求说明原因并尽量降级。

6. 把轮换做成日常流程

密钥轮换不应该只在事故后发生。SendGrid、Stripe、GitHub token、数据库密码、OAuth client secret、webhook signing secret、云端 trust policy，都应该记录 owner、环境、消费者、最近轮换日期和下次复查日期。

## Secret rotation checklist
- [ ] Identify owner, environment, consumers, and business impact.
- [ ] Create a new secret with the smallest required scope.
- [ ] Store it in CI/CD secrets or the cloud secret store.
- [ ] Deploy one service or job with the new value.
- [ ] Confirm logs and metrics without printing the secret.
- [ ] Revoke the old secret.
- [ ] Scan Git history, tickets, docs, screenshots, and chat snippets.
- [ ] Record the rotation date and next review date.

Claude Code 很适合把这份清单变成 Issue 模板、Runbook 或迁移计划。但不要把旧 key 或新 key 发给它。更安全的提法是：“找出所有SENDGRID_API_KEY引用，并为 v2 key 准备灰度切换计划。”

7. 发布前先检查失败案例

只要出现以下任一情况，就应该暂停发布或部署：

• .env或.env.production被提交过，但暴露的 key 没有撤销。
• 截图、CI 日志、错误报告、文章示例里出现 token、数据库 URL 或 OAuth secret。
• 云端 key 有管理员权限，而实际只需要部署权限。
• 本地开发复用了生产 Stripe、SendGrid、数据库或 GitHub 凭证。
• OAuth client secret 或 webhook signing secret 没有 owner 和轮换手册。
• AI 被喂入真实密钥后，又把它写进 README、测试、工单或博客草稿。

安全事故往往来自流程缺口，而不只是代码错误。可以用安全审计清单检查权限，用安全失败案例训练评审视角，用API 开发指南梳理服务边界；如果涉及 SendGrid 或事务邮件，也请参考邮件自动化文章。

8. 团队落地方式

不要一开始就把所有服务都迁到云端密钥库。先选一个应用，把.gitignore、.env.example、配置加载器、日志脱敏、CI/CD secrets、生产密钥库和轮换记录跑通。然后再按常见类型迁移：SendGrid、Stripe、GitHub token、DATABASE_URL、OAuth client secret、部署凭证。

ClaudeCodeLab 的培训和咨询会基于真实仓库结构，但不会收集真实密钥值。我们会一起界定 Claude Code 可以看的文件，设计 CI/CD secret 边界，启用 GitHub secret scanning，规划 AWS/GCP/Azure 密钥库迁移，并留下可复用的提示词和 Runbook。这样团队第二天就能在代码评审中使用，而不是只听一场抽象讲座。

总结一下，密钥管理不是单纯“藏字符串”。它是把值和代码分开，隔离环境，启动时校验，日志中脱敏，收窄权限，并能定期轮换。Claude Code 可以帮助建立和审查这个体系，但不应该变成另一个复制密钥的地方。

在 Masa 的示例 Node.js 应用中实际验证后，配置加载器成功发现缺失变量，redactConfig让 CI 日志不再暴露数据库 URL 和 API key，部署 workflow 也去掉了多余的 write 权限。唯一的意外是旧截图里残留了 Stripe 测试 key，因此在发布前重新发行了 key。经验是：日志、截图和草稿也要像源码一样严格检查。