129 lines
3.9 KiB
Markdown
129 lines
3.9 KiB
Markdown
# 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 | 冷却最大时长 (秒) |
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
# 构建并启动
|
||
cd /home/vincent/sidecar-v2
|
||
docker compose up -d --build
|
||
|
||
# 查看日志
|
||
docker logs sidecar-v2 -f
|
||
|
||
# 重启
|
||
docker compose restart
|
||
```
|
||
|
||
### Nginx 反向代理
|
||
|
||
```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 |