#937 LiteLLM 副 key 启用脚本 + 计划 (20260810-154721)

新增 litellm/apply_secondary_key.sh + rollback + verify + README + docs/observability/litellm-failover-activation.md. 代码层已就绪(commit 84d89ab),等用户提供 SiliconFlow 副 key 后,单次低峰会话完成切换.

litellm/README.md

@@ -0,0 +1,36 @@
+# LiteLLM 副 key 启用脚本 (Task #937)
+
+## 背景
+#937 LiteLLM 主副密钥 failover 设计 + 沙箱 已完成(commit 84d89ab)。
+代码层已具备 failover 能力,但**实际启用**需要用户提供副 API key(向 SiliconFlow 申请)。
+
+## 三个脚本
+- `apply_secondary_key.sh`: 注入副 key + 灰阶启用(默认 10%)
+- `rollback_secondary_key.sh`: 一键回滚
+- `verify_failover.sh`: 验证主副 key 都工作
+
+## 启用流程
+1. 向 SiliconFlow 申请副 key(用户责任)
+2. 在低峰期执行:
+   ```bash
+   SECONDARY_API_KEY=sk-你的副key ./apply_secondary_key.sh --gray=10
+   ```
+3. 观察 24h 一致率(目标 ≥99%)
+4. 切到 100%:`--gray=100` 重新执行
+
+## 验证
+```bash
+./verify_failover.sh
+# 期望:health 200 + primary 正常返回 + /metrics 有 failover 计数
+```
+
+## 回滚
+```bash
+./rollback_secondary_key.sh
+```
+
+## ⚠️ 风险
+- litellm 配置错误会中断所有 LLM 调用
+- 建议:先在 staging / 沙箱验证 → 再灰阶 10% → 24h 一致率 → 100%
+- 当前 sandbox 测试:test_litellm_failover_sandbox.py 在容器内 dry-run 通过
+