298 lines
8.8 KiB
Markdown
298 lines
8.8 KiB
Markdown
# Fischer AgentKit — 密钥轮换 Runbook
|
||
|
||
本文档给出全部 10 个 secret slot（KTD-4 / R2a）的轮换操作流程。
|
||
所有轮换遵循「双密钥并行 → 切换 → 旧密钥退役」原则，避免服务中断。
|
||
|
||
## 通用轮换原则
|
||
|
||
1. **零停机**：新密钥生效后再淘汰旧密钥，避免单点切换失败。
|
||
2. **审计先行**：轮换前记录当前密钥指纹（hash8），轮换后校验变更。
|
||
3. **回滚预案**：保留旧密钥值至少一个轮换周期，便于快速回滚。
|
||
4. **权限最小化**：轮换操作仅限归属角色，操作全程审计日志。
|
||
5. **后端无关**：以下步骤适用于 Sealed Secrets 与 External Secrets 两种后端，
|
||
差异处单独标注。
|
||
|
||
---
|
||
|
||
## Slot 1：JWT 签名密钥（90 天）
|
||
|
||
**影响**：所有签发的 JWT access/refresh token 失效，用户需重新登录。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 生成新密钥（32 字节随机串，base64）
|
||
NEW_KEY=$(openssl rand -base64 32)
|
||
|
||
# 2) 更新密钥后端
|
||
# Sealed Secrets：
|
||
kubectl create secret generic agentkit-secrets-new --dry-run=client -o yaml \
|
||
--from-literal=jwt-signing-key="${NEW_KEY}" | \
|
||
kubeseal --controller-name=sealed-secrets --controller-namespace=kube-system \
|
||
--format yaml --merge-into agentkit-sealedsecret.yaml
|
||
# External Secrets：在 Vault/SM 中更新 agentkit/jwt-signing-key
|
||
|
||
# 3) 应用并等待同步
|
||
kubectl apply -f agentkit-sealedsecret.yaml -n agentkit
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 4) 验证
|
||
kubectl exec -n agentkit deploy/agentkit-agentkit -- \
|
||
python -c "import os; print('jwt key len:', len(os.environ['JWT_SIGNING_KEY']))"
|
||
|
||
# 5) 用户重新登录（旧 token 失效）
|
||
```
|
||
|
||
**回滚**：保留旧密钥值，若新密钥异常，恢复 SealedSecret/ExternalSecret 并 restart。
|
||
|
||
---
|
||
|
||
## Slot 2：API Key（180 天）
|
||
|
||
**影响**：使用旧 API Key 的客户端调用失败。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 生成新 API Key
|
||
NEW_KEY=$(openssl rand -hex 32)
|
||
|
||
# 2) 更新密钥后端（同 Slot 1 步骤 2，key=api-key）
|
||
|
||
# 3) 通知所有使用 API Key 的客户端更新（agentkit pair 重新生成）
|
||
|
||
# 4) 应用并 restart
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 5) 验证：用新 key 调用 /api/v1/auth/me 或 SCIM 端点
|
||
```
|
||
|
||
**回滚**：恢复旧 key 值。
|
||
|
||
---
|
||
|
||
## Slot 3：DB 凭据 / DATABASE_URL（90 天）
|
||
|
||
**影响**：数据库连接断开，需与 DBA 协同。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) DBA 在 PostgreSQL 创建新密码（或新用户）
|
||
psql -U postgres -c "ALTER USER agentkit WITH PASSWORD 'new-pg-pwd';"
|
||
|
||
# 2) 更新 DATABASE_URL（含新密码）
|
||
NEW_URL="postgresql+asyncpg://agentkit:new-pg-pwd@postgres:5432/agentkit"
|
||
|
||
# 3) 更新密钥后端（key=database-url）
|
||
|
||
# 4) restart pod（连接池重建）
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 5) 验证：触发一次 DB 操作（如 GET /api/v1/memory）
|
||
|
||
# 6) DBA 回收旧密码（确认新连接正常后）
|
||
```
|
||
|
||
**注意**：PostgreSQL `ALTER USER` 立即生效，旧连接保持直到连接池重建。
|
||
建议在低峰期操作。
|
||
|
||
**回滚**：DBA 恢复旧密码 + 恢复 DATABASE_URL。
|
||
|
||
---
|
||
|
||
## Slot 4：IDP 签名证书（365 天）
|
||
|
||
**影响**：OIDC/SAML 登录校验失败。多 IDP 时仅影响轮换的 IdP。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 从 IdP 管理后台导出新签名证书 PEM
|
||
|
||
# 2) 更新 JSON map（保留其他 IdP 证书不变）
|
||
# 例如轮换 feishu 证书：
|
||
NEW_CERTS='{"feishu":"-----BEGIN CERTIFICATE-----\n新证书\n-----END CERTIFICATE-----","azure_ad":"<原证书>"}'
|
||
|
||
# 3) 更新密钥后端（key=idp-signing-certs）
|
||
|
||
# 4) restart pod（证书热轮换不重启，但 Helm 部署需 restart 加载新 Secret）
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 5) 验证：通过该 IdP 发起一次 SSO 登录
|
||
```
|
||
|
||
**回滚**：恢复旧证书 JSON map。
|
||
|
||
---
|
||
|
||
## Slot 5：第三方 API Key / LLM providers（90 天）
|
||
|
||
**影响**：对应 provider 的 LLM 调用失败。JSON map 结构，单 provider 轮换不影响其他。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 在 provider 控制台生成新 key（DashScope / DeepSeek / OpenAI / Anthropic）
|
||
|
||
# 2) 更新 JSON map（保留其他 provider 不变）
|
||
NEW_KEYS='{"dashscope":"sk-new1","deepseek":"sk-new2","openai":"sk-old"}'
|
||
|
||
# 3) 更新密钥后端（key=third-party-api-keys）
|
||
|
||
# 4) restart pod
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 5) 验证：调用对应 provider 的模型（如 agentkit chat 发一条测试消息）
|
||
|
||
# 6) 在 provider 控制台撤销旧 key
|
||
```
|
||
|
||
**回滚**：恢复旧 key（需 provider 控制台未撤销旧 key，建议保留旧 key 一个周期）。
|
||
|
||
---
|
||
|
||
## Slot 6：TLS 服务器证书（365 天）
|
||
|
||
**影响**：Ingress TLS 终止证书过期，浏览器告警 / mTLS 客户端握手失败。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 签发新证书（cert-manager 自动续期，或手动从 CA 申请）
|
||
# cert-manager 模式：证书到期前自动续期，无需手动操作。
|
||
|
||
# 2) 若手动：更新 kubernetes.io/tls 类型 Secret
|
||
kubectl create secret tls agentkit-tls \
|
||
--cert=new.crt --key=new.key --dry-run=client -o yaml | \
|
||
kubectl apply -f - -n agentkit
|
||
|
||
# 3) Ingress controller 自动感知新证书（无需 restart）
|
||
|
||
# 4) 验证
|
||
echo | openssl s_client -connect agentkit.your-domain.com:443 -servername agentkit.your-domain.com 2>/dev/null | openssl x509 -noout -dates
|
||
```
|
||
|
||
**注意**：本 slot 不在 SealedSecret/ExternalSecret 的 encryptedData 内统一管理
|
||
（TLS Secret 类型为 `kubernetes.io/tls`，与普通 Secret 不同）。
|
||
SealedSecret 模板中登记仅用于清单追踪，实际由 cert-manager 或运维单独管理。
|
||
|
||
**回滚**：恢复旧证书 Secret。
|
||
|
||
---
|
||
|
||
## Slot 7：mTLS 客户端证书（180 天）
|
||
|
||
**影响**：与下游服务（KMS/HSM、内部 API）mTLS 握手失败。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 从内部 PKI 签发新客户端证书 + 私钥 + CA 证书
|
||
|
||
# 2) 更新密钥后端（key=mtls-client-cert，PEM 文本）
|
||
NEW_PEM="$(cat client.crt client.key ca.crt)"
|
||
|
||
# 3) 更新密钥后端
|
||
|
||
# 4) restart pod
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 5) 验证：触发一次 mTLS 调用（如 KMS 签名操作）
|
||
```
|
||
|
||
**回滚**：恢复旧 PEM。
|
||
|
||
---
|
||
|
||
## Slot 8：KMS/HSM PKCS#11 PIN（365 天）
|
||
|
||
**影响**：HSM 访问失败，密钥托管 / 签名 / 解密不可用。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) HSM 管理员通过 HSM 管理工具轮换 PIN（具体命令依 HSM 型号）
|
||
|
||
# 2) 更新密钥后端（key=kms-hsm-pin）
|
||
NEW_PIN='<new-pin>'
|
||
|
||
# 3) restart pod
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 4) 验证：触发一次 HSM 操作（如 PKCS#11 签名）
|
||
```
|
||
|
||
**注意**：HSM PIN 轮换需物理 / 管理员协同，建议提前预约维护窗口。
|
||
|
||
**回滚**：恢复旧 PIN（HSM 管理工具支持回滚 PIN）。
|
||
|
||
---
|
||
|
||
## Slot 9：OTel exporter token（90 天）
|
||
|
||
**影响**：遥测数据上报失败（trace/metrics 丢失）。服务本身不受影响。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) 在 OTel collector / 可观测性平台生成新 token
|
||
|
||
# 2) 更新密钥后端（key=otel-exporter-token，格式 'Authorization: Bearer <token>'）
|
||
NEW_TOKEN='Bearer new-otel-token'
|
||
|
||
# 3) restart pod
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 4) 验证：在 collector 端确认收到新 trace/metrics
|
||
```
|
||
|
||
**回滚**：恢复旧 token。
|
||
|
||
---
|
||
|
||
## Slot 10：Redis-PG 密码（90 天）
|
||
|
||
**影响**：Redis / PostgreSQL 连接断开。需与基础设施层协同。
|
||
|
||
**步骤**：
|
||
|
||
```bash
|
||
# 1) Redis 轮换密码
|
||
redis-cli -a '<old-redis-pwd>' CONFIG SET requirepass '<new-redis-pwd>'
|
||
|
||
# 2) PostgreSQL 轮换密码（DBA）
|
||
psql -U postgres -c "ALTER USER agentkit WITH PASSWORD 'new-pg-pwd';"
|
||
|
||
# 3) 更新密钥后端（两个 key：redis-password + postgres-password）
|
||
|
||
# 4) 更新 Redis 服务配置（若 Redis 由 docker-compose / StatefulSet 管理，
|
||
# 需同步更新 requirepass 并 restart Redis）
|
||
|
||
# 5) restart agentkit pod
|
||
kubectl rollout restart deployment/agentkit-agentkit -n agentkit
|
||
|
||
# 6) 验证
|
||
kubectl exec -n agentkit deploy/agentkit-agentkit -- \
|
||
python -c "import redis,os; redis.from_url(os.environ['REDIS_URL'],password=os.environ['REDIS_PASSWORD']).ping()"
|
||
```
|
||
|
||
**注意**：Redis `CONFIG SET requirepass` 立即生效，旧连接保持到断开。
|
||
建议低峰期操作，且 Redis 持久化配置（redis.conf）需同步更新，避免重启后失效。
|
||
|
||
**回滚**：恢复 Redis / PG 旧密码 + 恢复 Secret。
|
||
|
||
---
|
||
|
||
## 紧急轮换（泄露响应）
|
||
|
||
发生密钥泄露时，立即按以下流程处置：
|
||
|
||
1. **隔离**：撤销泄露密钥（provider 控制台 / HSM / CA）
|
||
2. **轮换**：按上述对应 slot 步骤紧急轮换
|
||
3. **审计**：检索泄露密钥的使用日志，确认无异常调用
|
||
4. **通报**：通知安全团队 + 受影响用户
|
||
5. **复盘**：记录泄露原因，加固访问控制
|
||
|
||
紧急轮换不遵循「双密钥并行」原则，直接切换到新密钥并废弃旧密钥。
|