常见问题（FAQ）

本页面汇集了 Claude Code Hub 使用过程中的常见问题及解决方案，涵盖部署、配置、使用、供应商管理、性能优化和安全等方面。如果您遇到的问题未在此列出，欢迎在 GitHub Issues 提交反馈。

部署相关问题

数据库连接失败怎么办？

可能原因：

1. DSN 环境变量格式错误
2. 数据库服务未启动
3. 网络或防火墙问题
4. 凭据不正确

解决方案：

1. 确认 DSN 格式正确：

   # 标准格式
   DSN="postgres://用户名:密码@主机:端口/数据库名"
   
   # Docker Compose 示例
   DSN="postgres://postgres:postgres@postgres:5432/claude_code_hub"
   

2. 检查数据库服务状态：

   # Docker Compose 部署
   docker compose ps
   docker compose logs postgres
   
   # 本地 PostgreSQL
   pg_isready -h localhost -p 5432
   

3. 测试数据库连接：

   # 进入数据库命令行
   docker compose exec postgres psql -U postgres -d claude_code_hub
   

Redis 离线会影响服务吗？

影响范围：

Claude Code Hub 采用 Fail-Open 策略，即 Redis 不可用时，系统会自动降级而不是拒绝请求：

建议措施：

1. 监控日志中的 Redis Error 告警
2. 确保 Redis 配置持久化以加速恢复
3. 生产环境考虑 Redis Sentinel 或 Cluster 实现高可用

# 检查 Redis 状态
docker compose logs redis
redis-cli -h localhost -p 6379 ping

如何升级到新版本？

Docker Compose 部署：

# 拉取最新镜像并重启
docker compose pull
docker compose up -d

# 查看升级日志
docker compose logs -f app

源码部署：

git pull origin main
bun install
bun run build
bun run start

配置相关问题

环境变量如何配置？

核心配置说明：

限流相关配置：

熔断器相关配置：

Cookie 无法设置导致登录失败怎么办？

问题原因：

ENABLE_SECURE_COOKIES=true（默认值）要求 HTTPS 连接才能设置 Cookie。通过 HTTP 远程访问时浏览器会拒绝设置 Secure Cookie。

解决方案：

1. 推荐：配置 HTTPS（Nginx/Caddy 反向代理 + SSL 证书）

2. 内网部署：如果是纯内网环境，可关闭安全 Cookie：

   ENABLE_SECURE_COOKIES=false
   

如何配置代理访问供应商？

在供应商管理页面为每个供应商单独配置代理：

支持的代理协议：

• HTTP 代理：http://host:port
• HTTPS 代理：https://host:port
• SOCKS5 代理：socks5://user:pass@host:port

配置步骤：

1. 进入「供应商管理」页面
2. 编辑目标供应商
3. 在「代理设置」填入代理 URL
4. 可选：启用「代理失败时直连」（proxy_fallback_to_direct）
5. 使用「测试连接」按钮验证配置

使用相关问题

客户端如何接入 Claude Code Hub？

Claude Code CLI 配置：

# 设置 API 端点
export ANTHROPIC_BASE_URL=http://your-cch-server:23000

# 设置 API Key（从 CCH 后台获取）
export ANTHROPIC_API_KEY=cch_your_api_key_here

Codex CLI 配置：

# 设置 API 端点
export OPENAI_BASE_URL=http://your-cch-server:23000/v1

# 设置 API Key
export OPENAI_API_KEY=cch_your_api_key_here

API 请求示例：

curl -X POST http://your-cch-server:23000/v1/messages \
  -H "Authorization: Bearer cch_your_api_key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

触发限流后如何处理？

当请求触发限流时，系统返回 HTTP 429 状态码并包含限流原因：

限流类型及重置机制：

处理建议：

1. 检查响应中的 x-rate-limit-* 头部了解限额详情
2. 等待限额重置或联系管理员调整配额
3. 分散请求时间，避免集中调用

如何查看我的使用情况？

管理员视角：

1. 仪表盘：查看整体调用量、成本、活跃 Session
2. 排行榜：按用户统计请求数、Token、成本
3. 日志查询：筛选特定用户的请求记录
4. 限流监控：查看限流事件统计和受影响用户

普通用户：

目前普通用户无法直接查看自己的使用情况，需联系管理员获取。

日志清理后排行榜/统计数据为什么消失了？

原因说明：

排行榜和消费统计数据是基于请求日志（message_request 表）实时计算的，系统不存在独立的统计汇总表。当日志被清理后，用于计算排行榜的原始数据已不存在，因此统计也随之消失。

建议措施：

供应商相关问题

熔断器持续打开如何排查？

熔断器状态说明：

默认熔断配置：

• 失败阈值：连续失败 5 次后触发熔断
• 熔断持续时间：30 分钟
• 恢复阈值：半开状态下成功 2 次后关闭熔断器

排查步骤：

1. 查看应用日志中的 [CircuitBreaker] 记录：

   docker compose logs app | grep CircuitBreaker
   

2. 确认失败原因：

   • 4xx 错误：检查 API Key 是否有效、额度是否充足
   • 5xx 错误：供应商服务异常
   • 网络错误：检查代理配置、DNS 解析

3. 在管理后台检查供应商健康状态

4. 如需手动恢复，可重启应用或等待熔断时间结束

提示「无可用供应商」该怎么办？

可能原因及解决方案：

查看决策链日志：

# 查看请求日志中的 providerChain 字段
# 可以看到每次供应商选择的尝试和失败原因

不同格式的 API 如何转换？

Claude Code Hub 支持多种 API 格式的自动转换：

支持的转换路径：

Claude Messages API ←→ OpenAI Chat Completions
Claude Messages API ←→ Codex Response API
Claude Messages API ←→ Gemini API

格式对应关系：

自动转换行为：

• 请求到达时自动检测格式
• 根据目标供应商类型转换请求格式
• 响应返回时转换回客户端期望的格式
• 流式响应保持正确的 SSE 格式

性能相关问题

响应延迟较高怎么优化？

延迟构成分析：

总延迟 = CCH 处理延迟 + 网络延迟 + 供应商响应延迟
         (目标 <50ms)   (取决于网络)  (取决于供应商)

CCH 侧优化：

1. 确保 Redis 正常运行：Session 和限流检查依赖 Redis
2. 减少供应商切换：合理配置权重和优先级
3. 启用 Session 粘性：SESSION_TTL 设置合理值（默认 300 秒）

网络侧优化：

1. CCH 部署在靠近用户的位置
2. 供应商选择延迟较低的节点
3. 代理配置使用低延迟线路

排查工具：

# 查看请求日志中的 durationMs 字段
# 分析各环节耗时

连接超时如何配置？

供应商超时配置：

在供应商管理页面为每个供应商配置独立的超时参数：

API 测试超时：

# 供应商测试连接的超时时间
API_TEST_TIMEOUT_MS=15000  # 默认 15 秒，范围 5000-120000

安全相关问题

API Key 如何安全存储？

CCH 的安全措施：

1. 哈希存储：API Key 使用 SHA-256 哈希后存储，数据库中不保存明文
2. 脱敏显示：管理界面仅显示 Key 的最后 4 位
3. 日志脱敏：请求日志中不记录完整的 API Key
4. 创建时显示：Key 仅在创建时完整显示一次，请务必保存

用户侧建议：

1. 不要在代码仓库中明文存储 Key
2. 使用环境变量或密钥管理服务
3. 定期轮换 API Key
4. 为不同用途创建不同的 Key

如何防止敏感内容泄露？

内置防护：

1. 敏感词过滤：在「设置 > 敏感词」配置过滤规则
2. 请求内容不默认存储：STORE_SESSION_MESSAGES=false
3. 日志脱敏：敏感信息自动脱敏

配置敏感词过滤：

1. 进入「设置 > 敏感词管理」
2. 添加需要过滤的词汇或正则表达式
3. 支持精确匹配和正则匹配
4. 匹配的请求将被拒绝并记录

管理员令牌丢失怎么办？

解决方案：

1. 修改 .env 文件中的 ADMIN_TOKEN 为新值
2. 重启应用：

   docker compose restart app
   

3. 使用新令牌登录后台

消息推送只支持企业微信吗？

不是。 Claude Code Hub 的消息推送基于标准 Webhook 协议，可以对接任何支持 Webhook 的平台。企业微信只是开箱即用的示例。

平台支持情况：

关键技术点：

Claude Code Hub 发送的请求格式：

{
  "msgtype": "markdown",
  "markdown": { "content": "消息内容" }
}

期望的成功响应：

{ "errcode": 0, "errmsg": "ok" }

只要目标平台能返回此格式的响应，就可以直接对接。否则可以通过 Cloudflare Worker 等中间层进行格式转换。

详细配置请参考：消息推送 - Webhook 配置指南

更多帮助

如果上述内容未能解决您的问题，可通过以下渠道获取帮助：

• GitHub Issues：提交问题
• Telegram 交流群：加入讨论
• 项目文档：查阅其他文档页面了解更多功能细节

相关文档

• 系统设置 - 部署和初始配置指南
• 供应商管理 - 供应商配置详解
• 限流监控 - 限流机制说明
• 可用性监控 - 熔断器和健康状态监控