💡 致谢 本项目基于 zsio/claude-code-hub 二次开发而来。 感谢原作者 @zsio 的开源贡献!
- 🔄 统一代理 - 一个 API 接口管理所有 AI 服务提供商（OpenAI、Claude、Gemini 等）
- ⚖️ 智能负载 - 基于权重的智能分发 + 自动故障转移 + 会话保持
- 👥 多租户 - 完整的用户体系，细粒度权限控制和配额管理
- 🔑 密钥管理 - API Key 生成、轮换、过期管理
- 📊 实时监控 - 请求统计、成本追踪、性能分析、可视化报表
- 🎨 现代 UI - 基于 Shadcn UI 的响应式管理面板，深色模式
- 🚀 生产就绪 - Docker 一键部署、自动数据库迁移、健康检查
本项目基于 zsio/claude-code-hub 进行了大量增强和优化：
- 📋 详细日志记录 - 完整的请求日志，包含 Token 使用、成本计算、缓存命中等详细信息
- 🔒 并发控制 - 支持为用户和供应商设置并发 Session 限制
- ⏱️ 多时段限流 - 5小时/周/月 三个时间窗口的金额限制，更灵活的配额管理
- 📈 统计排行榜 - 日统计、月统计排行榜，快速了解用户和供应商使用情况
- 🎚️ 优先级路由 - 支持多供应商优先级和权重设置，精细化流量分配
- 🔗 决策链追踪 - 完整的供应商调用链记录，支持错误切换决策链显示
- 🛡️ 熔断保护 - 供应商出错时自动临时熔断，避免重复调用失败的服务
- 💰 价格同步 - 一键拉取 LiteLLM 模型价格表，自动更新价格信息
- 🤖 OpenAI 兼容（即将到来） - 将于下一大版本支持 Codex，包括模型重定向、价格管理
首页面板 - 系统概览与快速访问
供应商管理 - 配置上游服务、权重分配、流量限制
统计排行榜 - 用户和供应商使用情况一目了然
详细日志记录 - Token 使用、成本计算、调用链追踪
- Docker 和 Docker Compose
- ⏱️ 仅需 2 分钟即可启动完整服务
1. 配置环境变量
复制 .env.example 为 .env 并修改必要配置：
cp .env.example .envADMIN_TOKEN 为强密码！
查看完整环境变量说明：.env.example
2. 启动服务
# 启动所有服务（后台运行）
docker compose up -d
# 查看启动日志
docker compose logs -f3. 验证部署
docker compose ps确保三个容器都是 healthy 或 running 状态：
claude-code-hub-db(PostgreSQL)claude-code-hub-redis(Redis)claude-code-hub-app(应用服务)
- docker-compose.yaml - Docker Compose 配置文件
- .env.example - 环境变量配置模板
# 查看日志
docker compose logs -f # 所有服务
docker compose logs -f app # 仅应用
# 重启服务
docker compose restart app # 重启应用
# 升级到最新版本
docker compose pull && docker compose up -d
# 备份数据（数据持久化在宿主机 ./data/ 目录）
# - ./data/postgres 映射到容器 /data (PostgreSQL 数据目录: /data/pgdata)
# - ./data/redis 映射到容器 /data (Redis AOF 持久化文件)
tar -czf backup_$(date +%Y%m%d_%H%M%S).tar.gz ./data/更多管理命令
服务管理：
docker compose stop # 停止服务
docker compose down # 停止并删除容器
docker compose restart redis # 重启 Redis数据库操作：
# SQL 备份
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.sqlRedis 操作：
docker compose exec redis redis-cli ping # 检查连接
docker compose exec redis redis-cli info stats # 查看统计
docker compose exec redis redis-cli --scan # 查看所有 key
docker compose exec redis redis-cli FLUSHALL # ⚠️ 清空数据完全重置（
docker compose down && rm -rf ./data/ && docker compose up -d首次访问 http://localhost:23000
使用 ADMIN_TOKEN 登录管理后台。
进入 设置 → 供应商管理，点击"添加供应商"：
📌 重要说明：API 格式兼容性
本服务仅支持 Claude Code 格式的 API 接口（如智谱 GLM、Kimi、Packy 等）。如果您需要使用其他格式的 AI 服务，比如 Gemini、OpenAI、 Ollama 等格式，请先使用
claude-code-router进行格式转换，然后将转换后的服务地址添加到本系统。
添加用户：
- 进入 设置 → 用户管理
- 点击"添加用户"
- 配置：
- 用户名称
- 描述信息
- RPM 限制（每分钟请求数）
- 每日额度（USD）
生成 API 密钥：
- 选择用户，点击"生成密钥"
- 设置密钥名称
- 设置过期时间（可选）
⚠️ 复制并保存密钥（仅显示一次）
用户使用生成的密钥调用服务：
查看 http://localhost:23000/usage-doc
仪表盘页面提供：
- 📈 实时请求量趋势
- 💰 成本统计和分析
- 👤 用户活跃度排行
- 🔧 供应商性能对比
⚠️ 异常请求监控
进入 设置 → 价格管理，配置各模型的计费单价：
- 支持按模型配置输入/输出 Token 单价（包括 Claude 和 OpenAI 格式模型）
- 支持缓存 Token 单独定价（
cache_creation_input_tokens、cache_read_input_tokens） - 自动计算请求成本
- 导出成本报表
OpenAI 模型价格配置示例：
- 模型名称：
gpt-5-codex - 输入价格（USD/M tokens）：
0.003 - 输出价格（USD/M tokens）：
0.006
❓ 如何重置管理员密码？
编辑 .env 文件，修改 ADMIN_TOKEN，然后重启：
docker compose restart app❓ 端口已被占用怎么办？
编辑 docker-compose.yaml，修改端口映射：
services:
app:
ports:
- "8080:23000" # 修改左侧端口为可用端口❓ 数据库迁移失败怎么办？
-
检查应用日志：
docker compose logs app | grep -i migration -
手动执行迁移：
docker compose exec app pnpm db:migrate -
如果持续失败，重置数据库（
⚠️ 会丢失数据）：docker compose down && rm -rf ./data/postgres && docker compose up -d
❓ Redis 连接失败怎么办？
本服务采用 Fail Open 策略，Redis 连接失败不会影响服务可用性。
检查 Redis 状态：
docker compose ps redis
docker compose exec redis redis-cli ping # 应返回 PONGRedis 不可用时，限流功能会自动降级，所有请求仍然正常通过。
更多 Redis 操作请参考常用管理命令部分。
❓ HTTP 访问时无法登录怎么办？
问题现象：使用 HTTP 访问系统（非 localhost）时，登录页面显示 Cookie 安全警告，无法登录。
原因：默认情况下，系统启用了 Cookie 安全策略（ENABLE_SECURE_COOKIES=true），仅允许 HTTPS 传输 Cookie。浏览器会自动放行 localhost 的 HTTP 访问，但拒绝远程 HTTP。
解决方案：
方案 1：使用 HTTPS 访问（推荐）
配置反向代理（如 Nginx）并启用 HTTPS，参见下方 如何配置反向代理（Nginx + HTTPS） 部分。
方案 2：允许 HTTP Cookie（降低安全性）
编辑 .env 文件，添加或修改：
ENABLE_SECURE_COOKIES=false重启应用：
docker compose restart appfalse 会允许 HTTP 传输 Cookie，仅推荐用于内网部署或测试环境。
❓ 支持哪些 AI 服务提供商？
本服务仅支持 Claude Code 格式的 API 接口。
直接支持：
- 原生提供 Claude Code 格式接口的服务商
间接支持（需要先部署 claude-code-router 进行协议转换）：
- 🔄 智谱 AI (GLM)、Moonshot AI (Kimi)、Packy 等
- 🔄 阿里通义千问、百度文心一言等
- 🔄 其他非 Claude Code 格式的 AI 服务
❓ 如何配置反向代理（Nginx + HTTPS）？
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_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;
}
}配置 HTTPS 后，确保 .env 中 ENABLE_SECURE_COOKIES=true（默认值），以启用 Cookie 安全传输。
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
本项目采用 MIT 许可证
如果这个项目对你有帮助，请给它一个 ⭐
Based on zsio/claude-code-hub • Modified by ding113