xtokenhub

# XTokenHub XTokenHub 是一个自托管的 LLM 提供商 API 聚合网关。它将你在各提供商处持有的 API 密钥收集到一个基于渠道的面板中，向客户端暴露标准化协议端点，并实时报告 Token 用量和缓存命中率。其核心设计原则是尽可能以提供商的原生协议透传流量，将协议转换作为备选方案。 ## 核心能力 - **基于渠道的密钥管理** — 每个提供商端点对应一个条目，支持可用性探测、启用/禁用切换，以及在提供商提供支持时查询余额。 - **模型分组与路由** — 每个渠道携带各自的模型列表（按需从上游拉取），所有上游合并为一个模型列表端点。路由使用优先级加加权随机选择，并在服务同一模型的渠道之间实现自动故障转移。 - **用量洞察** — 仪表板报告请求数、Token 用量、缓存命中率和平均延迟，按模型、渠道或调用方密钥聚合，并附带 GitHub 风格活动热力图和通过 WebSocket 推送的每日趋势图。 - **协议转换** — 网关同时暴露 OpenAI 风格的 chat/responses 端点和 Anthropic 风格的 messages 端点。仅当入站协议与上游协议不同时才进行转换；匹配时直接透传，据项目所述可保留工具调用和多模态载荷。 - **网关密钥与逐调用方统计** — 向不同调用方签发客户端密钥，并按密钥聚合请求和 Token 总量。 - **单二进制自托管** — 前端嵌入 Go 二进制中，构建产出单一静态制品（无需 CGO），可直接复制到 Linux 或 macOS 机器运行。 ## 路由与计量机制 README 描述的四方流程如下： 1. 创建渠道，填写提供商基础 URL、API 密钥和模型列表。认证方式（OpenAI 兼容用 Bearer，Anthropic 兼容用 x-api-key）根据基础 URL 自动检测，也可手动覆盖。支持多种基础 URL 挂载形式，包括裸域名、/v1 后缀、子路径挂载（如 /anthropic）以及版本化挂载。 2. 原生协议探针向各协议的端点发送最小请求；收到 2xx 响应即标记该协议为该渠道的原生协议，也可手动修正。 3. 入站请求过滤到服务目标模型且已启用的渠道，优先选择原生协议渠道，仅在必要时回退到转换渠道。选路按优先级升序排列并加入加权随机，遇到网络错误、401/403/408/429 或 5xx 等失败触发故障转移。 4. 能从上游响应中解析到的用量数据直接采用（自动附加流式用量选项）；上游未报告时则使用本地启发式估算。缓存命中率来自提供商的缓存 Token 字段，每条请求均写入日志表并推送到 UI。 ## 仪表板与 API 接口 管理 API 涵盖渠道管理、网关密钥管理、请求日志（含保留清理）、一组统计端点（摘要、每日趋势、按模型、按渠道、按密钥、终身总计及模型趋势），以及健康检查和用于实时事件的 WebSocket 端点。网关端点包括合并后的模型列表，以及 chat、responses 和 messages 路由。调用方认证支持 Bearer 令牌或 x-api-key 头，可通过配置关闭。 ## 配置与运维 配置优先级为环境变量 > YAML 文件 > 内置默认值。数据存储在 SQLite WAL 模式下单写连接。请求日志默认无上限增长，因此设有保留任务删除超过配置天数以外的行，支持设置周期间隔、批次大小及可选的 VACUUM 操作。项目注明 SQLite 文件在删除后不会自动缩小。 ## 测试 单元测试位于镜像外部测试包结构中，覆盖配置加载、内存 SQLite 存储库、事件总线、WebSocket 行为、通过模拟上游的提供商探测与转换、网关选路与统计持久化，以及端到端处理器/路由器路径。README 报告全量并发安全测试已通过，语句覆盖率达 87.6%，另含前端 WebSocket 重连和数据变换测试。 ## 项目已知限制 - 转换路径仅处理文本聊天；工具调用、多模态和缓存控制载荷需依赖原生透传渠道。 - 余额查询目前仅覆盖 DeepSeek，其他提供商的余额 API 因未公开文档、需过期 Cookie 认证或非公开而无法支持。 - 本地 Token 估算基于启发式规则，仅作为备选。 - 管理 API 无登录认证，面向自托管内网使用并依赖网络隔离；密钥以明文存储。 - 缓存命中率和逐密钥聚合基于请求日志快照，因此已删除密钥的历史用量仍保留在其名称下。 ## 配套应用与许可 独立的 SwiftUI 菜单栏应用复用相同的管理 API 和 WebSocket，无需修改后端。XTokenHub 以 MIT 许可证发布。