ccLoad

Claude Code、Codex、Gemini、OpenAI 多协议 AI API 网关。

English | 简体中文

智能路由 | 自动故障切换 | 指数冷却 | 多 URL 调度 | 协议转换 | 实时监控 | 成本控制

ccLoad 用一个 Go 服务接住多上游 AI API 的复杂度：Claude Code、Codex、Gemini、OpenAI 兼容客户端统一接入同一个网关，渠道选择、故障切换、冷却、协议转换、请求可观测性和费用限制都在服务端处理，不再散落到每个客户端脚本里。

🎯 解决什么问题

当你同时维护多个 AI API 渠道时，真正麻烦的是这些问题：

• 渠道切换靠手工：不同 Key、有效期、额度和上游 URL 混在一起，迟早失控。
• 限流和故障打断工作流：429、502、504、Key 过期、供应商过载，都不应该让客户端直接停摆。
• 请求状态不可见：长时间流式请求没有实时状态，只能猜卡在客户端、网关还是上游。
• HTTP 200 里藏错误：部分上游返回成功状态码，但响应体实际是错误。
• 成本不可控：共享网关需要渠道级和令牌级限额，不能等账单出来再补救。

ccLoad 直接处理这些问题：

• 🎯 智能路由：高优先级渠道优先使用，同级渠道按平滑加权轮询分流。
• 🔀 自动故障切换：按错误类型跳过故障 Key、渠道或 URL。
• ⏰ 指数冷却：异常上游自动退避，避免重试持续打到坏渠道。
• 🌐 多 URL 调度：一个渠道可配置多个上游 URL，按延迟和健康度分配流量。
• 🔄 协议转换：Anthropic、OpenAI、Gemini、Codex 请求和响应可在网关层转换。
• 📊 实时监控：活跃请求、日志、Token、TTFB、费用和上游详情在后台直接可见。
• 🔍 软错误检测：HTTP 200 伪装成功也会触发故障切换。已覆盖：
• {"error": {...}} 结构的 JSON 错误
• type 字段是 "error" 的响应
• SSE error 事件中的明确限流（rate_limit_exceeded / too_many_requests）按 429 处理
• "当前模型负载过高" 之类的纯文本告警

✨ 主要特性

核心能力直接对应生产问题：

能力	亮点	效果
🚀 性能怪兽	Gin框架 + Sonic JSON	1000+并发，高性能缓存
🧮 本地算Token	不调API就能估算消耗	响应<5ms，准确度93%+
🎯 错误分类器	Key级/渠道级/客户端错误	200伪装错误也能揪出来
🔀 智能调度	优先级+平滑加权轮询+健康度排序	异常渠道自动降权
🛡️ 故障秒切	指数退避冷却机制	2min→4min→8min→30min
📊 数据大屏	趋势图+日志+Token统计	一眼看清用量情况
🎯 多API兼容	Claude Code/Codex/Gemini/OpenAI	一套配置走天下
📦 开箱即用	单文件+嵌入式SQLite	零依赖，下载就能跑
🐳 云原生	多架构镜像+CI/CD	amd64/arm64都支持
🤗 免费托管	Hugging Face免费托管	适合个人试用
💰 成本限额	渠道每日成本上限	达到限额自动跳过
🚦 渠道RPM限制	每渠道滚动60秒请求上限	0=不限，超限自动跳过
🚧 渠道并发限制	每渠道同时在飞请求上限	0=不限，超限自动跳过
🔐 令牌限额	API令牌费用上限+模型限制	精细化访问控制
⏱️ 首字节监控	流式请求TTFB记录	便于诊断上游延迟
🌐 多URL负载均衡	单渠道多URL+加权随机	延迟低的URL自动多分流
💵 service_tier定价	OpenAI priority/flex/default层级	费用倍率精准计算
🖼️ 图像工具计费	Responses image_generation/gpt-image-2	图像生成成本不漏算
📉 分层定价	GPT-5.4/Qwen-Plus/Gemini长上下文	超量token自动降档计费
🔄 协议转换	Anthropic/OpenAI/Gemini/Codex互转	保留采样与思考参数，一个渠道服务多种客户端协议
💬 对话式模型测试	按渠道/按模型/对话三种模式	支持图片上传、思考等级、内置搜索与对话导出
🔍 调试日志	上游请求/响应原始数据捕获	敏感头脱敏，排障利器
🕐 定时检测	渠道可用性后台定时探测	自动发现故障渠道
🔄 自动更新	默认每 12 小时检查新版本	可在设置页调整检测间隔
🧩 自定义请求规则	渠道级请求头/JSON 请求体改写（remove/override/append）	认证头保护 + CRLF 防护 + 容量上限
🎛️ 日志列自定义	表格列显隐可配置，设置持久化到浏览器	按需查看，减少信息噪音

🏗️ 架构概览

ccLoad 的请求链路很直接：

从你的应用发请求到API返回结果，中间经过这几层： - 认证层 - 验证访问权限 - 路由分发 - 判断请求协议与路径，按 Claude Code、Codex、Gemini、OpenAI 分流处理 - 协议转换 - 客户端用OpenAI格式？上游是Anthropic？自动翻译，无感切换 - 智能调度 - 从多个渠道中选择当前最合适的上游 - 故障切换 - 选中的渠道失败后自动切换备用渠道

核心亮点：存储层用工厂模式，SQLite 和 MySQL 共享代码，消除了 467 行重复代码。数据层边界清晰，切换数据库只需要调整环境变量。

graph TB
    subgraph "客户端"
        A[用户应用] --> B[ccLoad代理]
    end

    subgraph "ccLoad服务"
        B --> C[认证层]
        C --> D[路由分发]
        D --> E[渠道选择器]
        E --> F[负载均衡器]

        subgraph "核心组件"
            F --> G[渠道A

优先级:10]
            F --> H[渠道B

优先级:5]
            F --> I[渠道C

优先级:5]
            G --> G1[URL选择器

加权随机]
            H --> H1[URL选择器

加权随机]
            I --> I1[URL选择器

加权随机]
        end

        subgraph "存储层"
            J[(存储工厂)]
            J3[Schema定义层]
            J4[统一SQL层]
            J1[(SQLite)]
            J2[(MySQL)]
            J --> J3
            J3 --> J4
            J4 --> J1
            J4 --> J2
        end

        subgraph "监控层"
            K[日志系统]
            L[统计分析]
            M[趋势图表]
        end
    end

    subgraph "上游服务"
        G1 --> N[Claude API]
        H1 --> O[Claude API]
        I1 --> P[Claude API]
    end

    E <--> J
    F <--> J
    K <--> J
    L <--> J
    M <--> J

    style B fill:#4F46E5,stroke:#000,color:#fff
    style F fill:#059669,stroke:#000,color:#fff
    style E fill:#0EA5E9,stroke:#000,color:#fff

🚀 快速开始

选择适合当前环境的部署方式：

部署方式	难度	成本	适合谁	HTTPS	持久化
🐳 Docker	⭐⭐	需VPS	生产环境、追求稳定	需配置	✅
🤗 Hugging Face	⭐	免费	个人试用、快速体验	✅自动	✅
🔧 源码编译	⭐⭐⭐	需服务器	开发、定制构建	需配置	✅
📦 二进制	⭐⭐	需服务器	轻量部署	需配置	✅

方式一：Docker 部署（推荐）

生产环境建议优先使用 Docker。官方镜像已发布到 GitHub Container Registry，可直接拉取运行。

使用预构建镜像（推荐）：

# 方式 1: 使用 docker-compose（最简单）
curl -o docker-compose.yml https://raw.githubusercontent.com/caidaoli/ccLoad/master/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/caidaoli/ccLoad/master/.env.example
# 编辑 .env 文件设置密码
docker-compose up -d

# 方式 2: 直接运行镜像
docker pull ghcr.io/caidaoli/ccload:latest
docker run -d --name ccload \
  -p 8080:8080 \
  -e CCLOAD_PASS=your_secure_password \
  -v ccload_data:/app/data \
  ghcr.io/caidaoli/ccload:latest

从源码构建：

需要审计镜像内容或定制构建时，可从源码构建：

# 克隆项目
git clone https://github.com/caidaoli/ccLoad.git
cd ccLoad

# 使用 docker-compose 构建并运行
docker-compose -f docker-compose.build.yml up -d

# 或手动构建
docker build -t ccload:local .
docker run -d --name ccload \
  -p 8080:8080 \
  -e CCLOAD_PASS=your_secure_password \
  -v ccload_data:/app/data \
  ccload:local

方式二：源码编译

需要本地开发或修改代码时，使用源码编译：

# 克隆项目
git clone https://github.com/caidaoli/ccLoad.git
cd ccLoad

# 构建项目（默认使用高性能 JSON 库）
go build -tags sonic -o ccload .

# 或使用 Makefile
make build

# 直接运行开发模式
go run -tags sonic .
# 或
make dev

方式三：二进制下载

不需要 Docker 或 Go 环境时，可直接下载对应平台的二进制文件：

# 从 GitHub Releases 下载对应平台的二进制文件
wget https://github.com/caidaoli/ccLoad/releases/latest/download/ccload-linux-amd64
chmod +x ccload-linux-amd64
./ccload-linux-amd64

方式四：Hugging Face Spaces 部署

Hugging Face Spaces 提供免费的 Docker 托管和自动 HTTPS，适合个人试用与轻量场景。

部署步骤

1. 登录 Hugging Face

访问 huggingface.co 并登录你的账户

1. 创建新 Space

2. 点击右上角 "New" → "Space"

3. Space name: ccload（或自定义名称）
4. License: MIT
5. Select the SDK: Docker
6. Visibility: Public 或 Private（私有需付费订阅）

7. 点击 "Create Space"

8. 创建 Dockerfile

在 Space 仓库中创建 Dockerfile 文件，内容如下：

dockerfile FROM ghcr.io/caidaoli/ccload:latest ENV TZ=Asia/Shanghai ENV PORT=7860 ENV SQLITE_PATH=/tmp/ccload.db EXPOSE 7860

可以通过以下方式创建：

方式 A - Web 界面（推荐）: - 在 Space 页面点击 "Files" 标签 - 点击 "Add file" → "Create a new file" - 文件名输入 Dockerfile - 粘贴上述内容 - 点击 "Commit new file to main"

方式 B - Git 命令行: ```bash # 克隆你的 Space 仓库 git clone https://huggingface.co/spaces/YOUR_USERNAME/ccload cd ccload

# 创建 Dockerfile cat > Dockerfile << 'EOF' FROM ghcr.io/caidaoli/ccload:latest ENV TZ=Asia/Shanghai ENV PORT=7860 ENV SQLITE_PATH=/tmp/ccload.db EXPOSE 7860 EOF

# 提交并推送 git add Dockerfile git commit -m "Add Dockerfile for ccLoad deployment" git push ```

1. 配置环境变量（Secrets）

在 Space 设置页面（Settings → Variables and secrets → New secret）添加：

变量名	值	必填	说明
CCLOAD_PASS	your_admin_password	✅ 必填	管理界面密码
CCLOAD_API_TOKENS	token1\|生产,token2\|开发	可选	启动时预置 API 访问令牌

注意: - API 访问令牌可通过 CCLOAD_API_TOKENS 预置，也可在 Web 管理界面 /web/tokens.html 配置 - PORT 和 SQLITE_PATH 已在 Dockerfile 中设置，无需配置 - Hugging Face Spaces 重启后 /tmp 目录会清空

1. 等待构建和启动

推送 Dockerfile 后，Hugging Face 会自动： - 拉取预构建镜像（约 30 秒） - 启动应用容器（约 10 秒） - 总耗时约 1-2 分钟（比从源码构建快 3-5 倍）

1. 访问应用

构建完成后，通过以下地址访问： - 应用地址: https://YOUR_USERNAME-ccload.hf.space - 管理界面: https://YOUR_USERNAME-ccload.hf.space/web/ - API 端点: https://YOUR_USERNAME-ccload.hf.space/v1/messages

首次访问提示: - 如果 Space 处于休眠状态，首次访问需等待 20-30 秒唤醒 - 后续访问会立即响应

Hugging Face 部署特点

优势: - ✅ 完全免费: 公开 Space 永久免费，包含 CPU 和存储 - ✅ 极速部署: 使用预构建镜像，1-2 分钟即可完成（比源码构建快 3-5 倍） - ✅ 自动 HTTPS: 无需配置 SSL 证书，自动提供安全连接 - ✅ 自动重启: 应用崩溃后自动重启 - ✅ 版本控制: 基于 Git，方便回滚和协作 - ✅ 简单维护: 仅需 5 行 Dockerfile，无需管理源码

限制: - ⚠️ 资源限制: 免费版提供 2 CPU + 16GB RAM - ⚠️ 休眠策略: 48 小时无访问会进入休眠，首次访问需等待唤醒（约 20-30 秒） - ⚠️ 固定端口: 必须使用 7860 端口 - ⚠️ 公网访问: Space 默认公开，必须通过 Web 管理界面配置 API 访问令牌才能访问 /v1/* API（否则 401）

数据持久化

重要: Hugging Face Spaces 的存储策略

由于 Hugging Face Spaces 的限制（/tmp 目录重启后清空），强烈推荐使用外部 MySQL 数据库实现完整的数据持久化：

方案一：混合存储模式（推荐，性能最优） - ✅ 极速查询: 所有读写走本地 SQLite，延迟 <1ms（免费 MySQL 延迟 800ms+） - ✅ 重启不丢数据: 异步同步到 MySQL，启动时自动恢复 - ✅ 统计缓存: 智能 TTL 缓存，减少重复聚合查询 - 配置方法: 在 Secrets 中添加 CCLOAD_MYSQL + CCLOAD_ENABLE_SQLITE_REPLICA=1

Dockerfile 示例（混合模式）:

FROM ghcr.io/caidaoli/ccload:latest
ENV TZ=Asia/Shanghai
ENV PORT=7860
# Secrets 中配置: CCLOAD_MYSQL + CCLOAD_ENABLE_SQLITE_REPLICA=1
EXPOSE 7860

方案二：纯 MySQL 模式 - ✅ 完整持久化: 渠道配置、日志记录、统计数据全部保留 - ✅ 重启不丢数据: 数据存储在外部数据库，不受 Space 重启影响 - ⚠️ 查询较慢: 免费 MySQL 延迟较高，统计页面响应慢 - 配置方法: 在 Secrets 中添加 CCLOAD_MYSQL 环境变量

推荐的免费 MySQL 服务: - TiDB Cloud Serverless - 免费 5GB 存储，MySQL 兼容，无连接数限制，推荐首选 - Aiven for MySQL - 免费 1GB 存储，支持多区域部署

MySQL 配置示例（以 TiDB Cloud 为例）: 1. 注册 TiDB Cloud 账户 2. 创建 Serverless Cluster（免费） 3. 获取连接信息，格式为：user:password@tcp(host:4000)/database?tls=true 4. 在 Hugging Face Space 的 Secrets 中添加 CCLOAD_MYSQL 变量 5. （可选）启用混合模式: 添加 CCLOAD_ENABLE_SQLITE_REPLICA=1 获得最佳性能 6. 重启 Space，所有数据将自动持久化到 MySQL

Dockerfile 示例（纯 MySQL）:

FROM ghcr.io/caidaoli/ccload:latest
ENV TZ=Asia/Shanghai
ENV PORT=7860
# 不需要 SQLITE_PATH，使用 CCLOAD_MYSQL 环境变量
EXPOSE 7860

方案三：仅本地存储（不推荐） - ⚠️ 数据丢失: Space 重启后 /tmp 目录会清空，渠道配置会丢失 - ⚠️ 手动恢复: 需要重新通过 Web 界面或 CSV 导入配置渠道 - 使用场景: 仅用于临时测试

更新部署

由于使用预构建镜像，更新非常简单：

镜像更新: - 当官方发布新版本镜像（ghcr.io/caidaoli/ccload:latest）时 - 在 Space 设置中点击 "Factory rebuild" 即可自动拉取最新镜像 - 或等待 Hugging Face 自动重启（通常 48 小时后）

手动触发更新:

# 在 Space 仓库中添加一个空提交来触发重建
git commit --allow-empty -m "Trigger rebuild to pull latest image"
git push

版本锁定（可选）: 如果需要锁定特定版本，修改 Dockerfile：

FROM ghcr.io/caidaoli/ccload:v2.44.1  # 指定版本号
ENV TZ=Asia/Shanghai
ENV PORT=7860
ENV SQLITE_PATH=/tmp/ccload.db
EXPOSE 7860

基本配置

部署完成后，按场景选择 SQLite 或 MySQL：

SQLite 模式（默认）： 个人或小团队可优先使用 SQLite，零外部依赖，单文件持久化：

# 设置环境变量
export CCLOAD_PASS=your_admin_password
export PORT=8080
export SQLITE_PATH=./data/ccload.db

# 或使用 .env 文件
echo "CCLOAD_PASS=your_admin_password" > .env
echo "PORT=8080" >> .env
echo "SQLITE_PATH=./data/ccload.db" >> .env

# 启动服务
./ccload

MySQL 模式： 生产环境、高并发或多实例部署建议使用 MySQL：

# 1. 创建 MySQL 数据库
mysql -u root -p -e "CREATE DATABASE ccload CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 2. 设置环境变量
export CCLOAD_PASS=your_admin_password
export CCLOAD_MYSQL="user:password@tcp(localhost:3306)/ccload?charset=utf8mb4"
export PORT=8080

# 或使用 .env 文件
echo "CCLOAD_PASS=your_admin_password" > .env
echo "CCLOAD_MYSQL=user:password@tcp(localhost:3306)/ccload?charset=utf8mb4" >> .env
echo "PORT=8080" >> .env

# 3. 启动服务（自动创建表结构）
./ccload

Docker + MySQL:

# 方式 1: docker-compose（推荐）
cat > docker-compose.mysql.yml << 'EOF'
version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: ccload
      MYSQL_USER: ccload
      MYSQL_PASSWORD: ccloadpass
    volumes:
      - mysql_data:/var/lib/mysql
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  ccload:
    image: ghcr.io/caidaoli/ccload:latest
    environment:
      CCLOAD_PASS: your_admin_password
      CCLOAD_MYSQL: "ccload:ccloadpass@tcp(mysql:3306)/ccload?charset=utf8mb4"
      PORT: 8080
    ports:
      - "8080:8080"
    depends_on:
      mysql:
        condition: service_healthy

volumes:
  mysql_data:
EOF

docker-compose -f docker-compose.mysql.yml up -d

# 方式 2: 直接运行（需要已有 MySQL 服务）
docker run -d --name ccload \
  -p 8080:8080 \
  -e CCLOAD_PASS=your_admin_password \
  -e CCLOAD_MYSQL="user:pass@tcp(mysql_host:3306)/ccload?charset=utf8mb4" \
  ghcr.io/caidaoli/ccload:latest

服务启动后访问： - 管理界面：http://localhost:8080/web/ - API 代理：POST http://localhost:8080/v1/messages - API 令牌管理：http://localhost:8080/web/tokens.html - 通过 Web 界面配置 API 访问令牌

📖 使用说明

配置完成后即可通过兼容 API 调用：

API 代理

Claude API 代理（需授权）：

先在 Web 界面配置 API 令牌，然后按 Claude API 兼容接口调用：

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -H "x-api-key: your-claude-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude!"
      }
    ]
  }'

OpenAI 兼容 API 代理（Chat Completions）：

OpenAI SDK 只需替换 base_url 即可接入，业务代码无需改动：

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

本地 Token 计数

发送请求前可用本地 Token 估算接口预估消耗，不调用上游 API：

```bash curl -X POST http://localhost:8080/v1/messages/count_tokens \ -H "Content