跳到主要内容

总体架构

这一页说明 OmniGate 的目标、非目标与整体结构。设计稿面向贡献者,但其中的取舍对部署和排障也有帮助。

1. 目标与非目标​

1.1 目标​

#能力说明
G1OpenAI 兼容代理对下游暴露 /v1/chat/completions(含 SSE 流式)、/v1/embeddings、/v1/rerank、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/videos(异步提交 + 轮询 + 下载)、/v1/models
G2逻辑模型路由请求一个逻辑 modelId(如 glm),按权重分发到 N 个真实模型(可以是不同模型);也可直接用 provider/model 锁定物理模型
G3提供商/密钥/模型实体Provider → ApiKey;模型与密钥多对多绑定(须同提供商);模型内 key 按权重分配(等权轮询)
G4阶梯熔断模型×密钥组合粒度:可重试失败 30s → 1m → 3m 阶梯冷却、连续 3 次永久禁用并明确报错;401/403 立即禁用,429 短冷却
G5多维统计次数 / token / 首字延迟 / 总耗时 / 费用,按 路由·模型·提供商·key·状态·时间 聚合
G6隐私默认成功请求内容捕获为显式开关(默认关);关闭时默认记录转发失败;全部实例无效不记
G7Web 管理界面实体 CRUD、健康状态、手动解禁、统计报表、请求日志查询
G8分层配置 + 热生效启动层(监听地址、管理鉴权)在本地 config.yaml/命令行;运行层(熔断、限流、捕获等)全存 SQLite,管理面保存即生效

1.2 非目标(v1 明确不做)​

  • 多实例集群 / 高可用(单机单进程)
  • 多用户 / RBAC / 多租户组织层级(v1 仅单管理员 + 虚拟密钥凭证体系:限流、限额、按路由授权)
  • 协议转换仅覆盖 chat/completions(openai ↔ responses ↔ anthropic ↔ gemini,见 model.protocol);embeddings/rerank/images/tts/stt 按业界事实格式直通(仅重写 model 字段),不做跨厂商转换;完整字段映射与限制见 协议转换
  • 虚拟密钥仅进程内限流(每小时请求数、并发上限,不落库)与日/月美元限额;无 TPM、模型级限流与周期自动重置

2. 总体架构​

客户端(OpenAI SDK / 任意工具)
│ OpenAI 兼容协议
▼
┌─────────────────────────── OmniGate 单进程 ───────────────────────────┐
│ │
│ 代理面 核心引擎 管理面 │
│ ┌────────────┐ ┌──────────────────────────┐ ┌────────────────────┐ │
│ │ /v1/chat/ │──▶│ 路由解析(逻辑modelId) │ │ Admin REST API │ │
│ │ completions│ │ → 加权选模型目标 │ │ 实体CRUD/统计/健康 │ │
│ │ /v1/models │ │ → key轮询(按模型) │ └─────────┬──────────┘ │
│ └────────────┘ │ → 熔断态key跳过 │ │ 写库后事件 │
│ │ │ → 转发+SSE透传 │ ▼ │
│ ▼ │ → 失败转移重试 │ ┌────────────────────┐ │
│ ┌────────────┐ └──────────┬───────────────┘ │ 配置快照原子替换 │ │
│ │ 统计记录器 │◀─────────────┘ 生命周期埋点 │ (RWMutex/atomic) │ │
│ └─────┬──────┘ └────────────────────┘ │
│ ▼ │ 读快照 │
│ ┌────────────────────────────────────┐ ▼ │
│ │ SQLite (modernc.org/sqlite 纯Go) │◀── 熔断(模型×key 组合粒度) │
│ │ 实体/配置/请求日志/(可选内容日志) │ │
│ └────────────────────────────────────┘ │
│ Web UI(React+AntD,go:embed 内嵌,随二进制分发) │
└──────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
提供商 A(智谱) 提供商 B(任意 OpenAI 兼容)
├─ 密钥[key1..keyN] ├─ 密钥[key1..keyM]
└─ ... └─ ...

10. Web UI 页面清单(React 18 + Ant Design 5 + ECharts,go:embed 内嵌,挂在 /manage)​

页面内容
Dashboard今日请求量/成功率/token/费用卡片;TTFT 与耗时趋势图;后端健康卡片(熔断态一目了然,禁用项红色+解禁按钮)
配置中心左右布局:左侧提供商卡片(选中高亮、编辑/删除);右侧 Tab = 模型 / 密钥,内容随左侧选中过滤。模型表单含上游协议(completions/responses/messages/gemini)+ 绑定密钥及权重
路由管理逻辑 modelId CRUD + 目标模型加权编辑器(可视化权重占比条)
MCP 后端MCP Server CRUD + 路由关联 + 暴露工具白名单
虚拟密钥消费者凭证 CRUD:限流(每小时请求数/并发)、日/月限额、按路由授权、用量统计与预算重置
统计报表维度切换(路由/模型/提供商/key/状态)+ 时间范围;分位数延迟;错误码分布
请求日志筛选列表;详情抽屉(元数据 + 捕获内容查看;成功未开捕获 / 全部实例无效时明确提示)
Playground对话(流式 Markdown、思考过程折叠)、Embedding、Rerank、生图四面板;挂载 MCP 路由即自动工具调用
设置全部配置项表单;通知渠道管理(配额告警分区);开机自启;版本与更新;危险操作(清空统计)二次确认
通知中心顶栏铃铛 + 未读角标(30s 轮询未读数);抽屉内列表支持只看未读、单条已读/未读/删除、全部已读、清除已读、按 subject 跳转到对应页面

只读门户(/portal,与 /manage 共用同一份前端产物,main.tsx 按路径分流):虚拟密钥持有者用密钥登录,可看自己的仪表盘、模型广场(可调用的路由与模型、加权价格、curl 示例与一键测试)、MCP 页(可调用的 MCP 路由与工具清单)、自己的请求日志与配额通知;全站无任何写入口。