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 — 列出所有 Provider
• POST /api/admin/backends — 添加 Provider
• PUT /api/admin/backends/{id} — 更新 Provider
• DELETE /api/admin/backends/{id} — 删除 Provider
• GET /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/completions
• POST /v1/completions
• POST /v1/embeddings
• GET /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