docker-configs/router/README.md

Claude API Router

智能的Claude API路由器，提供自动故障转移和负载均衡功能。当主要API服务遇到限制或错误时，自动切换到备用提供商。

🚀 功能特性

• 自动故障转移: 检测到速率限制或错误时自动切换API提供商
• 多提供商支持: 支持Claude Pro、DeepSeek、Kimi
• 手动切换: 支持手动强制切换到指定提供商
• 健康检查: 自动监控和恢复主要提供商
• 完全兼容: 与Anthropic Claude API完全兼容
• 流式响应: 支持流式和非流式响应

📋 支持的提供商

按优先级排序：

1. Claude Pro - 最高优先级，首选提供商
2. DeepSeek - OpenAI兼容的备用提供商
3. Kimi - OpenAI兼容的备用提供商

🛠️ 安装和配置

1. 环境要求

cd router
pip install -r requirements.txt

2. 配置API密钥

在 /home/will/docker/tokens.txt 文件中添加以下令牌：

claude_api_key=your_claude_api_key_here
deepseek_api_key=your_deepseek_api_key_here
kimi_api_key=your_kimi_api_key_here

或者设置环境变量：

export CLAUDE_API_KEY="your_claude_api_key"
export DEEPSEEK_API_KEY="your_deepseek_api_key"
export KIMI_API_KEY="your_kimi_api_key"

3. 启动服务

# 开发模式
python app.py

# 生产模式 (使用Docker Compose)
docker-compose up -d

服务将在 http://localhost:8000 启动。

🔧 手动切换提供商

API端点

POST /v1/switch-provider
Content-Type: application/json

{
    "provider": "provider_name"
}

可用的提供商名称

• claude_pro - Claude Pro提供商 (默认)
• deepseek - DeepSeek提供商
• kimi - Kimi提供商

使用示例

curl命令

# 切换到DeepSeek
curl -X POST http://localhost:8000/v1/switch-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "deepseek"}'

# 切换到Kimi
curl -X POST http://localhost:8000/v1/switch-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "kimi"}'

# 切换回Claude Pro
curl -X POST http://localhost:8000/v1/switch-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "claude_pro"}'

Python脚本

import requests

def switch_provider(provider_name):
    """切换API提供商"""
    url = "http://localhost:8000/v1/switch-provider"
    data = {"provider": provider_name}
    
    response = requests.post(url, json=data)
    if response.status_code == 200:
        result = response.json()
        print(f"成功切换到: {result['current_provider']}")
        return True
    else:
        print(f"切换失败: {response.text}")
        return False

# 使用示例
switch_provider("deepseek")
switch_provider("kimi")
switch_provider("claude_pro")

查看当前状态

# 查看当前使用的提供商
curl http://localhost:8000/v1/health

# 响应示例
{
    "status": "healthy",
    "current_provider": "claude_pro",
    "providers": {
        "claude_pro": "available",
        "deepseek": "unknown",
        "kimi": "unknown"
    }
}

🔄 自动故障转移

路由器会自动检测以下错误并进行故障转移：

• 速率限制 (Rate limit exceeded)
• 使用配额超额 (Usage limit exceeded)
• HTTP 429错误
• 每日/月度限制达到
• 网络连接错误

故障转移流程

1. 检测到故障转移触发条件
2. 自动切换到下一个优先级提供商
3. 重试请求
4. 记录切换日志
5. 定期尝试恢复到主要提供商

🩺 健康检查和自动恢复

• 自动检查频率: 每小时的前5分钟
• 检查内容: 向Claude Pro发送测试请求
• 自动恢复: 如果Claude Pro恢复可用，自动切换回去

🔌 API兼容性

路由器完全兼容Anthropic Claude API，支持：

• 所有Claude模型 (claude-3-sonnet, claude-3-opus等)
• 流式和非流式响应
• 系统消息和用户消息
• 所有API参数 (max_tokens, temperature等)

使用示例

import requests

# 标准Claude API调用
url = "http://localhost:8000/v1/messages"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_claude_api_key"
}
data = {
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1000,
    "messages": [
        {"role": "user", "content": "Hello, Claude!"}
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

🐛 故障排除

常见问题

1. 自动切换不工作

问题: 遇到限制时不自动切换

解决方案:

# 手动切换到备用提供商
curl -X POST http://localhost:8000/v1/switch-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "deepseek"}'

2. API密钥错误

问题: 提示API密钥无效

解决方案:

1. 检查 tokens.txt 文件中的密钥格式
2. 确保密钥没有多余的空格或换行
3. 验证密钥是否有效

3. 服务无法启动

问题: 路由器启动失败

解决方案:

# 检查日志
docker-compose logs router

# 手动启动调试
cd router
python app.py

调试模式

启用详细日志：

import logging
logging.basicConfig(level=logging.DEBUG)

📊 监控和日志

日志级别

• INFO: 正常操作日志
• WARNING: 提供商切换警告
• ERROR: 错误和故障转移事件

关键日志信息

• 提供商切换事件
• API请求失败
• 健康检查结果
• 自动恢复操作

⚙️ 高级配置

自定义故障转移条件

编辑 app.py 中的 should_failover 方法：

def should_failover(self, error_message: str) -> bool:
    # 添加自定义错误检测条件
    custom_indicators = [
        "your_custom_error",
        "specific_provider_error"
    ]
    return any(indicator in error_message.lower() 
               for indicator in custom_indicators)

调整健康检查频率

修改 app.py 中的定时任务：

# 每30分钟检查一次
@scheduler.cron("*/30 * * * *")
async def health_check_claude_pro():
    # ... 健康检查逻辑

🤝 SillyTavern集成

在SillyTavern中使用此路由器：

1. API URL: http://localhost:8000/v1/messages
2. API Key: 使用你的Claude API密钥
3. 模型: 选择任何Claude模型

路由器会自动处理故障转移，对SillyTavern完全透明。

📄 许可证

MIT License

🆘 获取帮助

如果遇到问题：

1. 检查日志文件
2. 验证API密钥配置
3. 尝试手动切换提供商
4. 查看健康检查状态

需要进一步帮助请查看代码注释或联系开发者。