Files
ipass__ipass/rust/crates/plugin-llm/src/llm.rs
T
admin bfa3cf8ff8 feat(llm): 上游多账号路由 + 账号级负载统计 (1.0.14)
一个 slot 挂多把上游账号 Key,解决厂商「单账号额度/并发受限」与
「同一用户缓存命中」两个矛盾诉求。

多账号路由 (plugin-llm)
- models: Upstream.accounts[] (auth/note/resets) + 上游级
  exhaust_status/exhaust_markers;顶层 auth 保留兼容(accounts 为空时合成单账号)
- upstreams::pick_account:粘性绑定 ukb:<key> 优先 → 无绑定时
  FNV-1a(下游 Key) % 可用数 冷分散 → 绑定账号冷却则重新分散 → 全冷却取最早恢复
  * 分散避开厂商单账号 agent 并发上限;落点固定保住 prompt/token 缓存
- cool_until_until 天锚定冷却:boundary = day0 + ceil(已过/窗口)*窗口,
  封顶次日 0 点(MiniMax 5h 窗口、24=5*4+4 → 末段 20:00-24:00 只有 4h 随天重置)
- 耗尽双检测 (log 阶段):$upstream_status 命中 exhaust_status,或
  usage_filter 流式扫到 marker → $llm_acct 定位本次账号 → 写冷却 uac:
- shm: up:/upa:/uac:/ukb:/upe: 五类前缀;$llm_acct 变量 (NOCACHEABLE)

账号级负载统计(问题发现与跟踪)
- 新增 uda:<slot>:<idx>:<day>(请求/token)与 uex:(耗尽次数) 日桶,
  复用内核 usage::bump_day —— 无数据库、无新进程(项目红线)
- 计数点只在 log 阶段一次;pick_account 会被 $llm_target/$llm_auth/$llm_acct
  三个变量各触发一次,放进那里会三倍计数
- view() 投影带每账号 load 与 account_trend + trend_labels(日期由后端算)
- 管理台「上游」页密钥列:各 Key 今日请求/token/耗尽 + 负载比例条 +
  14 天迷你趋势(自绘 SVG,零第三方依赖)+ 冷却/耗尽徽标 + 上游合计

测试与验证
- 回归 279 条全绿(网关 102 + LLM 177),新增 6 条多账号/负载断言
- 假上游新增 UPSTREAM_FAIL_AUTH 模拟账号额度耗尽;靶机验证 Key 真被替换
- 前端以真实 admin.css + upstreams.js 渲染路径做无头浏览器断言:
  比例条与负载成比例(412 vs 96 → 100%/23%)、每账号 14 条块、
  悬停峰值日期与数据逐位吻合、单账号/无账号兜底正常、无横向溢出、零 JS 错误

文档
- 新增 docs/llm/MULTI_ACCOUNT_ROUTING.md(数据模型/路由/冷却数学/shm 布局/负载统计)
- readme §11 数据模型 + §15 上游配置 + §15 用量统计 + §12.6 tag 表 + §16 变更记录
- 修正 docs/llm/*.md 中插件化前的过时路径(rust/src/* → crates/plugin-llm/src/*)
2026-09-14 11:57:08 +08:00

362 lines
16 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! LLM API 代理热路径。
//!
//! 客户端把 base_url 指向 `https://llm.yourdomain.com/<slot>`,用**与域名接口
//! 同一套** API Key 鉴权,由网关换成上游真实密钥后转发:
//!
//! ```text
//! POST /openai/v1/chat/completions
//! │ Authorization: Bearer sk_<本网关签发的 Key>
//! ▼
//! ① 取 URL 第一段 → slot = "openai"
//! ② 查 ukey:<key> → 身份(纯内存,不读 users.json)
//! ③ 查 up:<slot> → 上游基址 + 上游真 Key(纯内存)
//! ④ 填 $llm_target/Host/Auth → 交给 proxy_pass 转发
//! ```
//!
//! ## 三条硬约束
//!
//! * **鉴权绝不能走 `users::find_by_key`**。它每次都同步读 `users.json` 并全表
//! JSON 解码——管理接口低频无所谓,但 LLM 每个推理请求都吃这个代价。按项目
//! 实测口径(CLAUDE.md「性能基线」),这类同步文件 I/O 足以把吞吐打到 1/25。
//! 所以身份预置在 `ukey:` 键里,热路径只碰共享内存。取 Key / 查身份 /
//! 限流配额 / OpenAI 兼容错误体已下沉内核 `ipass_core::auth`(LLM 与 apix
//! 两条下行链路共用)。
//! * **access 阶段读不到请求体**,因此这里不解析 `model` 字段,上游由 URL 前缀
//! 决定(原因见 `upstreams` 模块头注释)。
//! * **错误体必须是 OpenAI 兼容格式**(`{"error":{...}}`)。客户端的 SDK 只认这个,
//! 项目自己的 `{"code":400,"msg":...}` 会被 SDK 报成「无法解析的响应」。
use core::ptr;
use ngx::core::{Pool, Status};
use ngx::ffi::{
NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, ngx_conf_t, ngx_http_add_variable,
ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, ngx_str_t, ngx_uint_t,
};
use ngx::http::HTTPStatus;
use ngx::ngx_string;
use serde_json::json;
use crate::config;
use crate::upstreams;
use ipass_core::{auth, http, state, util};
// ===========================================================================
// 变量分派标记
// ===========================================================================
/// `$llm_target`:完整上游 URL(含 path 与 query),直接交给 `proxy_pass`
pub const VAR_TARGET: usize = 1;
/// `$llm_host`:上游 Host 头(`proxy_set_header Host $llm_host`)
///
/// 变量形式的 `proxy_pass` 不会自动推导 Host,必须显式设,
/// 否则打给 OpenAI / Cloudflare 后端会因 Host 不符被拒。
pub const VAR_HOST: usize = 2;
/// `$llm_auth`:上游 Authorization 头值
pub const VAR_AUTH: usize = 3;
/// `$llm_acct`:本次请求选中的上游账号下标(多账号路由用;log 阶段据此标记耗尽)。
/// 由 `pick_account` 在变量求值时计算(与 `$llm_auth` 同源,保证一致)。
pub const VAR_ACCT: usize = 4;
// ===========================================================================
// preconfiguration:注册变量
// ===========================================================================
/// 注册 LLM 四件套只读变量(gateway preconfiguration 经插件循环调用)。
///
/// 名字里的 `llm_` 前缀不要省:nginx 变量名全局唯一,
/// 将来接入别的模块时才不会撞名。
///
/// # Safety
/// `cf` 由 nginx 传入且有效。
pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
let mut target = ngx_string!("llm_target");
let mut host = ngx_string!("llm_host");
let mut auth_var = ngx_string!("llm_auth");
let mut acct_var = ngx_string!("llm_acct");
unsafe {
add_var(cf, &raw mut target, VAR_TARGET)
&& add_var(cf, &raw mut host, VAR_HOST)
&& add_var(cf, &raw mut auth_var, VAR_AUTH)
&& add_var(cf, &raw mut acct_var, VAR_ACCT)
}
}
/// 注册一个只读变量,值由 [`var_get`] 按 `slot` 分派计算。
///
/// 与 `$proxy_backend_addr` 不同,LLM 三件套**不需要**
/// `ngx_http_get_variable_index`——它们是纯只读的,模块从不主动写,
/// 只有 `proxy_pass` / `proxy_set_header` 求值时触发 get_handler。
unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> bool {
// SAFETY: cf 由 nginx 传入;name 指向本函数调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe {
ngx_http_add_variable(
cf,
name,
(NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t,
)
};
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化;data 承载分派标记
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = slot;
}
true
}
// ===========================================================================
// 请求解析
// ===========================================================================
/// 上游在共享内存里是否可用(原 `state::get_upstream` 的语义:`get_live`
/// 精确取 `up:<slot>`,过期视为不存在)。**未命中即 404,无回源兜底**。
pub fn upstream_live(slot: &str) -> bool {
state::get_live(config::KEY_UP_PREFIX, slot.as_bytes(), util::now()).is_some()
}
/// 剥掉内部测试前缀:`/_upstream_test/<slot>/...` → `/<slot>/...`
///
/// 管理台的「测试」按钮经 `ngx_http_internal_redirect` 落到这个内部 location,
/// 复用本文件的取 slot / 拼 URL / 换密钥逻辑。**slot_of 与 upstream_uri 都必须
/// 走这一步**——漏一边的表现(实测):slot 被当成路径段留给上游,拼出
/// `.../v1/deepseeklike/v1/chat/completions` → 404/502;对「任何路径都回 200」
/// 的 echo 靶机则会掩盖成假绿,必须看靶机实际收到的 path。
fn strip_internal_prefix(uri: &str) -> &str {
uri.strip_prefix("/_upstream_test").unwrap_or(uri)
}
/// 取 URL 第一段作为上游 slot:`/openai/v1/chat/completions` → `openai`
///
/// 兼容一条内部链路:管理台的「测试」按钮走
/// `POST /api/admin/upstreams/test`,模块校验后 `ngx_http_internal_redirect`
/// 到管理 server 的内部 location `/_upstream_test/<slot>/v1/chat/completions`,
/// 让 `proxy_pass $llm_target` 原样复用本文件的取 slot / 拼 URL / 换密钥逻辑。
/// 前缀剥掉后语义与客户端直打 `/<slot>/...` 完全一致(同一套鉴权变量)。
pub fn slot_of(r: *mut ngx_http_request_t) -> Option<String> {
let uri = http::uri(r);
let rest = strip_internal_prefix(&uri).strip_prefix('/')?;
let slot = rest.split('/').next().unwrap_or("");
if slot.is_empty() {
return None;
}
Some(slot.to_ascii_lowercase())
}
/// 剥掉 slot 段、拼回 query:`/openai/v1/chat/completions?a=1` → `/v1/chat/completions?a=1`
///
/// query 必须在这里拼——变量形式的 `proxy_pass` **不会**自动追加原始 args。
pub fn upstream_uri(r: *mut ngx_http_request_t) -> String {
let uri = http::uri(r);
let uri = strip_internal_prefix(&uri);
let rest = uri.strip_prefix('/').unwrap_or(uri);
// 只有 slot、没有后续路径时(如 `/openai`)打到上游根
let path = match rest.find('/') {
Some(i) => &rest[i..],
None => "/",
};
let args = http::args_raw(r);
if args.is_empty() {
path.to_owned()
} else {
format!("{}?{}", path, String::from_utf8_lossy(&args))
}
}
/// 从 `https://api.openai.com:443` 取出 `api.openai.com:443`(去掉 scheme 与路径)
fn host_of(base: &str) -> &str {
let rest = match base.find("://") {
Some(i) => &base[i + 3..],
None => base,
};
match rest.find('/') {
Some(i) => &rest[..i],
None => rest,
}
}
/// 拆 base:`https://api.deepseek.com/v1` → `("https://api.deepseek.com", "/v1")`
fn split_origin(base: &str) -> (&str, &str) {
let Some(i) = base.find("://") else {
return (base, "");
};
let after = &base[i + 3..];
match after.find('/') {
Some(j) => (&base[..i + 3 + j], &after[j..]),
None => (base, ""),
}
}
/// 拼上游完整 URL:`base + 客户端路径(已剥掉 slot)`。
///
/// **唯一的例外是版本段重复**:上游 base 自带路径(如 DeepSeek 的
/// `https://api.deepseek.com/v1`)而客户端路径又正好以同一段开头时,
/// 只保留一份。否则会拼出 `/v1/v1/chat/completions`。
///
/// ```text
/// base .../v1 + /v1/chat/completions → .../v1/chat/completions (去重)
/// base .../v1 + /chat/completions → .../v1/chat/completions (照常前缀)
/// base .../llm + /v1/chat/completions → .../llm/v1/chat/completions
/// ```
///
/// 这条规则是**实测踩坑换来的**:厂商文档里的 base_url 通常自带 `/v1`
/// (`https://api.deepseek.com/v1`),管理员照抄进 `llm-upstreams.json`,
/// 客户端又按 OpenAI 习惯把 `/v1` 带上 → 上游 404 且**响应体为空**,
/// 从网关侧完全看不出是拼接问题。去重后两种写法都通,
/// base_url 也就能做到「把厂商文档里的 host 换成网关域名」的逐个字符替换。
fn join_target(base: &str, path: &str) -> String {
let (origin, base_path) = split_origin(base);
if !base_path.is_empty() {
let with_slash = format!("{base_path}/");
if path == base_path || path.starts_with(&with_slash) {
return format!("{origin}{path}");
}
}
format!("{base}{path}")
}
// ===========================================================================
// 模型发现(本地应答,不去上游)
// ===========================================================================
/// 是不是"列出模型"请求:`GET /v1/models`(OpenAI SDK 的 `client.models.list()`)。
///
/// **必须在查 slot 之前判断**:URL 第一段被当作 slot,`/v1/models` 天然会被
/// 解析成 `slot=v1` → 「上游不存在」404。这两个路径是本网关自己的元信息接口,
/// 与"某个上游的模型清单"(`GET /<slot>/v1/models`,照常透传给厂商)互不干扰。
pub fn is_models_probe(r: *mut ngx_http_request_t) -> bool {
if !http::method_str(r).eq_ignore_ascii_case("GET") {
return false;
}
let uri = http::uri(r);
let uri = uri.trim_end_matches('/');
uri == "/v1/models" || uri == "/models"
}
/// 本地应答模型列表,形状与 OpenAI 的 `/v1/models` 一致。
///
/// 客户端 SDK 只认这个形状,返回项目自己的 `{code,msg,data}` 会让 SDK
/// 报"无法解析的响应"——与错误体必须 OpenAI 兼容是同一个理由。
///
/// 顶层额外挂一个 `x_ipass_upstreams`(OpenAI SDK 忽略未知字段):
/// 每个**该账号可用**的上游一段,给出 OpenAI / Anthropic 两种 base_url、
/// 登记的模型清单与健康状态——客户端拿一把有效 Key 一次就能取齐
/// 「能调哪些地址、哪些模型、哪些上游当前失效」。健康来自真实流量的
/// log 阶段标记(`uh:` 缓存),从没被调用过 = `unknown`。
pub fn respond_models(r: *mut ngx_http_request_t, allowed: &[String]) -> Status {
let data: Vec<serde_json::Value> = upstreams::models_flat(allowed)
.into_iter()
.map(|(model, slot)| {
json!({ "id": model, "object": "model", "created": 0, "owned_by": slot })
})
.collect();
// base_url 跟随调用方所用的端口(与账号态 /api/v1/models 同一口径)
let port = http::host_port(r);
let x_upstreams: Vec<serde_json::Value> = upstreams::available(allowed)
.into_iter()
.map(|(slot, up)| {
let (status, code, checked_at) = match upstreams::health(&slot) {
Some((ok, c, ts)) => (if ok { "ok" } else { "failed" }, c, ts),
None => ("unknown", 0, 0),
};
json!({
"slot": slot,
"base_url": upstreams::base_url(&slot, &up, &port),
"anthropic_base_url": upstreams::anthropic_base_url(&slot, &up, &port),
"models": up.models,
"status": status,
"status_code": if code > 0 { json!(code) } else { serde_json::Value::Null },
"checked_at": checked_at,
})
})
.collect();
let body =
json!({ "object": "list", "data": data, "x_ipass_upstreams": x_upstreams }).to_string();
// 与错误路径同一手法:自己把响应发出去,再把状态码交回 nginx。
// 注意**不能**返回 NGX_OK——access 阶段的 OK 语义是"放行、继续走 content",
// 那样 `proxy_pass` 照样会执行,客户端拿到模型列表的同时上游被真调一次。
let _ = http::send(r, HTTPStatus::OK, &body);
Status(HTTPStatus::OK.0 as ngx_int_t)
}
// ===========================================================================
// 变量 get_handler
// ===========================================================================
/// 在请求内存池里分配字符串并写进变量槽。随请求回收,无需手动释放。
///
/// # Safety
/// `r` / `v` 必须由 nginx 传入且在本调用期间有效。
unsafe fn set_value(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
value: &str,
) -> ngx_int_t {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = value.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
(*v).set_not_found(1);
return Status::NGX_ERROR.into();
}
ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
(*v).data = data;
(*v).set_len(bytes.len() as _);
(*v).set_valid(1);
(*v).set_no_cacheable(1);
(*v).set_not_found(0);
Status::NGX_OK.into()
}
/// 四个 LLM 变量共用一个 get_handler,靠 `var.data` 分派(值由 `preconfiguration` 写入)。
///
/// 共用代价:每个变量各调一次 `pick_account`(一次读锁 + 几次 BTreeMap 查找 + 一次
/// 小分配,微秒级),相对一次 LLM 推理完全可忽略;换来不必维护四份相近代码。
///
/// `$llm_acct` 的求值会顺带把「用户 key → 账号」粘性绑定写进共享内存
/// (仅当下行 key 存在且绑定变化),是幂等副作用。log 阶段读取 `$llm_acct` 即得到
/// 本次请求实际打到的账号下标(用于额度耗尽时精确标记那一个账号)。
pub extern "C" fn var_get(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
data: usize,
) -> ngx_int_t {
// SAFETY: r/v 由 nginx 传入且有效;slot_of/upstream_uri 只读请求结构
unsafe {
let resolved = (|| -> Option<(String, String, String, usize)> {
let slot = slot_of(r)?;
let key = auth::downstream_key(r);
let now = util::now();
// 选账号:粘性绑定 + 跳过冷却中账号,返回 (下标, auth, base)
let (idx, auth, base) = upstreams::pick_account(&slot, key.as_deref(), now)?;
let target = join_target(&base, &upstream_uri(r));
let host = host_of(&base).to_owned();
Some((target, host, auth, idx))
})();
match resolved {
Some((target, host, auth, idx)) => {
// 四个分支各取一个字段(只有命中分支的 String 被移动出去)
let value = match data {
VAR_TARGET => target,
VAR_HOST => host,
VAR_AUTH => auth,
VAR_ACCT => idx.to_string(),
_ => return Status::NGX_ERROR.into(),
};
set_value(r, v, &value)
}
None => {
(*v).set_not_found(1);
(*v).set_valid(0);
Status::NGX_ERROR.into()
}
}
}
}