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
This commit is contained in:
admin committed 2026-09-13 11:43:22 +08:00
1 parent 1fb83e4dda
commit 74aeefee58
35 files changed
+2513 -1360

No files matched your search

+485
View File
@@ -0,0 +1,485 @@
//! 插件路由表(过渡期):LLM 上游 / 用量 / API 代理类端点。
//!
//! 身份类端点已下沉 `ipass-core::api`(CorePlugin),域名类端点已下沉
//! `plugin-domain::api`(DomainPlugin)。本表随 P3 / P4 把 llm 与 apix
//! 端点迁入各自插件后逐步清空、最终删除。
//!
//! 鉴权语义与内核共用一套:`ipass_core::api::{Guard, Actor, run_guarded}`。
use ngx::core::{Pool, Status};
use ngx::ffi::ngx_http_request_t;
use ngx::http::HTTPStatus;
use serde_json::{Value, json};
use ipass_core::api::{Actor, Guard, run_guarded, user_or_401};
use crate::apix;
use crate::config;
use crate::http;
use crate::state;
use crate::stats;
use crate::upstreams;
use crate::users;
use crate::util;
// ===========================================================================
// 路由
// ===========================================================================
/// 路由表。刻意用精确匹配而非正则——接口路径是固定的,
/// 正则只会引入「写错锚点导致前缀误匹配」的风险。
fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> {
let entry: (Guard, Handler) = match (method, uri) {
("GET", "/api/admin/upstreams") => (Guard::Admin, h_admin_upstreams),
("POST", "/api/admin/upstreams/save") => (Guard::Admin, h_admin_upstream_save),
("POST", "/api/admin/upstreams/test") => (Guard::Admin, h_admin_upstream_test),
("POST", "/api/admin/upstreams/delete") => (Guard::Admin, h_admin_upstream_delete),
("GET", "/api/admin/usage") => (Guard::Admin, h_admin_usage),
("GET", "/api/admin/trend") => (Guard::Admin, h_admin_trend),
("GET", "/api/admin/apix") => (Guard::Admin, h_admin_apix),
("POST", "/api/admin/apix/save") => (Guard::Admin, h_admin_apix_save),
("POST", "/api/admin/apix/delete") => (Guard::Admin, h_admin_apix_delete),
("POST", "/api/admin/apix/test") => (Guard::Admin, h_admin_apix_test),
("GET", "/api/v1/apix") => (Guard::User, h_my_apix),
("GET", "/api/v1/models") => (Guard::User, h_my_models),
("GET", "/api/v1/usage") => (Guard::User, h_my_usage),
("GET", "/api/v1/upstreams") => (Guard::User, h_my_upstreams),
_ => return None,
};
Some(entry)
}
type Handler = fn(*mut ngx_http_request_t, Actor) -> Status;
/// 本表分发:认领则返回响应状态,不认领返回 `None`(交给下一个插件)。
pub fn dispatch(r: *mut ngx_http_request_t) -> Option<Status> {
let method = http::method_str(r);
let uri = http::uri(r);
let Some((guard, handler)) = route(&method, &uri) else {
return None;
};
Some(run_guarded(r, guard, handler))
}
// ===========================================================================
// 管理员:LLM 上游
// ===========================================================================
fn h_admin_upstreams(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
http::ok(
r,
json!({ "items": upstreams::view_all(&upstreams::all(), &http::host_port(r)) }),
"ok",
)
}
fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
// 表单没提交 enabled 字段时视为「启用」——否则改个备注就会把上游改停,
// 这种误伤在管理台上极难自查
let enabled = match p.get("enabled") {
None => true,
Some(v) => util::to_bool(Some(v)),
};
// models 缺省 = 保持原清单;显式传(哪怕是空串)= 覆盖。
// 分隔符同时接受换行/逗号/顿号/分号——粘一份厂商文档里的模型列表是常见操作。
let models = p.get("models").map(|raw| parse_model_list(raw));
let slot_raw = p.get("slot").map(String::as_str).unwrap_or("");
match upstreams::upsert(
slot_raw,
p.get("base").map(String::as_str).unwrap_or(""),
models,
p.get("auth"),
enabled,
p.get("note"),
) {
Ok(up) => {
// 用校验后的 slot 回显;直接拿原始入参会把大小写差异带进响应
let slot = upstreams::validate_slot(slot_raw).unwrap_or_default();
util::log_notice(&format!(
"[api] 保存 LLM 上游 {slot} enabled={enabled} models={}",
up.models.len()
));
// base_url 带「调用方正在用的端口」:见 upstreams::base_url 的说明
http::ok(r, upstreams::view(&slot, &up, &http::host_port(r)), "已保存")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 把管理台/接口传入的模型列表串拆成模型名数组。
///
/// 允许的写法(混用也认):`a,b` / `a、b` / `a;b` / 一行一个。
pub fn parse_model_list(raw: &str) -> Vec<String> {
raw.split(|c: char| c == ',' || c == '、' || c == ';' || c == '\n' || c == '\r' || c == '\t')
.map(|s| util::trim(s).to_owned())
.filter(|s| !s.is_empty())
.collect()
}
fn h_admin_upstream_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
match upstreams::remove(p.get("slot").map(String::as_str).unwrap_or("")) {
Ok(slot) => {
util::log_notice(&format!("[api] 删除 LLM 上游 {slot}"));
http::ok(r, json!({ "slot": slot }), "已删除")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:上游连通性测试(管理台「测试」按钮)。
///
/// 面板把 slot 放在 query(`?slot=x`),把**要发给上游的探测 JSON**(真实
/// chat/completions 请求,max_tokens=1)放在请求体——模块对体零改写。
/// 实现上校验 slot 存在后 `ngx_http_internal_redirect` 到管理 server 的
/// 内部 location `/_upstream_test/<slot>/v1/chat/completions`:
///
/// * `proxy_pass $llm_target` 原样复用 LLM 链路的取 slot / 拼路径 / 换真 Key
/// 逻辑(见 `llm::slot_of` 对 `/_upstream_test` 前缀的识别);
/// * 请求体在 API 两段式读取里已经进 `r->request_body`,内部重定向后由
/// proxy 原样转发;
/// * 上游的真实状态码与响应体直接透传给面板——通不通、错在哪个厂商,
/// 面板看到的就是厂商原话。
///
/// 为什么不能在浏览器里直测:上游真 Key 只存在服务端(面板只有掩码),
/// 且 lm 域名与 mdm 不同源,fetch 会被 CORS 拦住——测试必须在服务端发起。
fn h_admin_upstream_test(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let slot_raw = http::params(r).get("slot").cloned().unwrap_or_default();
let slot = match upstreams::validate_slot(&slot_raw) {
Ok(s) => s,
Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e),
};
if state::get_upstream(&slot).is_none() {
return http::fail(r, HTTPStatus::NOT_FOUND, &format!("上游 {slot} 不存在"));
}
let uri = format!("/_upstream_test/{slot}/v1/chat/completions");
util::log_notice(&format!("[api] 测试 LLM 上游 {slot}"));
// ⚠️ nginx 的 internal_redirect 只**浅拷贝 ngx_str_t 结构体**(data 指针 + len),
// 不拷贝字节内容。若把栈上 String 的指针直接递过去,函数一返回堆内存就被回收,
// 之后 log 阶段读 r->uri 全是 NUL——健康标记、slot 解析全部静默失效(实测踩过)。
// 必须把 URI 字节拷进**请求池**,让它活到请求结束。
//
// SAFETY: r 有效;池内存在整个请求生命周期内有效。
unsafe {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = uri.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
return http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, "内存分配失败");
}
core::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
let mut u = nginx_sys::ngx_str_t {
len: bytes.len(),
data,
};
let mut args = nginx_sys::ngx_str_t {
len: 0,
data: std::ptr::null_mut(),
};
nginx_sys::ngx_http_internal_redirect(r, &mut u, &mut args);
}
Status::NGX_DONE
}
/// 管理员:LLM 用量总览(每人 / 每上游 / 合计)。
///
/// 口径是**请求数**,且只统计真正转发出去的请求(见 `stats` 模块头注释)。
/// 想看 token 级用量得改架构(自建 upstream 拦响应体),不在本项目范围。
fn h_admin_usage(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
http::ok(r, stats::overview(util::now()), "ok")
}
/// 管理员:LLM 用量趋势(图表数据源)。
///
/// `days` 缺省 14 天,上限由 `config::TREND_DAYS_MAX` 兜住。
/// 按账号 / 按上游两个维度需要**先知道有哪些名字**(键里带日窗 id,扫不出来),
/// 所以这里把 users / upstreams 的名册传进去,由 stats 逐个精确取键。
fn h_admin_trend(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let days = p
.get("days")
.and_then(|v| util::trim(v).parse::<i64>().ok())
.unwrap_or_else(stats::trend_default_days);
let usernames: Vec<String> = users::all().into_iter().map(|u| u.username).collect();
// API 代理与 LLM 上游共用同一片用量键空间,只是 slot 带 `api/` 前缀
// (见 `config::APIX_STATS_PREFIX`)——这里一起列出,趋势图才会出现它们
let slots: Vec<String> = upstreams::all()
.into_iter()
.map(|(slot, _)| slot)
.chain(apix::all().into_iter().map(|(slug, _)| format!("{}{}", config::APIX_STATS_PREFIX, slug)))
.collect();
http::ok(r, stats::trend(util::now(), days, &usernames, &slots), "ok")
}
// ===========================================================================
// API 代理管理
// ===========================================================================
/// 管理员:API 代理清单
fn h_admin_apix(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let port = http::host_port(r);
let list = apix::all();
http::ok(
r,
json!({
"items": apix::view_all(&list, &port),
"count": list.len(),
}),
"ok",
)
}
/// 管理员:新增/修改一个 API 代理条目
fn h_admin_apix_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let slug = p.get("slug").cloned().unwrap_or_default();
let asset = p.get("asset_id").cloned().unwrap_or_default();
// 参数清单允许两种写法:逗号分隔(`q,format`)或 JSON 数组(`["q"]`)
let params = p.get("params").and_then(|v| {
let v = util::trim(v);
if v.is_empty() {
return None;
}
Some(if let Ok(Value::Array(arr)) = serde_json::from_str::<Value>(v) {
arr.into_iter()
.filter_map(|x| x.as_str().map(str::to_owned))
.collect::<Vec<String>>()
} else {
v.split(',').map(str::to_owned).collect::<Vec<String>>()
})
});
// 不带 enabled 视为「启用」:新建表单里漏勾是常见手滑,默认值取更安全的一侧
let enabled = match p.get("enabled") {
Some(v) => util::to_bool(Some(v)),
None => true,
};
match apix::upsert(
&slug,
&asset,
p.get("base"),
p.get("key"),
p.get("supplier"),
p.get("name"),
p.get("desc"),
params,
enabled,
p.get("note"),
) {
Ok(item) => {
util::log_notice(&format!("[api] 保存 API 代理 {slug} → {asset}"));
http::ok(r, json!({ "slug": slug, "asset_id": item.asset_id }), "已保存")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:删除一个 API 代理条目
fn h_admin_apix_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
match apix::remove(p.get("slug").map(String::as_str).unwrap_or("")) {
Ok(slug) => {
util::log_notice(&format!("[api] 删除 API 代理 {slug}"));
http::ok(r, json!({ "slug": slug }), "已删除")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:探测供应商 Key 是否可用(管理台「测试」按钮)。
///
/// 走供应商的**免费预估**接口(`/api/v1/ai/estimate`):它不执行资产、不扣费,
/// 响应里还带 `current_balance_usd` —— 一次调用同时拿到「Key 通不通」和
/// 「还剩多少钱」。实现上内部重定向到管理 server 的 `/_apix_probe/<slug>`,
/// 复用 `$apix_probe_*` 变量(拼体、换 Key 与真实转发同一套逻辑)。
fn h_admin_apix_test(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let slug_raw = http::params(r).get("slug").cloned().unwrap_or_default();
let slug = match apix::validate_slug(&slug_raw) {
Ok(s) => s,
Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e),
};
if apix::lookup(&slug).is_none() {
return http::fail(r, HTTPStatus::NOT_FOUND, &format!("代理 {slug} 不存在或已停用"));
}
let uri = format!("{}{}", apix::PROBE_URI_PREFIX, slug);
util::log_notice(&format!("[api] 测试 API 代理 {slug}"));
// ⚠️ 与 h_admin_upstream_test 同一个坑:internal_redirect 只浅拷贝 ngx_str_t,
// 必须把字节拷进请求池,否则函数返回后 r->uri 全是 NUL。
// SAFETY: r 有效;池内存在整个请求生命周期内有效。
unsafe {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = uri.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
return http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, "内存分配失败");
}
core::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
let mut u = nginx_sys::ngx_str_t { len: bytes.len(), data };
let mut args = nginx_sys::ngx_str_t {
len: 0,
data: core::ptr::null_mut(),
};
nginx_sys::ngx_http_internal_redirect(r, &mut u, &mut args);
}
Status::NGX_DONE
}
/// 账号态:列出当前可用的 API 代理及调用地址
fn h_my_apix(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let port = http::host_port(r);
let items: Vec<Value> = apix::all()
.into_iter()
.filter(|(_, it)| it.enabled)
.map(|(slug, it)| apix::view(&slug, &it, &port))
.collect();
http::ok(r, json!({ "items": items, "count": items.len() }), "ok")
}
/// 账号态:看看自己能用哪些上游。
///
/// 刻意只回显 slot / base_url / **模型清单**——**不回显任何密钥**(连脱敏都不给,
/// 上游密钥与调用方无关,没有知道的必要)。
fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status {
// 回显的 base_url 必须带「调用方正在用的端口」,否则客户端照着拼会打不通
let port = http::host_port(r);
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let items: Vec<Value> = upstreams::available(&user.allowed_models)
.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,
"note": up.note,
"status": status,
"status_code": if code > 0 { json!(code) } else { Value::Null },
"checked_at": checked_at,
})
})
.collect();
http::ok(r, json!({ "items": items }), "ok")
}
/// 账号态:列出自己**可用的模型**(上游登记的模型清单,按白名单过滤)。
///
/// 与 LLM 域名下的 `GET /v1/models` 是同一份数据:那边给 OpenAI SDK 用
/// (形状 `{object:"list",data:[{id,...}]}`),这边给管理/自研客户端用
/// (形状 `{code,msg,data}`,带 base_url 便于直接拼请求)。
fn h_my_models(r: *mut ngx_http_request_t, actor: Actor) -> Status {
// 同 h_my_upstreams:base_url 跟随调用方所用的端口
let port = http::host_port(r);
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let available = upstreams::available(&user.allowed_models);
let mut items: Vec<Value> = Vec::new();
for (slot, up) in &available {
for model in &up.models {
items.push(json!({
"model": model,
"slot": slot,
"base_url": upstreams::base_url(slot, up, &port),
"note": up.note,
}));
}
}
http::ok(
r,
json!({
"items": items,
"upstreams": available
.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 { Value::Null },
"checked_at": checked_at,
})
})
.collect::<Vec<_>>(),
}),
"ok",
)
}
/// 账号态:查自己的 LLM 用量(今日 / 累计 / 最近调用 + 分上游明细)。
fn h_my_usage(r: *mut ngx_http_request_t, actor: Actor) -> Status {
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let now = util::now();
let usage = stats::user(&user.username, now);
// token 计量(body filter 从上游 usage 抓的;抓不到 = 0,不补估)
let tin = stats::tokens_user(&user.username, now);
let models: Vec<Value> = stats::user_models(&user.username, now)
.into_iter()
.map(|(slot, u)| {
json!({
"slot": slot,
"today": u.today,
"total": u.total,
"last_ts": u.last_ts,
"last_ts_text": if u.last_ts > 0 { util::fmt_time(u.last_ts) } else { String::new() },
})
})
.collect();
http::ok(
r,
json!({
"username": user.username,
"display_name": user.display_name,
"today": usage.today,
"total": usage.total,
"last_ts": usage.last_ts,
"last_ts_text": if usage.last_ts > 0 { util::fmt_time(usage.last_ts) } else { String::new() },
"tokens": tin.json(),
"models": models,
// 限额一起回显:客户端可据此自我节流,不必等 429
"limits": { "rpm": user.llm_rpm, "daily": user.llm_daily },
}),
"ok",
)
}
+563
View File
@@ -0,0 +1,563 @@
//! 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/<slug>`)
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<String, String> {
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<String, String> {
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<String, String> {
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<Vec<String>, String> {
if raw.len() > config::APIX_PARAM_MAX {
return Err(format!("单个代理最多声明 {} 个参数", config::APIX_PARAM_MAX));
}
let mut out: Vec<String> = 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<String> {
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<String> {
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<Vec<String>>,
enabled: bool,
note: Option<&String>,
) -> Result<ApiProxy, String> {
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<String, String> {
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<Value> {
list.iter().map(|(slug, it)| view(slug, it, port)).collect()
}
File diff suppressed because it is too large. Load diff
+442
View File
@@ -0,0 +1,442 @@
//! 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()
}
}
}
}
+200
View File
@@ -0,0 +1,200 @@
//! LLM 对话审计:把每个**被转发**的 LLM 请求体落盘存档,供事后审计与用量复盘。
//!
//! 设计要点(详见 docs/llm/AUDIT_LOG.md):
//! * **捕获方式**:LLM location 开 `client_body_in_file_only clean`,nginx 自己把
//! 请求体刷到临时文件;本模块在 **log 阶段**(临时文件此刻尚未被清理)把它
//! 复制进审计目录。热路径零改动——access 阶段不读体、不碰内存缓冲,
//! SSE 流式透传不受任何影响。被拒请求(401/403/404/429)与本地应答
//! (/v1/models)的 body 从未被读走 → 没有临时文件 → 天然不入档。
//! * **目录**:`<审计根>/YYYY-MM-DD/<毫秒>_<rand>.json` + 每目录一份 `meta.jsonl`。
//! 审计根默认 = data 目录的兄弟目录 `audit/`(`ipass_audit_dir` 指令可覆盖)。
//! * **清理**:按容量触发(`AUDIT_MAX_BYTES`)——写入后节流巡检
//! (≥ `AUDIT_PURGE_MIN_INTERVAL` 秒一次、AtomicBool 单飞),超限时按日期
//! 目录**从旧到新整目录删除**;worker 启动时强制巡检一次(不依赖外部 cron)。
//! * **失败策略**:审计是旁路功能,任何失败只 `log_err`,绝不影响转发结果。
use std::fs;
use std::io::Write;
use std::path::PathBuf;
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
use ngx::ffi::ngx_http_request_t;
use serde_json::json;
use crate::config;
use crate::store;
use crate::util;
/// `ipass_audit_dir` 覆盖值。配置阶段由 nginx 主线程设置一次,之后只读。
static AUDIT_DIR_OVERRIDE: Mutex<Option<String>> = Mutex::new(None);
/// 上次容量巡检时刻(秒);0 = 从未巡检。
static LAST_PURGE_AT: AtomicI64 = AtomicI64::new(0);
/// 巡检单飞标记:多 worker / 多请求并发时只放一个进去。
static PURGING: AtomicBool = AtomicBool::new(false);
/// 指令 `ipass_audit_dir <path>`:显式指定审计根目录(缺省 = data 兄弟目录)。
pub fn set_dir(dir: &str) {
if let Ok(mut slot) = AUDIT_DIR_OVERRIDE.lock() {
*slot = Some(dir.to_owned());
}
}
/// 审计根目录:显式指令优先,否则取 data 目录的兄弟目录。
/// 每次现算(配置阶段后才可能被调用,store::data_dir() 已就绪)。
fn root() -> PathBuf {
if let Ok(slot) = AUDIT_DIR_OVERRIDE.lock() {
if let Some(d) = slot.as_deref() {
return PathBuf::from(d);
}
}
PathBuf::from(store::data_dir())
.parent()
.map(|p| p.join(config::AUDIT_DIR_NAME))
.unwrap_or_else(|| PathBuf::from(config::AUDIT_DIR_NAME))
}
/// worker 启动:确保审计目录存在 + 强制巡检一次容量。
/// 失败只降级(审计停用 / 跳过本次巡检),绝不阻塞 worker 启动。
pub fn startup() {
let r = root();
if let Err(e) = fs::create_dir_all(&r) {
util::log_err(&format!("[audit] 建目录失败 {}: {e},审计停用", r.display()));
return;
}
purge(true);
}
/// log 阶段捕获:复制 body 临时文件进审计目录 + 追加一行元数据。
///
/// `tin` / `tout` 是 body filter 旁路抓到的 token 数(`llm_usage` 模块提供),
/// 0 = 上游没给 usage(如 OpenAI 流式未开 include_usage)。
///
/// SAFETY: r 必须是 nginx 当前正在 finalize 的请求(log 阶段回调保证)。
pub unsafe fn capture(r: *mut ngx_http_request_t, username: &str, slot: &str, tin: u64, tout: u64) {
let rb = (*r).request_body;
if rb.is_null() {
return;
}
let tf = (*rb).temp_file;
if tf.is_null() {
// body 没被刷过盘(本地应答 / 被拒请求 / 无 body)→ 不审计
return;
}
// 临时文件路径:ngx_temp_file_t.file.name(nginx 创建时填好的完整路径)
let src = match core::str::from_utf8((*tf).file.name.as_bytes()) {
Ok(s) if !s.is_empty() => s.to_owned(),
_ => return,
};
let ts = util::now();
let day = util::fmt_time(ts).get(..10).unwrap_or("unknown").to_owned();
let dir = root().join(&day);
if let Err(e) = fs::create_dir_all(&dir) {
util::log_err(&format!("[audit] 建日期目录失败 {}: {e}", dir.display()));
return;
}
let fname = format!("{}_{}.json", ts * 1000, util::rand_digits(6));
let dst = dir.join(&fname);
// 复制(不是 rename):nginx 在请求池销毁时还要 unlink 临时文件,
// 改名会让它打出 unlink 失败告警;多一次拷贝换零噪音。
if let Err(e) = fs::copy(&src, &dst) {
util::log_err(&format!("[audit] 复制请求体失败 {src}: {e}"));
return;
}
let bytes = fs::metadata(&dst).map(|m| m.len()).unwrap_or(0);
let status = (*r).headers_out.status as u64;
let user = if username.is_empty() { "-" } else { username };
let up = if slot.is_empty() { "-" } else { slot };
let line = json!({
"ts": ts,
"time": util::fmt_time(ts),
"user": user,
"slot": up,
"status": status,
"tin": tin,
"tout": tout,
"file": format!("{day}/{fname}"),
"bytes": bytes,
});
match fs::OpenOptions::new()
.create(true)
.append(true)
.open(dir.join("meta.jsonl"))
{
Ok(mut f) => {
if let Err(e) = writeln!(f, "{line}") {
util::log_err(&format!("[audit] 写 meta 失败: {e}"));
}
}
Err(e) => util::log_err(&format!("[audit] 打开 meta 失败: {e}")),
}
purge(false);
}
/// 容量巡检入口。force=true 跳过节流(启动时用);平时每分钟最多一次。
pub fn purge(force: bool) {
let now = util::now();
if !force && now - LAST_PURGE_AT.load(Ordering::Relaxed) < config::AUDIT_PURGE_MIN_INTERVAL {
return;
}
LAST_PURGE_AT.store(now, Ordering::Relaxed);
if PURGING.swap(true, Ordering::Acquire) {
return; // 已有巡检在跑
}
let result = purge_once();
PURGING.store(false, Ordering::Release);
if let Err(e) = result {
util::log_err(&format!("[audit] 容量巡检失败: {e}"));
}
}
/// 扫描审计根:目录名即日期(字典序 = 时间序),总量超限就从最旧整目录删。
///
/// ⚠️ 本模块无法跑 `cargo test`(dylib 依赖 nginx 主程序的运行时符号,
/// `cargo test --lib` 直接 SIGABRT)——行为由 tests/llm/e2e.sh【9】覆盖。
fn purge_once() -> Result<(), String> {
let r = root();
let mut total: u64 = 0;
let mut dirs: Vec<(PathBuf, u64)> = Vec::new();
for ent in fs::read_dir(&r).map_err(|e| e.to_string())?.flatten() {
let p = ent.path();
if !p.is_dir() {
continue;
}
let mut size: u64 = 0;
if let Ok(files) = fs::read_dir(&p) {
for f in files.flatten() {
if let Ok(md) = f.metadata() {
if md.is_file() {
size += md.len();
}
}
}
}
total += size;
dirs.push((p, size));
}
if total <= config::AUDIT_MAX_BYTES {
return Ok(());
}
dirs.sort_by(|a, b| a.0.cmp(&b.0));
for (p, size) in dirs {
if total <= config::AUDIT_MAX_BYTES {
break;
}
match fs::remove_dir_all(&p) {
Ok(()) => {
total = total.saturating_sub(size);
util::log_notice(&format!("[audit] 超容量,已删除 {}", p.display()));
}
Err(e) => util::log_err(&format!("[audit] 删除 {} 失败: {e}", p.display())),
}
}
Ok(())
}
+275
View File
@@ -0,0 +1,275 @@
//! LLM token 计量:注册 body filter,旁路扫描上游响应,提取尾部 `usage` 的 token 数。
//!
//! 为什么调研结论是「要做 C 模块」、最后只用 Rust 就成了:`ngx_http_top_body_filter`
//! 是 nginx **导出的全局符号**(`src/http/ngx_http.c:76` 定义,`ngx_http.h:197`
//! extern),动态模块可以直接 FFI 引用并把自己插到链头——不需要第二个 .so,
//! 「单容器单动态库」红线无伤。做法与官方 C 模块(copy/postpone filter)同款:
//! `next = top; top = ours;`,next 自持一份。
//!
//! ## 工作方式
//!
//! * **只旁观、不改动**:filter 拿到 chunk 后原样交给下一环(SSE 透传零影响),
//! 同时把内存 buf 的字节追加进 32 KiB **尾部窗口**(请求池分配,随请求回收)。
//! 必须在调下一环**之前**读——下游 filter(write)发送后会前移 `pos`。
//! * **流量识别**:`r->loc_conf` 的 `ModuleConfig.llm` 为真才建窗口——
//! 管理台 / 子域名转发不经过扫描,零开销。
//! * **token 提取**(不做 JSON 解析,按键扫数字,容错优先):
//! - 入 token:`"prompt_tokens"`(OpenAI) / `"input_tokens"`(Anthropic) /
//! `"promptTokenCount"`(Gemini)——**路过就记**(Anthropic 的 message_start
//! 在流头,长流会滑出尾部窗口,不能等收尾再找);
//! - 出 token:`"completion_tokens"` / `"output_tokens"` /
//! `"candidatesTokenCount"`——流结束时取尾部窗口**最后一次**出现
//! (Anthropic message_delta 是累计值,最后一次 = 终值);
//! - 兜底:入出都为 0 时试 Gemini `"totalTokenCount"`。
//! 搜索键都带前导引号,天然避开 `cache_read_input_tokens` 这类子串陷阱。
//! * **记账**:窗口值挂在模块 ctx 上,log 阶段(AuditHandler)统一
//! `stats::add_tokens`(键 `utt:` / `utms:`)并写进审计 meta 行——
//! 身份解析只在 log 阶段做一次,body filter 全程无身份语义。
//!
//! ## 口径
//!
//! OpenAI 系**流式**需要客户端带 `stream_options: {"include_usage": true}`
//! 才有 usage 块(Anthropic / Gemini 默认就带);非流式 JSON 天然带 usage。
//! 抓不到 = 记 0,绝不猜测、绝不补估。
use core::slice;
use ngx::core::Status;
use ngx::ffi::{ngx_chain_t, ngx_http_request_t, ngx_int_t, ngx_pool_t};
use ngx::http::HttpModule;
use crate::Module;
use crate::ModuleConfig;
/// 尾部窗口容量:SSE 最终 usage 块 / 非 stream JSON 的尾部都远小于此。
const TAIL_CAP: usize = 32 * 1024;
type BodyFilterPt =
Option<unsafe extern "C" fn(*mut ngx_http_request_t, *mut ngx_chain_t) -> ngx_int_t>;
extern "C" {
/// nginx 导出的 body filter 链头(动态模块引用主程序符号,dlopen 时解析)
static mut ngx_http_top_body_filter: BodyFilterPt;
}
/// 插入前的原链头——与官方 C 模块同款,每个模块自持一份 next。
static mut NEXT_BODY_FILTER: BodyFilterPt = None;
/// postconfiguration 阶段调用:把自己插到 body filter 链头。
pub fn install() {
unsafe {
NEXT_BODY_FILTER = ngx_http_top_body_filter;
ngx_http_top_body_filter = Some(body_filter);
}
}
// ===========================================================================
// usage 键与数字扫描
// ===========================================================================
/// 入 token 候选键(带前导引号防子串误配)
const KEYS_IN: [&[u8]; 3] = [
b"\"prompt_tokens\":",
b"\"input_tokens\":",
b"\"promptTokenCount\":",
];
/// 出 token 候选键
const KEYS_OUT: [&[u8]; 3] = [
b"\"completion_tokens\":",
b"\"output_tokens\":",
b"\"candidatesTokenCount\":",
];
fn find_from(hay: &[u8], needle: &[u8], from: usize) -> Option<usize> {
if needle.is_empty() || hay.len() < needle.len() {
return None;
}
let end = hay.len() - needle.len();
let mut i = from;
while i <= end {
if &hay[i..i + needle.len()] == needle {
return Some(i);
}
i += 1;
}
None
}
/// 从键名结束处解析 `: <digits>`
fn value_at(hay: &[u8], key_end: usize) -> Option<u64> {
let mut i = key_end;
while i < hay.len() && (hay[i] == b' ' || hay[i] == b'\t') {
i += 1;
}
let start = i;
while i < hay.len() && hay[i].is_ascii_digit() {
i += 1;
}
if i == start {
return None;
}
core::str::from_utf8(&hay[start..i]).ok()?.parse::<u64>().ok()
}
/// 一段字节里,各键**第一次**出现的非零值
fn first_u64(hay: &[u8], keys: &[&[u8]]) -> u64 {
for k in keys {
if let Some(p) = find_from(hay, k, 0) {
if let Some(v) = value_at(hay, p + k.len()) {
if v > 0 {
return v;
}
}
}
}
0
}
/// 一段字节里,各键**最后一次**出现的非零值(Anthropic message_delta 累计语义)
fn last_u64(hay: &[u8], keys: &[&[u8]]) -> Option<u64> {
let mut out = None;
for k in keys {
let mut from = 0;
while let Some(p) = find_from(hay, k, from) {
if let Some(v) = value_at(hay, p + k.len()) {
if v > 0 {
out = Some(v);
}
}
from = p + 1;
}
}
out
}
// ===========================================================================
// per-request 扫描窗口(挂在模块 ctx 上,请求池分配、随请求回收)
// ===========================================================================
#[repr(C)]
struct ScanCtx {
tail: [u8; TAIL_CAP],
len: usize,
tin: u64,
tout: u64,
}
impl ScanCtx {
fn append(&mut self, data: &[u8]) {
// 入 token 路过就记(Anthropic message_start 在流头,收尾时早滑出窗口)
if self.tin == 0 {
self.tin = first_u64(data, &KEYS_IN);
}
// 维护「最后 TAIL_CAP 字节」窗口
let n = data.len();
if n >= self.tail.len() {
let off = n - self.tail.len();
self.tail.copy_from_slice(&data[off..]);
self.len = self.tail.len();
} else if self.len + n > self.tail.len() {
let drop = self.len + n - self.tail.len();
self.tail.copy_within(drop..self.len, 0);
self.len -= drop;
self.tail[self.len..self.len + n].copy_from_slice(data);
self.len += n;
} else {
self.tail[self.len..self.len + n].copy_from_slice(data);
self.len += n;
}
}
/// last_buf:从尾部窗口取出/收拢 token 数
fn finish(&mut self) {
let w = &self.tail[..self.len];
if let Some(v) = last_u64(w, &KEYS_OUT) {
self.tout = v;
}
if self.tin == 0 {
self.tin = last_u64(w, &KEYS_IN).unwrap_or(0);
}
if self.tin == 0 && self.tout == 0 {
// 兜底:Gemini totalTokenCount
if let Some(v) = last_u64(w, &[b"\"totalTokenCount\":" as &[u8]]) {
self.tout = v;
}
}
}
}
unsafe fn ctx_slot(r: *mut ngx_http_request_t) -> *mut *mut ScanCtx {
let idx = (*Module::module()).ctx_index as usize;
(*r).ctx.add(idx) as *mut *mut ScanCtx
}
// ===========================================================================
// filter 本体
// ===========================================================================
/// body filter:先旁观扫描,再原样交下一环。任何异常都只影响计量,不影响转发。
unsafe extern "C" fn body_filter(r: *mut ngx_http_request_t, in_: *mut ngx_chain_t) -> ngx_int_t {
if !r.is_null() && !in_.is_null() && (*r).main == r {
scan(r, in_);
}
// 无条件放行给下一环——本 filter 对数据链零改动
match NEXT_BODY_FILTER {
Some(f) => f(r, in_),
None => Status::NGX_OK.into(),
}
}
unsafe fn scan(r: *mut ngx_http_request_t, in_: *mut ngx_chain_t) {
// 只有 LLM location 才扫:管理台 / 子域名转发零开销直过
let lc = (*(*r).loc_conf.add((*Module::module()).ctx_index as usize)) as *const ModuleConfig;
if lc.is_null() || !(*lc).llm {
return;
}
let slot = ctx_slot(r);
let mut ctx = *slot;
if ctx.is_null() {
let p = nginx_sys::ngx_pcalloc((*r).pool, core::mem::size_of::<ScanCtx>()) as *mut ScanCtx;
if p.is_null() {
// 分配失败:放弃本请求的 token 计量,不影响转发
return;
}
*slot = p;
ctx = p;
}
let mut cl = in_;
while !cl.is_null() {
let buf = (*cl).buf;
cl = (*cl).next;
if buf.is_null() {
continue;
}
let (pos, last) = ((*buf).pos, (*buf).last);
if !pos.is_null() && !last.is_null() && last > pos {
// SAFETY: 内存 buf 的 pos..last 由 nginx 保证有效
let data = slice::from_raw_parts(pos, last as usize - pos as usize);
(*ctx).append(data);
}
if (*buf).last_buf() != 0 {
(*ctx).finish();
}
}
}
/// log 阶段读取本请求抓到的 token 数(ctx 随请求池整体回收,无需清理钩子)。
pub fn take(r: *mut ngx_http_request_t) -> (u64, u64) {
if r.is_null() {
return (0, 0);
}
unsafe {
let c = *ctx_slot(r);
if c.is_null() {
(0, 0)
} else {
((*c).tin, (*c).tout)
}
}
}
// 让 ngx_pool_t 出现在 use 里不产生 unused 告警(签名可读性)
#[allow(dead_code)]
type PoolRef = *mut ngx_pool_t;
+585
View File
@@ -0,0 +1,585 @@
//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。
//!
//! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、
//! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。
//!
//! ```text
//! ust:<username> → <日窗id>:<今日数>:<累计数>:<最近调用时间戳>
//! ums:<username>:<slot> → 同 上
//! ```
//!
//! ## 口径:只统计"真的转发出去"的请求
//!
//! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**,
//! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同——
//! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义;
//! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。
//!
//! ## token 级计量(2026-09-12 起)
//!
//! token 数来自上游响应体里的 `usage` 字段:`llm_usage` 模块在 **body filter 链**
//! 旁路扫描响应(SSE 尾部 / 非 stream JSON 尾部),零缓冲、不影响透传;
//! log 阶段统一入账到 `utt:` / `utms:` 两个键前缀,编码与本文件同款格式。
//! 抓不到 usage(如 OpenAI 流式客户端没带 `include_usage`)= 记 0,不补估。
//! 计数口径与请求数一致:**只算真的转发出去且上游给了 usage 的**。
use std::collections::BTreeMap;
use serde_json::{Value, json};
use crate::config::{
KEY_UDAY_PREFIX, KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UMS_PREFIX,
KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, TREND_DAYS_DEFAULT, TREND_DAYS_MAX,
TREND_KEEP_SECS,
};
use crate::state;
use crate::util;
/// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Usage {
/// 今日(本地自然日)请求数
pub today: i64,
/// 累计请求数(自该计数键建立以来,不随跨天归零)
pub total: i64,
/// 最近一次调用时间戳;0 = 从未调用
pub last_ts: i64,
}
impl Usage {
/// 累加(聚合用)。`last_ts` 取最大。
fn merge(&mut self, other: &Usage) {
self.today += other.today;
self.total += other.total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"today": self.today,
"total": self.total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// token 计量读数。日窗语义与 [`Usage`] 相同:跨天 today 归零、累计保留。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct TokenUsage {
/// 今日入 token(prompt / input)
pub tin_today: i64,
/// 累计入 token
pub tin_total: i64,
/// 今日出 token(completion / output)
pub tout_today: i64,
/// 累计出 token
pub tout_total: i64,
/// 最近一次有 token 记账的调用时间戳;0 = 从未
pub last_ts: i64,
}
impl TokenUsage {
/// 累加(聚合用)。`last_ts` 取最大。
fn merge(&mut self, other: &TokenUsage) {
self.tin_today += other.tin_today;
self.tin_total += other.tin_total;
self.tout_today += other.tout_today;
self.tout_total += other.tout_total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"in_today": self.tin_today,
"in_total": self.tin_total,
"out_today": self.tout_today,
"out_total": self.tout_total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// 一个账号的用量 + 其下每个上游的明细
pub struct UserUsage {
pub username: String,
pub usage: Usage,
pub models: Vec<(String, Usage)>,
}
/// 一个上游的用量 + 用它的每个账号的明细
pub struct ModelUsage {
pub slot: String,
pub usage: Usage,
pub users: Vec<(String, Usage)>,
}
// ===========================================================================
// 编解码
// ===========================================================================
/// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。
/// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。
fn encode(day: i64, u: &Usage) -> String {
format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts)
}
/// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。
fn decode(payload: &str, day: i64) -> Usage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
Usage { today: if stored_day == day { today } else { 0 }, total, last_ts }
}
fn bump(prefix: &[u8], name: &str, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default();
let next = Usage {
today: current.today + 1,
total: current.total + 1,
last_ts: now,
};
// 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次),
// 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。
state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0);
}
// ===========================================================================
// 写
// ===========================================================================
/// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。
pub fn record(username: &str, slot: &str, now: i64) {
if username.is_empty() || slot.is_empty() {
return;
}
let day = util::day_id(now);
bump(KEY_UST_PREFIX, username, day, now);
bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now);
// 日桶:趋势图数据源(请求维度)。三个维度各写一次,键名带日窗 id
let delta = DayBucket { requests: 1, ..Default::default() };
bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta);
bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta);
bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta);
}
// ===========================================================================
// 日桶(趋势图数据源)
// ===========================================================================
//
// `ust:` / `utt:` 只留「今日 + 累计」两个数:今日跨天归零、累计不区分日期,
// 都画不出历史曲线。所以另开一组**以自然日为键**的桶:一个桶一天,
// 读取时按日窗 id **精确取键**(`get_live`),不做前缀扫描——
// 键数随时间增长也不会拖慢任何热路径。
/// 一天的聚合值
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DayBucket {
/// 请求数(已放行并真正转发)
pub requests: i64,
/// 入 token
pub tin: i64,
/// 出 token
pub tout: i64,
}
impl DayBucket {
fn merge(&mut self, other: &DayBucket) {
self.requests += other.requests;
self.tin += other.tin;
self.tout += other.tout;
}
}
/// `<请求数>:<入token>:<出token>`
fn encode_day(b: &DayBucket) -> String {
format!("{}:{}:{}", b.requests, b.tin, b.tout)
}
fn decode_day(payload: &str) -> DayBucket {
let mut it = payload.split(':');
let num = |v: Option<&str>| v.and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
DayBucket {
requests: num(it.next()),
tin: num(it.next()),
tout: num(it.next()),
}
}
/// 累加一日桶。TTL = `TREND_KEEP_SECS`,到期由共享内存自然淘汰
/// (`get_live` 视为不存在),不需要额外的清理任务。
fn bump_day(prefix: &[u8], name: &str, delta: &DayBucket) {
// 用共享内存的 TTL 而不是读时比对——日桶是「写一次、读很多次」,
// 让它自己过期比每次算保留窗口更省事,也避免键无限堆积。
let mut next = state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default();
next.merge(delta);
// 写入失败只记日志:统计是旁路功能,绝不影响转发
if !state::put(
prefix,
name.as_bytes(),
encode_day(&next).as_bytes(),
util::now() + TREND_KEEP_SECS,
) {
util::log_err("[stats] 日桶写入失败(共享内存不足?)");
}
}
/// 读一个日桶(不存在 = 全 0)
fn day_bucket(prefix: &[u8], name: &str) -> DayBucket {
state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default()
}
/// `<日窗id>:<入今日>:<入累计>:<出今日>:<出累计>:<最近时间戳>`
fn encode_t(day: i64, t: &TokenUsage) -> String {
format!(
"{}:{}:{}:{}:{}:{}",
day, t.tin_today, t.tin_total, t.tout_today, t.tout_total, t.last_ts
)
}
fn decode_t(payload: &str, day: i64) -> TokenUsage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let live = stored_day == day;
TokenUsage {
tin_today: if live { in_today } else { 0 },
tin_total: in_total,
tout_today: if live { out_today } else { 0 },
tout_total: out_total,
last_ts,
}
}
fn bump_t(prefix: &[u8], name: &str, tin: u64, tout: u64, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default();
// 与 bump 同款读-增-写近似语义(并发下偶发少计),计量用途可接受
let next = TokenUsage {
tin_today: current.tin_today + tin as i64,
tin_total: current.tin_total + tin as i64,
tout_today: current.tout_today + tout as i64,
tout_total: current.tout_total + tout as i64,
last_ts: now,
};
state::put(prefix, name.as_bytes(), encode_t(day, &next).as_bytes(), 0);
}
/// 累加一次真实 token 消耗(来源:body filter 从上游响应抓到的 usage)。
/// 口径:只有抓到 usage 才记账;抓不到不补估。
pub fn add_tokens(username: &str, slot: &str, tin: u64, tout: u64, now: i64) {
if username.is_empty() || slot.is_empty() || (tin == 0 && tout == 0) {
return;
}
let day = util::day_id(now);
bump_t(KEY_UTT_PREFIX, username, tin, tout, day, now);
bump_t(KEY_UTMS_PREFIX, &format!("{username}:{slot}"), tin, tout, day, now);
// 日桶:趋势图数据源(token 维度)。与 record 写的是同一批键,字段互补
let delta = DayBucket { tin: tin as i64, tout: tout as i64, ..Default::default() };
bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta);
bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta);
bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta);
}
/// 删除账号时清理其全部用量键(`ust:<user>` 与 `ums:<user>:*`)。
///
/// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让
/// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的
/// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。
pub fn forget(username: &str) {
if username.is_empty() {
return;
}
// 先物化键名再删,避免"遍历中改表"(四个键前缀同一套路)
let prefix = format!("{username}:");
for p in [KEY_UST_PREFIX, KEY_UTT_PREFIX] {
state::remove(p, username.as_bytes());
}
// 日桶两个维度也要清:`udu:<user>:<day>` 是按前缀扫不到的(键里还带日窗 id),
// 靠 TTL 自然淘汰也能收敛,但删账号后趋势图仍会挂着幽灵账号 90 天
for p in [KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UDAY_USER_PREFIX] {
let keys: Vec<String> = state::iter_prefix(p)
.into_iter()
.map(|(name, _)| name)
.filter(|name| name.starts_with(&prefix))
.collect();
for name in keys {
state::remove(p, name.as_bytes());
}
}
}
// ===========================================================================
// 读
// ===========================================================================
/// 单账号读数(不含模型明细)
pub fn user(username: &str, now: i64) -> Usage {
let day = util::day_id(now);
state::get(KEY_UST_PREFIX, username.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default()
}
/// 单账号 × 上游明细,按 slot 升序
pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> {
let day = util::day_id(now);
let prefix = format!("{username}:");
let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX)
.into_iter()
.filter_map(|(name, payload)| {
let slot = name.strip_prefix(&prefix)?.to_owned();
Some((slot, decode(&payload, day)))
})
.collect();
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
/// 全部账号的用量(含各自的模型明细),按账号名升序。
///
/// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。
pub fn all_users(now: i64) -> Vec<UserUsage> {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, Vec<(String, Usage)>> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
by_user
.entry(username.to_owned())
.or_default()
.push((slot.to_owned(), decode(&payload, day)));
}
for models in by_user.values_mut() {
models.sort_by(|a, b| a.0.cmp(&b.0));
}
state::iter_prefix(KEY_UST_PREFIX)
.into_iter()
.map(|(username, payload)| {
let usage = decode(&payload, day);
let models = by_user.remove(&username).unwrap_or_default();
UserUsage { username, usage, models }
})
.collect()
}
/// 全部上游的用量(含用到它的账号明细),按 slot 升序。
pub fn all_models(now: i64) -> Vec<ModelUsage> {
let day = util::day_id(now);
// slot → (总量, 各账号)
let mut by_slot: BTreeMap<String, (Usage, Vec<(String, Usage)>)> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let u = decode(&payload, day);
let entry = by_slot.entry(slot.to_owned()).or_default();
entry.0.merge(&u);
entry.1.push((username.to_owned(), u));
}
by_slot
.into_iter()
.map(|(slot, (usage, mut users))| {
users.sort_by(|a, b| a.0.cmp(&b.0));
ModelUsage { slot, usage, users }
})
.collect()
}
/// 全局合计
pub fn totals(now: i64) -> Usage {
let day = util::day_id(now);
let mut sum = Usage::default();
for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) {
sum.merge(&decode(&payload, day));
}
sum
}
/// 单账号 token 读数
pub fn tokens_user(username: &str, now: i64) -> TokenUsage {
let day = util::day_id(now);
state::get(KEY_UTT_PREFIX, username.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default()
}
/// token 全表一次扫齐:`(按账号, 按上游, 按 账号→上游)`。
/// utt/utms 各扫一遍,避免报表页多次遍历共享内存。
fn tokens_scan(
now: i64,
) -> (
BTreeMap<String, TokenUsage>,
BTreeMap<String, TokenUsage>,
BTreeMap<String, BTreeMap<String, TokenUsage>>,
) {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, TokenUsage> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UTT_PREFIX) {
by_user.insert(name, decode_t(&payload, day));
}
let mut by_slot: BTreeMap<String, TokenUsage> = BTreeMap::new();
let mut by_pair: BTreeMap<String, BTreeMap<String, TokenUsage>> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UTMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let t = decode_t(&payload, day);
by_slot.entry(slot.to_owned()).or_default().merge(&t);
by_pair.entry(username.to_owned()).or_default().insert(slot.to_owned(), t);
}
(by_user, by_slot, by_pair)
}
/// 管理台用量页的完整投影
pub fn overview(now: i64) -> Value {
let (t_by_user, t_by_slot, t_by_pair) = tokens_scan(now);
let users: Vec<Value> = all_users(now)
.into_iter()
.map(|u| {
let tin = t_by_pair.get(&u.username);
json!({
"username": u.username,
"today": u.usage.today,
"total": u.usage.total,
"last_ts": u.usage.last_ts,
"last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() },
"tokens": t_by_user.get(&u.username).cloned().unwrap_or_default().json(),
"models": u.models.iter().map(|(slot, usage)| {
json!({ "slot": slot, "today": usage.today, "total": usage.total,
"tokens": tin.and_then(|m| m.get(slot)).cloned().unwrap_or_default().json() })
}).collect::<Vec<_>>(),
})
})
.collect();
let models: Vec<Value> = all_models(now)
.into_iter()
.map(|m| {
json!({
"slot": m.slot,
"today": m.usage.today,
"total": m.usage.total,
"last_ts": m.usage.last_ts,
"last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() },
"tokens": t_by_slot.get(&m.slot).cloned().unwrap_or_default().json(),
"users": m.users.iter().map(|(name, usage)| {
json!({ "username": name, "today": usage.today, "total": usage.total })
}).collect::<Vec<_>>(),
})
})
.collect();
let sum = totals(now);
let mut tsum = TokenUsage::default();
for t in t_by_user.values() {
tsum.merge(t);
}
json!({
"total": sum.json(),
"tokens": tsum.json(),
"users": users,
"models": models,
})
}
// ===========================================================================
// 趋势(图表数据源)
// ===========================================================================
/// 把一串日桶摊成图表直接能吃的三条等长数组
fn buckets_json(v: &[DayBucket]) -> Value {
json!({
"requests": v.iter().map(|b| b.requests).collect::<Vec<_>>(),
"in": v.iter().map(|b| b.tin).collect::<Vec<_>>(),
"out": v.iter().map(|b| b.tout).collect::<Vec<_>>(),
})
}
/// 最近 `days_req` 天的趋势序列(全局 / 按账号 / 按上游)。
///
/// `days_req` 会被夹到 `[1, TREND_DAYS_MAX]`——URL 里塞个 99999 也不会把
/// 共享内存扫爆。三个维度都是**按键精确取**(键名带日窗 id),
/// 成本 = 天数 × (1 + 账号数 + 上游数) 次查表,且不随历史增长。
pub fn trend(now: i64, days_req: i64, users: &[String], slots: &[String]) -> Value {
let days = days_req.clamp(1, TREND_DAYS_MAX);
// 往前推 N 天:每个采样点一个时间戳,日窗 id 现算(本地自然日,不用 UTC)
let stamps: Vec<i64> = (0..days).rev().map(|i| now - i * 86400).collect();
let labels: Vec<String> = stamps.iter().map(|t| util::fmt_day(*t)).collect();
let ids: Vec<i64> = stamps.iter().map(|t| util::day_id(*t)).collect();
let total: Vec<DayBucket> = ids.iter().map(|d| day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect();
let by_user: Vec<Value> = users
.iter()
.map(|u| {
let series: Vec<DayBucket> = ids
.iter()
.map(|d| day_bucket(KEY_UDAY_USER_PREFIX, &format!("{u}:{d}")))
.collect();
let mut o = buckets_json(&series);
// 全 0 的账号不回传:趋势图里一堆积零的线只会把图例挤爆
let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0);
if let Value::Object(ref mut m) = o {
m.insert("username".to_owned(), json!(u));
m.insert("empty".to_owned(), json!(empty));
}
o
})
.collect();
let by_slot: Vec<Value> = slots
.iter()
.map(|s| {
let series: Vec<DayBucket> = ids
.iter()
.map(|d| day_bucket(KEY_UDAY_SLOT_PREFIX, &format!("{s}:{d}")))
.collect();
let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0);
let mut o = buckets_json(&series);
if let Value::Object(ref mut m) = o {
m.insert("slot".to_owned(), json!(s));
m.insert("empty".to_owned(), json!(empty));
}
o
})
.collect();
json!({
"days": days,
"labels": labels,
"total": buckets_json(&total),
"users": by_user,
"slots": by_slot,
})
}
/// 趋势接口的默认天数(URL 没给 `days` 时用)
pub fn trend_default_days() -> i64 {
TREND_DAYS_DEFAULT
}
+397
View File
@@ -0,0 +1,397 @@
//! LLM 上游配置与共享内存同步。
//!
//! 这是「转发映射」机制在 LLM 侧的翻版:`domains.rs` 管
//! `子域名 → 后端`,本模块管 `路径前缀(slot) → 上游(基址 + 密钥)`。
//! 两者都**写穿共享内存**,理由相同——热路径未命中即失败,不回源读文件。
//!
//! ## 为什么按 URL 前缀分上游,而不是按请求体里的 `model`
//!
//! 转发决策点在 access 阶段,而请求体要到 content 阶段才读得到
//! (见 `http::collect_body` 的调用前提)。按 `model` 字段分流就必须放弃
//! `proxy_pass`、自己实现 upstream 转发,代码量与出错面差一个数量级。
//! 代价只是客户端 base_url 需要带上 slot 段,可接受。
//!
//! `data/llm-upstreams.json` 含上游真实 API Key,**敏感级别等同 `users.json`**。
use serde_json::{Value, json};
use crate::config::{KEY_UH_PREFIX, KEY_UP_PREFIX, LLM_PUBLIC_HOST, MODEL_NAME_MAX_LEN,
UPSTREAM_BASE_MAX_LEN, UPSTREAM_MODELS_MAX, UPSTREAM_SLOT_MAX_LEN,
};
use crate::models::Upstream;
use crate::state;
use crate::store;
use crate::util;
/// 共享内存 payload 的内部分隔符:base 与 auth 之间。
///
/// 与 `config::VAL_SEP`(0x1f,负责切 payload / expires_at)是两层不同的
/// 分隔,不能混用。base 是 URL、auth 是 `Bearer <token>`,都不可能含换行。
pub const PAYLOAD_SEP: char = '\n';
// ===========================================================================
// 校验
// ===========================================================================
/// slot:小写字母/数字开头,其后可含短横线、下划线,总长 ≤ 32。
///
/// 允许下划线(`azure_openai` 这类厂牌写法很常见),这点比子域名规则宽。
pub fn validate_slot(raw: &str) -> Result<String, String> {
let s = util::trim(raw).to_ascii_lowercase();
if s.is_empty() {
return Err("缺少 slot 参数".to_owned());
}
if s.len() > UPSTREAM_SLOT_MAX_LEN {
return Err(format!("slot 长度不能超过 {UPSTREAM_SLOT_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("slot 只能是小写字母、数字、短横线或下划线,且不能以符号开头".to_owned());
}
Ok(s)
}
/// 模型名清单:去空白、去空项、去重、限长。
///
/// 刻意**允许** `/` `.` `:` 等字符——`Qwen/Qwen2.5-7B`(HF 风格)、
/// `llama3:8b`(Ollama 标签)都是合法模型名。只挡空白与控制字符,
/// 因为模型名要出现在 URL/JSON/HTML 里,空白只会带来歧义。
fn check_models(raw: &[String]) -> Result<Vec<String>, String> {
let mut out: Vec<String> = Vec::new();
for item in raw {
let m = util::trim(item);
if m.is_empty() {
continue;
}
if m.chars().count() > MODEL_NAME_MAX_LEN {
return Err(format!("模型名「{m}」超过 {MODEL_NAME_MAX_LEN} 个字符"));
}
if m.chars().any(char::is_whitespace) || m.chars().any(char::is_control) {
return Err(format!("模型名「{m}」不能包含空格或控制字符"));
}
if !out.iter().any(|x| x == m) {
out.push(m.to_owned());
}
}
if out.len() > UPSTREAM_MODELS_MAX {
return Err(format!("单个上游最多登记 {UPSTREAM_MODELS_MAX} 个模型"));
}
Ok(out)
}
/// 上游基址:必须显式带 `http://` 或 `https://`。
///
/// 比子域名的 `backend`(纯 host:port)宽——LLM 上游常挂在网关路径下
/// (如 `https://gw.corp.com/llm`),所以要允许尾随路径。
pub fn validate_base(raw: &str) -> Result<String, String> {
let s = util::trim(raw).trim_end_matches('/').to_owned();
if s.is_empty() {
return Err("缺少 base 参数".to_owned());
}
if s.len() > UPSTREAM_BASE_MAX_LEN {
return Err(format!("base 长度不能超过 {UPSTREAM_BASE_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.openai.com".to_owned());
};
if rest.is_empty() {
return Err("base 缺少主机名".to_owned());
}
if rest.chars().any(char::is_whitespace) || rest.contains('@') {
return Err("base 不允许包含空格或用户信息(user@host)".to_owned());
}
if rest.split('/').next().unwrap_or("").is_empty() {
return Err("base 缺少主机名".to_owned());
}
Ok(s)
}
// ===========================================================================
// 共享内存同步(写穿 / 装载)
// ===========================================================================
/// 把一条上游配置同步进共享内存。**所有写操作之后必须调用它**。
///
/// 关闭(`enabled=false`)时是**删除**而不是写入空值——热路径
/// 「查不到 = 不可用」,这样停用即刻生效,且不留残留条目。
pub fn sync_shm(slot: &str, up: &Upstream) {
if up.enabled {
if !state::put_upstream(slot, &payload_of(up)) {
util::log_err(&format!(
"[upstreams] 上游配置写共享内存失败 slot={slot} —— 该上游会 404(共享内存可能已满)"
));
}
} else {
state::remove_upstream(slot);
}
}
fn payload_of(up: &Upstream) -> String {
format!("{}{}{}", up.base, PAYLOAD_SEP, up.auth)
}
/// 全量重载上游表(启动装载 / 批量变更后)。返回装载条数。
///
/// 只清 `up:` 前缀,不会误伤转发映射与管理会话。
pub fn reload_shm() -> usize {
state::clear_prefix(KEY_UP_PREFIX);
let mut expected = 0;
let mut loaded = 0;
for (slot, up) in store::read_upstreams() {
if up.enabled {
expected += 1;
}
if up.enabled && state::put_upstream(&slot, &payload_of(&up)) {
loaded += 1;
}
}
if loaded != expected {
util::log_err(&format!(
"[upstreams] 上游装载不全:{loaded}/{expected} —— 有上游会 404"
));
}
loaded
}
/// 拆 payload:`base \n auth` → `(base, auth)`。
///
/// 无分隔符时视为「只有 base、无鉴权头」——兼容手工编辑文件时漏写分隔的情况。
pub fn split_payload(payload: &str) -> (&str, &str) {
match payload.split_once(PAYLOAD_SEP) {
Some((b, a)) => (b, a),
None => (payload, ""),
}
}
// ===========================================================================
// 查询
// ===========================================================================
/// 全部上游,按 slot 升序
pub fn all() -> Vec<(String, Upstream)> {
store::read_upstreams().into_iter().collect()
}
pub fn get(slot: &str) -> Option<Upstream> {
store::read_upstreams().remove(slot)
}
/// 某账号**可用**的上游(已启用,且在白名单内;`allowed` 为空 = 不限)。
///
/// 账号态接口与模型发现都用它,避免"能看见但不能用"或反之的两套判定。
pub fn available(allowed: &[String]) -> Vec<(String, Upstream)> {
all()
.into_iter()
.filter(|(slot, up)| {
up.enabled && (allowed.is_empty() || allowed.iter().any(|s| s == slot))
})
.collect()
}
/// 客户端应当使用的 base_url。
///
/// 规则:**把上游 base 的 scheme+host 换成网关域名,路径原样保留**——
/// 这样它才真的能和厂商文档里的 base_url 逐个字符替换:
///
/// ```text
/// https://api.deepseek.com/v1 → https://lm.mayishangshu.cn:88/deepseek/v1
/// https://api.openai.com → https://lm.mayishangshu.cn:88/openai
/// ```
///
/// `port` 由调用方从请求 Host 头取(`http::host_port`),**不要写死**:
/// 部署在 88 时客户端必须带 `:88` 才连得到,而放在 443 反代后面时又必须不带端口。
/// 写死任何一种,都会在另一种部署里给出一个「看着对、实际打不通」的地址。
///
/// 反过来(不管上游 base 的路径、一律拼 `/v1`)会让「base 自带 /v1」的上游
/// 变成 `/v1/v1/chat/completions` → 上游 404,且客户端拿到的是空响应体,
/// 排查起来完全看不出是网关拼错了。**实测踩过,别再改回去。**
pub fn base_url(slot: &str, up: &Upstream, port: &str) -> String {
let rest = up.base.split("://").nth(1).unwrap_or("");
let path = match rest.find('/') {
Some(i) => &rest[i..],
None => "",
};
format!("https://{LLM_PUBLIC_HOST}{port}/{slot}{path}")
}
/// Anthropic 客户端(Claude Code / Claude SDK)应当使用的 `ANTHROPIC_BASE_URL`。
///
/// 协议段由**客户端**负责表达(网关不猜协议),但这段路径是网关替客户端拼好的,
/// 所以要处理重合:上游 `base` 若已钉在 `…/anthropic`(协议钉死型记录),其
/// `base_url` 末尾已经带 `/anthropic`,再无脑追加会得到 `…/anthropic/anthropic`。
pub fn anthropic_base_url(slot: &str, up: &Upstream, port: &str) -> String {
let b = base_url(slot, up, port);
if b.ends_with("/anthropic") {
b
} else {
format!("{b}/anthropic")
}
}
/// 模型发现:把可用上游挂载的模型摊平成 `(模型名, slot)` 列表。
///
/// 没登记 `models` 的上游不产出任何条目(清单未知 ≠ 有 0 个模型),
/// 但它的转发能力不受影响——模型发现只是"告诉你有什么",
/// 不是"允许你用什么"。
pub fn models_flat(allowed: &[String]) -> Vec<(String, String)> {
let mut out = Vec::new();
for (slot, up) in available(allowed) {
for model in &up.models {
out.push((model.clone(), slot.clone()));
}
}
out
}
// ===========================================================================
// 写入
// ===========================================================================
/// 新增或覆盖一个上游。
///
/// `auth = None` 表示**保持原值**(表单只改 base 时不必回填密钥);
/// `Some("")` 表示显式清空。`models = None` 同款语义(保持原清单)。
/// `enabled = false` 会立刻从共享内存移除。
pub fn upsert(
slot_raw: &str,
base_raw: &str,
models: Option<Vec<String>>,
auth_raw: Option<&String>,
enabled: bool,
note: Option<&String>,
) -> Result<Upstream, String> {
let slot = validate_slot(slot_raw)?;
let base = validate_base(base_raw)?;
let models = match models {
Some(list) => Some(check_models(&list)?),
None => None,
};
let key = slot.clone();
let up = store::update_upstreams(move |table| {
// 先克隆出来:下面 insert 需要可变借用,不能与这里的不可变借用并存
let existing = table.get(&key).cloned();
let auth = match auth_raw {
Some(a) => util::trim(a).to_owned(),
None => existing.as_ref().map(|e| e.auth.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 models = match models {
Some(m) => m,
None => existing.as_ref().map(|e| e.models.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 = Upstream { base, models, auth, enabled, note, created_at };
table.insert(key.clone(), item.clone());
Ok(item)
})?;
sync_shm(&slot, &up);
Ok(up)
}
/// 删除上游,并立刻从共享内存摘掉
pub fn remove(slot_raw: &str) -> Result<String, String> {
let slot = validate_slot(slot_raw)?;
let key = slot.clone();
store::update_upstreams(move |table| {
if table.remove(&key).is_none() {
return Err(format!("上游 {key} 不存在"));
}
Ok(())
})?;
state::remove_upstream(&slot);
Ok(slot)
}
// ===========================================================================
// 对外投影
// ===========================================================================
/// 转成管理台可见的字段。
///
/// **绝不回显完整 auth**——管理台页面会被截图、被浏览器插件读取,
/// 回显上游真 Key 等于把公司所有厂商密钥摆在一个 HTML 里。
pub fn view(slot: &str, up: &Upstream, port: &str) -> Value {
let (status, code, checked_at) = match health(slot) {
Some((ok, c, ts)) => (if ok { "ok" } else { "failed" }, c, ts),
None => ("unknown", 0, 0),
};
json!({
"slot": slot,
"base": up.base,
"base_url": base_url(slot, up, port),
"anthropic_base_url": anthropic_base_url(slot, up, port),
"models": up.models,
"model_count": up.models.len(),
"auth_set": !up.auth.is_empty(),
"auth_mask": if up.auth.is_empty() { "-".to_owned() } else { util::mask_key(&up.auth) },
"enabled": up.enabled,
"note": up.note,
"created_at": up.created_at,
"created_at_text": util::fmt_time(up.created_at),
"status": status,
"status_code": if code > 0 { json!(code) } else { Value::Null },
"checked_at": checked_at,
"checked_at_text": if checked_at > 0 { util::fmt_time(checked_at) } else { String::new() },
})
}
pub fn view_all(list: &[(String, Upstream)], port: &str) -> Vec<Value> {
list.iter().map(|(slot, up)| view(slot, up, port)).collect()
}
// ===========================================================================
// 上游健康缓存(uh:)
// ===========================================================================
/// 记录一次上游真实响应结果。**只读端不会用它做任何决策**——转发路径
/// 从不查这份缓存,所以误标最多影响展示,不会误杀请求。
///
/// 写失败必须出声(热路径无回源兜底是转发侧的事,这里出声是为了
/// 别让「列表永远显示未探测」这种静默怪象无人解释)。
pub fn mark_health(slot: &str, ok: bool, code: i64) {
let ts = util::now();
let payload = format!("{}\n{}\n{}", if ok { 1 } else { 0 }, code, ts);
if !state::put(
KEY_UH_PREFIX,
slot.as_bytes(),
payload.as_bytes(),
ts + 30 * 86400,
) {
util::log_err(&format!("[upstreams] 健康状态写共享内存失败 slot={slot}"));
}
}
/// 读健康缓存:`Some((是否正常, 上游状态码, 记录时刻))`,没探测过 = `None`。
pub fn health(slot: &str) -> Option<(bool, i64, i64)> {
let (payload, _) = state::get(KEY_UH_PREFIX, slot.as_bytes())?;
let mut it = payload.split('\n');
let ok = it.next().unwrap_or("0").trim() == "1";
let code = it
.next()
.and_then(|s| s.trim().parse::<i64>().ok())
.unwrap_or(0);
let ts = it
.next()
.and_then(|s| s.trim().parse::<i64>().ok())
.unwrap_or(0);
Some((ok, code, ts))
}