Files
ssw__ipass/rust/gateway/src/llm.rs
T
admin 74aeefee58 refactor(plugin): P0-P2 插件化落地 —— workspace 化 + ipass-core + plugin-domain
- P0: rust/ 改 workspace(ipass-core 内核 + gateway 唯一 cdylib),
  [profile.release] 上移根、依赖收敛 workspace.dependencies;
  users::delete 的 stats::forget 依赖改为 on_delete 钩子注册表
- P1: 契约层 core/plugin.rs(Plugin trait)+ core/loc.rs(Switch 并集 +
  set_switch_fn,未实现变体保守 false);gateway PLUGINS 分发循环,
  不认领统一 404(插件绝不自行 404)
- P2: 身份端点下沉 core/api.rs(CorePlugin + CoreExt 扩展注册表,
  gateway 作装配根回填域名数/用量/连带回收/白名单校验);
  plugin-domain crate(domains + DomainEntry + sub: 前缀 + ResolveHandler
  + $proxy_backend_addr + 域名类端点含 purge)
- 行为等价:conf/nginx.conf、Dockerfile、tests 零改动,262 回归全绿
- 方案文档 docs/plugin/PLUGINIZATION_PLAN.md
2026-09-13 11:43:22 +08:00

443 lines
18 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:` 键里,热路径只碰共享内存。
//! * **access 阶段读不到请求体**,因此这里不解析 `model` 字段,上游由 URL 前缀
//! 决定(原因见 `upstreams` 模块头注释)。
//! * **错误体必须是 OpenAI 兼容格式**(`{"error":{...}}`)。客户端的 SDK 只认这个,
//! 项目自己的 `{"code":400,"msg":...}` 会被 SDK 报成「无法解析的响应」。
use core::ptr;
use ngx::core::{Pool, Status};
use ngx::ffi::{ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t};
use ngx::http::HTTPStatus;
use serde_json::json;
use crate::config;
use crate::state;
use crate::upstreams;
use crate::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;
// ===========================================================================
// 请求解析
// ===========================================================================
/// 剥掉内部测试前缀:`/_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 = crate::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 = crate::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 = crate::http::args_raw(r);
if args.is_empty() {
path.to_owned()
} else {
format!("{}?{}", path, String::from_utf8_lossy(&args))
}
}
/// 取下游 Key。
///
/// 依次尝试三种携带方式,覆盖主流 SDK 的默认行为:
/// `Authorization: Bearer`(OpenAI)、`x-api-key`(Anthropic)、`X-API-Key`(本项目域名接口)。
/// 「同一套 Key」意味着这三个位置放的都应该是 `users.json` 里那把 `sk_...`。
pub fn downstream_key(r: *mut ngx_http_request_t) -> Option<String> {
if let Some(raw) = crate::http::header(r, "authorization") {
let raw = raw.trim();
let rest = raw
.strip_prefix("Bearer ")
.or_else(|| raw.strip_prefix("bearer "));
if let Some(k) = rest {
let k = k.trim();
if !k.is_empty() {
return Some(k.to_owned());
}
}
}
for name in ["x-api-key", "api-key"] {
if let Some(k) = crate::http::header(r, name) {
let k = k.trim().to_owned();
if !k.is_empty() {
return Some(k);
}
}
}
None
}
/// 查共享内存拿身份:`(username, allowed_slots, rpm, daily)`。
///
/// `allowed_slots` 为空表示不限(老账号没有该字段,反序列化即空表)。
/// `rpm` / `daily` 是限流上限;旧版 payload 只有 2 行,此时按全局默认兜底。
pub fn identity(key: &str) -> Option<(String, Vec<String>, i64, i64)> {
let payload = state::get_live(config::KEY_UKEY_PREFIX, key.as_bytes(), util::now())?;
let mut lines = payload.split('\n');
let name = lines.next().unwrap_or("");
let allowed = lines.next().unwrap_or("");
let rpm = lines
.next()
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(config::LLM_RPM_DEFAULT);
let daily = lines
.next()
.and_then(|s| s.parse::<i64>().ok())
.unwrap_or(config::LLM_DAILY_DEFAULT);
if name.is_empty() {
return None;
}
let slots: Vec<String> = if allowed.is_empty() {
Vec::new()
} else {
allowed
.split(',')
.map(|s| s.trim().to_owned())
.filter(|s| !s.is_empty())
.collect()
};
Some((name.to_owned(), slots, rpm, daily))
}
/// 从 `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}")
}
// ===========================================================================
// 响应
// ===========================================================================
/// OpenAI 兼容的错误体。客户端 SDK 只认这个形状。
///
/// **返回状态码而不是 `NGX_OK`**——这一点是正确性关键:access 阶段返回 OK 的
/// 语义是「放行、继续走 content 阶段」,那么鉴权失败的请求照样会被 `proxy_pass`
/// 转发给上游。表现是「客户端收到 401,但上游仍然被调用了一次」:白烧上游额度,
/// 而且从上游账单上完全看不出这是一次被拒绝的请求。实测踩过。
pub fn fail(r: *mut ngx_http_request_t, status: HTTPStatus, code: &str, msg: &str) -> Status {
fail_typed(r, status, "invalid_request_error", code, msg)
}
/// 同 [`fail`],但 `type` 字段可指定——429 限流应返回 `rate_limit_error`,
/// SDK(尤其 OpenAI 官方库)据此做退避重试,写成 `invalid_request_error`
/// 会被当成「请求本身有问题」而直接放弃。
pub fn fail_typed(
r: *mut ngx_http_request_t,
status: HTTPStatus,
err_type: &str,
code: &str,
msg: &str,
) -> Status {
let body = json!({
"error": {
"message": msg,
"type": err_type,
"code": code,
}
})
.to_string();
let http_code = status.0 as ngx_int_t;
// 先把自定义响应体发出去(nginx 之后不会再补一份默认错误页,因为 header 已发)
let _ = crate::http::send(r, status, &body);
// 再把状态码交回 nginx,由它终结本请求
Status(http_code)
}
// ===========================================================================
// 限流与配额
// ===========================================================================
/// 限流与每日配额检查。拒绝时直接发 429 并返回 Some(状态),放行返回 None。
///
/// **先增后判**:窗口计数里也包含被拒的请求。这只影响「超限后计数继续涨」,
/// 不影响正确性(反正已在超限状态);换来的是实现无需区分「合法请求才计数」。
///
/// # Safety
/// `r` 由 nginx 传入且有效。
pub unsafe fn check_quota(
r: *mut ngx_http_request_t,
username: &str,
rpm: i64,
daily: i64,
) -> Option<Status> {
let now = util::now();
// 每分钟窗口(60s 滚动对齐到自然分钟)。rpm<=0 表示不限,跳过计数省一次写
if rpm > 0 {
let used = state::bump_window(config::KEY_RL_PREFIX, username, now / 60);
if used > rpm {
util::log_warn(&format!(
"[llm] {username} 触发每分钟限流 {used}/{rpm},本请求 429"
));
return Some(fail_typed(
r,
HTTPStatus::TOO_MANY_REQUESTS,
"rate_limit_error",
"rate_limit_exceeded",
&format!("请求过于频繁:每分钟上限 {rpm} 次,请稍后重试"),
));
}
}
// 每日窗口按本地自然日切(见 util::day_id)
if daily > 0 {
let today = state::bump_window(config::KEY_ST_PREFIX, username, util::day_id(now));
if today > daily {
util::log_warn(&format!(
"[llm] {username} 触发每日配额 {today}/{daily},本请求 429"
));
return Some(fail_typed(
r,
HTTPStatus::TOO_MANY_REQUESTS,
"insufficient_quota",
"insufficient_quota",
&format!("已达每日请求上限 {daily} 次,明日 0 点重置或联系管理员调整"),
));
}
}
None
}
// ===========================================================================
// 模型发现(本地应答,不去上游)
// ===========================================================================
/// 是不是"列出模型"请求:`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 !crate::http::method_str(r).eq_ignore_ascii_case("GET") {
return false;
}
let uri = crate::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 = crate::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 _ = crate::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` 写入)。
///
/// 共用的代价是每个变量各查一次共享内存:一次读锁 + 一次 BTreeMap 查找 +
/// 一次小分配,量级在微秒以内,相对一次 LLM 推理完全可忽略;
/// 换来的是不必维护三份几乎相同的代码。
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> {
let slot = slot_of(r)?;
let payload = state::get_upstream(&slot)?;
let (base, auth) = upstreams::split_payload(&payload);
Some(match data {
VAR_TARGET => join_target(base, &upstream_uri(r)),
VAR_HOST => host_of(base).to_owned(),
VAR_AUTH => auth.to_owned(),
_ => return None,
})
})();
match resolved {
Some(value) => set_value(r, v, &value),
None => {
(*v).set_not_found(1);
(*v).set_valid(0);
Status::NGX_ERROR.into()
}
}
}
}