0.6.2 你的密码放对地方了吗——环境变量与密钥管理：安全存储的最佳实践

一句话破题

密钥不进代码库，不进日志。环境变量 + 密钥管理服务 + 轮换机制，是基础中的基础。

.env 文件层级

• .env.local：本地私有，开发者机器的机密配置；不提交版本库。
• .env.development：团队共享的开发环境变量（不含密钥）。
• .env.production：生产环境变量（不含明文密钥）；密钥由密钥管理服务注入。

密钥管理与 .gitignore

• .gitignore 示例：

.env*
.env.local
.env.production.local

• 禁止将 API Key、数据库连接串等明文放入代码或日志。
• 生产环境使用云密钥服务：AWS Secrets Manager、Azure Key Vault、GCP Secret Manager。

Windows PowerShell 操作

• 查看：Get-ChildItem Env:
• 会话设置：$env:DB_URL = 'postgres://user:pass@host:5432/db'
• 持久化：setx DB_URL "postgres://user:pass@host:5432/db"

TypeScript 安全读取示例

type EnvVars = {
  NODE_ENV: 'development' | 'production' | 'test'
  API_BASE: string
  DB_URL: string
}

const required: ReadonlyArray<keyof EnvVars> = ['NODE_ENV', 'API_BASE', 'DB_URL']

function readEnv(): EnvVars {
  const missing: string[] = []
  const env = process.env
  required.forEach((k) => {
    if (!env[k]) {
      missing.push(k)
    }
  })
  if (missing.length > 0) {
    throw new Error('Missing env: ' + missing.join(','))
  }
  return {
    NODE_ENV: env.NODE_ENV as EnvVars['NODE_ENV'],
    API_BASE: env.API_BASE as string,
    DB_URL: env.DB_URL as string,
  }
}

const cfg = readEnv()

密钥轮换

• 定期更新：每季度轮换关键密钥；高风险密钥更频繁。
• 版本管理：密钥以标签标识版本，旧版本短时间保留以支持平滑切换。
• 自动化：CI/CD 在部署前拉取最新密钥；发布后验证连接可用。

生产环境密钥：云服务商的密钥管理

• 在云侧创建密钥，配置访问策略（最小权限），仅允许特定服务读取。
• 应用启动时动态注入密钥，避免在镜像与代码中存储明文。
• 审计与告警：读取事件记录在案；异常访问触发告警。

AI 协作指南

• 核心意图：让 AI 生成环境变量规范与轮换流程，并输出 PowerShell 命令。
• 需求定义公式：
  • “为生产环境设计环境变量与密钥注入流程，包含 .gitignore 规则与轮换策略，输出 PowerShell 命令。”
• 关键术语：env, Secrets Manager, Key Vault, 轮换, 最小权限。

避坑指南

• 不要把密钥放到 .env.development 或任何共享文件；只在 .env.local 或云密钥服务中保存。
• 不要在日志中打印 process.env；必要信息做遮罩处理。