# Sidecar V2 — API Key Encryption Rotation SOP

> 版本: v1.0 | 维护者: 严维序 (opengineer)

## 背景

Sidecar V2 使用 AES-256-GCM 加密存储所有 Provider 的 API Key。加密密钥通过 `SIDECAR_ENCRYPTION_KEY` 环境变量传入，启动时通过 `init_crypto()` 初始化。

## ⚠️ 关键警告

**更换 SIDECAR_ENCRYPTION_KEY 会导致所有已存储的 API Key 永久不可恢复！**

`crypto.py` 的 `try_decrypt_existing()` 在密钥变更时会静默返回 `None`，已有加密数据将无法解密。请在轮换密钥前执行以下步骤。

## 安全轮换步骤

### Step 1: 导出当前 API Key 明文（必须）

```bash
# 使用旧密钥启动 sidecar，通过 admin API 导出
curl -s -H "Authorization: Bearer <ADMIN_TOKEN>" \
  http://127.0.0.1:9190/api/admin/backends | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
# 注意：api_key 是 masked 的，需要重新从安全渠道获取原始 key
print(json.dumps(data, indent=2))
"
```

### Step 2: 停止服务

```bash
systemctl stop sidecar-v2
# 或
docker compose down
```

### Step 3: 备份数据库

```bash
cp /app/data/sidecar_v2.db /app/data/backups/pre-rotation-$(date +%Y%m%d_%H%M%S).db
```

### Step 4: 更新密钥

更新 `/etc/sidecar-v2/env` 或 docker `.env` 文件中的 `SIDECAR_ENCRYPTION_KEY`：

```
SIDECAR_ENCRYPTION_KEY=<new_64_hex_char_key>
```

生成新密钥：
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

### Step 5: 清空加密 Key 并重新录入

由于密钥变更后旧加密数据不可读，需要：

1. 启动服务（此时所有旧 Provider 的 API Key 不可用）
2. 通过 Admin API 重新录入所有 Provider 的 API Key：
```bash
curl -s -X PUT -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "<NEW_PLAIN_KEY>"}' \
  http://127.0.0.1:9190/api/admin/backends/<backend_id>
```

### Step 6: 验证

```bash
# 确认 Provider 状态为 healthy
curl -s http://127.0.0.1:9190/api/admin/pools
# 发送测试请求
curl -s -X POST http://127.0.0.1:9190/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"<model_name>","messages":[{"role":"user","content":"test"}],"max_tokens":5}'
```

## 应急预案

如果在密钥轮换过程中出错：

1. 恢复旧密钥环境变量
2. 恢复旧数据库备份
3. 重启服务

旧 Key 会正常工作，因为未被覆盖的数据仍然用旧密钥加密。