llmux

command module
v0.0.0-...-58ab21b Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 26 Imported by: 0

README

LLMux

LLMux

多供应商 LLM API 网关 —— 统一出口、协议互转、两层负载均衡与自动故障转移。

Go 1.25 React 19 MIT

简介

LLMux 是一个自托管的 LLM API 网关与代理。对外,它提供与 OpenAI / Anthropic 兼容的 /v1/* 接口,让现有 SDK 与客户端工具直接接入;对内,它提供 Web 管理后台,用来管理供应商、号池与凭据、模型目录、模型关联、虚拟模型、健康检查与模型同步,并查看请求日志和用量指标。

一次请求依次经过:虚拟模型解析(第一层负载均衡)→ 真实模型 → 供应商内部三层选路(端点匹配 → 分组加权 → 凭据轮询)→ 协议转换 → 上游。任一环节失败都会在候选池内重试并自动切换到下一个候选。

界面预览

系统概览 提供商管理
系统概览 提供商管理

更多截图见 docs/screenshots/。

功能特性

  • 统一出口 + 协议互转:入站支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages;协议中枢走统一模型(models/unified),出站按端点协议适配。
  • 协议与上游解耦:新增一家 OpenAI 兼容上游只需在 providers/ 注册元数据,转换层零改动。
  • 两层负载均衡:虚拟模型(真实模型级)→ 模型关联(供应商级,按优先级 + 权重)。
  • 供应商内部三层选路:端点匹配 → 分组加权 → 凭据轮询 + 冷却。
  • 号池与凭据管理:号池容器支持批量导入;凭据加密存储,可启停恢复、备注与按归属过滤,并可对单条凭据做真实补全点测(测试模型按归属配置)。
  • 调用方 API Key:多 key 管理,值以密文 + hash 两种形式存储,是 /v1 鉴权的数据源。
  • 健康检查与自动调整:失败触发权重 / 优先级衰减,连续失败自动停用关联。
  • 模型同步与自动关联:从上游拉取模型列表并自动建立模型-供应商关联。
  • 可观测性:请求日志、ChatIO 详情、仪表盘指标与数据保留策略。
  • 可靠回写:候选池重试、跨真实模型故障转移、全局总超时与首字节等待看门狗。

架构

flowchart LR
    C["客户端<br/>OpenAI / Anthropic SDK"] -->|"/v1/*"| MW["鉴权中间件<br/>API Key"]
    MW --> H["handler/v1"]
    H --> CH["service/chat<br/>编排核心"]
    CH --> VM["虚拟模型<br/>第一层 LB"]
    VM --> RT["真实模型<br/>第二层 LB"]
    RT --> CHN["供应商三层选路<br/>端点 → 分组 → 凭据"]
    CHN --> TR["协议转换<br/>unified"]
    TR --> UP["上游供应商"]
    UP -. 流式 / 非流式回写 .-> C

    A["管理后台 React SPA"] -->|"/api/*"| API["handler/*"]
    API --> SVC["service/*"]
    API --> REPO["repository"]
    SVC --> REPO
    REPO --> DB[("SQLite")]

依赖方向:webui / 外部客户端 → middleware + handler → service → providers + repository → models + SQLite。完整设计说明见 docs/architecture/README.md。

快速开始

前置要求

  • Go 1.25+
  • Node.js 20+ 与 pnpm 10+(构建管理后台需要)
  • 可选:Docker

[!IMPORTANT] main.go 通过 //go:embed webui/dist 内嵌管理后台,而 webui/dist 不入库。首次运行前必须先构建前端,否则 Go 编译会报 pattern webui/dist: no matching files found。

从源码运行

git clone https://github.com/qkf688/llmux.git
cd llmux
cp .env.example .env    # 至少填入 JWT_SECRET
make webui              # 构建管理后台到 webui/dist(供 embed)
make run                # 启动服务,默认 http://localhost:7070

Windows 用户可直接用脚本,它会先构建前端并释放 7070 端口:

copy .env.example .env
run.bat                 :: 构建 webui 后启动
run.bat --no-build      :: 跳过前端构建,使用已有 webui/dist

启动后打开 http://localhost:7070 进入管理后台。首次启动若未设置 ADMIN_PASSWORD,密码会随机生成并打印到日志。

Docker

docker compose up -d

或直接运行镜像:

docker run -d --name llmux -p 7070:7070 \
  -v $(pwd)/db:/app/db \
  -e JWT_SECRET=<你的密钥> \
  -e GIN_MODE=release \
  qkf688/llmux:latest

[!WARNING] CREDENTIAL_ENCRYPTION_KEY 是部署级永久密钥。换掉它会让已存储的凭据密文全部不可读,必须重新录入全部凭据。未设置时首启会自动生成并落盘 ./db/credential.key,请连同 db/ 一起备份。

环境变量

变量 必填 说明
JWT_SECRET 是 管理后台 JWT 签名密钥。未设置时进程启动即退出。
CREDENTIAL_ENCRYPTION_KEY 否 凭据加密密钥,32 字节 hex。未设置时首启自动生成 ./db/credential.key。
ADMIN_PASSWORD 否 首启动 admin 密码,留空则随机生成并打印到日志。
TRUSTED_PROXIES 否 可信代理网段(逗号分隔 IP/CIDR)。只有网段内代理的 X-Forwarded-For 会被采信为访问日志 ClientIP;留空 = 全关,直连部署默认安全。
GIN_MODE 否 debug / release / test。
TZ 否 时区,如 Asia/Shanghai。

支持项目根目录 .env 文件(启动时自动加载,模板见 .env.example)。

客户端接入

/v1 接口使用管理后台创建的 API Key 鉴权(Authorization: Bearer <key>)。

方法 路径 说明
GET /v1/models 模型列表
POST /v1/chat/completions OpenAI Chat Completions
POST /v1/responses OpenAI Responses
POST /v1/messages Anthropic Messages
POST /v1/messages/count_tokens Token 计数(Anthropic 官方路径)
POST /v1/count_tokens Token 计数(兼容别名)
curl http://localhost:7070/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "model": "gpt-4-balanced",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

model 可以是真实模型名,也可以是虚拟模型名 —— 虚拟模型会按配置的策略在第一层做负载均衡与故障转移。详见 虚拟模型使用指南。

开发

命令 作用
make run 格式化 + 整理依赖 + 建库目录 + 启动后端(:7070)
make webui 构建管理后台到 webui/dist(供 Go embed)
make test 全量 Go 测试 go test ./... -count=1
make check 提交前一键自查:fmt + vet + test
make fmt / make tidy go fmt ./... / go mod tidy

前端(在 webui/ 下):

pnpm dev         # Vite HMR,:5173,/api 代理到 :7070
pnpm build       # tsc -b && vite build
pnpm typecheck   # 仅类型检查,比 build 快
pnpm lint        # eslint
pnpm test        # vitest

前后端分离调试:

dev.bat                  :: 或 .\dev.ps1
dev.ps1 -BackendOnly     :: 只起后端
dev.ps1 -FrontendOnly    :: 只起前端

[!NOTE] 改完前端并希望体现在 Go 二进制里,必须重新执行 pnpm run build(或 make webui)—— 管理后台是构建产物内嵌进二进制的。

文档

文档 内容
docs/architecture/README.md 架构总览:模块索引、依赖方向、请求主路径
docs/architecture/modules/ 各业务模块的职责、边界与接口契约
docs/architecture/interactions.md 模块间调用、Hook 与注册表
docs/architecture/conventions.md 命名规范
docs/guides/extension.md 新增供应商 / 协议 style / 策略 / 设置项 / 页面
docs/guides/framework-conventions.md Gin 关闭序、前端 dialog、协议代理约定
docs/virtual-models-guide.md 虚拟模型使用指南
AGENTS.md AI 与人类协作者的协作规范

本项目基于 MIT 许可证 开源。

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
纯逻辑:白名单透传判据与合流入站头。
纯逻辑:白名单透传判据与合流入站头。
bgtask
Package bgtask 登记后台 goroutine,使进程关闭时能统一等待它们退出。
Package bgtask 登记后台 goroutine,使进程关闭时能统一等待它们退出。
credentialcrypto
Package credentialcrypto 提供凭据(API Key)的对称加密、解密与哈希。
Package credentialcrypto 提供凭据(API Key)的对称加密、解密与哈希。
apikeys
Package apikeys 提供 /v1 调用 key(api_keys 表)的管理端 CRUD。
Package apikeys 提供 /v1 调用 key(api_keys 表)的管理端 CRUD。
httpx
Package httpx 提供 handler 层共用的请求绑定辅助(分页 / 路径 ID / JSON)。
Package httpx 提供 handler 层共用的请求绑定辅助(分页 / 路径 ID / JSON)。
v1
internal
testutil
Package testutil 是仓库唯一的测试建库工具(Stage 35 测试隔离收口)。
Package testutil 是仓库唯一的测试建库工具(Stage 35 测试隔离收口)。
Package repository 封装对持久层(GORM/SQLite)的访问,为 service/handler 提供与数据访问框架解耦的接口。
Package repository 封装对持久层(GORM/SQLite)的访问,为 service/handler 提供与数据访问框架解耦的接口。
auth
Package auth 提供鉴权相关的纯工具函数:密码哈希与 JWT 签发/解析。
Package auth 提供鉴权相关的纯工具函数:密码哈希与 JWT 签发/解析。
chatstats
Package chatstats 负责把一次请求的结果落到各维度统计表。
Package chatstats 负责把一次请求的结果落到各维度统计表。
credimport
Package credimport 批量导入凭据的行处理(纯编排,与 HTTP 解耦)。
Package credimport 批量导入凭据的行处理(纯编排,与 HTTP 解耦)。
credview
View 凭据对外视图(管理端 JSON 形状)的唯一来源。
View 凭据对外视图(管理端 JSON 形状)的唯一来源。
protocolprobe
Package protocolprobe 是「协议支持检测」的**判定内核**:把上游实际回了什么,折算成 「这条协议能不能用 / 像不像直通 / 字段全不全」,再据此给出带置信度的建议。
Package protocolprobe 是「协议支持检测」的**判定内核**:把上游实际回了什么,折算成 「这条协议能不能用 / 像不像直通 / 字段全不全」,再据此给出带置信度的建议。
transform/anthropic
Package anthropic provides a thin transform adapter that delegates to the upstream service/anthropic implementation.
Package anthropic provides a thin transform adapter that delegates to the upstream service/anthropic implementation.
transform/responses
Package responses provides a thin transform adapter that delegates to the upstream service/responses implementation.
Package responses provides a thin transform adapter that delegates to the upstream service/responses implementation.
transform/shared
Package shared contains cross-protocol helpers used by the transform sub-packages (openai, responses, streaming, etc.).
Package shared contains cross-protocol helpers used by the transform sub-packages (openai, responses, streaming, etc.).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL