//! API 代理:把外部供应商的 API 资产挂到网关下。 //! //! 与 LLM 代理(`llm.rs`)是**同一套下行契约**——都认 `sk_` 那把 Key、都吃 //! 同一份限流配额、都进同一套用量统计——差别只在上游形态: //! //! | | LLM 代理 | API 代理 | //! | --- | --- | --- | //! | 上游 | N 家厂商,各有基址与密钥 | 每条记录自带基址与供应商 Key | //! | URL 第一段 | `slot` → `up:` 里的 `base \n auth` | `slug` → `ax:` 里的 `base \n key \n asset_id` | //! | 请求体 | 客户端原样带过来 | **由网关从 query 拼**(见下) | //! //! ## 为什么请求体必须由网关拼 //! //! 供应商侧只有一个收口 `POST /api/v1/ai/request`,资产靠**请求体里的 //! `asset_id`** 区分。如果让客户端自己带 `asset_id`,管理员就失去了 //! 「只暴露免费资产」的控制力——任何人都能拿网关的 Key 去刷最贵的那个模型。 //! 所以资产选择权留在服务端:`slug → asset_id` 由管理员配置, //! 调用方只能决定参数。 //! //! 反过来,参数只能走 **query string**:转发决策在 access 阶段,而请求体 //! 要到 content 阶段才读得到(见 `llm.rs` 模块头注释)。nginx 侧靠 //! `proxy_method POST` + `proxy_set_body $apix_body` 把 GET 变成 //! 带体的 POST,网关不需要自己实现 upstream。 //! //! `data/api-proxies.json` 含供应商真 Key,**敏感级别等同 `users.json`**。 use ngx::core::Status; use ngx::ffi::{ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t}; use serde_json::{Value, json}; use crate::config; use crate::http; use crate::models::{ApiProxy, ApiProxyStore}; use crate::state; use crate::store; use crate::util; // =========================================================================== // 变量分派标记 // =========================================================================== /// `$apix_target`:完整上游 URL(`base + /api/v1/ai/request`) pub const VAR_TARGET: usize = 1; /// `$apix_host`:上游 Host 头 pub const VAR_HOST: usize = 2; /// `$apix_key`:供应商 API Key(下行那把 `sk_` 到此为止,不往上游传) pub const VAR_KEY: usize = 3; /// `$apix_body`:由 query 拼出的调用体 pub const VAR_BODY: usize = 4; /// `$apix_probe_target` / `$apix_probe_body`:管理台「测试」用的**免费**预估调用 pub const VAR_PROBE_TARGET: usize = 5; pub const VAR_PROBE_BODY: usize = 6; /// shm payload 内部分隔符:base / 供应商 Key / asset_id 之间。 /// /// base 是 URL、key 与 asset_id 都是 token 类字符串,都不可能含换行。 pub const PAYLOAD_SEP: char = '\n'; /// 内部探测前缀(管理台「测试」按钮经内部重定向落到 `/_apix_probe/`) pub const PROBE_URI_PREFIX: &str = "/_apix_probe/"; const PROBE_PREFIX: &str = PROBE_URI_PREFIX; /// 对外的 API 代理前缀 const PUB_PREFIX: &str = "/apix/"; // =========================================================================== // 校验 // =========================================================================== /// slug:小写字母/数字开头,其后可含短横线、下划线。与 `upstreams::validate_slot` /// 同一套规则(保持一致,管理员不用记两套),只把错误文案换成「slug」。 pub fn validate_slug(raw: &str) -> Result { let s = util::trim(raw).to_ascii_lowercase(); if s.is_empty() { return Err("缺少 slug 参数".to_owned()); } if s.len() > config::APIX_SLUG_MAX_LEN { return Err(format!("slug 长度不能超过 {} 个字符", config::APIX_SLUG_MAX_LEN)); } let bytes = s.as_bytes(); let head_ok = matches!(bytes[0], b'a'..=b'z' | b'0'..=b'9'); let tail_ok = bytes[1..].iter().all(|&b| matches!(b, b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_')); if !head_ok || !tail_ok { return Err("slug 只能是小写字母、数字、短横线或下划线,且不能以符号开头".to_owned()); } Ok(s) } /// 供应商基址:`http(s)://host`,允许尾随路径(供应商挂在子路径下的情况)。 pub fn validate_base(raw: &str) -> Result { let s = util::trim(raw).trim_end_matches('/').to_owned(); if s.is_empty() { return Err("缺少 base 参数".to_owned()); } if s.len() > config::APIX_URL_MAX_LEN { return Err(format!("base 长度不能超过 {} 个字符", config::APIX_URL_MAX_LEN)); } let rest = if let Some(r) = s.strip_prefix("https://") { r } else if let Some(r) = s.strip_prefix("http://") { r } else { return Err("base 必须以 http:// 或 https:// 开头,例如 https://api.example.com".to_owned()); }; if rest.is_empty() || rest.split('/').next().unwrap_or("").is_empty() { return Err("base 缺少主机名".to_owned()); } if rest.chars().any(char::is_whitespace) || rest.contains('@') { return Err("base 不允许包含空格或用户信息(user@host)".to_owned()); } Ok(s) } /// asset_id:供应商那边的资产标识。宽进——各供应商的命名规则不同, /// 这里只挡空白与控制字符(它要出现在 JSON 与 HTML 里)。 fn validate_asset(raw: &str) -> Result { let s = util::trim(raw).to_owned(); if s.is_empty() { return Err("缺少 asset_id 参数".to_owned()); } if s.chars().count() > config::APIX_ASSET_MAX_LEN { return Err(format!("asset_id 超过 {} 个字符", config::APIX_ASSET_MAX_LEN)); } if s.chars().any(char::is_whitespace) || s.chars().any(char::is_control) { return Err("asset_id 不能包含空格或控制字符".to_owned()); } Ok(s) } fn check_params(raw: &[String]) -> Result, String> { if raw.len() > config::APIX_PARAM_MAX { return Err(format!("单个代理最多声明 {} 个参数", config::APIX_PARAM_MAX)); } let mut out: Vec = Vec::new(); for item in raw { let p = util::trim(item); if p.is_empty() { continue; } if p.chars().count() > config::APIX_NAME_MAX_LEN { return Err(format!("参数名「{p}」超过 {} 个字符", config::APIX_NAME_MAX_LEN)); } if p.chars().any(char::is_whitespace) || p.chars().any(char::is_control) { return Err(format!("参数名「{p}」不能包含空格或控制字符")); } if !out.iter().any(|x| x == p) { out.push(p.to_owned()); } } Ok(out) } // =========================================================================== // 共享内存同步(写穿 / 装载) // =========================================================================== fn payload_of(item: &ApiProxy) -> String { format!("{}{PAYLOAD_SEP}{}{PAYLOAD_SEP}{}", item.base, item.key, item.asset_id) } /// 拆 payload:`base \n key \n asset_id` pub fn split_payload(payload: &str) -> (&str, &str, &str) { let mut it = payload.splitn(3, PAYLOAD_SEP); let base = it.next().unwrap_or(""); let key = it.next().unwrap_or(""); let asset = it.next().unwrap_or(""); (base, key, asset) } /// 把一条代理同步进共享内存。**所有写操作之后必须调用它**。 /// /// 停用 = 删除(与 `upstreams::sync_shm` 同一手法):热路径「查不到 = 不可用」, /// 这样停用即刻生效且不留残留。 pub fn sync_shm(slug: &str, store: &ApiProxyStore) { let Some(item) = store.items.get(slug) else { state::remove(config::KEY_AX_PREFIX, slug.as_bytes()); return; }; if !item.enabled { state::remove(config::KEY_AX_PREFIX, slug.as_bytes()); return; } let payload = payload_of(item); if !state::put(config::KEY_AX_PREFIX, slug.as_bytes(), payload.as_bytes(), 0) { util::log_err(&format!( "[apix] 代理配置写共享内存失败 slug={slug} —— 该代理会 404(共享内存可能已满)" )); } } /// 全量重载代理表(启动装载 / 供应商凭据变更后)。返回装载条数。 pub fn reload_shm() -> usize { state::clear_prefix(config::KEY_AX_PREFIX); let data = store::read_api_proxies(); let mut expected = 0; let mut loaded = 0; for (slug, item) in &data.items { if !item.enabled { continue; } expected += 1; let payload = payload_of(item); if state::put(config::KEY_AX_PREFIX, slug.as_bytes(), payload.as_bytes(), 0) { loaded += 1; } } if loaded != expected { util::log_err(&format!( "[apix] 代理装载不全:{loaded}/{expected} —— 有代理会 404" )); } loaded } /// 热路径查表:`slug → (base, 供应商Key, asset_id)` pub fn lookup(slug: &str) -> Option<(String, String, String)> { let payload = state::get(config::KEY_AX_PREFIX, slug.as_bytes())?.0; let (base, key, asset) = split_payload(&payload); if asset.is_empty() { return None; } Some((base.to_owned(), key.to_owned(), asset.to_owned())) } // =========================================================================== // 请求解析 // =========================================================================== /// 取 URL 里的 slug:`/apix/search?q=1` 或 `/_apix_probe/search` → `search` /// /// 两个前缀都认:对外出口与内部探测共用同一套「取 slug → 拼体 → 换 Key」逻辑, /// 与 `llm::slot_of` 对 `/_upstream_test` 的处理是同一个手法。 pub fn slug_of(r: *mut ngx_http_request_t) -> Option { let uri = crate::http::uri(r); let rest = uri .strip_prefix(PROBE_PREFIX) .or_else(|| uri.strip_prefix(PUB_PREFIX))?; let slug = rest.split('/').next().unwrap_or(""); if slug.is_empty() { return None; } Some(slug.to_ascii_lowercase()) } /// 从 `https://api.example.com:443` 取出 `api.example.com:443` 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, } } /// JSON 字符串字面量(含两侧引号)。 /// /// 自己拼而不走 `serde_json` 是因为输入来自 query string,中文与特殊字符 /// 都会被 percent-encode 过一遍,这里必须按 JSON 规则重新转义—— /// 直接 `format!("\"{v}\"")` 遇到 `"` 或 `\` 就拼出非法 JSON, /// 上游报 400 而从网关日志完全看不出是拼体的问题。 fn json_quote(v: &str) -> String { let mut out = String::with_capacity(v.len() + 2); out.push('"'); for c in v.chars() { match c { '"' => out.push_str("\\\""), '\\' => out.push_str("\\\\"), '\n' => out.push_str("\\n"), '\r' => out.push_str("\\r"), '\t' => out.push_str("\\t"), c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)), c => out.push(c), } } out.push('"'); out } /// 单个参数值截断(bytes 级,避免把几 MB 的垃圾塞进调用体) fn clip(v: &str) -> &str { if v.len() <= config::APIX_VAL_MAX { return v; } // 截断到字符边界,否则 `\u{fffd}` 会污染整个 JSON let mut end = config::APIX_VAL_MAX; while end > 0 && !v.is_char_boundary(end) { end -= 1; } &v[..end] } /// 由 query 拼出供应商的调用体。 /// /// ```text /// ?q=nginx&format=json → {"asset_id":"searxng-search","call_data":{"q":"nginx","format":"json"}} /// ?prompt=你好 → {"asset_id":"minimax-m3","prompt":"你好","call_data":{}} /// ``` /// /// `prompt` 单独提到顶层:供应商的 model 类资产(MiniMax-M3 等)把它当必填字段, /// 塞进 `call_data` 会被当成未知参数。其余参数一律进 `call_data`。 pub fn build_body(asset_id: &str, args: &[(String, String)]) -> String { let mut call = String::new(); let mut prompt: Option<&str> = None; let mut n = 0; for (k, v) in args { if k.is_empty() || n >= config::APIX_ARG_MAX { continue; } if k == "prompt" { prompt = Some(v); continue; } if !call.is_empty() { call.push(','); } call.push_str(&json_quote(k)); call.push(':'); call.push_str(&json_quote(clip(v))); n += 1; } let mut body = String::with_capacity(128 + call.len()); body.push_str("{\"asset_id\":"); body.push_str(&json_quote(asset_id)); if let Some(p) = prompt { body.push_str(",\"prompt\":"); body.push_str(&json_quote(clip(p))); } body.push_str(",\"call_data\":{"); body.push_str(&call); body.push_str("}}"); body } fn build_body_from_request(r: *mut ngx_http_request_t, asset_id: &str) -> String { let args = util::parse_kv(&http::args_raw(r)); build_body(asset_id, &args) } // =========================================================================== // 变量 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 = ngx::core::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(); } core::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() } /// 六个 API 代理变量共用一个 get_handler,靠 `var.data` 分派。 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 传入且有效;slug_of 只读请求结构 unsafe { let resolved = (|| -> Option { let slug = slug_of(r)?; let (base, key, asset) = lookup(&slug)?; Some(match data { VAR_TARGET => format!("{base}{}", config::APIX_REQUEST_PATH), VAR_PROBE_TARGET => format!("{base}{}", config::APIX_ESTIMATE_PATH), VAR_HOST => host_of(&base).to_owned(), VAR_KEY => key, VAR_BODY => build_body_from_request(r, &asset), VAR_PROBE_BODY => { // 预估是**免费**的,且不真正执行资产——用它当连通性探针, // 响应里的 current_balance_usd 顺带把供应商余额带回来 format!("{{\"asset_id\":{},\"max_tokens\":1}}", json_quote(&asset)) } _ => 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() } } } } // =========================================================================== // 查询 / 写入 // =========================================================================== pub fn all() -> Vec<(String, ApiProxy)> { store::read_api_proxies() .items .into_iter() .collect() } /// 客户端应当使用的调用地址(base,不带 query)。端口由调用方从请求 Host 头取, /// **不要写死**(部署在 88 时要带 `:88`,放在 443 反代后面时不能带)。 /// query 参数由前端按 `params` 拼一次(避免后端与前端各拼一次导致 `?q=?q=`)。 pub fn call_url(slug: &str, port: &str) -> String { format!("https://{}{port}{PUB_PREFIX}{slug}", config::LLM_PUBLIC_HOST) } /// 新增或覆盖一个代理条目。 /// /// `params = None` 表示保持原值(只改名字时不必回填参数清单)。 /// `base` / `key` / `supplier` 同理:`None` 或空串都表示「保留原值」—— /// 这样编辑时不必把密钥再抄一遍。新建时若填了空串仍为空,则报错 /// (没有基址与密钥无法转发)。 pub fn upsert( slug_raw: &str, asset_raw: &str, base_raw: Option<&String>, key_raw: Option<&String>, supplier_raw: Option<&String>, name: Option<&String>, desc: Option<&String>, params: Option>, enabled: bool, note: Option<&String>, ) -> Result { let slug = validate_slug(slug_raw)?; let asset_id = validate_asset(asset_raw)?; let params = match params { Some(list) => Some(check_params(&list)?), None => None, }; // base / key:空串视为「保留原值」,交给下方闭包按 existing 决定 let new_base = match base_raw { Some(b) => { let b = util::trim(b); if b.is_empty() { None } else { Some(validate_base(&b)?) } } None => None, }; let new_key = match key_raw { Some(k) => { let k = util::trim(k).to_owned(); if k.is_empty() { None } else { if k.chars().count() > config::APIX_KEY_MAX_LEN { return Err(format!("供应商 Key 超过 {} 个字符", config::APIX_KEY_MAX_LEN)); } Some(k) } } None => None, }; let key = slug.clone(); let (item, snapshot) = store::update_api_proxies(move |data| { let existing = data.items.get(&key).cloned(); let base = new_base .or_else(|| existing.as_ref().map(|e| e.base.clone())) .unwrap_or_default(); let key_val = new_key .or_else(|| existing.as_ref().map(|e| e.key.clone())) .unwrap_or_default(); if existing.is_none() && (base.is_empty() || key_val.is_empty()) { return Err("新建代理必须提供供应商基址与密钥".to_owned()); } let supplier = match supplier_raw { Some(s) => util::trim(s).chars().take(config::APIX_NAME_MAX_LEN).collect(), None => existing.as_ref().map(|e| e.supplier.clone()).unwrap_or_default(), }; let name = match name { Some(n) => util::trim(n).chars().take(config::APIX_NAME_MAX_LEN).collect(), None => existing.as_ref().map(|e| e.name.clone()).unwrap_or_default(), }; let desc = match desc { Some(d) => util::trim(d).chars().take(config::APIX_DESC_MAX_LEN).collect(), None => existing.as_ref().map(|e| e.desc.clone()).unwrap_or_default(), }; let note = match note { Some(n) => util::trim(n).to_owned(), None => existing.as_ref().map(|e| e.note.clone()).unwrap_or_default(), }; let params = match params { Some(p) => p, None => existing.as_ref().map(|e| e.params.clone()).unwrap_or_default(), }; let created_at = existing .as_ref() .map(|e| e.created_at) .filter(|&t| t > 0) .unwrap_or_else(util::now); let item = ApiProxy { asset_id, supplier, base, key: key_val, name, desc, params, enabled, note, created_at }; data.items.insert(key.clone(), item.clone()); Ok((item, data.clone())) })?; sync_shm(&slug, &snapshot); Ok(item) } pub fn remove(slug_raw: &str) -> Result { let slug = validate_slug(slug_raw)?; let key = slug.clone(); store::update_api_proxies(move |data| { if data.items.remove(&key).is_none() { return Err(format!("代理 {key} 不存在")); } Ok(()) })?; state::remove(config::KEY_AX_PREFIX, slug.as_bytes()); Ok(slug) } // =========================================================================== // 对外投影 // =========================================================================== /// 转成管理台可见的字段。 /// /// **绝不回显完整供应商 Key**——与 `upstreams::view` 同一理由:管理台页面会被 /// 截图、被浏览器插件读取,回显真 Key 等于把供应商余额摆在一个 HTML 里。 /// `url` 只给 base 路径,query 参数由前端按 `params` 拼一次。 pub fn view(slug: &str, item: &ApiProxy, port: &str) -> Value { json!({ "slug": slug, "asset_id": item.asset_id, "supplier": item.supplier, "base": item.base, "name": item.name, "desc": item.desc, "params": item.params, "enabled": item.enabled, "key_set": !item.key.is_empty(), "key_mask": if item.key.is_empty() { "-".to_owned() } else { util::mask_key(&item.key) }, "note": item.note, "created_at": item.created_at, "created_at_text": util::fmt_time(item.created_at), "url": call_url(slug, port), }) } pub fn view_all(list: &[(String, ApiProxy)], port: &str) -> Vec { list.iter().map(|(slug, it)| view(slug, it, port)).collect() }