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

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

docs/observability/litellm-failover-activation.md

@@ -0,0 +1,29 @@
+# LiteLLM 副 key 启用计划 (Task #937)
+
+## 必要性判断
+- **必要性**: 🟡 中等(非紧急,设计已就绪)
+- **理由**: #937 failover 设计 + 沙箱已交付(commit 84d89ab),`test_litellm_failover_sandbox.py` 在沙箱跑通。但**实际启用**需要用户提供副 key。
+- **冲突**: 修改 litellm config + kill -HUP 1 会触发 litellm reload,可能瞬时影响 LLM 调用。
+
+## 当前状态(本会话交付)
+- **代码就绪**:`app/core/llm_router.py` + `test_llm_router.py` 已支持熔断 + 路由
+- **沙箱验证**:`tests/test_litellm_failover_sandbox.py` dry-run 通过
+- **运维脚本**:`litellm/apply_secondary_key.sh` + `rollback_secondary_key.sh` + `verify_failover.sh` + README
+
+## 启用流程(等用户提供副 key)
+1. 用户:向 SiliconFlow 申请副 key(用户责任,无法自动化)
+2. 在低峰期执行 `SECONDARY_API_KEY=sk-xxx ./apply_secondary_key.sh --gray=10`
+3. 观察 24h 一致率
+4. 切到 100%:`./apply_secondary_key.sh --gray=100`
+5. 验证:`./verify_failover.sh`
+
+## 不启用的代价
+- **当前可用**: 主 key 正常,实测 1-4% CPU 误判已修
+- **风险**: 主 key 限流时整个 LLM 服务中断
+- **概率**: 低(SiliconFlow 个人账户默认 1k req/min,平台日均 200 req)
+
+## 总结
+- **现在做**:运维脚本 + 文档(本会话已交付,commit 下一行)
+- **不实际启用**:等用户提供副 key
+- **执行时机**:用户给副 key 后,单次低峰期会话完成切换
+