managing-secrets

管理密钥

为应用和基础设施安全地存储、轮换和交付密钥（API 密钥、数据库凭据、TLS 证书）。

何时使用此技能

在以下情况下使用：

• 存储 API 密钥、数据库凭据或加密密钥
• 实施密钥轮换（手动或自动）
• 将外部存储中的密钥同步到 Kubernetes
• 设置动态密钥（数据库、云提供商）
• 扫描代码以查找泄露的密钥
• 实施零知识模式
• 满足合规要求（SOC 2、ISO 27001、PCI DSS）

快速决策框架

框架 1：选择密钥存储

场景	首选方案	替代方案
Kubernetes + 多云	Vault + ESO	Cloud Secret Manager + ESO
Kubernetes + 单云	Cloud Secret Manager + ESO	Vault + ESO
无服务器（AWS Lambda）	AWS Secrets Manager	AWS Parameter Store
多云企业	HashiCorp Vault	Doppler (SaaS)
小型团队（<10 个应用）	Doppler、Infisical	1Password Secrets Automation
GitOps 为中心	SOPS（git 加密）	Sealed Secrets（仅限 K8s）

决策树：

• Kubernetes？→ 使用所选后端的 External Secrets Operator (ESO)
• 单云？→ 使用云原生方案（AWS/GCP/Azure）
• 多云/本地部署？→ HashiCorp Vault
• GitOps？→ SOPS 或 Sealed Secrets

框架 2：静态密钥与动态密钥

密钥类型	使用动态密钥？	TTL	解决方案
数据库凭据	是	1 小时	Vault DB 引擎
云 IAM（AWS/GCP）	是	15 分钟	Vault 云引擎
SSH/RDP 访问	是	5 分钟	Vault SSH 引擎
TLS 证书	是	24 小时	Vault PKI / cert-manager
第三方 API 密钥	否	每季度	Vault KV v2（手动轮换）

框架 3：Kubernetes 密钥交付

方法	使用场景	轮换	是否需要重启
External Secrets Operator	静态密钥、定期同步	轮询（1 小时）	是
Secrets Store CSI Driver	基于文件、监视轮换	inotify	否
Vault Secrets Operator	Vault 专用、动态密钥	自动续期	可选

HashiCorp Vault 基础知识

核心组件

• 密钥引擎：KV v2（静态）、Database（动态）、AWS、PKI、SSH
• 身份验证方法：Kubernetes、JWT/OIDC、AppRole、LDAP
• 策略：基于 HCL 的访问控制（最小权限）
• 租约：密钥 TTL、自动续期、自动撤销

静态密钥（KV v2）

# Create secret
vault kv put secret/myapp/config api_key=sk_live_EXAMPLE

# Read secret
vault kv get secret/myapp/config

# List versions
vault kv metadata get secret/myapp/config

动态数据库凭据

# Configure PostgreSQL
vault write database/config/postgres \
  plugin_name=postgresql-database-plugin \
  connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb"

# Create role
vault write database/roles/app-role \
  db_name=postgres \
  creation_statements="CREATE ROLE \"{{name}}\"..." \
  default_ttl="1h"

# Generate credentials
vault read database/creds/app-role

有关 Vault 架构的详细信息，请参阅 references/vault-architecture.md。

Kubernetes 集成

External Secrets Operator (ESO)

将 30 多个提供商的密钥同步到 Kubernetes Secrets。

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      auth:
        kubernetes:
          role: "app-role"

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
  target:
    name: db-credentials
  data:
  - secretKey: password
    remoteRef:
      key: secret/data/database/config

Vault Secrets Operator (VSO)

与 Kubernetes 原生集成的 Vault，并支持自动续期租约。

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  name: postgres-creds
spec:
  vaultAuthRef: vault-auth
  mount: database
  path: creds/app-role
  renewalPercent: 67  # Renew at 67% of TTL
  destination:
    name: dynamic-db-creds

有关 ESO、CSI 和 VSO 的比较，请参阅 references/kubernetes-integration.md。

密钥轮换模式

模式 1：版本化静态密钥（蓝绿）

1. 在 Vault 中创建新的密钥版本
2. 更新预发布环境
3. 监控错误（24–48 小时）
4. 逐步发布到生产环境（10% → 50% → 100%）
5. 撤销旧密钥（7 天后）

模式 2：动态数据库凭据

Vault 自动生成 TTL 较短的凭据：

• 应用从 Vault 获取凭据
• Vault 自动续期租约（达到 TTL 的 67% 时）
• 到期时，Vault 撤销访问权限
• 续期失败时，应用请求新凭据

模式 3：TLS 证书轮换

使用 cert-manager + Vault PKI：

• cert-manager 向 Vault 请求证书
• 到期前自动续期（默认：有效期的 67%）
• 续期时更新 Kubernetes Secret
• 可选择重启 Pod（通过 Reloader）

有关轮换工作流的详细信息，请参阅 references/rotation-patterns.md。

多语言集成

Python (hvac)

import hvac

client = hvac.Client(url='https://vault.example.com')
client.auth.kubernetes(role='app-role', jwt=jwt)

# Fetch dynamic credentials
response = client.secrets.database.generate_credentials(name='postgres-role')
username = response['data']['username']
password = response['data']['password']

Go (Vault API)

import vault "github.com/hashicorp/vault/api"

client, _ := vault.NewClient(vault.DefaultConfig())
k8sAuth, _ := auth.NewKubernetesAuth("app-role")
client.Auth().Login(context.Background(), k8sAuth)

secret, _ := client.Logical().Read("database/creds/postgres-role")

TypeScript (node-vault)

import vault from 'node-vault';

const client = vault({ endpoint: 'https://vault.example.com' });
await client.kubernetesLogin({ role: 'app-role', jwt });

const response = await client.read('database/creds/postgres-role');

完整示例请参见 examples/dynamic-db-credentials/。

密钥扫描

提交前钩子（Gitleaks）

# Install Gitleaks
brew install gitleaks

# Run on staged files
gitleaks protect --staged --verbose

提交前钩子可防止密钥被提交。 设置方法请参见 examples/secret-scanning/pre-commit。

CI/CD 集成

# GitHub Actions
- name: Run Gitleaks
  uses: gitleaks/gitleaks-action@v2

补救工作流

密钥泄露时：

1. 立即轮换（1 小时内）
2. 在提供方处撤销
3. 从 Git 历史记录中删除（BFG Repo-Cleaner）
4. 强制推送（通知团队）
5. 审计访问情况（泄露期间哪些人曾有访问权限）
6. 记录事件

详细的补救方法请参见 references/secret-scanning.md。

零知识模式

客户端加密（E2EE）

用户密码 → PBKDF2 → 加密密钥 → 加密密钥内容 → 发送到服务端

服务端只存储加密后的数据块（无法解密）。

Shamir 秘密共享

将密钥拆分为 N 份，至少需要 M 份才能还原（例如，5 份中需要 3 份）。

# Initialize Vault with Shamir shares
vault operator init -key-shares=5 -key-threshold=3

# Unseal requires 3 of 5 key shares
vault operator unseal <KEY_1>
vault operator unseal <KEY_2>
vault operator unseal <KEY_3>

实现方法请参见 references/zero-knowledge.md。

库推荐（2025）

密钥存储

库	用例	信任评分
HashiCorp Vault	企业、多云	高（73.3/100）
External Secrets Operator	Kubernetes 集成	高（85.0/100）
AWS Secrets Manager	AWS 工作负载	高
GCP Secret Manager	GCP 工作负载	高
Azure Key Vault	Azure 工作负载	高

密钥扫描

库	用例	信任评分
Gitleaks	提交前、CI/CD	高（89.9/100）
TruffleHog	Git 历史记录扫描	中

客户端库

语言	库	版本
Python	hvac	2.2.0+
Go	vault/api	最新
TypeScript	node-vault	0.10.2+
Rust	vaultrs	0.7+

常见工作流

工作流 1：在 Kubernetes 上使用 Vault + ESO

1. 安装 Vault（Helm chart）
2. 初始化并解封 Vault
3. 启用 Kubernetes 身份验证
4. 安装 External Secrets Operator
5. 创建 SecretStore（Vault 连接）
6. 创建 ExternalSecret（密钥映射）

分步指南请参见 examples/vault-eso-setup/。

工作流 2：动态数据库凭据

1. 启用数据库密钥引擎
2. 配置数据库连接
3. 创建带有 TTL 的角色
4. 应用获取凭据
5. Vault 自动续租

实现方法请参见 examples/dynamic-db-credentials/。

工作流 3：密钥扫描补救

1. Gitleaks 检测到密钥
2. 阻止提交（提交前钩子）
3. 开发者移除密钥
4. 开发者将密钥存储在 Vault 中
5. 开发者引用 Vault 路径

设置方法请参见 examples/secret-scanning/。

与相关技能集成

• auth-security：OAuth 客户端密钥、JWT 签名密钥
• databases-*：动态数据库凭据
• deploying-applications：容器注册表凭据
• observability：Grafana/Datadog API 密钥
• infrastructure-as-code：云提供商凭据

安全最佳实践

1. 切勿将密钥提交到 Git（使用 Gitleaks 提交前钩子）
2. 尽可能使用动态密钥
3. 定期轮换密钥（静态密钥每季度轮换，动态密钥每小时轮换）
4. 实施最小权限原则（Vault 策略、RBAC）
5. 启用审计日志
6. 静态加密（Vault 存储、etcd 加密）
7. 使用较短的 TTL（动态密钥少于 24 小时）
8. 监控失败的访问尝试

常见问题

环境变量中的密钥

环境变量可在进程列表中查看。 **解决方案：**使用基于文件的密钥（Kubernetes 卷、CSI 驱动程序）。

清单中硬编码的密钥

Base64 不是加密。 **解决方案：**使用 External Secrets Operator。

不轮换密钥

过期凭据会增加泄露风险。 **解决方案：**使用动态密钥或自动轮换。

生产环境中的 Root Token

权限不受限制。 **解决方案：**使用具有最小权限策略的身份验证方法。

详细信息请参阅

• references/vault-architecture.md - Vault 内部机制、高可用设置和策略
• references/kubernetes-integration.md - ESO、CSI 驱动程序和 VSO 对比
• references/rotation-patterns.md - 详细的轮换工作流
• references/secret-scanning.md - Gitleaks 和修复流程
• references/zero-knowledge.md - E2EE、Shamir 秘密共享
• references/cloud-providers.md - AWS、GCP、Azure 密钥管理器
• examples/vault-eso-setup/ - 完整的 Kubernetes 设置
• examples/dynamic-db-credentials/ - 多语言示例
• examples/secret-scanning/ - 预提交钩子、CI/CD
• scripts/setup_vault.sh - 自动安装 Vault