项目概述
Claude Code Hub 是一个现代化的企业级 API 代理平台，通过统一接口管理多个 AI 服务提供商。系统实现了智能负载均衡、多维度限流、用户管理和消费追踪，适合团队和企业使用 Claude、OpenAI、Gemini 等 AI 服务。
客户端Claude Code / Gemini CLI
→
Hub 代理认证 & 限流
→
负载均衡权重 & 熔断
→
多ProviderClaude / OpenAI / Gemini
技术栈
- 框架：Next.js 15 (App Router) + Hono
- 数据库：PostgreSQL + Drizzle ORM
- 缓存：Redis
- 运行时：Bun (≥1.3) 或 Node.js (≥20)
核心功能
⚖️ 智能负载均衡
权重 + 优先级 + 分组调度，内置熔断器保护，最多 3 次故障转移重试。
🚦 多维度限流
RPM（每分钟请求）、消费额度（5小时/周/月）、并发 Session 限制，Redis Lua 原子保证。
🔌 多Provider支持
同时集成 Claude、Codex、Gemini CLI 和 OpenAI 兼容服务，支持模型重定向。
📊 实时监控
活跃会话、消费排行、决策链日志、Provider 状态追踪，全面可视化。
📖 API 文档自动生成
从 Server Actions 自动生成 39 个 REST 端点，OpenAPI 3.1.0 规范，Swagger + Scalar UI。
🛡️ 熔断器保护
Provider 连续失败自动熔断，Fail-Open 降级策略，保障服务稳定性。
系统要求
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| 运行时 | Node.js 20+ 或 Bun 1.3+ | Bun 1.3+（性能更优） |
| 数据库 | PostgreSQL 14+ | PostgreSQL 16 |
| 缓存 | Redis 6+ | Redis 7+ |
| 内存 | 1GB | 2GB+ |
| 操作系统 | Linux / macOS / Windows | |
安装部署
方式一：一键部署脚本（推荐）
脚本自动安装 Docker、生成安全令牌、启动所有服务。
Linux / macOS
Windows
# Linux / macOS 一键部署
curl -fsSL https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.sh -o deploy.sh
chmod +x deploy.sh
./deploy.sh
# Windows PowerShell（以管理员身份运行）
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.ps1" -OutFile "deploy.ps1"
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\deploy.ps1
方式二：Docker Compose 部署
# 1. 克隆项目
git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
# 2. 复制并编辑配置文件
cp .env.example .env
# 3. 编辑 .env，设置 ADMIN_TOKEN（必须修改！）
# ADMIN_TOKEN=your-secure-admin-token-here
# 4. 启动服务
docker compose up -d
# 5. 查看日志
docker compose logs -f
方式三：本地开发部署
# 使用 Makefile 快速启动开发环境
make dev # 启动 PostgreSQL + Redis + 开发服务器（热重载）
# 或者手动启动
bun install
bun run build
bun run start
⚠️ 安全警告
- 必须修改 ADMIN_TOKEN：默认值为
change-me，生产环境必须更改 - 建议使用反向代理（Nginx/Caddy）并启用 HTTPS
- 生产环境设置
ENABLE_SECURE_COOKIES=true
环境变量配置
| 变量名 | 默认值 | 说明 | 必填 |
|---|---|---|---|
ADMIN_TOKEN |
change-me | 管理后台登录凭证 | 必填 |
DSN |
— | PostgreSQL 连接字符串 | 必填 |
REDIS_URL |
redis://localhost:6379 | Redis 服务器地址 | 可选 |
APP_PORT |
23000 | 服务监听端口 | 可选 |
AUTO_MIGRATE |
true | 自动执行数据库迁移 | 可选 |
SESSION_TTL |
300 | 会话缓存时长（秒） | 可选 |
ENABLE_RATE_LIMIT |
true | 启用多维度限流 | 可选 |
ENABLE_SECURE_COOKIES |
true | 强制 HTTPS Cookie | 可选 |
API_TEST_TIMEOUT_MS |
15000 | Provider API 测试超时（5000-120000ms） | 可选 |
初始配置步骤
- 访问管理面板：打开浏览器访问
http://localhost:23000，使用 ADMIN_TOKEN 登录 - 添加 Provider：进入 Provider 管理，添加 Claude/OpenAI 等 API 提供商，配置 API Key
- 配置负载均衡：为每个 Provider 设置权重、优先级和分组
- 创建用户：添加团队成员，分配 API 密钥和限流配额
- 配置限流规则：设置 RPM、消费额度（5小时/周/月）、并发限制
- 测试连接：使用管理面板的测试功能验证 Provider 可用性
API 端点
| 端点 | 说明 | 用途 |
|---|---|---|
http://localhost:23000 |
管理后台 | Provider 管理、用户管理、监控 |
/v1/chat/completions |
OpenAI 兼容接口 | API 代理入口 |
/api/actions/scalar |
Scalar UI | 交互式 API 文档 |
/api/actions/docs |
Swagger UI | API 文档浏览 |
实际使用案例
案例一：Claude Code 集成
将 Claude Code CLI 连接到 Hub 代理服务：
# 设置环境变量
export ANTHROPIC_BASE_URL="http://localhost:23000/v1"
export ANTHROPIC_API_KEY="your-hub-api-key"
# 启动 Claude Code
claude
效果：所有请求经过 Hub 负载均衡，自动选择最优 Provider，失败自动切换。
案例二：Gemini CLI 集成
将 Gemini CLI 连接到 Hub：
# 设置环境变量
export CODE_ASSIST_ENDPOINT="http://localhost:23000/gemini"
export GOOGLE_CLOUD_ACCESS_TOKEN="your-hub-api-key"
# 启动 Gemini CLI
gemini
案例三：团队多维度限流管理
场景：20人开发团队，需要精细控制 API 使用成本。
- 创建用户分组：高级开发者 / 普通开发者 / 实习生
- 配置差异化限流：
- 高级开发者：100 RPM，月消费 $500
- 普通开发者：50 RPM，月消费 $200
- 实习生：20 RPM，月消费 $50
- 设置熔断阈值：单 Provider 连续失败 5 次自动熔断
- 配置告警：消费达到 80% 时邮件通知
案例四：多 Provider 负载均衡
场景：同时使用多个 Claude 账号和 OpenAI 作为备份。
# Provider 配置示例
providers:
- name: claude-primary
type: claude
weight: 60 # 60% 流量
priority: 1 # 最高优先级
- name: claude-secondary
type: claude
weight: 30 # 30% 流量
priority: 2
- name: openai-backup
type: openai
weight: 10 # 10% 流量，作为备份
priority: 3
效果：正常情况按权重分配，主 Provider 故障时自动切换到备份。
完整运行示例
以下是在 macOS 上从零开始部署 Claude Code Hub 的完整流程：
# ========== 第一步：一键部署 ==========
# 下载并执行部署脚本
curl -fsSL https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/deploy.sh -o deploy.sh
chmod +x deploy.sh
./deploy.sh
# 脚本会自动：
# 1. 检查/安装 Docker
# 2. 生成安全的 ADMIN_TOKEN
# 3. 创建 .env 配置文件
# 4. 启动 PostgreSQL + Redis + Hub 服务
# ========== 第二步：记录 ADMIN_TOKEN ==========
# 部署完成后会显示 ADMIN_TOKEN，请妥善保存
# 例如：ADMIN_TOKEN=a1b2c3d4e5f6g7h8i9j0...
# ========== 第三步：访问管理后台 ==========
# 浏览器打开
open http://localhost:23000
# 使用 ADMIN_TOKEN 登录
# ========== 第四步：添加 Provider ==========
# 在管理后台：
# 1. 进入 "Providers" 页面
# 2. 点击 "Add Provider"
# 3. 选择类型（Claude/OpenAI）
# 4. 填写 API Key
# 5. 设置权重和优先级
# 6. 点击 "Test" 验证连接
# 7. 保存
# ========== 第五步：创建用户和 API Key ==========
# 在管理后台：
# 1. 进入 "Users" 页面
# 2. 点击 "Add User"
# 3. 设置用户名和限流规则
# 4. 生成 API Key（如：hub_sk_xxxxxxxxxxxx）
# ========== 第六步：配置客户端 ==========
# Claude Code
export ANTHROPIC_BASE_URL="http://localhost:23000/v1"
export ANTHROPIC_API_KEY="hub_sk_xxxxxxxxxxxx"
claude
# 或写入配置文件永久生效
echo 'export ANTHROPIC_BASE_URL="http://localhost:23000/v1"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="hub_sk_xxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
# ========== 常用管理命令 ==========
# 进入项目目录（macOS 默认安装位置）
cd ~/Applications/claude-code-hub
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f
# 重启服务
docker compose restart
# 停止服务
docker compose down
# 更新到最新版本
git pull && docker compose up -d --build
开发命令速查
| 命令 | 说明 |
|---|---|
make dev |
启动 PostgreSQL + Redis + 开发服务器（热重载） |
make db |
仅启动数据库和 Redis |
make logs |
查看服务日志 |
make db-shell |
进入 PostgreSQL 命令行 |
make migrate |
手动执行数据库迁移 |
make clean |
清理环境 |
make reset |
重置所有数据 |
与 Claude Relay Service 对比
| 维度 | Claude Code Hub | Claude Relay Service |
|---|---|---|
| 定位 | 企业级 API 代理平台 | 轻量级中继服务 |
| 数据库 | PostgreSQL + Redis | 仅 Redis |
| 负载均衡 | 权重+优先级+熔断器 | 简单轮询 |
| 限流维度 | RPM/消费额度/并发Session | 基础速率限制 |
| API 文档 | 自动生成 OpenAPI 3.1 | 无 |
| 适用场景 | 团队 10+ 人，企业级需求 | 个人或小团队（<10人） |
| 部署复杂度 | 中等 | 简单 |
默认安装路径
| 操作系统 | 安装路径 |
|---|---|
| Linux | /www/compose/claude-code-hub |
| macOS | ~/Applications/claude-code-hub |
| Windows | C:\ProgramData\claude-code-hub |