feat(sidecar-v2): implement multi-pool provider proxy with cooldown, rate limiting, WebUI

BIZ-52 Step3 开发实现:
- storage: backend/usage/cooldown/config CRUD with SQLite WAL
- crypto: AES-256-GCM API key encryption
- pool_manager: primary/fallback pool routing
- cooldown_manager: 429 exponential backoff cooldown
- rate_limiter: per-backend token bucket RPM control
- router: model → backend routing with pool priority
- proxy: multi-pool request forwarding with retry
- server: FastAPI admin API + OpenAI-compatible proxy + SSE
- dashboard: WebUI with provider CRUD, stats, charts

Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
2026-06-25 16:39:01 +08:00
parent 4fd89b038d
commit 611ebd11a8
19 changed files with 3034 additions and 0 deletions
+77
View File
@@ -0,0 +1,77 @@
# 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
```
## 快速开始
```bash
# 设置加密密钥 (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