9728a8054f
- Implement Claude API smart router with automatic failover - Support 4 providers: Claude Pro, DeepSeek, Kimi, Claude API - Update models: DeepSeek to deepseek-reasoner, Kimi to kimi-k2 - Add AdWireGuard: WireGuard VPN + AdGuard DNS filtering - Consolidate tokens into single tokens.txt file - Add mDNS reflector to Home Assistant setup 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
238 lines
5.4 KiB
Markdown
238 lines
5.4 KiB
Markdown
# Claude Router
|
||
|
||
一个智能的Claude API路由器，支持Claude Pro和Claude API之间的自动故障转移。当Claude Pro达到使用限制时，自动切换到Claude API，确保服务的连续性。
|
||
|
||
## 功能特性
|
||
|
||
- **自动故障转移**: 检测到速率限制或使用限制时自动切换provider
|
||
- **定时健康检查**: 每小时前5分钟自动检测Claude Pro限额恢复
|
||
- **智能恢复**: 自动切换回Claude Pro，优先使用高级功能
|
||
- **手动切换**: 支持手动切换到指定provider
|
||
- **兼容Claude Code CLI**: 完全兼容Anthropic API格式
|
||
- **Docker化部署**: 一键部署，开箱即用
|
||
|
||
## 快速开始
|
||
|
||
### 1. 使用Docker Compose部署
|
||
|
||
```bash
|
||
# 克隆或进入项目目录
|
||
cd /home/will/docker/router
|
||
|
||
# 构建并启动服务
|
||
docker-compose up -d
|
||
|
||
# 查看服务状态
|
||
docker-compose ps
|
||
```
|
||
|
||
### 2. 验证服务运行
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:8000/health
|
||
|
||
# 查看当前状态
|
||
curl http://localhost:8000/v1/status
|
||
```
|
||
|
||
### 3. 配置Claude Code CLI
|
||
|
||
设置环境变量将Claude Code CLI指向路由器：
|
||
|
||
```bash
|
||
# 设置API endpoint为路由器地址
|
||
export ANTHROPIC_API_URL="http://localhost:8000"
|
||
|
||
# 添加到bashrc使其永久生效
|
||
echo 'export ANTHROPIC_API_URL="http://localhost:8000"' >> ~/.bashrc
|
||
|
||
# 测试配置
|
||
echo "Hello Claude Router" | claude --print
|
||
```
|
||
|
||
**注意**: 无需修改ANTHROPIC_API_KEY，路由器会自动处理API密钥。
|
||
|
||
## API端点
|
||
|
||
### 主要端点
|
||
|
||
- `POST /v1/messages` - Claude API消息创建（兼容Anthropic API）
|
||
- `GET /health` - 健康检查
|
||
- `GET /v1/status` - 获取路由器状态
|
||
- `POST /v1/switch-provider` - 手动切换provider
|
||
- `POST /v1/health-check` - 手动触发Claude Pro健康检查
|
||
|
||
### 健康检查响应示例
|
||
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"current_provider": "claude_pro",
|
||
"failover_count": 0,
|
||
"last_failover": null,
|
||
"last_health_check": "2025-07-14T19:00:00.000Z",
|
||
"health_check_failures": 0,
|
||
"providers": {
|
||
"claude_pro": {"active": true},
|
||
"claude_api": {"active": true}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 环境变量
|
||
|
||
- `CLAUDE_API_KEY`: Claude API密钥
|
||
- `ROUTER_HOST`: 服务监听地址（默认: 0.0.0.0）
|
||
- `ROUTER_PORT`: 服务监听端口（默认: 8000）
|
||
- `MAX_RETRIES`: 最大重试次数（默认: 3）
|
||
- `RETRY_DELAY`: 重试延迟（默认: 1.0秒）
|
||
|
||
### 健康检查配置
|
||
|
||
- `health_check_enabled`: 是否启用定时健康检查（默认: true）
|
||
- `health_check_cron`: 检查时间表达式（默认: "0-4 * * * *" - 每小时前5分钟）
|
||
- `health_check_message`: 测试消息内容（默认: "ping"）
|
||
- `health_check_model`: 使用的模型（默认: claude-3-haiku-20240307）
|
||
|
||
### Token文件
|
||
|
||
路由器会自动从 `/home/will/docker/tokens.txt` 读取API密钥，无需手动配置环境变量。
|
||
|
||
## 故障转移机制
|
||
|
||
当检测到以下错误时，路由器会自动切换到下一个可用的provider：
|
||
|
||
- 429 (Too Many Requests)
|
||
- 速率限制错误
|
||
- 使用限制达到
|
||
- "usage limit reached"相关错误
|
||
|
||
**优先级顺序**: Claude Pro → Claude API
|
||
|
||
## 使用示例
|
||
|
||
### 基本API调用
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/v1/messages \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-d '{
|
||
"model": "claude-3-sonnet-20240229",
|
||
"max_tokens": 1024,
|
||
"messages": [
|
||
{"role": "user", "content": "Hello, Claude!"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 手动切换provider
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/v1/switch-provider \
|
||
-H "Content-Type: application/json" \
|
||
-d '"claude_api"'
|
||
```
|
||
|
||
### 手动健康检查
|
||
|
||
```bash
|
||
# 立即检测Claude Pro是否可用
|
||
curl -X POST http://localhost:8000/v1/health-check
|
||
|
||
# 查看详细状态
|
||
curl http://localhost:8000/v1/status
|
||
```
|
||
|
||
## 开发和调试
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 运行应用
|
||
python app.py
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# Docker容器日志
|
||
docker-compose logs -f claude-router
|
||
|
||
# 实时日志
|
||
docker logs -f claude-router
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **服务无法启动**
|
||
- 检查tokens.txt文件是否存在且格式正确
|
||
- 确认端口8000未被占用
|
||
|
||
2. **API调用失败**
|
||
- 验证API密钥是否有效
|
||
- 检查网络连接到api.anthropic.com
|
||
|
||
3. **自动切换不工作**
|
||
- 查看日志确认错误检测逻辑
|
||
- 确认backup provider配置正确
|
||
|
||
### 监控
|
||
|
||
- 健康检查: `http://localhost:8000/health`
|
||
- 状态监控: `http://localhost:8000/v1/status`
|
||
- Docker健康检查: `docker inspect claude-router`
|
||
|
||
## 技术架构
|
||
|
||
- **框架**: FastAPI + Uvicorn
|
||
- **HTTP客户端**: httpx
|
||
- **AI库**: anthropic
|
||
- **容器化**: Docker + Docker Compose
|
||
- **配置管理**: pydantic + python-dotenv
|
||
|
||
## 版本信息
|
||
|
||
- 版本: 1.0.0 (MVP)
|
||
- Python: 3.11+
|
||
- 支持: Claude-3 系列模型
|
||
|
||
## 更新日志
|
||
|
||
### v1.1.0 (2025-07-14)
|
||
- ✅ 添加定时健康检查功能
|
||
- ✅ 每小时前5分钟自动检测Claude Pro限额恢复
|
||
- ✅ 智能自动切换回Claude Pro
|
||
- ✅ 新增手动健康检查API
|
||
- ✅ 完善日志记录和状态监控
|
||
|
||
### v1.0.0 (2025-07-14)
|
||
- ✅ 基础路由器功能
|
||
- ✅ Claude Pro到Claude API自动故障转移
|
||
- ✅ Docker容器化部署
|
||
- ✅ Claude Code CLI兼容性
|
||
|
||
## 后续开发计划
|
||
|
||
- [ ] 添加DeepSeek API支持
|
||
- [ ] 添加ChatGPT API支持
|
||
- [ ] 实现请求统计和监控面板
|
||
- [ ] 添加请求缓存功能
|
||
- [ ] 支持负载均衡
|
||
- [ ] 集成Kimi v2 API
|
||
|
||
## 许可证
|
||
|
||
MIT License |