TokHub

在搭建 AI API 中转站或企业内部网关时，你是否遇到过这样的困境：公开的状态页只能显示“通”或“不通”，却说不清是 DNS 解析失败、TLS 握手错误，还是模型本身不可用？或者，当你拥有多个上游供应商时，缺乏一个统一的地方来监控健康度、管理配额和审计用量？

TokHub 是一个开源的一站式解决方案。它将公开状态页、供应商排行、用户工作区、管理后台、分层探测、用量计量、告警审计以及 OpenAI 兼容网关整合在一个系统中。无论是用于搭建公共的 AI 服务导航站，还是作为企业内部的专属网关和多上游容灾入口，它都能提供完整的基础设施支持。

核心痛点与解决思路

传统的监控往往过于粗糙，无法区分网络层、鉴权层和生成层的问题。TokHub 通过三层探测机制，将通道健康度拆解得明明白白：

• L1 连通性探测：检查 DNS 解析、TCP 连接、TLS 握手（含证书过期时间）以及 HTTP HEAD 请求。它能精准定位 dns_failed、tcp_failed 或 tls_failed 等基础网络问题。
• L2 模型可用性探测：调用上游 /models 接口，验证 API Key 是否有效、模型列表是否可解析、指定模型是否存在。这能识别 auth_error（鉴权失败）或 model_not_found（模型缺失）。
• L3 真实生成探测：发起最小化的 Chat Completions 请求，要求模型返回固定内容。这不仅验证了推理链路是否通畅，还记录了总延迟、首 Token 时间、Token 用量和成本。它能捕捉到那些“HTTP 成功但模型未正常生成”的假阳性情况。

基于这三层结果，系统会合成最终状态：healthy（健康）、degraded（降级，如慢响应或限流）、connectivity_down（连接中断）、functional_down（生成失败）或 auth_error（鉴权错误）。

OpenAI 兼容专属网关

TokHub 对外暴露 /gateway/v1/* 接口，完全兼容 OpenAI 风格的 Models 和 Chat Completions 调用。

• 智能路由：网关可以绑定多个上游（包括平台公共上游和用户私有上游）。它支持三种路由策略：
  • latency：优先选择 P95 延迟最低的上游。
  • success：优先选择成功率最高的上游。
  • cost：优先选择成本最低的上游。
• 熔断与降级：系统会自动跳过短期熔断中的通道。如果所有优选上游都故障，它会退化到所有启用上游，避免服务完全中断。路由计划缓存于 Redis，即使 Redis 不可用，服务也能降级到内存熔断和数据库路由，保证核心网关能力不中断。
• 细粒度管控：Gateway Key 支持 QPS 限制、月配额管理、状态控制及一次性明文展示。每次请求都会记录模型、上游通道、状态码、Token、延迟、成本和错误类型，便于后续审计和分析。

安全与隐私保护

作为处理密钥和敏感数据的系统，TokHub 在安全设计上毫不妥协：

• 密钥加密：上游 API Key、私有通道 Key 和通知目标均使用 AES-GCM 加密存储。主密钥由环境变量 TOKHUB_SECRET_KEY 派生，生产环境强制要求至少 32 字符。
• Gateway Key 管理：使用 sk-th- 前缀随机生成，服务端仅保存 SHA-256 哈希、短前缀和掩码。完整 Key 仅在创建时展示一次，后续只能轮换或重新签发。
• 防 SSRF 攻击：在抓取官网或解析通道介绍时，系统会阻断 localhost、内网、链路本地、组播及保留地址，降低服务器端请求伪造风险。
• 审计与清理：删除通道或用户时，相关密钥材料会被彻底清理或擦除，并写入审计事件，确保数据不留痕迹。

部署与运营

TokHub 支持 Docker 自托管部署，并提供了生产预检、备份恢复、无演示数据检查和安全扫描等发布门禁功能。

• 公开前台：提供首页、通道列表、详情页、供应商排行和精选推荐。支持按品牌、模型、状态、价格、延迟等维度展示。后台可配置精选位、新人福利和场景推荐，并通过 /api/public/* 提供公开数据接口。
• 用户工作区：用户可以收藏公共通道，或创建私有通道（包含 Endpoint、模型、额度等）。工作区数据按组织隔离，普通用户无法访问其他资源。
• 管理后台：管理员可管理平台通道、用户、组织、Gateway Key 及推荐运营配置。支持 CSV 导入导出、批量启停、全局用量报表、成本估算及审计导出。

对于需要构建高可用、可监控、可审计的 AI API 服务的团队来说，TokHub 提供了一个成熟、安全且可二次开发的开源基座。它不仅解决了“能不能用”的问题，更回答了“好不好用”和“贵不贵”的问题。