- 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
443 lines
18 KiB
Rust
443 lines
18 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:` 键里,热路径只碰共享内存。
|
||
//! * **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()
|
||
}
|
||
}
|
||
}
|
||
}
|