English | 中文

Claude Code Hub

🚀 智能 AI API 代理中转服务平台｜面向团队的多供应商统一接入、弹性调度与精细化运营中心

Claude Code Hub 通过 Next.js 15 + Hono + PostgreSQL + Redis 组合，实现 Claude/OpenAI 兼容 API 代理、智能负载均衡、实时监控、价格管理与自动化文档，帮助团队安全、可观测地管理多家 AI 服务商。

💬 加入讨论：有部署、功能或技术问题？欢迎加入 *** 交流群 与社区一起讨论！

DING113CCH

WITHCCH

✨ 核心功能 Highlights

• 🤖 智能负载均衡：权重 + 优先级 + 分组调度，内置熔断保护与最多 3 次故障转移，保障请求稳定。
• 🧩 多供应商管理：同时接入 Claude、Codex、Gemini CLI、OpenAI Compatible，自定义模型重定向与 HTTP/HTTPS/SOCKS 代理。
• 🛡️ 限流与并发控制：RPM、金额（5 小时/周/月）、并发 Session 多维限制，Redis Lua 脚本确保原子性与 Fail-Open 降级。
• 📘 自动化 OpenAPI 文档：39 个 REST 端点由 Server Actions 自动生成 OpenAPI 3.1.0，Swagger + Scalar UI 双界面即刻试用。
• 📊 实时监控与统计：仪表盘、活跃 Session、消耗排行榜、决策链记录、代理状态追踪，秒级掌控运行态势。
• 💰 价格表管理：分页查询 + SQL 优化，支持搜索防抖、LiteLLM 同步，千级模型也能快速检索。
• 🔁 Session 管理：5 分钟上下文缓存，记录决策链，避免频繁切换供应商并保留全链路审计。
• 🔄 OpenAI 兼容端点：支持 /v1/chat/completions（OpenAI 兼容格式），工具调用与 reasoning 字段透传，严格同格式路由，无跨格式转换。 /v1/chat/completions

⚡️ 快速开始 Quick Start

环境要求

• Docker 与 Docker Compose（推荐使用最新版本）
• 可选（本地开发）：Node.js ≥ 20，Bun ≥ 1.3

🚀 一键部署脚本（✨ 推荐方式，全自动安装）

一键部署脚本会自动完成以下所有步骤：

• 检查并安装 Docker 和 Docker Compose（Linux/macOS 支持自动安装）
• 创建部署目录并配置文件
• 生成安全的管理员令牌和数据库密码
• 启动所有服务并等待健康检查
• 显示访问地址和管理员令牌 Linux / macOS:

或者使用 wget：

Windows (PowerShell 管理员模式):

部署目录：

• Linux: /www/compose/claude-code-hub /www/compose/claude-code-hub

• macOS: ~/Applications/claude-code-hub ~/Applications/claude-code-hub

• Windows: C:\ProgramData\claude-code-hub C:\ProgramData\claude-code-hub

分支选择：

脚本会提示选择部署分支：

• main（默认）：稳定版本，推荐生产环境使用 main

• dev：开发版本，包含最新功能，用于测试 dev

重要提示：

• ⚠️ 请妥善保存脚本输出的管理员令牌（Admin Token），这是登录后台的唯一凭证！
• ⚠️ Windows 用户：如果未安装 Docker Desktop，脚本会自动打开下载页面

三步启动（Docker Compose）

• 克隆项目并配置环境 git clone https://github.com/ding113/claude-code-hub.git cd claude-code-hub cp .env.example .env 克隆项目并配置环境

• 修改配置文件 编辑 .env 文件，必须修改 ADMIN_TOKEN（后台登录令牌）： # 必须修改此项！ ADMIN_TOKEN=your-secure-token-here

Docker Compose 默认配置（通常无需修改）

DSN=postgres://postgres:postgres@postgres:5432/claude_code_hub REDIS_URL=redis://redis:6379 修改配置文件

编辑 .env 文件，必须修改 ADMIN_TOKEN（后台登录令牌）：

.env

ADMIN_TOKEN

• 启动服务 docker compose up -d 查看启动状态： docker compose ps docker compose logs -f app 启动服务

查看启动状态：

访问应用

启动成功后：

• 管理后台：http://localhost:23000（使用 .env 中的 ADMIN_TOKEN 登录） http://localhost:23000

.env

ADMIN_TOKEN

• API 文档（Scalar UI）：http://localhost:23000/api/actions/scalar http://localhost:23000/api/actions/scalar

• API 文档（Swagger UI）：http://localhost:23000/api/actions/docs http://localhost:23000/api/actions/docs

• API 认证指南：docs/api-authentication-guide.md 💡 提示：

• 如需修改端口，请编辑 docker-compose.yml 中的 ports 配置。 docker-compose.yml

ports

• 如需通过脚本或编程调用 API，请参考 API 认证指南。

🖼️ 界面预览 Screenshots

🏗️ 架构说明 Architecture

高层架构

客户端 / CLI / 第三方系统 │ ▼ Next.js 15 App Router (v1 API 路由) │ Hono + Proxy Pipeline (认证 → Session 分配 → 限流 → 供应商选择 → 请求转发 → 响应处理) │ 多供应商 (Claude / OpenAI / Gemini / 第三方) + PostgreSQL + Redis

• App 层：src/app 中的 dashboard、settings、api actions，提供 UI 与内部 API。 src/app

• Proxy 核心：src/app/v1/_lib/proxy-handler.ts 串联 Auth、SessionGuard、RateLimitGuard、ProviderResolver、Forwarder、ResponseHandler。 src/app/v1/_lib/proxy-handler.ts

• 业务逻辑：src/lib 存放限流、Session、熔断器、代理、price-sync；src/repository 封装 Drizzle ORM 查询。 src/lib

src/repository

• 文档体系：src/app/api/actions/[...route]/route.ts 自动注册 Action → OpenAPI 端点。 src/app/api/actions/[...route]/route.ts

数据流与组件

• 入口：请求携带 API Key 命中 Next.js API Route → ProxyAuthenticator 校验身份。 ProxyAuthenticator

• 上下文管理：SessionManager 从 Redis 读取 5 分钟缓存，控制并发并记录决策链。 SessionManager

• 限流：RateLimitService 使用 Lua 脚本原子写入 RPM/金额/并发指标，Redis 不可用则 Fail-Open 降级。 RateLimitService

• 调度：ProviderResolver 根据权重、优先级、熔断状态与 Session 复用策略选择最佳供应商，至多 3 次重试。 ProviderResolver

• 转发与响应处理：ProxyForwarder 负责上游请求转发，ProxyResponseHandler 处理响应流并保留端点原生格式，支持代理与模型重定向。 ProxyForwarder

ProxyResponseHandler

• 监控：日志、排行榜、价格表等 UI 通过 repository 查询 PostgreSQL，以小时级聚合呈现指标。