# TokHub

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

English: [README.en.md](docs/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`：网络、模型和生成链路正常。