中转塔台 · Relay Tower

AI 大模型聚合中转网关 · 上游倍率差分监控 · 统一入口切线 · Prompt Cache 路由亲和 · Telegram 移动端调度

English · 简体中文 · 为什么选择本项目？ · 核心特性 · 系统架构 · 快速开始 · 客户端接入 · 常见问题

📌 GitHub 检索与技术标签 (Topics & Tags)

Keywords: ai-gateway llm-proxy claude-code cursor-ai deepseek-api openai-proxy anthropic-proxy new-api one-api prompt-cache rate-limiter circuit-breaker load-balancer telegram-bot docker-compose reverse-proxy

📖 项目简介

在当下的大模型（LLM）API 分发与中转站运营中，开发者与中转站运营者面临着几大核心痛点：

1. 上游悄悄调高倍率：上游供应商可能在半夜或高峰期暗中上涨进货倍率，导致中转站产生巨额亏损；
2. 多渠道分流影响 Prompt Cache：同一上下文在不同服务商或节点间分流，可能降低提示词缓存命中率，增加 Token 费用和延迟；
3. 突发断流与宕机无法离机切线：深夜上游突然宕机或被封禁，运维无法立刻开电脑登录后台切换通道；
4. 客户端热切换成本高：传统中转系统切换渠道需要客户端重启或重新配置。

中转塔台 (Relay Tower) 是开源大模型中转网关与监控调度系统，包含上游倍率监控、统一反向代理网关 (/v1)、Telegram 手机端切线机器人以及 Sub2API 容器化部署配置。

⚖️ 为什么选择 中转塔台 (Relay Tower)？(横向对比)

✨ 核心特性矩阵

1. 📊 实时上游倍率大盘与智能探针

• 成本倍率即时透视：支持自动对接主流 New-API / One-API /api/pricing 价格探针，实时大盘呈现各渠道最新进货倍率（如 0.65x, 0.85x, 1.10x）。
• 网络延迟与真实连通性探活：周期性向各上游渠道发起轻量探针，毫秒级反馈延迟（ms）与健康状态。
• 进销毛利动态核算：结合终端销售分组倍率，自动核算毛利差（Spread）与利润率（Margin %），实时高亮亏损通道。

2. 🚨 差分调价感知与高危涨价强告警

• 定时差分检测：每轮倍率检查比较变化幅度（如 0.65x -> 1.10x (+69.2%)），默认周期为 5 分钟；通道探活默认每 3 小时执行，可手动触发检查。检测速度受周期及上游响应影响。
• 全维度立体报警：屏幕居中强警示弹窗 + Web Audio 合成声效警报 + 完整调价审计日志。
• 主力通道涨价一键熔断：当正在出海的主力通道被上游暗度陈仓涨价时，系统自动触发红色高危警报，并在消息界面提供“一键切换到更低倍率备选通道”快捷按钮。

3. 🔒 单主调独占与 Prompt Cache 路由亲和

• 减少双开分流：适用分组保留一个主调，同组独立通道设为冷备 (schedulable=false, priority=10)；跨组共享渠道自动保留全局调度开关，仅调低组内优先级 (priority=10)，杜绝跨组误杀，完全支持一个渠道挂载多个业务分组。
• 缓存亲和：尽量将后续请求交给同一上游通道，减少跨通道分流。上游仍可在内部调度不同实例；实际缓存命中率和节省金额取决于上游缓存策略、请求内容与有效期，不保证物理实例固定或特定命中率。
• 原子互斥交接：切线操作（手动切换或自动熔断）执行原子 SQL 事务，瞬间关停旧主调、激活新主调，切线瞬间零分流冗余。

4. ⚡ 统一反向代理网关 (Smart Proxy Gateway)

• 统一接入终结点：对外开放统一端口 http://localhost:3300/v1。
• 统一入口切换：客户端（Claude Code CLI、Cursor、CC Switch、Chatbox、NextChat）配置此端口后，无需修改入口即可让后续请求使用新主调。已有请求不会迁移，故障请求仍可能需要重试。
• 🛡️ 专属网关密钥鉴权 (Gateway Key)：外部请求调用 /v1/* 强制校验 Authorization: Bearer <Gateway-Key> 或 x-api-key，杜绝未授权外部访问盗刷上游高价值商业 Token；本地回环 (127.0.0.1) 自动放行。密钥可在中控台【安全设置】随时查看、复制与重置。
• ⚡ 标准 HTTP 502/503 异常透传：彻底杜绝 Mock 伪造 200 假响应。上游连接失败返回 502 Bad Gateway，无可用上游返回 503 Service Unavailable，确保客户端自动触发错误重试。
• 🔒 独家单主 Prompt Cache 排他保护：即使开启按成本自动准入，系统亦自动保留副调与备用渠道的冷备状态 (schedulable=false)，避免多节点轮询导致缓存击穿。
• 💾 操作系统级原子写盘：配置持久化采用 .tmp + renameSync 原子替换，规避高并发和异常关机时的 JSON 文件截断风险。
• 内置代理分流验证器：中控台内嵌真实请求测试器，可随时模拟客户端调用，即时核验当前生效通道的分流效果。

5. ✈️ Telegram 机器人离机中控 (Telegram Bot Remote Console)

• 离机实时预警推送：
  • 上游进货倍率变动实时告警（附带涨跌百分比与变动渠道）；
  • 主力通道涨价高危警报（消息底部附带低价备用线路的 一键切换交互按钮）；
  • 首字延迟 (TTFT) 超时熔断或上游宕机切线报告。
• 手机端双向交互与一键切线：
  • /status：查看当前主力通道、进货倍率、销售毛利率、延迟与自动切线状态；
  • /switch：弹出所有上游通道的 Inline Keyboard 点击交互按钮，在手机上点击任意渠道秒级完成调度切线；
  • /auto：在手机上一键开关自动切线保护，或切换成本优先/极速优先策略；
  • /rates：输出所有上游渠道进货倍率从低到高天梯榜；
  • /check：立即发起全量上游价格探针与测速巡检。
• 长轮询架构：采用 Long Polling 机制，内网、本地 Docker、无公网 IP VPS 均无需域名或 SSL 证书即可开箱即用。

6. 🛡️ 自动化故障转移与首字延迟 (TTFT) 熔断

• 实时统计真实流式请求的建立时间与首字时间（Time to First Token）。当检测到通道故障、5xx 错误超标或首字等待超时（TTFT Spike）时，自动平滑转移至备选候选池。

🏗️ 系统架构

flowchart TD
    subgraph Clients["客户端与开发者工具 (Developer Clients)"]
        C1["Claude Code CLI"]
        C2["Cursor / VS Code"]
        C3["CC Switch / Chatbox"]
        C4["OpenAI / Anthropic SDK"]
    end

    subgraph Gateway["智能调度与监控中枢 (Upstream Monitor: 3300)"]
        Proxy["⚡ 统一反向代理网关 (/v1)"]
        CacheLock["🔒 Prompt Cache 独占锁引擎"]
        Engine["🧠 自动调度与 TTFT 熔断引擎"]
        Probe["🔍 上游倍率与延迟定时探针"]
        Dashboard["💻 响应式 Web 中控台大盘"]
    end

    subgraph Control["控制平面 (Remote Control)"]
        TG["✈️ Telegram Bot (双向交互与一键切线)"]
        Admin["👤 管理员浏览器控制台"]
    end

    subgraph Core["底层路由与账本 (Sub2API 容器集群)"]
        S2A["Sub2API 核心服务 (8080)"]
        PG[("PostgreSQL 数据库")]
        RD[("Redis 缓存集群")]
    end

    subgraph Upstreams["上游渠道池 (Upstream Channels)"]
        U1["OpenAI 官方直连 / Azure"]
        U2["Anthropic 优质专线"]
        U3["DeepSeek / 第三方聚合源 A"]
        U4["低价备用冷备渠道 B"]
    end

    Clients -->|API 请求| Proxy
    Proxy -->|请求转发| Upstreams
    Probe -->|定时探测价格与延迟| Upstreams
    Probe --> Engine
    Engine --> CacheLock
    CacheLock -->|单主严格独占 / 互斥切线| Proxy
    Engine -->|告警推送| TG
    TG -->|/switch 交互指令| Engine
    Admin --> Dashboard
    Dashboard --> Proxy
    Proxy -.->|可选直连或账号同步| S2A
    S2A --> PG
    S2A --> RD

📂 项目模块结构

├── 🚀 upstream-monitor/            # 核心系统：上游监控中枢与调度网关
│   ├── public/                    # 现代化响应式 Web UI (大盘看板、策略面板、在线调试器)
│   ├── server.js                  # 统一智能反代 (/v1)、故障熔断与多维巡检调度核心
│   ├── telegram.js                # Telegram 离机报警与移动端双向交互中控 Bot (长轮询免公网IP)
│   ├── auth.js                    # PBKDF2 安全认证、会话持久化与防暴力破解层
│   ├── Dockerfile                 # 监控中枢容器构建文件
│   └── data/                      # 示例配置模板
│       ├── channels.example.json           # 示例渠道配置
│       ├── telegram_config.example.json    # 示例 Telegram 配置
│       └── auto_switch_config.example.json # 示例切线策略配置
├── 🐳 docker-compose.yml           # 全栈容器化一键部署 (Sub2API + PG + Redis + Monitor)
├── ⚙️ .env.example                 # 根目录全局环境变量配置模板
├── 📖 CONTRIBUTING.md              # 社区贡献指南与规范
├── 🛡️ SECURITY.md                  # 安全责任披露策略
└── 📄 LICENSE                      # MIT 开源协议

🚀 快速开始

方式一：Docker Compose 一键全栈部署（推荐）

只需 3 步，拉起包含数据库、Redis、Sub2API 路由与 Upstream Monitor 的全套生产系统：

# 1. 克隆仓库
git clone https://github.com/oisano11/relay-tower.git
cd relay-tower

# 2. 准备配置文件
cp .env.example .env
cp upstream-monitor/.env.example upstream-monitor/.env

# 3. 启动所有容器服务
docker-compose up -d

启动完成后，直接在浏览器中访问：

• 监控与调度中控台：http://localhost:3300
• 统一 API 代理终结点：http://localhost:3300/v1
• Sub2API 核心后台：http://localhost:8080

方式二：独立运行监控中枢 (Node.js)

如果您已有正在运行的 New-API、One-API 或第三方中转服务，只想单独使用 Upstream Monitor 调度监控中枢：

cd upstream-monitor

# 1. 安装轻量依赖
npm install

# 2. 初始化配置模板
cp .env.example .env
cp data/channels.example.json data/channels.json
cp data/telegram_config.example.json data/telegram_config.json
cp data/auto_switch_config.example.json data/auto_switch_config.json

# 3. 启动服务
node server.js
# 或使用自带脚本
./scripts/start.sh

打开浏览器访问 http://localhost:3300，终端将在首次启动时输出安全管理员密码。

💻 客户端无缝接入指南

将常用 AI 工具的 Base URL 指向中控台网关 http://localhost:3300/v1，即可使用缓存路由亲和与统一入口切换。

[!TIP]
网关密钥获取：示例中的 sk-your-relay-key 为网关接入密钥（Gateway API Key），可在控制台顶栏【安全设置】弹窗中一键查看、复制或重置。若客户端与服务部署在同一台机器通过 127.0.0.1 访问，系统默认免密放行。

1. Claude Code CLI

export ANTHROPIC_BASE_URL="http://localhost:3300"
export ANTHROPIC_API_KEY="sk-your-relay-key"
claude

2. Cursor / VS Code

• OpenAI Base URL: http://localhost:3300/v1
• API Key: sk-your-relay-key
• 开启支持 Claude 3.7 Sonnet / DeepSeek V3 等任意模型。

3. Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3300/v1",
    api_key="sk-your-relay-key"
)

response = client.chat.completions.create(
    model="claude-3-7-sonnet-20250219",
    messages=[{"role": "user", "content": "你好，请介绍一下 Prompt Cache 的优势！"}]
)
print(response.choices[0].message.content)

4. Node.js / TypeScript

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'http://localhost:3300/v1',
  apiKey: 'sk-your-relay-key',
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Ping!' }],
  });
  console.log(completion.choices[0].message.content);
}
main();

5. cURL 快速验证

curl http://localhost:3300/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-relay-key" \
  -d '{
    "model": "claude-3-7-sonnet-20250219",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

✈️ Telegram 机器人配置与使用说明

1. 获取 Bot Token

1. 在 Telegram 中搜索 @BotFather；
2. 发送 /newbot 指令，按照指引输入机器人名称与用户名；
3. 获取形如 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ 的 API Token；
4. 将 Token 填入中控台 Telegram 设置 弹窗中，或配置在环境变量 TELEGRAM_BOT_TOKEN 中。

2. 管理员一键免密绑定

• 在 Telegram 中私聊机器人，使用 /bind <控制台管理密码> 绑定，或在控制台配置管理员个人 Telegram ID；
• /start 不会自动授予管理员权限。通知群仅接收消息，加入通知群不会使群成员获得操作权限。

3. 指令速查表

⚙️ 环境变量配置参考

全局根目录 (.env)

监控中枢 (upstream-monitor/.env)

❓ 常见问题 (FAQ)

Q1: 为什么要开启“单主调严格独占”？它如何保护 Prompt Cache？

答：单主调减少跨上游通道分流，有助于保持缓存亲和性。系统完全支持一个渠道属于多个业务组，对跨组共享账号智能保留全局调度开关并仅降级组内优先级，防止误杀其他分组。

当前架构边界

数据库和 Redis 同步仍包含同步子进程调用，慢查询或 SSH 等待可能阻塞网关事件循环。异步数据库访问、后台任务与网关分进程属于后续架构工作。本次修复计划与验收范围见 修复计划；镜像启动检查已加入 CI，实际部署需以运行结果为准。

Q2: Telegram 机器人需要公网 IP 或独立域名吗？

答：完全不需要！ 机器人采用官方推荐的 Long Polling（长轮询）机制，只要运行机器能访问外网（支持配置 HTTP/SOCKS5 代理），即使部署在本地内网电脑、NAT 家宽或无公网 IP 的容器中，也能随时向你的手机推送报警并接收交互指令。

Q3: 现有生产中转站如何平滑接入本项目？

答：您可以仅部署 upstream-monitor。进入该目录执行 node server.js，通过中控台导入渠道配置，并将开发工具的 Base URL 切换为 http://your-server:3300/v1，即可使用倍率监控与统一入口切线。迁移前应确认客户端兼容性及所需数据库连接。

🤝 参与贡献

我们极其欢迎社区贡献！无论是新特性建议、Bug 反馈还是文档优化：

1. 提交前请阅读 CONTRIBUTING.md；
2. 遵守安全责任披露策略 SECURITY.md；
3. 遵循 Conventional Commits 规范提交 PR。

📄 开源许可证

本项目基于 MIT License 开源发布。自由使用，商业与个人友好。