[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92300":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},92300,"TokHub","yaojingang\u002FTokHub","yaojingang","AI API 中转站监控、推荐运营与 OpenAI 兼容专属网关系统，支持分层探测、健康评分、用量计量、告警审计和 Docker 自托管。","https:\u002F\u002Fwww.tokhub.me\u002F",null,"TypeScript",177,16,1,0,41,47.79,"Apache License 2.0",false,"main",true,[],"2026-07-22 04:02:05","# TokHub\n\nTokHub 是面向 AI API 中转站的开源监控、推荐运营与 OpenAI 兼容专属网关系统。它把公开状态页、供应商排行、用户工作区、平台管理后台、分层探测、用量计量、告警审计、密钥加密和 Docker 自托管部署放在同一个系统里，适合用来搭建 AI API 服务导航、可用性监控平台、企业内部专属网关或多上游容灾入口。\n\nEnglish: [README.en.md](docs\u002FREADME.en.md)\n\n## 它解决什么问题\n\nAI API 中转站、模型服务商和企业自建上游通常会遇到几类问题：\n\n- 公开页面只能展示“可用”或“不可用”，但不知道是 DNS、TLS、鉴权、模型列表还是生成链路出了问题。\n- 用户有自己的私有 Key 和上游地址，却缺少统一的健康监控、配额、网关和审计。\n- 平台推荐页依赖人工整理，缺少可复用的榜单规则、推荐位、点击统计和公开 Open API。\n- 企业想用一个 OpenAI 兼容入口接入多个上游，但需要按延迟、成功率、成本做路由，并记录每次请求的用量和费用。\n- 自托管部署不应只给源码，还需要生产预检、备份恢复、无演示数据检查、安全扫描和发布门禁。\n\nTokHub 的目标是把这些能力做成一个可运行、可部署、可二次开发的开源基础系统。\n\n## 核心能力\n\n### 公开监控和推荐前台\n\n- 公开首页、通道列表、通道详情、供应商排行和精选推荐。\n- 支持按品牌、模型、状态、价格、延迟、成功率等维度组织展示。\n- 前台推荐页由后台配置驱动，支持精选位、新人福利、场景推荐和多套榜单规则。\n- 提供 `\u002Fapi\u002Fpublic\u002F*` 公开数据接口和 `\u002Fv1\u002Fstatus\u002F*` 第三方只读 Open API。\n- 支持生成独立通道站点资产，便于把公开监控和推荐能力拆给不同站点使用。\n\n### 用户工作区\n\n- 用户可以收藏公开通道，也可以创建自己的私有通道。\n- 私有通道支持 Endpoint、模型、额度、状态、立即探测和连接测试。\n- 用户工作区包含专属网关、Gateway Key、成员、用量、告警、事件和审计。\n- 工作区数据按组织隔离，普通用户不能访问平台后台和其它工作区资源。\n\n### 平台管理后台\n\n- 管理平台通道、私有通道、用户、组织、成员、Gateway Key、Open API 站点和推荐运营配置。\n- 支持通道 CSV 导入导出、通道同步、批量启停、批量删除和二次密码验证。\n- 支持全局用量报表、请求事件、成本估算、审计导出和治理概览。\n- 支持站点配置、前台文案、模型目录和价格配置的后台维护。\n\n### OpenAI 兼容专属网关\n\n- 对外暴露 `\u002Fgateway\u002Fv1\u002F*`，兼容 OpenAI 风格的 Models 和 Chat Completions 调用。\n- 每个网关可以绑定多个平台上游或用户私有上游。\n- Gateway Key 支持 QPS、月配额、状态管理、撤销、删除和一次性明文展示。\n- 兼容非流式和流式响应，记录请求模型、上游通道、状态码、Token、延迟、成本和错误类型。\n\n## 探测和健康算法\n\nTokHub 把通道健康拆成三层，不把“接口能连上”和“模型真的能生成”混为一谈。\n\n### L1 连通性探测\n\nL1 负责基础网络链路：\n\n- 解析 Endpoint URL。\n- DNS 解析目标主机。\n- 建立 TCP 连接。\n- 对 HTTPS 目标执行 TLS 握手，并记录证书过期时间。\n- 发起 HTTP HEAD 请求，判断入口是否可达。\n\nL1 能定位 `dns_failed`、`tcp_failed`、`tls_failed`、`http` 层错误和坏 Endpoint。\n\n### L2 模型可用性探测\n\nL2 调用上游 `\u002Fmodels`，验证：\n\n- API Key 是否有效。\n- 上游是否返回可解析的模型列表。\n- 当前配置的模型是否存在或可用。\n- 部分供应商可按 provider profile 跳过模型列表探测。\n\nL2 会把 401、403 识别为 `auth_error`，把模型缺失识别为 `model_not_found`。\n\n### L3 真实生成探测\n\nL3 发起最小 Chat Completions 请求，提示词要求模型只返回固定内容，用来验证真实推理链路：\n\n- 记录总延迟、首 Token 估算、HTTP 状态、Token 用量和成本。\n- 校验生成内容是否符合预期，避免“HTTP 成功但模型没有正常生成”的假阳性。\n- 对慢响应、限流、空内容、鉴权失败和模型不可用分别归类。\n\n### 状态合成\n\n系统会把 L1、L2、L3 的结果合成通道状态：\n\n- `healthy`：网络、模型和生成链路正常。\n- `degraded`：仍可用，但存在慢响应、限流、模型探测异常或局部网络问题。\n- `connectivity_down`：基础连接或模型列表链路不可达。\n- `functional_down`：网络可能可达，但真实生成链路失败。\n- `auth_error`：上游凭据失效或权限不足。\n- `unknown`：探测数据不足。\n\n健康评分会结合当前状态和成功率生成，快照会记录 24 小时可用率、成功率、P95 延迟、L1\u002FL2\u002FL3 延迟、Token 和成本。\n\n## 网关路由算法\n\n专属网关会先读取网关绑定的上游，再生成候选路由：\n\n1. 跳过未启用上游。\n2. 优先过滤 `connectivity_down`、`auth_error`、`functional_down` 等故障上游。\n3. 如果全部候选都故障，则退回到所有启用上游，避免空路由。\n4. 按网关策略排序。\n5. 跳过短期熔断中的通道。\n6. 把本次路由计划写入 Redis，便于观测和后续扩展。\n\n支持三种策略：\n\n- `latency`：按 P95 延迟从低到高排序，同分时健康评分高的优先。\n- `success`：按成功率从高到低排序，同分时健康评分高的优先。\n- `cost`：按成本从低到高排序，同分时健康评分高的优先。\n\nRedis 还承担 Gateway QPS 秒级桶、通道短期熔断标记和路由计划缓存。即使 Redis 不可用，服务也会降级到内存熔断和数据库路由，不直接中断核心网关能力。\n\n## 安全和加密\n\nTokHub 默认把密钥材料当作生产数据处理。\n\n- 上游 API Key、私有通道 Key 和通知目标使用 AES-GCM 加密保存。\n- 主密钥由 `TOKHUB_SECRET_KEY` 派生，生产环境要求至少 32 字符。\n- 每次加密使用随机 nonce，数据库保存 ciphertext、nonce、mask 和 fingerprint。\n- Gateway Key 使用 `sk-th-` 前缀随机生成，服务端保存 SHA-256 哈希、短前缀和 mask。\n- 完整 Gateway Key 只在创建响应中展示一次，后续只能轮换或重新签发。\n- 登录密码使用 bcrypt 保存，Session Token 只保存哈希。\n- 浏览器写操作使用 Cookie + CSRF Token 双重校验。\n- 生产环境要求 `TOKHUB_SESSION_SECURE=true`，避免明文 Cookie。\n- 官网抓取和通道介绍解析会阻断 localhost、内网、链路本地、组播、保留地址和文档网段，降低 SSRF 风险。\n- 删除通道、删除用户和治理动作会清理或擦除相关密钥材料，并写入审计事件。\n\n## 技术栈\n\n| 层级 | 技术 |\n| --- | --- |\n| 后端 | Go、go-chi、pgx、sqlc、bcrypt |\n| 前端 | React、Vite、TypeScript、React Router、Radix UI |\n| 数据库 | PostgreSQL、TimescaleDB、迁移 SQL、sqlc 生成查询 |\n| 缓存和限流 | Redis |\n| 事件和任务扩展 | NATS |\n| 探测和网关 | L1\u002FL2\u002FL3 Probe、OpenAI 兼容网关、Anthropic\u002FGemini\u002FOpenAI 适配 |\n| 部署 | Dockerfile、Docker Compose、分 role Compose、Helm 模板 |\n| 验证 | Go test、go vet、TypeScript、Vite build、Playwright、发布脚本和安全扫描 |\n\n## 架构特点\n\n### 单入口，多角色\n\n后端只有一个 Go 入口 `cmd\u002Ftokhub`，通过 `TOKHUB_ROLE` 切换运行角色：\n\n- `all`：单进程运行 Web、API、Gateway、探测和任务能力，适合本地和小团队自托管。\n- `api`：只运行公开前台、用户控制台、平台后台和 Open API。\n- `gateway`：只运行 OpenAI 兼容专属网关。\n- `prober`：运行探测任务。\n- `worker`：运行异步任务扩展。\n- `migrate`：执行数据库迁移。\n- `seed`：初始化管理员、默认组织、站点配置和模型目录。\n\n### 从单容器到分角色\n\n默认部署用单容器 Compose，适合最小化运维成本。需要扩展时，可以叠加 `deploy\u002Fcompose\u002Fdocker-compose.roles.yml`，把 API、Gateway、Prober 和 Worker 拆开部署。\n\n### 数据模型围绕真实运营\n\n核心表包括用户、组织、通道、通道凭据、模型目录、模型价格、探测运行、探测快照、Incident、Gateway、Gateway Key、请求事件、用量 Rollup、告警、通知通道、审计和 Open API 站点。它不是只给演示用的状态页模型，而是面向运营、监控和网关调用的完整数据边界。\n\n### 发布硬化\n\n仓库包含开源发布预检、生产变量预检、无演示数据检查、备份、恢复演练、安全扫描、Compose 配置校验、Docker 构建和 smoke 测试脚本。发布前可以用一个命令跑基础门禁。\n\n## 快速启动\n\n```bash\ncp -n .env.example .env || true\ndocker compose up -d --build\n```\n\n默认入口：\n\n- Web \u002F API \u002F Gateway：`http:\u002F\u002Flocalhost:8080`\n- OpenAPI：`http:\u002F\u002Flocalhost:8080\u002Fopenapi.yaml`\n- Metrics：`http:\u002F\u002Flocalhost:8080\u002Fmetrics`\n- Gateway：`http:\u002F\u002Flocalhost:8080\u002Fgateway\u002Fv1\u002F*`\n- 本地开发管理员账号：`admin`\n- 本地开发默认密码：`admin@tokhub.local`\n\n上述账号和密码也是默认后台管理入口的登录账号和登录密码，只用于本地开发。生产环境必须在 `.env.production` 中替换 `TOKHUB_ADMIN_PASSWORD` 和 `TOKHUB_SECRET_KEY`。\n\n服务启动后的轻量冒烟：\n\n```bash\nTOKHUB_BASE_URL=http:\u002F\u002Flocalhost:8080 npm run test:smoke\n```\n\n## 本地验收\n\n基础检查：\n\n```bash\ngo test .\u002F...\ngo vet .\u002F...\nsqlc generate\nnpm run typecheck\nnpm run lint\nnpm run build\nnpm run test:security\ndocker compose config\n```\n\n应用启动后可以继续跑：\n\n```bash\nnpm run test:ops\nnpm run test:restore\nnpm run test:e2e\nnpm run test:visual\n```\n\n发布前建议运行：\n\n```bash\ndeploy\u002Fscripts\u002Frelease-check.sh\n```\n\n如果本地 Docker 服务已启动，并且要做完整发布检查：\n\n```bash\nRUN_DB_CHECK=1 RUN_RESTORE=1 RUN_E2E=1 RUN_VISUAL=1 RUN_SMOKE=1 deploy\u002Fscripts\u002Frelease-check.sh\n```\n\n## 生产部署\n\n生产环境不要使用 `.env.example` 中的开发默认值。至少需要准备：\n\n- `TOKHUB_PUBLIC_URL`\n- `TOKHUB_ADMIN_EMAIL`\n- `TOKHUB_ADMIN_PASSWORD`\n- `TOKHUB_SECRET_KEY`\n- `DATABASE_URL`\n- `REDIS_URL`\n- `NATS_URL`\n- `SMTP_URL`，如果需要真实邮件通知\n\n生产环境推荐保持：\n\n- `TOKHUB_ENV=production`\n- `TOKHUB_SEED_MODE=prod`\n- `TOKHUB_UPSTREAM_MODE=real`\n- `TOKHUB_SESSION_SECURE=true`\n- `TOKHUB_EXPOSE_DEV_TOKENS=false`\n\n单容器发布：\n\n```bash\ncp .env.production.example .env.production\n# 填入真实密钥、域名和外部依赖地址\ndeploy\u002Fscripts\u002Fpreflight.sh --env-file .env.production\ndocker compose --env-file .env.production up -d --build\ncurl -fsS \"$TOKHUB_PUBLIC_URL\u002Fhealthz\"\ncurl -fsS \"$TOKHUB_PUBLIC_URL\u002Freadyz\"\n```\n\n分角色发布：\n\n```bash\ndocker compose --env-file .env.production -f docker-compose.yml -f deploy\u002Fcompose\u002Fdocker-compose.roles.yml up -d --build\n```\n\n更多细节见 [部署说明](docs\u002FDEPLOYMENT.md)、[发布流程](docs\u002FRELEASE.md) 和 [恢复演练](docs\u002FRECOVERY-DRILL.md)。\n\n## API\n\n- 人可读 API 接入说明：[docs\u002FAPI.md](docs\u002FAPI.md)\n- 机器可读 OpenAPI 合同：[docs\u002Fopenapi.yaml](docs\u002Fopenapi.yaml)\n- 管理员 Agent API：[docs\u002Fadmin-agent-api.md](docs\u002Fadmin-agent-api.md)\n- 管理员 Agent OpenAPI：[docs\u002Fadmin-agent.openapi.yaml](docs\u002Fadmin-agent.openapi.yaml)\n- 运行中服务 OpenAPI：`http:\u002F\u002Flocalhost:8080\u002Fopenapi.yaml`\n\n主要 API 分层：\n\n- `\u002Fapi\u002Fpublic\u002F*`：公开前台数据。\n- `\u002Fapi\u002Fauth\u002F*`：注册、登录、会话、邮箱验证和密码重置。\n- `\u002Fapi\u002Fme\u002F*`：个人收藏和私有通道。\n- `\u002Fapi\u002Fconsole\u002F*`：用户或企业工作区。\n- `\u002Fapi\u002Fadmin\u002F*`：平台管理后台。\n- `\u002Fv1\u002Fstatus\u002F*`：第三方状态 Open API。\n- `\u002Fgateway\u002Fv1\u002F*`：OpenAI 兼容专属网关。\n\n## 目录\n\n- `cmd\u002Ftokhub\u002F`：单入口进程，按 `TOKHUB_ROLE` 启动不同角色。\n- `internal\u002F`：后端模块，包括 API、认证、加密、探测、网关、事件和数据访问。\n- `web\u002F`：React \u002F Vite 前端。\n- `db\u002F`：数据库迁移和 sqlc 查询。\n- `deploy\u002F`：Compose、Helm、备份恢复、压测和发布脚本。\n- `docs\u002F`：API、部署、发布、恢复、开源规则和机器合同文档。\n- `tests\u002F`：Playwright 端到端和视觉测试。\n\n## 开源发布\n\n开源首发前请先阅读 [docs\u002FOPEN_SOURCE.md](docs\u002FOPEN_SOURCE.md)。不要使用 `git add .` 做首个公开提交，按文档中的 allowlist staging，避免把 `.env`、备份、临时目录、本地二进制、私有评审和原型材料带进公开仓库。\n\n开源发布预检：\n\n```bash\nnpm run open-source:preflight\n```\n\n## License\n\nTokHub is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n","TokHub 是一个开源的 AI API 中转站统一管理平台，提供 OpenAI 兼容网关、分层健康探测（L1\u002FL2\u002FL3）、用量计量、告警审计与推荐运营能力。它支持多上游路由（按延迟\u002F成功率\u002F成本策略）、密钥 AES-GCM 加密存储、Docker 一键自托管，并内置公开监控前台、用户私有工作区和平台管理后台。适用于构建 AI 服务导航门户、企业级 AI 网关、多模型供应商可用性监控平台及内部 AI 资源治理系统。",2,"2026-07-08 04:30:02","CREATED_QUERY"]