⚡️ 快速开始 Quick Start

环境要求

• Docker 与 Docker Compose（推荐使用最新版本）
• 可选（本地开发）：Node.js ≥ 20，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. 克隆项目并配置环境

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

2. 修改配置文件

   编辑 .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
   

3. 启动服务

   docker compose up -d
   

   查看启动状态：

   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/api-authentication-guide.md

💡 提示：

• 如需修改端口，请编辑 docker-compose.yml 中的 ports 配置。
• 如需通过脚本或编程调用 API，请参考 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. 启动：

   docker compose up -d
   

3. 查看日志与状态：

   docker compose logs -f app
   docker compose ps
   

4. 升级：

   docker compose pull && docker compose up -d
   

   若需停止并清理，执行 docker compose down.

本地开发（dev 工具链）

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

手动部署（bun build + start）

1. 安装依赖并构建：

   bun install
   bun run build      # 自动复制 VERSION
   

2. 设置环境变量（建议通过系统服务或 PM2 注入），确保数据库、Redis 可访问。
3. 启动生产服务器：

   bun run start
   

4. 注意：首次运行可开启 AUTO_MIGRATE=true 自动迁移，生产环境完成后建议改为 false 并使用 Drizzle CLI 手动管理。

⚙️ 配置说明 Configuration

| 变量