- 🔄 统一代理 - 一个 API 接口管理所有 AI 服务提供商（OpenAI、Claude、Gemini 等）
- ⚖️ 智能负载 - 基于权重的智能分发 + 自动故障转移 + 会话保持
- 👥 多租户 - 完整的用户体系，细粒度权限控制和配额管理
- 🔑 密钥管理 - API Key 生成、轮换、过期管理
- 📊 实时监控 - 请求统计、成本追踪、性能分析、可视化报表
- 🎨 现代 UI - 基于 Shadcn UI 的响应式管理面板，深色模式
- 🚀 生产就绪 - Docker 一键部署、自动数据库迁移、健康检查
实时统计面板 - 请求量、成本、用户活跃度一目了然
供应商管理 - 配置上游服务、权重分配、流量限制
- Docker 和 Docker Compose
- ⏱️ 仅需 2 分钟即可启动完整服务
使用 docker-compose.yaml 启动
📄 点击展开 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 状态
📝 完整环境变量配置说明
| 变量名 | 必需 | 默认值 | 说明 |
|---|---|---|---|
ADMIN_TOKEN |
✅ | change-me |
管理员登录令牌，必须修改为强密码 |
DB_USER |
❌ | postgres |
数据库用户名 |
DB_PASSWORD |
❌ | postgres |
数据库密码（生产环境建议修改） |
DB_NAME |
❌ | claude_code_hub |
数据库名称 |
AUTO_MIGRATE |
❌ | true |
启动时自动执行数据库迁移 |
生产环境安全建议：
⚠️ 必须修改ADMIN_TOKEN为强密码（≥20 字符，包含大小写字母、数字、特殊符号）⚠️ 建议修改DB_PASSWORD为强密码- 🔒 如果暴露到公网，建议配置反向代理（Nginx）+ HTTPS
- 🔒 限制数据库端口
35432的外部访问
# 查看日志
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首次访问 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 单价
- 自动计算请求成本
- 导出成本报表
查看项目的开发路线图和进度：
我们在 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 + 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_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❓ 支持哪些 AI 服务提供商？
本服务仅支持 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 许可证
如果这个项目对你有帮助，请给它一个 ⭐