Claude Relay Service API 完整文档 (v2.0)

概述

Claude Relay Service 是一个高性能的 Claude API 转发服务，提供用户管理、API Key 管理、积分系统等功能。采用统一的AdminController架构，提供完整的管理功能。

架构特点

统一管理控制器: 所有管理API现在使用统一的 AdminController 实例
模块化设计: 按功能分组的清晰架构（用户套餐、API Key、缓存、系统管理）
响应格式优化: 统一的成功/错误响应格式
高性能转发: 三级缓存机制，支持流式和非流式请求

认证方式

Claude API Routes: 使用 FastAPIKeyAuth 中间件进行 API Key 认证
- Header: Authorization: Bearer {api_key}
Management API Routes: 使用 AdminAPIAuth 中间件进行管理员 API Key 认证
- Header: Authorization: Bearer {admin_api_key}
Health Routes: 无需认证

通用响应格式

所有管理API接口遵循统一的响应格式：

成功响应:

{
  "success": true,
  "data": {}
}

分页响应:

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

错误响应:

{
  "success": false,
  "message": "错误信息"
}

1. Claude API 标准路由组 `/v1`

1.1 发送消息

路径: POST /v1/messages
描述: Claude API 核心转发接口，与官方 API 完全兼容
认证: 需要 API Key
控制器: controller.RelayMessages

请求参数:

{
  "model": "claude-3-sonnet-20240229",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, Claude!"
    }
  ],
  "stream": false,
  "temperature": 0.7
}

响应格式 (非流式):

{
  "id": "msg_01234567890abcdef",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-3-sonnet-20240229",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 25
  }
}

错误响应:

{
  "error": {
    "type": "authentication_error|invalid_request_error|api_error",
    "message": "错误描述信息"
  }
}

1.2 获取模型列表

路径: GET /v1/models
描述: 获取可用的 Claude 模型列表
认证: 需要 API Key
控制器: controller.GetModels

响应格式:

{
  "success": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "claude-3-sonnet-20240229",
        "object": "model",
        "created": 1677610602,
        "owned_by": "anthropic"
      },
      {
        "id": "claude-3-opus-20240229",
        "object": "model",
        "created": 1677610602,
        "owned_by": "anthropic"
      },
      {
        "id": "claude-3-haiku-20240307",
        "object": "model",
        "created": 1677610602,
        "owned_by": "anthropic"
      }
    ]
  }
}

2. 管理API路由组 `/api` (AdminController)

所有管理API现在使用统一的AdminController，提供更好的代码组织和维护性。

2.1 🔑 用户套餐管理

2.1.1 创建或更新用户套餐

路径: PUT /api/users/{userId}/plan
描述: 为指定用户创建或更新套餐信息
认证: 需要管理员 API Key
控制器: AdminController.CreateOrUpdateUserPlan

请求参数:

{
  "plan_name": "高级套餐",
  "credit_limit": 100000,
  "credit_recovery": 1000,
  "duration_days": 30
}

字段说明:

plan_name (string, required): 套餐名称，1-100字符
credit_limit (int64, required): 积分上限，不能为负
credit_recovery (int64, optional): 每日积分恢复数量，不能为负
duration_days (int, required): 有效期天数，1-3650天

响应格式:

{
  "success": true,
  "data": {
    "user_id": 123,
    "plan_name": "高级套餐",
    "credit_limit": 100000,
    "used_credits": 0,
    "available_credits": 100000,
    "credit_recovery": 1000,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T00:00:00Z",
    "status": "active",
    "operation": "created"
  }
}

2.1.2 查询用户套餐信息

路径: GET /api/users/{userId}/plan
描述: 获取指定用户的套餐详细信息
认证: 需要管理员 API Key
控制器: AdminController.GetUserPlan

响应格式:

{
  "success": true,
  "data": {
    "user_id": 123,
    "plan_name": "高级套餐",
    "credit_limit": 100000,
    "used_credits": 15000,
    "available_credits": 85000,
    "credit_recovery": 1000,
    "last_recharge_at": "2025-08-07T09:00:01Z",
    "status": "active",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T00:00:00Z",
    "recovery_enabled": true
  }
}

2.1.3 调整用户积分

路径: POST /api/users/{userId}/credits/adjust
描述: 调整指定用户的积分余额
认证: 需要管理员 API Key
控制器: AdminController.AdjustUserCredits

请求参数:

{
  "amount": 5000,
  "description": "充值",
  "type": "refund"
}

字段说明:

amount (int64, required): 调整金额，正数为充值，负数为扣减
description (string, required): 调整描述，1-500字符
type (string, required): 调整类型，可选值：consume(消费), refund(退款), adjustment(调整)

响应格式:

{
  "success": true,
  "data": {
    "user_id": 123,
    "adjustment_amount": 5000,
    "new_balance": 90000,
    "type": "refund",
    "description": "充值"
  }
}

2.2 🔐 API Key 管理

2.2.1 为用户创建 API Key

路径: POST /api/users/{userId}/keys
描述: 为指定用户生成新的 API Key
认证: 需要管理员 API Key
控制器: AdminController.CreateAPIKey

请求参数:

{
  "name": "My API Key",
  "expires_days": 30
}

字段说明:

name (string, required): API Key名称，1-100字符
expires_days (int, optional): 过期天数，1-3650天，不提供则永不过期

响应格式:

{
  "success": true,
  "data": {
    "id": 456,
    "user_id": 123,
    "name": "My API Key",
    "key_value": "sk-ant-sid01-abc123...",
    "prefix": "sk-ant-sid01",
    "status": "active",
    "expires_at": "2024-01-31T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

重要: key_value 字段只在创建时返回一次，请妥善保存

2.2.2 查询用户 API Keys

路径: GET /api/users/{userId}/keys
描述: 获取指定用户的所有 API Key 列表
认证: 需要管理员 API Key
控制器: AdminController.GetUserAPIKeys

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "My API Key",
      "prefix": "sk-ant-sid01",
      "status": "active",
      "last_used_at": "2024-01-15T10:30:00Z",
      "last_used_ip": "192.168.1.100",
      "expires_at": "2024-01-31T00:00:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

注意: 出于安全考虑，不返回完整的 key_value

2.2.3 更新 API Key 状态

路径: PUT /api/keys/{keyId}/status
描述: 更新指定 API Key 的状态（启用/禁用）
认证: 需要管理员 API Key
控制器: AdminController.UpdateAPIKeyStatus

请求参数:

{
  "status": "active"
}

字段说明:

status (string, required): 状态，可选值：active(活跃), inactive(禁用), revoked(已撤销)

响应格式:

{
  "success": true,
  "data": {
    "key_id": 456,
    "new_status": "active",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

2.2.4 删除 API Key

路径: DELETE /api/keys/{keyId}
描述: 删除指定的 API Key
认证: 需要管理员 API Key
控制器: AdminController.DeleteAPIKey

响应格式:

{
  "success": true,
  "data": {
    "key_id": 456,
    "deleted": true,
    "deleted_at": "2024-01-15T10:30:00Z"
  }
}

2.3 📊 积分历史和统计

2.3.1 用户积分明细

路径: GET /api/users/{userId}/credits/history
描述: 获取指定用户的积分使用历史记录
认证: 需要管理员 API Key
控制器: AdminController.GetCreditsHistory

查询参数:

page (int, optional): 页码，默认1
limit (int, optional): 每页数量，默认20，最大100
type (string, optional): 积分类型过滤

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 789,
      "type": "consume",
      "amount": -150,
      "balance_after": 84850,
      "description": "API调用 - claude-3-sonnet-20240229",
      "reference_type": "api_usage",
      "reference_id": "101",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50
  }
}

2.3.2 用户使用统计

路径: GET /api/users/{userId}/usage/stats
描述: 获取指定用户的API使用统计信息
认证: 需要管理员 API Key
控制器: AdminController.GetUsageStats

查询参数:

days (int, optional): 统计天数，默认30，最大365

响应格式:

{
  "success": true,
  "data": {
    "total_requests": 150,
    "total_tokens": 75000,
    "total_credits_cost": 15000,
    "average_request_time": 850,
    "model_usage": {
      "claude-3-sonnet-20240229": 100,
      "claude-3-haiku-20240307": 50
    },
    "daily_stats": [
      {
        "date": "2024-01-15",
        "requests": 25,
        "tokens": 12500,
        "credits_cost": 2500
      }
    ]
  }
}

2.4 📈 新增：仪表盘/余额/图表联动接口

2.4.1 仪表盘聚合

路径: GET /api/users/{userId}/dashboard
描述: 返回“当前订阅/余额卡片 + 今日汇总 + 今日请求列表”
认证: 需要管理员 API Key
控制器: AdminController.GetUserDashboard

响应示例:

{
  "success": true,
  "data": {
    "subscription": {
      "user_id": 123,
      "plan_name": "基础月付",
      "credit_limit": 5400,
      "used_credits": 2160,
      "available_credits": 3240,
      "credit_recovery_per_hour": 100,
      "status": "active",
      "start_date": "2025-08-01T00:00:00Z",
      "end_date": "2025-09-10T00:00:00Z",
      "recovery_enabled": true,
      "last_recharge_at": "2025-08-07T09:00:01Z"
    },
    "today_summary": {
      "requests": 300,
      "credits_consumed": 4040,
      "credits_recharged": 800,
      "since": "2025-08-07T00:00:00+08:00",
      "until": "2025-08-07T16:30:00+08:00"
    },
    "today_requests": [
      {
        "id": 10001,
        "time": "2025-08-07T16:00:00+08:00",
        "model": "claude-sonnet-4-20250514",
        "credits_cost": 10,
        "status": "success",
        "api_key_id": 555
      }
    ]
  }
}

说明:

今日按自然日统计（created_at >= CURDATE()）
last_recharge_at 来自 user_credits 最近 amount>0 记录

2.4.2 余额卡片

路径: GET /api/users/{userId}/balance
描述: 单独返回余额卡片数据
认证: 需要管理员 API Key
控制器: AdminController.GetUserBalance

响应示例:

{
  "success": true,
  "data": {
    "user_id": 123,
    "plan_name": "基础月付",
    "credit_limit": 5400,
    "used_credits": 2160,
    "available_credits": 3240,
    "credit_recovery_per_hour": 100,
    "status": "active",
    "start_date": "2025-08-01T00:00:00Z",
    "end_date": "2025-09-10T00:00:00Z",
    "last_recharge_at": "2025-08-07T09:00:01Z"
  }
}

2.4.3 图表 + 明细联动（每小时聚合）

路径: GET /api/users/{userId}/credits/analytics
描述: 在时间区间内返回每小时的“使用/补充/净变化”以及同一区间的积分明细（分页）
认证: 需要管理员 API Key
控制器: AdminController.GetCreditsAnalytics

查询参数:

start (string, required): YYYY-MM-DD HH:MM:SS，例如 2025-08-08 12:00:00
end (string, required): YYYY-MM-DD HH:MM:SS，需大于 start
tz (string, optional): 时区，默认 Asia/Shanghai
page (int, optional): 明细页码，默认 1
limit (int, optional): 明细每页数量，默认 20，最大 100
order (string, optional): asc|desc，默认 desc
type (string, optional): 明细类型过滤，consume|purchase|recovery|refund|reward|adjustment|all，默认 all

成功返回:

{
  "success": true,
  "data": {
    "meta": {
      "start": "2025-08-08T12:00:00+08:00",
      "end": "2025-08-09T11:00:00+08:00",
      "interval": "hour",
      "timezone": "Asia/Shanghai",
      "bucket_count": 23
    },
    "summary": {
      "consumed": 1720,
      "recharged": 1820,
      "net_change": 100
    },
    "series": [
      {
        "ts": "2025-08-08T12:00:00+08:00",
        "consumed": 12,
        "recharged": 0,
        "net_change": -12
      }
    ],
    "history": {
      "page": 1,
      "limit": 20,
      "total": 73,
      "records": [
        {
          "id": 98765,
          "time": "2025-08-08T13:12:39+08:00",
          "type": "consume",
          "amount": -2,
          "balance_after": 5398,
          "description": "使用了2积分 - Model: claude-sonnet-4-20250514 ...",
          "reference_type": "api_usage",
          "reference_id": 555
        }
      ]
    }
  }
}

图表口径:

区间 [start, end)，按 tz 对齐到整点；每小时一个桶，空桶补 0
consumed = SUM(-amount WHERE amount < 0)
recharged = SUM(amount WHERE amount > 0)
net_change = recharged - consumed

明细口径:

过滤：user_id = ? AND created_at >= start AND created_at < end
type != all 时，对明细增加 WHERE type = ?（不影响图表）
排序/分页：order + page/limit

错误码与边界:

400：缺少 start/end、时间格式错误、end <= start、跨度超过 90 天
200 且 series 全 0：区间内无记录
200 且 history.total = 0：区间无明细

性能与缓存:

图表聚合启用 Redis 缓存：analytics:{userId}:{start_unix}:{end_unix}:{tz}，TTL 60s
明细不缓存（受分页与类型影响），依赖索引 (user_id, created_at)

2.4 🔄 批量查询接口

2.4.1 批量查询用户状态

路径: POST /api/users/batch-status
描述: 批量查询多个用户的状态信息，专为Java系统优化
认证: 需要管理员 API Key
控制器: AdminController.BatchUserStatus

请求参数:

{
  "user_ids": [123, 456, 789]
}

字段说明:

user_ids (array[int64], required): 用户ID列表，最多100个

响应格式:

{
  "success": true,
  "data": [
    {
      "user_id": 123,
      "plan_status": "active",
      "credit_limit": 100000,
      "used_credits": 15000,
      "available_credits": 85000,
      "api_keys_count": 2,
      "last_activity": "2024-01-15T10:30:00Z"
    }
  ]
}

2.5 🔥 缓存管理接口

2.5.1 用户缓存失效

路径: POST /api/cache/invalidate/user/{userId}
描述: 使指定用户的缓存失效，Java系统调用
认证: 需要管理员 API Key
控制器: AdminController.InvalidateUserCache

响应格式:

{
  "success": true,
  "data": {
    "user_id": 123,
    "cleared": ["auth_cache", "credit_cache"],
    "message": "用户缓存清理成功"
  }
}

2.5.2 API Key缓存失效

路径: POST /api/cache/invalidate/apikey
描述: 使API Key相关缓存失效
认证: 需要管理员 API Key
控制器: AdminController.InvalidateAPIKeyCache

请求参数:

{
  "api_key": "sk-ant-sid01-abc123..."
}

字段说明:

api_key (string, required): 需要清理缓存的API Key，32-128字符

响应格式:

{
  "success": true,
  "data": {
    "api_key_prefix": "sk-ant-sid01-abc1...",
    "message": "API Key缓存清理成功"
  }
}

2.5.3 缓存统计信息

路径: GET /api/cache/stats
描述: 获取系统缓存的统计信息
认证: 需要管理员 API Key
控制器: AdminController.GetCacheStats

响应格式:

{
  "success": true,
  "data": {
    "cache_type": "multi_level",
    "l1_cache": "memory_auth_cache",
    "l2_cache": "redis_credit_cache",
    "features": [
      "redis_pubsub_invalidation",
      "auto_expiration",
      "cache_penetration_protection"
    ]
  }
}

2.6 🖥️ 系统管理接口

2.6.1 积分恢复状态

路径: GET /api/system/recovery/status
描述: 查询系统积分恢复的状态信息（内部调用）
认证: 需要管理员 API Key
控制器: AdminController.GetSystemRecoveryStatus

响应格式:

{
  "success": true,
  "data": {
    "pending_recovery_users": 10,
    "last_recovery_at": "2024-01-15T00:00:00Z",
    "next_recovery_at": "2024-01-16T00:00:00Z",
    "system_status": "healthy"
  }
}

2.6.2 手动触发积分恢复 🆕

路径: POST /api/system/recovery/trigger
描述: 手动触发积分恢复任务（管理员接口）
认证: 需要管理员 API Key
控制器: AdminController.TriggerCreditRecovery

响应格式:

{
  "success": true,
  "data": {
    "message": "积分恢复执行成功",
    "recovered_users": 5,
    "trigger_by": "admin"
  }
}

功能说明:

立即执行积分恢复任务，无需等待定时任务
返回实际恢复的用户数量
适用于紧急情况或测试场景

3. 健康检查路由

3.1 健康检查

路径: GET /health
描述: 系统健康检查端点，用于监控服务状态
认证: 无需认证
控制器: controller.Health

响应格式:

{
  "success": true,
  "message": "服务正常运行",
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-15 10:30:00"
  }
}

错误码说明

HTTP状态码

200 - 请求成功
400 - 请求参数错误
401 - 认证失败
403 - 权限不足
404 - 资源不存在
500 - 服务器内部错误

业务错误类型

authentication_error - 认证错误
invalid_request_error - 请求参数错误
api_error - API调用错误
insufficient_credits - 积分不足

中间件说明

PanicRecover: Panic恢复中间件，确保服务稳定性
CORS: 跨域资源共享中间件
RequestLogger: 请求日志记录中间件
ErrorHandler: 统一错误处理中间件
FastAPIKeyAuth: 高性能API Key认证（用于Claude API路由）
AdminAPIAuth: 管理员API Key认证（用于管理API路由）

技术栈与特性

核心技术

框架: GoFrame (gf/v2)
路由: ghttp.Server
架构: 分层架构（Controller-Service-DAO）
缓存: Redis + 内存双级缓存
数据库: MySQL/PostgreSQL

主要特性

高性能转发: 三级缓存机制，毫秒级响应
积分管理系统: 自动积分恢复，精确计费
统一管理架构: AdminController统一管理所有管理功能
安全认证: 双重API Key认证机制
实时监控: 完整的使用统计和健康检查
批量操作: 优化的批量查询接口

性能优化

缓存策略: 多级缓存避免数据库压力
异步处理: 计费和统计异步处理
连接池: 数据库连接池优化
流式支持: 支持Claude API流式响应

更新日志

v2.0 主要更新

统一控制器架构: 采用AdminController统一管理所有管理API
新增接口: 手动触发积分恢复功能 (POST /api/system/recovery/trigger)
响应格式优化: 统一的分页和错误响应格式
代码结构重构: 更清晰的模块化设计和注释
功能增强: 积分恢复系统初始化优化

API_Documentation_v2.md 20 KB Постоянна връзка История Директен файл

Claude Relay Service API 完整文档 (v2.0)

概述

架构特点

认证方式

通用响应格式

1. Claude API 标准路由组 /v1

1.1 发送消息

1.2 获取模型列表

2. 管理API路由组 /api (AdminController)

2.1 🔑 用户套餐管理

2.1.1 创建或更新用户套餐

2.1.2 查询用户套餐信息

2.1.3 调整用户积分

2.2 🔐 API Key 管理

2.2.1 为用户创建 API Key

2.2.2 查询用户 API Keys

2.2.3 更新 API Key 状态

2.2.4 删除 API Key

2.3 📊 积分历史和统计

2.3.1 用户积分明细

2.3.2 用户使用统计

2.4 📈 新增：仪表盘/余额/图表联动接口

2.4.1 仪表盘聚合

2.4.2 余额卡片

2.4.3 图表 + 明细联动（每小时聚合）

2.4 🔄 批量查询接口

2.4.1 批量查询用户状态

2.5 🔥 缓存管理接口

2.5.1 用户缓存失效

2.5.2 API Key缓存失效

2.5.3 缓存统计信息

2.6 🖥️ 系统管理接口

2.6.1 积分恢复状态

2.6.2 手动触发积分恢复 🆕

3. 健康检查路由

3.1 健康检查

错误码说明

HTTP状态码

业务错误类型

中间件说明

技术栈与特性

核心技术

主要特性

性能优化

更新日志

v2.0 主要更新

API_Documentation_v2.md 20 KB

Постоянна връзка История Директен файл

1. Claude API 标准路由组 `/v1`

2. 管理API路由组 `/api` (AdminController)