EnterpriseArchitect/services/nvidia_sidecar

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	冷却最大时长 (秒)

存储

• SQLite (WAL 模式)
• 表：backends, backend_usage_logs, cooldown_events, backend_health, system_config, daily_stats