English | 中文

Claude Code Hub

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

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

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

---

[!IMPORTANT] 当前项目正处于积极重构阶段

Claude Code Hub 的重构版本 Claude Code Hub Plus 预计将于第三季度以 AGPL 形式开源。Claude Code Hub Plus 致力于打造高性能、稳定的商用级 LLM 网关，提供格式转换、隐私过滤、模型广场、充值计费等完善的商用功能，并显著提升转发核心的理论性能。重构版本开发期间，Node.js 版本的开发进度和社区支持可能延误，敬请理解。

💎 特别优惠：Cubence 一家稳定高效的AI服务中转平台，为 Claude Code、Codex、Gemini 等AI工具提供中转服务，有着不错的稳定性和性价比。 Cubence 为 CCH 的使用用户提供了特别的优惠折扣：在购买时使用优惠券 DING113CCH，可享受 10% 优惠折扣 → 立即访问

💎 特别优惠：感谢 PackyCode 赞助本项目！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。 PackyCode 为本软件的用户提供了特别优惠，使用此链接注册并在充值时填写优惠码 WITHCCH，可享受 9 折优惠 → 立即访问

💎 特别优惠：YesCode 是一家低调务实的 AI API 中转服务商，专注于为开发者提供稳定可靠的 Claude、Codex、Gemini 等模型接入服务，以扎实的技术底蕴和持续稳定的服务质量赢得用户信赖。 通过此链接注册即可体验 → 立即访问

💎 特别优惠：AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的 AI 编程服务。提供灵活的订阅计划，可包月可套餐，零封号风险，国内直连，无需魔法，超大积分池，极速响应。 AIGoCode 为 CCH 的用户提供了特别福利，通过此链接注册的用户首次充值可以获得额外 10% 奖励额度 → 立即访问

💎 特别优惠：PatewayAI 是一家面向重度 AI 开发者、专注官方直连的高品质模型 API 中转服务商。提供 Claude 全系列与 Codex 系列模型，100% 官方源直供，不掺假不注水，欢迎检验。计费透明，Token 级账单可逐笔核验。 同时支持企业级高并发，并为企业客户提供了专业的管理平台，企业客户可签订正式合同并开具发票，更多详情进入官网获取联系方式。 现在通过 此链接注册 即送 $3 试用额度，用户充值低至 6 折，邀请好友双向赠送，邀请奖励可达 $150。

✨ 核心功能 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 字段透传，严格同格式路由，无跨格式转换。

⚡️ 快速开始 Quick Start

环境要求

• Docker 与 Docker Compose（推荐使用最新版本）
• 可选（本地开发）：Node.js ≥ 22.15（入站请求体 zstd 解压依赖原生 node:zlib zstd），Bun ≥ 1.3

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

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

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

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

或者使用 wget：

wget https://raw.githubusercontent.com/ding113/claude-code-hub/main/scripts/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

部署目录：

• Linux: /www/compose/claude-code-hub
• macOS: ~/Applications/claude-code-hub
• Windows: C:\ProgramData\claude-code-hub

分支选择：

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

• main（默认）：稳定版本，推荐生产环境使用
• dev：开发版本，包含最新功能，用于测试

重要提示：

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

三步启动（Docker Compose）

1. 克隆项目并配置环境

bash git clone https://github.com/ding113/claude-code-hub.git cd claude-code-hub cp .env.example .env

1. 修改配置文件

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

```bash # 必须修改此项！ ADMIN_TOKEN=your-secure-token-here

# Docker Compose 默认配置（通常无需修改） DSN=postgres://postgres:postgres@postgres:5432/claude_code_hub REDIS_URL=redis://redis:6379 ```

1. 启动服务

bash docker compose up -d

查看启动状态：

bash docker compose ps docker compose logs -f app

访问应用

启动成功后：

• 管理后台：http://localhost:23000（使用 .env 中的 ADMIN_TOKEN 登录）
• API 文档（Scalar UI）：http://localhost:23000/api/actions/scalar
• API 文档（Swagger UI）：http://localhost:23000/api/actions/docs
• 公开状态 API：docs/public-status-api.md
• API 认证指南：docs/api-authentication-guide.md

💡 提示： - 如需修改端口，请编辑 docker-compose.yml 中的 ports 配置。 - 如需通过脚本或编程调用 API，请参考 API 认证指南。 - 如需接入无需认证的公开状态接口，请参考 Public Status API。

🖼️ 界面预览 Screenshots

功能	截图	说明
仪表盘		汇总调用量、成本、活跃 Session 与时间分布，实时洞察整体使用情况。
供应商管理		为每个供应商配置权重、成本系数、并发限制、代理及模型重定向，实现精细调度。
日志与审计		统一查询请求日志，支持时间/用户/供应商/模型筛选，查看 Token、成本与缓冲命中情况。
排行榜		按用户统计请求数、Token 与成本，用于费用分摊与用量治理。

🏗️ 架构说明 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。
• Proxy 核心：src/app/v1/_lib/proxy-handler.ts 串联 Auth、SessionGuard、RateLimitGuard、ProviderResolver、Forwarder、ResponseHandler。
• 业务逻辑：src/lib 存放限流、Session、熔断器、代理、price-sync；src/repository 封装 Drizzle ORM 查询。
• 文档体系：src/app/api/actions/[...route]/route.ts 自动注册 Action → OpenAPI 端点。

数据流与组件

1. 入口：请求携带 API Key 命中 Next.js API Route → ProxyAuthenticator 校验身份。
2. 上下文管理：SessionManager 从 Redis 读取 5 分钟缓存，控制并发并记录决策链。
3. 限流：RateLimitService 使用 Lua 脚本原子写入 RPM/金额/并发指标，Redis 不可用则 Fail-Open 降级。
4. 调度：ProviderResolver 根据权重、优先级、熔断状态与 Session 复用策略选择最佳供应商，至多 3 次重试。
5. 转发与响应处理：ProxyForwarder 负责上游请求转发，ProxyResponseHandler 处理响应流并保留端点原生格式，支持代理与模型重定向。
6. 监控：日志、排行榜、价格表等 UI 通过 repository 查询 PostgreSQL，以小时级聚合呈现指标。

🚢 部署指南 Deployment

🐳 Docker Compose（✨ 推荐方式，开箱即用）

Docker Compose 是首选部署方式，自动配置数据库、Redis 和应用服务，无需手动安装依赖，适合生产环境快速部署。

1. 准备 .env（参考 .env.example）；确认 DSN 与 REDIS_URL 指向 Compose 内的服务。
2. 启动： bash docker compose up -d
3. 查看日志与状态： bash docker compose logs -f app docker compose ps
4. 升级： bash docker compose pull && docker compose up -d 若需停止并清理，执行 docker compose down.

☸️ Kubernetes / k3s（生产 / 多节点 / 高可用）

项目提供 k3s 与标准 Kubernetes 双兼容的一键部署脚本 scripts/deploy-k8s.sh 与运维 CLI scripts/cch，覆盖 HPA 自动扩缩容、PodDisruptionBudget、NetworkPolicy、滚动升级带自动回滚、定时备份等生产需求。

最简命令（本机无集群时会提示自动安装 k3s）：

git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
bash scripts/deploy-k8s.sh --install-k3s -y

带域名的标准 K8s 部署：

bash scripts/deploy-k8s.sh \
  --ingress-host hub.example.com \
  --ingress-class nginx \
  --storage-class standard \
  -y

部署完成后使用 cch 管理运行时：

cch status            # 查看 Pod / HPA / 资源
cch update            # 拉新镜像 + 自动迁移 + 滚动更新（失败自动回滚）
cch backup            # 备份 PostgreSQL
cch info              # 显示访问地址 + Admin Token
cch doctor            # 诊断集群与部署状态

完整参数、占位符说明、云厂商 StorageClass 对照、故障排查等详见：docs/k8s-deployment.md。

本地开发（dev 工具链）

1. 进入 dev/ 目录：cd dev.
2. make dev 一键启动 PostgreSQL + Redis + bun dev。
3. 常用命令：
4. make db：仅启动数据库与 Redis
5. make logs / make logs-app：快速查看服务日志
6. make clean / make reset：清理或重置环境
7. 推荐使用 make migrate、make db-shell 处理数据库变更。

手动部署（bun build + start）

1. 安装依赖并构建： bash bun install bun run build # 自动复制 VERSION
2. 设置环境变量（建议通过系统服务或 PM2 注入），确保数据库、Redis 可访问。
3. 启动生产服务器： bash bun run start
4. 注意：首次运行可开启 AUTO_MIGRATE=true 自动迁移，生产环境完成后建议改为 false 并使用 Drizzle CLI 手动管理。

⚙️ 配置说明 Configuration

变量	默认值	说明与建议
ADMIN_TOKEN	change-me	后台登录令牌，部署前必须修改。
DSN	-	PostgreSQL 连接串，如 postgres://user:pass@host:5432/db.
DB_POOL_MAX	生产环境 20 / 开发 10	PostgreSQL 连接池上限（每进程）；高并发可提高，k8s 多副本需结合 max_connections 分摊。
DB_POOL_IDLE_TIMEOUT	20	空闲连接回收（秒）；避免连接长期占用。
DB_POOL_CONNECT_TIMEOUT	10	建立连接超时（秒）；避免网络异常时卡住连接获取。
MESSAGE_REQUEST_WRITE_MODE	async	请求日志写入模式：async 异步批量（默认）；sync 同步写入（更实时但更慢）。
MESSAGE_REQUEST_ASYNC_FLUSH_INTERVAL_MS	250	异步批量写入 flush 间隔（毫秒）。
MESSAGE_REQUEST_ASYNC_BATCH_SIZE	200	单次批量写入最大条数（避免单条 SQL 过大）。
MESSAGE_REQUEST_ASYNC_MAX_PENDING	5000	内存队列上限（防止 DB 异常时无限增长；超限将丢弃最旧更新并告警）。
AUTO_MIGRATE	true	启动时自动执行 Drizzle 迁移；生产环境可关闭以人工控制。
REDIS_URL	redis://localhost:6379	Redis 地址，支持 rediss:// 用于 TLS。
REDIS_TLS_REJECT_UNAUTHORIZED	true	是否验证 Redis TLS 证书；设为 false 可跳过验证（用于自签/共享证书）。
ENABLE_RATE_LIMIT	true	控制多维限流开关；Fail-Open 策略在 Redis 不可用时自动降级。
ENABLE_API_KEY_VACUUM_FILTER	true	是否启用 API Key 真空过滤器（仅负向短路无效 key；可设为 false/0 关闭用于排查/节省内存）。
ENABLE_API_KEY_REDIS_CACHE	true	是否启用 API Key 鉴权 Redis 缓存（需 Redis 可用；异常自动回落到 DB）。
API_KEY_AUTH_CACHE_TTL_SECONDS	60	API Key 鉴权缓存 TTL（秒，默认 60，最大 3600）。
AUTH_SESSION_TTL_SECONDS	604800	Web UI 登录态 TTL（秒，默认 7 天）；ADMIN_TOKEN opaque 登录的签名 cookie 也使用该值。降低该值会按签发时间收紧已签发 admin 签名 cookie 的剩余寿命，且不会延长其原始 exp。
SESSION_TTL	300	代理请求上下文缓存时间（秒），影响供应商复用策略；不控制 Web UI 登录态。
ENABLE_SECURE_COOKIES	true	仅 HTTPS 场景能设置 Secure Cookie；HTTP 访问（非 localhost）需改为 false。
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS	false	是否将网络错误计入熔断器；开启后能更激进地阻断异常线路。
APP_PORT	23000	生产端口，可被容器或进程管理器覆盖。
APP_URL	空	设置后 OpenAPI 文档 servers 将展示正确域名/端口。
API_TEST_TIMEOUT_MS	15000	供应商 API 测试超时时间（毫秒，范围 5000-120000），跨境网络可适