Claude Code Hub

Name: claude-code-hub
Author: zsio

🚀 智能 AI API 代理中转服务平台

专为需要统一管理多个 AI 服务提供商的团队和企业设计

功能特性 • 快速部署 • 使用指南 • 路线图 • 常见问题

✨ 功能特性

核心能力

🔄 统一代理 - 一个 API 接口管理所有 AI 服务提供商（OpenAI、Claude、Gemini 等）
⚖️ 智能负载 - 基于权重的智能分发 + 自动故障转移 + 会话保持
👥 多租户 - 完整的用户体系，细粒度权限控制和配额管理
🔑 密钥管理 - API Key 生成、轮换、过期管理
📊 实时监控 - 请求统计、成本追踪、性能分析、可视化报表
🎨 现代 UI - 基于 Shadcn UI 的响应式管理面板，深色模式
🚀 生产就绪 - Docker 一键部署、自动数据库迁移、健康检查

界面预览

统计面板

实时统计面板 - 请求量、成本、用户活跃度一目了然

供应商管理

供应商管理 - 配置上游服务、权重分配、流量限制

🚀 快速部署

前置要求

Docker 和 Docker Compose
⏱️ 仅需 2 分钟即可启动完整服务

一键部署

使用 docker-compose.yaml 启动

services:
  postgres:
    image: postgres:18
    container_name: claude-code-hub-db
    restart: unless-stopped
    ports:
      - "35432:5432"
    environment:
      POSTGRES_USER: ${DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
      POSTGRES_DB: ${DB_NAME:-claude_code_hub}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-postgres} -d ${DB_NAME:-claude_code_hub}"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s

  app:
    image: zsio/claude-code-hub:latest
    container_name: claude-code-hub-app
    depends_on:
      postgres:
        condition: service_healthy
    env_file:
      - ./.env
    environment:
      NODE_ENV: production
      PORT: 23000
      DSN: postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@postgres:5432/${DB_NAME:-claude_code_hub}
    ports:
      - "23000:23000"
    restart: unless-stopped

volumes:
  postgres_data:
    driver: local

启动服务

# 启动所有服务（后台运行）
docker compose up -d

# 查看启动日志
docker compose logs -f

验证部署

检查服务状态

docker compose ps

确保两个容器都是 healthy 或 running 状态

环境变量配置

在项目根目录创建 .env 文件：

# 管理员登录令牌（必须修改为强密码）
ADMIN_TOKEN=!!!change-me-to-a-strong-password!!!

# 数据库配置（可选，已有默认值）
DB_USER=postgres
DB_PASSWORD=!!!change-me!!!
DB_NAME=claude_code_hub

| 变量名 | 必需 | 默认值 | 说明 | |--------|------|--------|------| | ADMIN_TOKEN | ✅ | change-me | 管理员登录令牌，必须修改为强密码 | | DB_USER | ❌ | postgres | 数据库用户名 | | DB_PASSWORD | ❌ | postgres | 数据库密码（生产环境建议修改） | | DB_NAME | ❌ | claude_code_hub | 数据库名称 | | AUTO_MIGRATE | ❌ | true | 启动时自动执行数据库迁移 |

管理命令

# 查看日志
docker compose logs -f          # 所有服务
docker compose logs -f app      # 仅应用
docker compose logs -f postgres # 仅数据库

# 重启服务
docker compose restart          # 重启所有
docker compose restart app      # 仅重启应用

# 停止服务
docker compose stop             # 停止但保留容器
docker compose down             # 停止并删除容器

# 升级到最新版本
docker compose pull             # 拉取最新镜像
docker compose up -d            # 重新创建容器（自动迁移）

# 备份数据
docker exec claude-code-hub-db pg_dump -U postgres claude_code_hub > backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复数据
docker exec -i claude-code-hub-db psql -U postgres claude_code_hub < backup.sql

# 完全清理（⚠️ 会删除所有数据）
docker compose down -v

📖 使用指南

1️⃣ 初始设置

首次访问 http://localhost:23000 使用 ADMIN_TOKEN 登录管理后台。

2️⃣ 添加 AI 服务提供商

进入 设置 → 供应商管理，点击"添加供应商"：

📌 重要说明：API 格式兼容性

本服务仅支持 Claude Code 格式的 API 接口（如智谱 GLM、Kimi、Packy 等）。如果您需要使用其他格式的 AI 服务，比如 Gemini、OpenAI、 Ollama 等格式，请先使用 claude-code-router 进行格式转换，然后将转换后的服务地址添加到本系统。

3️⃣ 创建用户和密钥

添加用户：

进入 设置 → 用户管理
点击"添加用户"
配置：
- 用户名称
- 描述信息
- RPM 限制（每分钟请求数）
- 每日额度（USD）

生成 API 密钥：

选择用户，点击"生成密钥"
设置密钥名称
设置过期时间（可选）
⚠️ 复制并保存密钥（仅显示一次）

4️⃣ 使用代理 API

用户使用生成的密钥调用服务：查看 http://localhost:23000/usage-doc

5️⃣ 监控和统计

仪表盘页面提供：

📈 实时请求量趋势
💰 成本统计和分析
👤 用户活跃度排行
🔧 供应商性能对比
⚠️ 异常请求监控

6️⃣ 配置模型价格

进入 设置 → 价格管理，配置各模型的计费单价：

支持按模型配置输入/输出 Token 单价
自动计算请求成本
导出成本报表

🗺️ 路线图

查看项目的开发路线图和进度：

📋 查看完整路线图

近期计划

我们在 GitHub Projects 上维护详细的开发路线图，包括：

欢迎在 Issues 中提出您的功能建议！

🛠️ 常见问题

编辑 .env 文件，修改 ADMIN_TOKEN，然后重启应用：

docker compose restart app

编辑 docker-compose.yaml，修改端口映射：

services:
  app:
    ports:
      - "8080:23000"  # 将 23000 改为任意可用端口

  postgres:
    ports:
      - "15432:5432"  # 修改数据库端口

# 实时查看应用日志
docker compose logs -f app

# 查看最近 200 行日志
docker compose logs --tail=200 app

# 查看数据库日志
docker compose logs -f postgres

检查数据库连接：

docker compose exec app sh -c 'echo "SELECT version();" | psql $DSN'

查看应用日志：

docker compose logs app | grep -i migration

手动执行迁移：

docker compose exec app pnpm db:migrate

如果持续失败，可以重置数据库（⚠️ 会丢失数据）：
```
docker compose down -v
docker compose up -d
```

Nginx 配置示例：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:23000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

自动备份（推荐）：

# 添加到 crontab（每天凌晨 2 点备份）
0 2 * * * docker exec claude-code-hub-db pg_dump -U postgres claude_code_hub | gzip > /backup/claude_$(date +\%Y\%m\%d).sql.gz

手动备份：

docker exec claude-code-hub-db pg_dump -U postgres claude_code_hub > backup.sql

恢复数据：

docker exec -i claude-code-hub-db psql -U postgres claude_code_hub < backup.sql

本服务仅支持 Claude Code 格式的 API 接口。

直接支持：

✅ 原生提供 Claude Code 格式接口的服务商

间接支持（需要先部署 claude-code-router 进行协议转换）：

🔄 智谱 AI (GLM)
🔄 Moonshot AI (Kimi)
🔄 Packy
🔄 阿里通义千问
🔄 百度文心一言
🔄 其他非 Claude Code 格式的 AI 服务

接入流程：

部署 claude-code-router 服务
在 router 中配置需要接入的上游 AI 服务
将 router 的地址作为供应商添加到本系统

使用 Docker 健康检查：

docker compose ps

查看容器资源使用：

docker stats claude-code-hub-app claude-code-hub-db

集成监控工具（可选）：

Prometheus + Grafana
Uptime Kuma
Zabbix

数据库优化：
- 定期执行 VACUUM ANALYZE
- 根据实际负载调整连接池大小
- 为高频查询字段添加索引
应用层优化：
- 启用 Redis 缓存（可选）
- 调整 Node.js 内存限制
- 使用 CDN 缓存静态资源
基础设施：
- 使用 SSD 存储
- 增加服务器内存
- 配置负载均衡（多实例部署）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证

🌟 Star History

如果这个项目对你有帮助，请给它一个 ⭐

📞 支持与反馈

🐛 报告问题 • 💡 功能建议 • 📖 查看文档

Made with ❤️ by zsio

claude-code-hub

Related Skills

Popular in API Integration