docker-configs/router/router/README.md

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部署

# 克隆或进入项目目录
cd /home/will/docker/router

# 构建并启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

2. 验证服务运行

# 健康检查
curl http://localhost:8000/health

# 查看当前状态
curl http://localhost:8000/v1/status

3. 配置Claude Code CLI

设置环境变量将Claude Code CLI指向路由器：

# 设置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健康检查

健康检查响应示例

{
  "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调用

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

curl -X POST http://localhost:8000/v1/switch-provider \
  -H "Content-Type: application/json" \
  -d '"claude_api"'

手动健康检查

# 立即检测Claude Pro是否可用
curl -X POST http://localhost:8000/v1/health-check

# 查看详细状态
curl http://localhost:8000/v1/status

开发和调试

本地开发

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行应用
python app.py

查看日志

# 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