Tokimorphling/tokilake-ai-gateway

Tokilake — Self-hosted AI Gateway for Distributed Local LLM GPUs

OpenAI-compatible LLM API gateway that connects Ollama, vLLM, SGLang and other GPU workers behind NAT via WebSocket/QUIC reverse tunnels.

GitHub release
GitHub stars
GitHub license
Docker
Go

Tokilake 是基于 One-API 生态构建的去中心化大模型 API 调度网关，专为分布式本地 GPU 工作节点设计。它彻底翻转了传统的 API 网关模型：不再局限于网关主动请求有公网 IP 的服务器，而是允许家庭、云端、边缘或私有数据中心的 GPU 节点（Tokiame）通过反向隧道（WebSocket 或 QUIC）主动接入中心网关（Hub）。无需公网 IP、无需配置 FRP/Ngrok 或入站防火墙规则，即可对外提供兼容 OpenAI 格式的 API。

Tokilake 基于 MartialBE/one-hub 以及后续的 One-API 生态分支持续演进而来。

你能用 Tokilake 搭建什么？

Tokilake 适用于以下场景：

- 私有部署的 AI 网关 / LLM API 聚合网关
- 兼容 OpenAI 格式的私有大模型调度与分发
- 分布式 GPU 算力池化（整合家庭、云端、工作室节点）
- 为 Ollama、vLLM、SGLang 和 ComfyUI 提供内网穿透与代理
- 搭建类似 OpenRouter 的私有模型计费与路由平台
- 零入站端口的 "自带模型" (BYOM) 基础设施
- 多租户的本地 LLM API 分发平台

📖 快速开始 / Quick Start

你可以通过 Tokilake Demo 快速体验核心功能。为了确保数据的绝对安全与分发的完全自主，我们强烈建议你参考端到端部署指南自行托管。无论你是初次体验还是准备深度部署，下方的文档都将为你提供完整指引。

- 📚 中文使用指南
- 📖 User Guide (English)
- 🖼️ 图像生成指南
- 🖼️ Image Generation Guide
- 🎬 异步视频生成
- 🎬 Async Video Generation

Tokilake vs LiteLLM, one-api, new-api and exo

Tokilake 在开源 LLM 基础设施中占据独特位置——它是唯一将 API 聚合网关、分布式 Worker 自注册 和 基于隧道的 NAT 穿透 三者合一的项目。

架构对比

┌─────────────────────────────────────────────────────────────────────┐
│                   one-api / new-api / LiteLLM                       │
│                                                                     │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐                     │
│   │ OpenAI   │    │ Claude   │    │ Gemini   │   静态后端           │
│   │ (公网)   │    │ (公网)   │    │ (公网)   │   手动配置           │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘                     │
│        └───────────────┼───────────────┘                            │
│                        ▼                                            │
│               ┌─────────────────┐                                   │
│               │   API 网关      │   无 Worker 注册                  │
│               │  (多 Provider)  │   无 NAT 穿透                     │
│               └─────────────────┘                                   │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                              exo                                    │
│                                                                     │
│   ┌─────────┐  TB5  ┌─────────┐  TB5  ┌─────────┐                 │
│   │ Mac A   │◄─────►│ Mac B   │◄─────►│ Mac C   │  一个大模型      │
│   │ 分片 1  │       │ 分片 2  │       │ 分片 3  │  拆到多设备       │
│   └─────────┘       └─────────┘       └─────────┘                  │
│                                                                     │
│   需要高速互联 (Thunderbolt / InfiniBand)                           │
│   P2P 自动发现，仅限局域网                                          │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                           Tokilake                                  │
│                                                                     │
│              ┌─────────────────────┐                                │
│              │   Tokilake 网关     │   中心节点                      │
│              │  (API 聚合调度)     │   OpenAI 兼容 API               │
│              └────────┬────────────┘                                │
│                       │                                             │
│          ┌────────────┼────────────┐                                │
│          │ WS/QUIC    │ WS/QUIC    │ WS/QUIC     NAT 穿透          │
│          │ 隧道       │ 隧道       │ 隧道        (仅出站连接)       │
│          ▼            ▼            ▼                                 │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐                           │
│   │Tokiame A │ │Tokiame B │ │Tokiame C │   独立 Worker             │
│   │ Ollama   │ │ vLLM     │ │ SGLang   │   各自跑不同模型          │
│   │ (家里)   │ │ (云端)   │ │ (边缘)   │   异构硬件                │
│   └──────────┘ └──────────┘ └──────────┘                           │
└─────────────────────────────────────────────────────────────────────┘

功能对比矩阵

| 能力 | one-api / new-api | LiteLLM | exo | Tokilake |
|---|:---:|:---:|:---:|:---:|
| 多 Provider API 聚合 | ✅ | ✅ | ❌ | ✅ |
| 静态后端配置 | ✅ | ✅ | ❌ | ✅ |
| 远程 Worker 自注册 | ❌ | ❌ | ✅ | ✅ |
| 基于隧道的 NAT 穿透 | ❌ | ❌ | ❌ | ✅ |
| 模型跨设备分片 | ❌ | ❌ | ✅ | ❌ |
| 异构硬件支持 | N/A | N/A | 有限 | ✅ |
| 支持跨公网部署 | ✅ | ✅ | ❌ | ✅ |
| Worker 零入站端口 | N/A | N/A | ❌ | ✅ |
| 心跳保活 & 自动故障转移 | ❌ | ❌ | ✅ | ✅ |

Tokilake 不是一个模型切分/分片（sharding）框架。它是一个兼容 OpenAI API 的网关，负责将请求路由给隐藏在 NAT 之后的多个独立 GPU worker。

何时选择 Tokilake

- 你的 GPU 散落在不同位置（家里、云端、边缘节点），想统一到一个 API 背后
- Worker 在 NAT/防火墙后面，不想或不能配置 FRP/Ngrok
- 不同 Worker 跑不同模型，而非把一个模型拆到多台设备
- 需要完整的 one-api 生态（计费、鉴权、分组、管理后台）加上分布式算力

🚀 一键部署 (推荐)

最快部署自带自动 HTTPS 和 QUIC 支持的 Tokilake Hub 的方法：

1. 克隆仓库
git clone https://github.com/Tokimorphling/Tokilake.git
cd Tokilake

2. 使用宿主机 nginx + Docker + Let's Encrypt 部署生产环境
sudo ./deploy/bootstrap-nginx-letsencrypt.sh \
--domain api.example.com \
--email admin@example.com \
--sql-dsn 'postgres://user:password@127.0.0.1:5432/tokilake'

部署完成后，即可通过 https://api.example.com 访问你的管理后台。

后续更新镜像：

sudo ./deploy/bootstrap-nginx-letsencrypt.sh \
--domain api.example.com \
--update

如果只想在本机快速试跑，不需要 nginx 和证书：

docker run -d \
--name tokilake-local \
--restart unless-stopped \
-p 19981:19981 \
-e TZ=Asia/Shanghai \
-e PORT=19981 \
-e GIN_MODE=release \
-e SERVER_ADDRESS="http://localhost:19981" \
-e USER_TOKEN_SECRET="$(openssl rand -hex 32)" \
-e SESSION_SECRET="$(openssl rand -hex 32)" \
-v tokilake-local-data:/data \
ghcr.io/tokimorphling/tokilake:latest

然后访问 http://localhost:19981。

🌟 核心理念

传统的 API 代理通常作为 Client，将请求路由到拥有公网 IP 地址的 Server。如果你的高算力显卡（如 RTX 4090）躺在家里的局域网内，或者散布在不同云厂商的临时竞价实例（Spot Instances）上，将其统一成稳定可用的 API 极具挑战。

Tokiame 改变了这一切。它作为一个轻量级守护进程，主动“拨号”连接到云端的 Tokilake 网关。连接成功后，Tokilake 会在系统内部将其无缝映射为一个标准的 Channel（渠道）。这意味着，你无需任何内网穿透工具（如 FRP/Ngrok），就可以享受网关自带的企业级负载均衡、高并发削峰、鉴权与计费链路。

Use Cases: AI Gateway, Local LLM, GPU Pooling and NAT Traversal

1. 个人与工作室的分布式 GPU 池化（穿透 NAT）
针对只有内网 IP 的家庭宽带或校园网环境。只需在本地运行 Tokiame 进程，立刻与云端网关打通隧道。你本地使用 Ollama / vLLM 部署的大语言模型，瞬间即可安全地对外提供标准的 OpenAI API 服务。

2. 跨云/多节点混合部署 (Hybrid Cloud Orchestration)
在不同算力平台（如 AWS, 阿里云, AutoDL, RunPod）购买了零散的 GPU 实例？不需要复杂的 SD-WAN 组网。新开实例只需附带启动 Tokiame，它便会自动注册进负载池；实例被销毁或关机时，心跳机制会自动将该节点安全下线，极大降低了运维成本。

3. 企业级数据隐私与“自带模型” (BYOM)
SaaS 服务商提供业务端，客户提供算力端。客户只需在自己绝对安全的私有机房内部署 Tokiame，单向连接到 SaaS 的网关。客户机房不暴露任何入站（Inbound）端口，即可完成业务对私有大模型的调度调用，满足极其严苛的安全审计要求。

4. 社区算力互助与 C2C 算力交易
基于内置的 私有分组 (Private Group) 和 邀请码 (Invite Code) 机制。用户 A 接入自己的算力节点，并生成一枚邀请码；用户 B 兑换邀请码后即可进入 A 的私有多租户环境调用算力，网关负责统一计费与鉴权，轻松搭建起你自己的 "OpenRouter"。

🛠 架构设计

graph TB
subgraph Users ["🌐 API 消费者"]
U1["应用 / SDK"]
U2["curl / ChatUI"]
end

subgraph Gateway ["☁️ Tokilake 网关 (Hub)"]
GIN["Gin HTTP Server"]
RELAY["Relay 路由层"]
PROV["Tokiame Provider"]
SM["Session Manager"]
DB[("DB / Channel 表")]
GIN --> RELAY --> PROV
PROV -->|"查找 Session"| SM
SM -->|"读写虚拟 Channel"| DB
end

subgraph Tunnel ["🔒 多路复用反向隧道"]
direction LR
CTRL["控制流register / heartbeat / models_sync"]
DATA["数据流TunnelRequest ↔ TunnelResponse"]
end

subgraph Workers ["🖥️ Tokiame 边缘节点 (NAT 内网)"]
W1["Tokiame 客户端 A"]
W2["Tokiame 客户端 B"]
B1["Ollama / vLLM本地 GPU"]
B2["SGLang / ComfyUI本地 GPU"]
W1 --> B1
W2 --> B2
end

U1 & U2 -->|"标准 OpenAI HTTP API"| GIN
PROV |"多路复用隧道"| Tunnel
Tunnel |"主动出站连接"| W1 & W2

- Tokilake (网关/Hub级别): 统一的流量入口。接收用户的标准 HTTP API 请求，并将其多路复用到对应的边缘节点。
- Tokiame (节点/Worker级别): 边缘侧轻量级客户端。通过 WebSocket（基于 xtaci/smux 多路复用）或 QUIC 协议维持极低延迟的反向隧道。
- tokilake-core: 独立的协议、隧道、会话和网关核心，不依赖 onehub 数据模型。📖 将 tokilake-core 集成到你自己的网关 →
- tokilake-onehub: onehub 适配层，负责把连接进来的 worker 映射为渠道、Provider 和视频任务。

传输协议选择

Tokiame 支持两种传输协议：

| 协议 | 说明 |
|------|------|
| WebSocket (默认) | 基于 xtaci/smux 流式多路复用，兼容标准 HTTP/HTTPS 网关。 |
| QUIC | 原生 QUIC 协议（quic-go），内置多路复用与 0-RTT 快速建立连接，需要 TLS 及专用 QUIC 网关端点。 |

传输模式选择（通过 TOKIAME_TRANSPORT_MODE 环境变量）：
- auto（默认）：优先尝试 QUIC，连接失败则降级到 WebSocket
- quic：仅使用 QUIC
- websocket：仅使用 WebSocket

QUIC 特别适合对延迟敏感且网络质量不稳定的场景，同时支持服务端连接迁移。

简明工作流
1. Tokiame 客户端使用标准的用户 API 令牌向 Tokilake 发起 WebSocket 或 QUIC 连接请求。
2. 网关验证通过后，自动在数据库中为其生成/绑定一个 type=100 的虚拟 Channel，并划入特定的私有分组。
3. 当用户通过网关发起大模型 HTTP 请求，网关就像处理普通渠道一样，将其透明地通过隧道流式推送给边缘层节点处理。
4. 基于实时的心跳保活。一旦边缘节点断网离线，网关将其虚拟 Channel 自动禁用摘流，实现零感知的故障转移 (Failover)。

致谢

- songquanpeng/one-api: 本项目的基础架构来源。
- Calcium-Ion/new-api: 部分供应商接入与异步任务思路参考。
- codedthemes/berry-free-react-admin-template: 前端管理台视觉基础。
- minimal-ui-kit/material-kit-react: 部分界面样式参考。
- zeromicro/go-zero: 限流器等实现参考。

Legacy README

旧版 README（历史介绍与兼容内容）