TokHub

TokHub 是面向 AI API 中转站的开源监控、推荐运营与 OpenAI 兼容专属网关系统。它把公开状态页、供应商排行、用户工作区、平台管理后台、分层探测、用量计量、告警审计、密钥加密和 Docker 自托管部署放在同一个系统里，适合用来搭建 AI API 服务导航、可用性监控平台、企业内部专属网关或多上游容灾入口。

English: README.en.md

它解决什么问题

AI API 中转站、模型服务商和企业自建上游通常会遇到几类问题：

• 公开页面只能展示“可用”或“不可用”，但不知道是 DNS、TLS、鉴权、模型列表还是生成链路出了问题。
• 用户有自己的私有 Key 和上游地址，却缺少统一的健康监控、配额、网关和审计。
• 平台推荐页依赖人工整理，缺少可复用的榜单规则、推荐位、点击统计和公开 Open API。
• 企业想用一个 OpenAI 兼容入口接入多个上游，但需要按延迟、成功率、成本做路由，并记录每次请求的用量和费用。
• 自托管部署不应只给源码，还需要生产预检、备份恢复、无演示数据检查、安全扫描和发布门禁。

TokHub 的目标是把这些能力做成一个可运行、可部署、可二次开发的开源基础系统。

核心能力

公开监控和推荐前台

• 公开首页、通道列表、通道详情、供应商排行和精选推荐。
• 支持按品牌、模型、状态、价格、延迟、成功率等维度组织展示。
• 前台推荐页由后台配置驱动，支持精选位、新人福利、场景推荐和多套榜单规则。
• 提供 /api/public/* 公开数据接口和 /v1/status/* 第三方只读 Open API。
• 支持生成独立通道站点资产，便于把公开监控和推荐能力拆给不同站点使用。

用户工作区

• 用户可以收藏公开通道，也可以创建自己的私有通道。
• 私有通道支持 Endpoint、模型、额度、状态、立即探测和连接测试。
• 用户工作区包含专属网关、Gateway Key、成员、用量、告警、事件和审计。
• 工作区数据按组织隔离，普通用户不能访问平台后台和其它工作区资源。

平台管理后台

• 管理平台通道、私有通道、用户、组织、成员、Gateway Key、Open API 站点和推荐运营配置。
• 支持通道 CSV 导入导出、通道同步、批量启停、批量删除和二次密码验证。
• 支持全局用量报表、请求事件、成本估算、审计导出和治理概览。
• 支持站点配置、前台文案、模型目录和价格配置的后台维护。

OpenAI 兼容专属网关

• 对外暴露 /gateway/v1/*，兼容 OpenAI 风格的 Models 和 Chat Completions 调用。
• 每个网关可以绑定多个平台上游或用户私有上游。
• Gateway Key 支持 QPS、月配额、状态管理、撤销、删除和一次性明文展示。
• 兼容非流式和流式响应，记录请求模型、上游通道、状态码、Token、延迟、成本和错误类型。

探测和健康算法

TokHub 把通道健康拆成三层，不把“接口能连上”和“模型真的能生成”混为一谈。

L1 连通性探测

L1 负责基础网络链路：

• 解析 Endpoint URL。
• DNS 解析目标主机。
• 建立 TCP 连接。
• 对 HTTPS 目标执行 TLS 握手，并记录证书过期时间。
• 发起 HTTP HEAD 请求，判断入口是否可达。

L1 能定位 dns_failed、tcp_failed、tls_failed、http 层错误和坏 Endpoint。

L2 模型可用性探测

L2 调用上游 /models，验证：

• API Key 是否有效。
• 上游是否返回可解析的模型列表。
• 当前配置的模型是否存在或可用。
• 部分供应商可按 provider profile 跳过模型列表探测。

L2 会把 401、403 识别为 auth_error，把模型缺失识别为 model_not_found。

L3 真实生成探测

L3 发起最小 Chat Completions 请求，提示词要求模型只返回固定内容，用来验证真实推理链路：

• 记录总延迟、首 Token 估算、HTTP 状态、Token 用量和成本。
• 校验生成内容是否符合预期，避免“HTTP 成功但模型没有正常生成”的假阳性。
• 对慢响应、限流、空内容、鉴权失败和模型不可用分别归类。

状态合成

系统会把 L1、L2、L3 的结果合成通道状态：

• healthy：网络、模型和生成链路正常。
• degraded：仍可用，但存在慢响应、限流、模型探测异常或局部网络问题。
• connectivity_down：基础连接或模型列表链路不可达。
• functional_down：网络可能可达，但真实生成链路失败。
• auth_error：上游凭据失效或权限不足。
• unknown：探测数据不足。

健康评分会结合当前状态和成功率生成，快照会记录 24 小时可用率、成功率、P95 延迟、L1/L2/L3 延迟、Token 和成本。

网关路由算法

专属网关会先读取网关绑定的上游，再生成候选路由：

1. 跳过未启用上游。
2. 优先过滤 connectivity_down、auth_error、functional_down 等故障上游。
3. 如果全部候选都故障，则退回到所有启用上游，避免空路由。
4. 按网关策略排序。
5. 跳过短