vincent
376ce97d91
When all primary backends are in cooldown, wait and retry the primary pool before falling through to fallback/emergency. This reduces unnecessary spend on paid fallback providers during temporary 429 storms. Config: - primary_wait_ms (default 5000, env SIDECAR_PRIMARY_WAIT_MS) - primary_wait_max_retries (default 6, env SIDECAR_PRIMARY_WAIT_MAX_RETRIES) Implementation: - config.py: 2 new config fields + env var loading - router.py: pick_primary_backend() — primary-pool-only selection - proxy.py: primary-wait loop between standard retries and emergency Expected win: 17% error rate during high concurrency drops, emergency passthrough count falls as requests wait for NVIDIA pool recovery instead of immediately routing to SiliconFlow fallback.
Sidecar V2 — Multi-Pool Provider Proxy
概述
Sidecar V2 是 OpenClaw 的 API 代理服务，实现多 Provider 池管理、负载均衡、429 冷却、RPM 队列控流。
核心功能
- Provider 池管理：主池 (primary) + 备用池 (fallback)，支持动态增删 Provider
- 429 冷却：检测 429 → 自动冷却 → 指数退避 → 自动恢复
- 按 Provider 独立 RPM 限流：每个 Provider 独立的 Token Bucket
- 路由策略：主池优先 → 备用池兜底 → 全部耗尽返 503
- WebUI 管理：Dashboard 仪表盘 + Provider CRUD
- 用量统计：Token 用量 + 费用统计 + 每小时/每日聚合
- API Key 加密：AES-256-GCM 加密存储
架构
OpenClaw → Sidecar V2 (port 9190) → 路由 → 主池 Provider 1,2,3...
↘ 备池 Provider 4,5...
↘ 全部耗尽 → 503
快速开始
# 设置加密密钥 (64位十六进制)
export SIDECAR_ENCRYPTION_KEY="0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff"
# 启动服务
python3 main.py
# OR via uvicorn
python3 -m uvicorn server:app --host 127.0.0.1 --port 9190
WebUI
访问 http://127.0.0.1:9190/dashboard
API 端点
Admin API
GET /api/admin/backends— 列出所有 ProviderPOST /api/admin/backends— 添加 ProviderPUT /api/admin/backends/{id}— 更新 ProviderDELETE /api/admin/backends/{id}— 删除 ProviderGET /api/admin/pools— 池状态汇总GET /api/admin/stats/total— 总计统计GET /api/admin/stats/hourly— 每小时用量GET /api/admin/stats/daily— 每日聚合GET /api/admin/stats/cooldown— 冷却事件历史GET /api/admin/config— 系统配置
代理 API (OpenAI 兼容)
POST /v1/chat/completionsPOST /v1/completionsPOST /v1/embeddingsGET /v1/models
监控
GET /health— 健康检查GET /dashboard/sse— Dashboard 实时数据流 (SSE)
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| SIDECAR_HOST | 127.0.0.1 | 监听地址 |
| SIDECAR_PORT | 9190 | 监听端口 |
| SIDECAR_ENCRYPTION_KEY | (必填) | API Key 加密密钥 (64 hex chars) |
| SIDECAR_DB_PATH | ./data/sidecar_v2.db | SQLite 数据库路径 |
| SIDECAR_RATE_RPM | 40 | 默认 RPM 限制 |
| SIDECAR_COOLDOWN_BASE | 30 | 冷却基础时长 (秒) |
| SIDECAR_COOLDOWN_MAX | 600 | 冷却最大时长 (秒) |
Docker 部署
# 构建并启动
cd /home/vincent/sidecar-v2
docker compose up -d --build
# 查看日志
docker logs sidecar-v2 -f
# 重启
docker compose restart
Nginx 反向代理
# 参考 deploy/nginx-sidecar-v2.conf
# Dashboard: http://192.168.1.99:19190/dashboard
# API: http://192.168.1.99:19190/v1/chat/completions
# Health: http://192.168.1.99:19190/health
生产环境 (当前)
- 部署地址: 192.168.1.99:9190 (Docker)
- Nginx 代理: 192.168.1.99:19190
- Dashboard: http://192.168.1.99:19190/dashboard
- 5 个 NVIDIA Primary Backends
- Git 仓库: http://192.168.1.99:12299/vincent/sidecar-v2
- BIZ-50 部署任务: 严维序 (opengineer)
- 开发: 徐聪 (costcodev)
已知问题 & 待办
- 配置 Fallback 池（至少 1 个非 NVIDIA provider）
- 清理 openclaw.json 中冗余的 NVIDIA API key
- 排查无效模型 404（nemotron-70b, nemotron-340b）
- 评估 RPM limit 调整降低冷却频率
变更记录
v2.0.1 (2026-06-25) — BIZ-50 部署修复
- proxy.py: 修复路由路径重复问题 (v1/v1 → v1)
- proxy.py: 修复 _emergency_count 全局变量
- server.py: 添加 logging.basicConfig 启用 INFO 日志
v2.0.0 — 初始版本
- 多池路由、429 冷却、RPM 限流
- Dashboard + Admin API
- API Key 加密存储
存储
- SQLite (WAL 模式)
- 表：backends, backend_usage_logs, cooldown_events, backend_health, system_config, daily_stats