一个 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/*)
362 lines
16 KiB
Rust
362 lines
16 KiB
Rust
//! 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()
|
||
}
|
||
}
|
||
}
|
||
}
|