# 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