//! LLM API 代理热路径。 //! //! 客户端把 base_url 指向 `https://llm.yourdomain.com/`,用**与域名接口 //! 同一套** API Key 鉴权,由网关换成上游真实密钥后转发: //! //! ```text //! POST /openai/v1/chat/completions //! │ Authorization: Bearer sk_<本网关签发的 Key> //! ▼ //! ① 取 URL 第一段 → slot = "openai" //! ② 查 ukey: → 身份(纯内存,不读 users.json) //! ③ 查 up: → 上游基址 + 上游真 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:`,过期视为不存在)。**未命中即 404,无回源兜底**。 pub fn upstream_live(slot: &str) -> bool { state::get_live(config::KEY_UP_PREFIX, slot.as_bytes(), util::now()).is_some() } /// 剥掉内部测试前缀:`/_upstream_test//...` → `//...` /// /// 管理台的「测试」按钮经 `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//v1/chat/completions`, /// 让 `proxy_pass $llm_target` 原样复用本文件的取 slot / 拼 URL / 换密钥逻辑。 /// 前缀剥掉后语义与客户端直打 `//...` 完全一致(同一套鉴权变量)。 pub fn slot_of(r: *mut ngx_http_request_t) -> Option { 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 //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 = 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 = 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() } } } }