iPass cache gateway 源码

容量管理: zones.rs 直读 nginx file_cache 共享内存记账(双轴: 磁盘 + keys_zone 索引内存), ?scan=1 扫盘上限 20 万文件; POST /api/admin/cache/purge 整区清理(只删文件不删目录, 根治 [crit] mkdir failed); POST /api/admin/cache/invalidate 按制品精准失效(预览->确认两步式, glob/子串, 删除上限 5000/扫描上限 20 万); GET /api/admin/cache 新增 capacity 块; 前端容量面板 + 按制品失效工具条; 测试 test-cache-capacity.sh 48/48(容量 27 + 精准失效 21, 含 EXPECT_MIN 护栏与前端静态契约); docs 容量管理章节
This commit is contained in:
ssw committed 2026-09-21 09:25:11 +08:00
commit 43718bd0c4
324 files changed
+40403

No files matched your search

+444
View File
@@ -0,0 +1,444 @@
//! LLM 插件的管理 API:上游 CRUD / 连通性测试 / 用量查询。
//!
//! 趋势接口 `/api/admin/trend` **不在本表**——它需要 users + upstreams +
//! apix 三方名册(日桶键带日窗 id,按前缀扫不出来),属于组合逻辑,
//! 由 gateway 作为装配根实现(对方案的有意偏离,见 PLUGINIZATION_PLAN)。
//!
//! 鉴权语义与内核共用一套:`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 ipass_core::{http, util};
use crate::llm;
use crate::llm_audit;
use crate::stats;
use crate::stats_persist;
use crate::upstreams;
// ===========================================================================
// 路由
// ===========================================================================
type Handler = fn(*mut ngx_http_request_t, Actor) -> Status;
/// 路由表。刻意用精确匹配而非正则——接口路径是固定的,
/// 正则只会引入「写错锚点导致前缀误匹配」的风险。
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/stats/persist") => (Guard::Admin, h_admin_stats_persist),
("POST", "/api/admin/stats/dump") => (Guard::Admin, h_admin_stats_dump),
("GET", "/api/admin/audit/days") => (Guard::Admin, h_admin_audit_days),
("GET", "/api/admin/audit/day") => (Guard::Admin, h_admin_audit_day),
("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)
}
/// 本表分发:认领则返回响应状态,不认领返回 `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));
// 多账号:前端把 `accounts` 作为 JSON 数组串传上来(每个 {auth, note, resets})。
// 缺省/空 = 沿用旧逻辑(用 `auth` 维护单账号)。
let accounts = p
.get("accounts")
.and_then(|s| {
let s = s.trim();
if s.is_empty() {
None
} else {
serde_json::from_str::<Vec<crate::models::UpstreamAccount>>(s).ok()
}
});
// 上游级「额度耗尽」探测配置(JSON 数组;也兼容逗号串)
let exhaust_status = parse_int_list(p.get("exhaust_status"));
let exhaust_markers = p
.get("exhaust_markers")
.and_then(|s| {
let s = s.trim();
if s.is_empty() {
None
} else {
serde_json::from_str::<Vec<String>>(s).ok()
}
});
let slot_raw = p.get("slot").map(String::as_str).unwrap_or("");
match upstreams::upsert(
slot_raw,
p.get("base"),
p.get("base_anthropic"),
models,
p.get("auth"),
accounts,
exhaust_status,
exhaust_markers,
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} accounts={} models={}",
up.effective_accounts().len(),
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),
}
}
/// 解析整数列表:优先 JSON 数组,回退逗号分隔串。
fn parse_int_list(raw: Option<&String>) -> Option<Vec<i64>> {
let s = raw?;
let s = s.trim();
if s.is_empty() {
return None;
}
if let Ok(v) = serde_json::from_str::<Vec<i64>>(s) {
return Some(v);
}
Some(
s.split(',')
.filter_map(|x| x.trim().parse::<i64>().ok())
.collect(),
)
}
/// 把管理台/接口传入的模型列表串拆成模型名数组。
///
/// 允许的写法(混用也认):`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 !llm::upstream_live(&slot) {
return http::fail(r, HTTPStatus::NOT_FOUND, &format!("上游 {slot} 不存在"));
}
// 与真实 OpenAI SDK 同形(必带 /v1)。1.0.42 曾改成裸 /chat/completions 绕智谱
// NPE——那是 join_target 剥冗余 /v1 落地(1.0.41)之前的坑位,且把**无路径 base**
// 的 openai/deepseek 探测打去了 /chat/completions(真端点 404,回归组11 抓到)。
// 1.0.43 用最小 dummy 体解决 NPE 后,这里恢复 /v1:base 带路径的厂商由
// join_target 剥除(llm.rs 单测钉死),不带路径的原样保留。
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` 模块头注释)。
///
/// **1.0.32**:在 `data.tokens` 下追加 `all_time` 块(自服务上线以来累计)——
/// 来自 audit meta.jsonl 真源聚合,**不受 stats 落盘/恢复影响**(audit 是
/// append-only,stats 会被 reset)。前端 `overview.html` 用此字段把"累计
/// token"从模糊的"自上次 stats 恢复以来"换成清晰的"自上线以来"。
fn h_admin_usage(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let now = util::now();
let mut view = stats::overview(now);
if let Some(tok) = view.get_mut("tokens").and_then(|v| v.as_object_mut()) {
tok.insert("all_time".to_owned(), llm_audit::all_time_total());
}
http::ok(r, view, "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",
)
}
// ===========================================================================
// 管理员:统计落盘
// ===========================================================================
//
// 用量/趋势只活在共享内存里,进程退出即清零。落盘/恢复见
// `crate::stats_persist` 模块注释与 docs/llm/STATS_PERSISTENCE.md。
// 这两个端点不参与任何转发逻辑,纯粹是「让运维看得见 + 手动兜一次」。
/// `GET /api/admin/stats/persist`:快照文件状态 + 当前共享内存键数。
///
/// 排障用法:发版后立刻查一次,`restored_keys` 应当等于 `file_keys`;
/// 若 `live_keys` 长期远大于 `file_keys`(且 `saved_at` 很旧),说明周期落盘没跑。
fn h_admin_stats_persist(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
http::ok(r, stats_persist::status(), "ok")
}
/// `POST /api/admin/stats/dump`:立刻落盘一次(不看间隔)。
///
/// 计划内维护前手动兜一次用;正常情况下不需要 —— 发版走 `exit_process` 钩子
/// 已经是零丢失,这个端点只是给个「我说了算」的把手。
fn h_admin_stats_dump(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
match stats_persist::dump_now("admin") {
Ok(n) => http::ok(r, json!({ "keys": n }), "已落盘"),
Err(e) => http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, &e),
}
}
/// 列出审计目录所有有 `meta.jsonl` 的日期(按新→旧排序)
fn h_admin_audit_days(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let days = llm_audit::list_days();
http::ok(r, json!({ "days": days, "count": days.len() }), "ok")
}
/// 读某天 meta.jsonl 的所有行(剔除 excerpt / body_hash,**仅供管理台聚合**)。
///
/// 1.0.27 起管理台「小时级趋势」直接读这个端点 → 前端按 `ts / 3600` 分组聚合。
/// 不在网关做 hour-bucket 持久化:避免给热路径加写、避免新增 shm 键空间。
fn h_admin_audit_day(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let day = match http::params(r).get("day") {
Some(d) => d.trim().to_owned(),
None => return http::fail(r, HTTPStatus::BAD_REQUEST, "缺少 day 参数(YYYY-MM-DD)"),
};
match llm_audit::read_day(&day) {
Ok(rows) => {
let n = rows.len();
http::ok(r, json!({ "day": day, "rows": rows, "count": n }), "ok")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
+249
View File
@@ -0,0 +1,249 @@
//! LLM 插件策略常量(自内核 config.rs 迁入;改策略只改这里)。
/// LLM 上游 slot 名长度上限(`/openai/v1/chat/completions` 里的 `openai`)
pub const UPSTREAM_SLOT_MAX_LEN: usize = 32;
/// LLM 上游基址长度上限(含 scheme 与可选端口)
pub const UPSTREAM_BASE_MAX_LEN: usize = 200;
/// 单个模型名长度上限
pub const MODEL_NAME_MAX_LEN: usize = 128;
/// 单个上游可登记的模型数量上限(挡住把整个模型库灌进 shm/JSON 的手滑)
pub const UPSTREAM_MODELS_MAX: usize = 200;
// ===========================================================================
// 共享内存键前缀(`up:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uh:`)
// ===========================================================================
/// 键前缀:LLM 上游 slot → `base \n auth`。
///
/// `base` 含 scheme(如 `https://api.openai.com`);`auth` 是完整的
/// Authorization 头值(如 `Bearer sk-xxx`)。两者合用一个 shm 键,
/// 使写操作只需同步一处、少一个漏同步的机会。
pub const KEY_UP_PREFIX: &[u8] = b"up:";
/// 键前缀:LLM **每用户**用量统计(口径 = 已放行的请求)。
///
/// 键 = `ust:<username>`,value = `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。
/// 与 `st:`(配额执行,先增后判)的区别:这里统计的是**真的转发出去**的请求
/// ——两者在超限时会差几个数,属预期。
pub const KEY_UST_PREFIX: &[u8] = b"ust:";
/// 键前缀:LLM **每用户 × 每上游**用量统计。
///
/// 键 = `ums:<username>:<slot>`(username 与 slot 都不含 `:`,切分安全),
/// value 同 `ust:`。管理台的「每个模型用量」就是把这些键按 slot 聚合出来的。
pub const KEY_UMS_PREFIX: &[u8] = b"ums:";
/// LLM token 计量(body filter 从上游响应抓的 usage):
/// 账号维度 `utt:<user>`,账号×上游维度 `utms:<user>:<slot>`
pub const KEY_UTT_PREFIX: &[u8] = b"utt:";
pub const KEY_UTMS_PREFIX: &[u8] = b"utms:";
/// 全局日桶。键 = `ud:<日窗id>`
pub const KEY_UDAY_PREFIX: &[u8] = b"ud:";
/// 1.0.32:每用户聚合缓存(增量 + 持久化),给 /api/v1/me 免去每次都从 audit
/// meta.jsonl 全聚合的开销。键 = `usum:<username>`,value = JSON
/// `{calls, tin, tout, by_slot: {slot: {...}}, last_ts}`。dump 走
/// stats_persist 的 PREFIXES 白名单,**自动落 llm-stats.json**,**自动恢复**。
///
/// 设计要点:
/// - 增量聚合:每次 user_recent 只扫 audit `ts > last_ts` 的 delta 行,累加
/// 到 shm → O(delta) 而非 O(7d 全量)
/// - 持久化:worker 退出时 dump 到 llm-stats.json,新 worker 启动时 restore
/// → 跨重启不丢历史
/// - 字段语义:calls/tin/tout 是**自上次 stats_persist 恢复以来的累计**
/// (audit meta 行是 append-only,sum 跟着 append 走)。
/// - hour_24h 不在这里——必须按 ts 过滤,无法 O(1),仍每次重算
pub const KEY_USER_SUM_PREFIX: &[u8] = b"usum:";
/// 按账号日桶。键 = `udu:<username>:<日窗id>`
pub const KEY_UDAY_USER_PREFIX: &[u8] = b"udu:";
/// 按上游(API 组)日桶。键 = `uds:<slot>:<日窗id>`
/// (apix 的 slug 带 `api/` 前缀共用这片键空间,见 core config 的 APIX_STATS_PREFIX)
pub const KEY_UDAY_SLOT_PREFIX: &[u8] = b"uds:";
/// 键前缀:上游**账号级**日桶(负载分布)。键 = `uda:<slot>:<idx>:<日窗id>`,
/// value = DayBucket(requests = 转发到该账号的请求数,tin/tout = 该账号 token 消耗)。
/// 与 `uds:`(slot 级)同构、多一维账号下标——「各上游 Key 负载」就靠它,
/// 无需数据库(项目红线)。TTL 90 天自然淘汰。
pub const KEY_UDAY_ACCT_PREFIX: &[u8] = b"uda:";
/// 键前缀:上游账号**额度耗尽次数**日桶。键 = `uex:<slot>:<idx>:<日窗id>`,
/// value = DayBucket(requests = 该账号被判定额度耗尽并冷却的次数)。
/// 仅作问题发现指标、不参与路由——哪把 Key 频繁撞额度一眼可见。TTL 90 天。
pub const KEY_UEX_PREFIX: &[u8] = b"uex:";
/// 管理台账号级负载迷你趋势的展示天数(与项目 `uds:` 趋势的默认 14 天一致)。
pub const ACCT_TREND_DAYS: i64 = 14;
/// 键前缀:LLM **上游健康缓存**。键 = `uh:<slot>`,
/// value = `<1|0> \n <上游状态码> \n <记录时刻>`。
///
/// 由 log 阶段处理器在每次真实转发完成后写入(见 `handlers::LlmHealthHandler`),
/// 管理台「测试」按钮的探测请求走同一条转发链路,因此也天然更新这份数据。
/// 30 天过期只是兜底——它随时会被下一次转发覆盖;删除上游时不必清理,
/// 列表接口只对现存 slot 展示。**这是纯展示缓存,不参与任何转发决策**,
/// 最多容忍客户端中途断连导致的误标(下一次真实转发即纠正)。
pub const KEY_UH_PREFIX: &[u8] = b"uh:";
// ===========================================================================
// 多账号路由(一个 slot 挂多个上游账号,粘性绑定 + 额度耗尽自动切换)
// ===========================================================================
/// 键前缀:上游账号静态配置。键 = `upa:<slot>:<idx>`,
/// value = `<auth> \n <resets csv>`(`resets` 为空则第二段为空)。
///
/// `auth` 是完整 Authorization 头值;`resets` 是该账号额度重置周期(秒,逗号分隔)。
/// 与 `up:` 拆开存,是因为账号是热路径要枚举的对象、而 `up:` 只存 base + 账号数,
/// 避免一次大 payload 反序列化;账号数记在 `up:<slot>` 第二段,热路径据此循环读取。
pub const KEY_UPA_PREFIX: &[u8] = b"upa:";
/// 键前缀:上游账号「额度耗尽」冷却(**运行时状态**,非配置)。
/// 键 = `uac:<slot>:<idx>`,value = `<backoff>:<next_probe_at>:<hard_cap>`(绝对/相对秒)。
///
/// 探测恢复闭环(1.0.44):冷却不再是「猜厂商重置点」,而是**指数退避 + 真实请求探测**——
/// * `backoff`:本轮退避长度(首标 = `ipass_probe_min`,每次探测后翻倍,封顶 `ACCT_COOL_HARD_CAP`);
/// * `next_probe_at`:到点后允许一个**无绑定/绑定失效**的真实请求把它当探测路由过去
/// (`pick_account` 选中即 re-arm,窗口不重复开);
/// * `hard_cap`:键 TTL。到期未验证成功 = 无条件回队,若仍耗尽会被真实流量再标——自愈。
///
/// 探测 2xx → log 阶段 `clear_cool` 删键回队。旧格式单段 `<until>` 值解析失败会被视作
/// 「立即到期可探测」,升级后 ~30 分钟内自然换代。
pub const KEY_UAC_PREFIX: &[u8] = b"uac:";
/// 键前缀:用户 key → 上游账号 粘性绑定。键 = `ukb:<downstream_key>`,
/// value = `<acct_idx>`(usize 字符串)。
///
/// 带 TTL(`AFFINITY_TTL_DEFAULT`,7 天),**尽力粘性**:重启后丢失、重新绑定,
/// 符合「尽可能同一用户 key 用同一上游 key」的语义。只有真正选了账号且拿到下行 key
/// 时才写;内部测试 location(无下行 key)不写,避免污染绑定表。
pub const KEY_UKB_PREFIX: &[u8] = b"ukb:";
/// 键前缀:上游级「额度耗尽」探测配置。键 = `upe:<slot>`,
/// value = `<status csv> \n <markers json>`(`markers` 是 JSON 字符串数组)。
///
/// slot 级(同一厂商所有账号共享错误形态),由 `sync_shm` 写、body filter 与 log 阶段读。
pub const KEY_UPE_PREFIX: &[u8] = b"upe:";
/// 默认「额度耗尽」HTTP 状态码(命中即判该账号额度耗尽并冷却)。
///
/// 402/429/403 是主流厂商表达「配额/额度/权限不足」的常态;5xx 与连接失败(502/504)
/// 视为机器/链路问题、**不**算额度耗尽(否则单台抖动会把整池账号都冷却掉)。
pub const EXHAUST_STATUS_DEFAULT: &[i64] = &[402, 429, 403];
/// 首轮探测退避的默认值(秒)。可被 `ipass_probe_min <秒>` 指令覆盖(见 gateway 模块壳)。
///
/// 冷却生命周期 = 指数退避:首轮 `probe_min`,每次探测后翻倍,封顶 `ACCT_COOL_HARD_CAP`。
/// 60s 起步对「限速 429(≠额度耗尽)」足够友好;对真·额度耗尽也只是多牺牲几个探测请求。
pub const PROBE_MIN_DEFAULT: i64 = 60;
/// 退避翻倍与冷却硬顶(秒,30 分钟)。
///
/// 语义是**退避/存在期**,不是「恢复时刻」——恢复由探测闭环判定(2xx 即 `clear_cool`),
/// 硬顶到期只表示「放弃未验证的持续锁定,账号回队,若仍耗尽会被真实流量再标」(自愈)。
///
/// 旧口径是「天锚定重置边界」(`cool_until_until`):它把厂商窗口算错过两次(1.0.14 的
/// 28800、1.0.24 的 0——后者误以为容器 TZ 会影响纯 epoch 算术,边界错开 8h,
/// 造成「MiniMax 15:00 重置、网关锁到 18:00」的线上事故),1.0.44 起整个删除,
/// `resets` 配置不再参与路由。**不要再往回加边界计算。**
pub const ACCT_COOL_HARD_CAP: i64 = 30 * 60;
/// 粘性绑定 TTL 兜底(秒):账号 `resets` 全空时绑定的最长保留时长(7 天)。
pub const AFFINITY_TTL_DEFAULT: i64 = 7 * 86400;
// ===========================================================================
// 趋势
// ===========================================================================
/// 日桶保留时长(秒):90 天。到期由共享内存自然淘汰(`get_live` 视为不存在),
/// 趋势接口默认只取最近 14 天,留足余量供改大区间。
pub const TREND_KEEP_SECS: i64 = 90 * 86400;
/// 趋势接口默认 / 最大天数(防止 URL 里塞个 99999 把共享内存扫爆)
pub const TREND_DAYS_DEFAULT: i64 = 14;
pub const TREND_DAYS_MAX: i64 = 90;
// ===========================================================================
// 对话审计(log 阶段旁路落盘,docs/llm/AUDIT_LOG.md)
// ===========================================================================
/// 审计目录名:默认挂在 data 目录的**父目录**下(即与 data 同级),可被
/// `ipass_audit_dir` 指令整体覆盖
pub const AUDIT_DIR_NAME: &str = "audit";
/// 审计总量上限(字节):超过即按日期目录从旧到新整目录删除,直到回落限内。
/// **1.0.18 起默认 1 GB**(旧 10 GB)——审计从「全量请求体」改为「meta + 100 字节摘要」,
/// 单条 ~400 B,1 GB 够撑约 250 万条(约 7 天 @ QPS 4);旧 10 GB 在新口径下等于
/// 「永远不会被 purge」的反向证据,留着只是误导容量判断。
pub const AUDIT_MAX_BYTES: u64 = 1024 * 1024 * 1024;
/// 容量巡检最小间隔(秒):巡检要扫整个审计树,节流避免高频 IO
pub const AUDIT_PURGE_MIN_INTERVAL: i64 = 60;
/// 请求体摘录字节数(meta 同一行的 `excerpt` 字段):
/// **1.0.27 起改为智能摘录**——短请求体(≤ `AUDIT_EXCERPT_BYTES`)保留原文;
/// 长请求体(> `AUDIT_EXCERPT_BYTES`)解析 JSON 后提取 `model` +
/// 最后一个 user message 的 `content`(按 `AUDIT_CONTENT_CHARS` 截前 N 字符),
/// 输出 `{"model":"…","content":"…"}`。
///
/// 设计取舍:大 body(带 tools / 多轮 history / context_management)只看
/// 前 100 字节 = 几乎全是结构噪声,看不到用户实际问啥。智能摘录**跳过
/// context_management / tools / temperature** 等结构字段,**优先把
/// 位置留给 user content**——对 100 KB+ 大请求也能复盘「当时问了啥」。
///
/// 想看全文就别存 audit,走 hot path 日志或实时抓包。
pub const AUDIT_EXCERPT_BYTES: usize = 100;
/// 智能 excerpt 中 user content 字符上限(按 Unicode scalar value 算)。
/// 200 字 ≈ 100 token,够支撑「用户问了啥」的诊断;超长 prompt 截前 200 字。
pub const AUDIT_CONTENT_CHARS: usize = 200;
/// 长请求体解析 JSON 时最多读前 N 字节。165 KB 那种大 body 不会全读进内存。
pub const AUDIT_JSON_PARSE_BYTES: usize = 16 * 1024;
/// `body_hash` 字段截断字节数(hex):完整 SHA256 64 字符太长,复盘只需要够用即可;
/// 16 hex = 64 bit 抗碰撞,远超 audit「识别同一请求」的需求。
/// ⚠️ 哈希对象是**请求体全文**(流式喂入,不整份读进内存),不是 excerpt —— 只哈希
/// 前 N 字节会因所有请求开头相同而全量碰撞。
pub const AUDIT_HASH_HEX_BYTES: usize = 16;
// ===========================================================================
// 统计落盘 / 恢复(docs/llm/STATS_PERSISTENCE.md)
// ===========================================================================
/// 运行期统计的快照文件名(落在 `data/` 下,与其他状态文件同级)。
///
/// **不含任何凭据**(只有账号名 / slot 名 / 计数 / token 数),但仍在 `data/` 里
/// ——`data/` 整体 gitignore,别把它单独挪到别处再误提交。
pub const STATS_FILE_NAME: &str = "llm-stats.json";
/// 周期性落盘间隔(秒)。**默认 60**,可被 `ipass_stats_persist <秒>` 覆盖,
/// `0` = 关闭周期落盘(只靠 worker 退出钩子那一次)。
///
/// 取 60 的理由:单次落盘要扫 10 个前缀 + 序列化,量级是毫秒;60 秒一次对磁盘与
/// 热路径都可忽略,而「最多丢 60 秒统计」远好于「丢全部历史」(1.0.18 之前的实际行为)。
/// 真要保零丢失也不靠调小它 —— 靠 worker 退出钩子(见 `stats_persist` 模块注释)。
pub const STATS_PERSIST_INTERVAL_DEFAULT: i64 = 60;
/// 快照格式版本。将来改结构时用它做兼容判断(版本对不上就**不恢复**,
/// 宁可从零开始,也不要把语义不明的旧数据灌进共享内存)。
pub const STATS_SNAPSHOT_VERSION: i64 = 1;
/// 键前缀:统计落盘模块的「上次恢复」记录(键 = `spr:last`,
/// value = `<时刻> \x1f <恢复键数> \x1f <快照键数>`)。
///
/// **刻意不在 `stats_persist::PREFIXES` 白名单里** —— 它是恢复过程的元信息,
/// 不是统计量,被持久化只会自我引用。
///
/// 为什么要落共享内存而不是进程内静态量:`init_process` 是**每 worker 跑一次**,
/// 首个 worker 恢复完、后续 worker 因 put-if-absent 全部跳过,各自计数天然不同
/// —— 管理接口落到哪个 worker 就报哪个数,运维看到的是随机值。放共享内存后
/// 所有 worker 报同一份,`/api/admin/stats/persist` 才可信。
pub const KEY_SPR_PREFIX: &[u8] = b"spr:";
/// 键前缀:统计落盘模块的「上次落盘」记录(键 = `spd:last`,value = `<时刻>`)。
///
/// 与 `KEY_SPR_PREFIX` **同类问题的同一解法**:落盘是每个 worker **各自发生**
/// 的(`maybe_dump` 由记账路径驱动,每个 worker 独立计数),记录若放进程内
/// 静态量,`/api/admin/stats/persist` 落到哪个 worker 就报哪个 worker 自己的
/// 时刻 —— 刚落下盘的 worker 报「刚刚」,另一个没落过的报「还没落过」,
/// 运维看到的是随机值(1.0.18 线上实测就是这个现象)。
///
/// 落在共享内存里一次解决两件事:
/// * **上报一致**:所有 worker 读同一个时刻;
/// * **节流收敛**:`maybe_dump` 慢路径查这一条,把「8 个 worker 各写一遍文件」
/// 收敛成「全局每间隔一次」。见 `stats_persist::maybe_dump`。
///
/// 同样**刻意不在 `stats_persist::PREFIXES` 白名单里**(不是统计量,持久化只会
/// 自我引用)。
pub const KEY_SPD_PREFIX: &[u8] = b"spd:";
+347
View File
@@ -0,0 +1,347 @@
//! LLM 插件的 phase handler:access 转发决策、log 阶段健康标记与对话审计。
//!
//! 插件化改造点(相对 gateway 旧版行为等价):
//! * location 开关改走内核契约 `loc::enabled(r, Switch::Llm)`——插件不认识
//! gateway 私有的 `ModuleConfig`;
//! * 下行鉴权(取 Key / 查身份 / 限流配额 / OpenAI 兼容错误体)用内核
//! `ipass_core::auth`(LLM 与 apix 两条下行链路共用);
//! * `$upstream_status` 变量索引的预取从 gateway postconfiguration 迁入本插件
//! 的 postconfig(见 [`prefetch_upstream_status_index`])。
use core::sync::atomic::{AtomicIsize, Ordering};
use ngx::core::{Status, NgxStr};
use ngx::ffi::{
ngx_conf_t, ngx_http_get_indexed_variable, ngx_http_get_variable_index,
ngx_http_request_t, ngx_str_t, ngx_uint_t,
};
use ngx::http::{HTTPStatus, HttpPhase, HttpRequestHandler, Request};
use crate::llm;
use crate::llm_audit;
use crate::stats;
use crate::upstreams;
use crate::usage_filter;
use ipass_core::{auth, http, loc, util};
use ipass_core::loc::Switch;
// ===========================================================================
// LLM 代理热路径(access)
// ===========================================================================
/// LLM 代理热路径:鉴权 → 校验上游与白名单 → 放行。
///
/// 刻意**只做决策、不搬数据**:真正的转发交给 nginx 的 proxy 模块,
/// 于是 SSE 流式、`proxy_buffering`、上游超时全部是 nginx 原生行为,
/// 不需要自己实现 upstream——那正是「按 body 里的 model 路由」代价高昂之处。
///
/// 变量(`$llm_target` / `$llm_host` / `$llm_auth`)不在这里赋值,
/// 而由 `llm::var_get` 在 `proxy_pass` 求值时计算,与 `$proxy_backend_addr` 同构。
pub struct LlmHandler;
impl HttpRequestHandler for LlmHandler {
const PHASE: HttpPhase = HttpPhase::Access;
type Output = Status;
fn handler(request: &mut Request) -> Self::Output {
let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t;
if !loc::enabled(r, Switch::Llm) {
return Status::NGX_DECLINED;
}
let Some(slot) = llm::slot_of(r) else {
return auth::fail(
r,
HTTPStatus::BAD_REQUEST,
"invalid_request_error",
"路径缺少上游段,正确形式:/<上游名>/v1/chat/completions",
);
};
let Some(key) = auth::downstream_key(r) else {
return auth::fail(
r,
HTTPStatus::UNAUTHORIZED,
"invalid_api_key",
"缺少 API Key,请在 Authorization: Bearer 或 x-api-key 中携带",
);
};
// 只碰共享内存:这里若改成 users::find_by_key 会每请求读一次 users.json
let Some((username, allowed, rpm, daily)) = auth::identity(&key) else {
util::log_warn(&format!(
"[llm] API Key 校验失败 slot={slot} client={}",
http::remote_addr(r)
));
return auth::fail(
r,
HTTPStatus::UNAUTHORIZED,
"invalid_api_key",
"API Key 无效或已失效",
);
};
// 「列出可用模型」是网关自己的元信息接口(OpenAI 兼容形状),
// 在查上游之前就地应答——否则 `/v1/models` 会被当成 slot=v1 → 404。
if llm::is_models_probe(r) {
return llm::respond_models(r, &allowed);
}
let upstream_live = llm::upstream_live(&slot);
if !upstream_live {
return auth::fail(
r,
HTTPStatus::NOT_FOUND,
"model_not_found",
&format!("上游 {slot} 不存在或已停用"),
);
}
// 空白名单 = 不限(老账号没有该字段时的语义)
if !allowed.is_empty() && !allowed.iter().any(|s| s == &slot) {
util::log_warn(&format!("[llm] {username} 无权访问上游 {slot}"));
return auth::fail(
r,
HTTPStatus::FORBIDDEN,
"permission_denied",
&format!("当前账号无权访问上游 {slot}"),
);
}
// 限流与每日配额(先增后判,纯共享内存)。放在最后:
// 鉴权/白名单都没过的请求不该消耗对方的计数
// SAFETY: r 由 nginx 传入且有效
if let Some(resp) = unsafe { auth::check_quota(r, &username, rpm, daily) } {
return resp;
}
// 用量统计:走到这里说明请求**真的会被转发**,才计入。
// 被拒的请求(401/403/404/429)不进统计——那是给人看的数字,
// 把拒绝也算进"用量"只会误导(与配额计数 st: 的语义刻意不同)。
stats::record(&username, &slot, util::now());
Status::NGX_DECLINED
}
}
// ===========================================================================
// log 阶段:上游健康标记
// ===========================================================================
/// `$upstream_status` 的变量索引,postconfiguration 时解析一次(log 阶段复用)。
static UPSTREAM_STATUS_IDX: AtomicIsize = AtomicIsize::new(-1);
/// `$llm_acct` 的变量索引(本插件注册),log 阶段读它拿到「本次请求打到的上游账号下标」,
/// 用于额度耗尽时精确标记那一个账号进入冷却。postconfiguration 时解析一次。
static LLM_ACCT_IDX: AtomicIsize = AtomicIsize::new(-1);
/// postconfiguration:预取 `$upstream_status` 与 `$llm_acct` 变量索引。
/// 失败返回 false,gateway 会 EMERG 退出。
pub fn prefetch_upstream_status_index(cf: *mut ngx_conf_t) -> bool {
let mut status_name = ngx_str_t {
len: "upstream_status".len() as usize,
data: b"upstream_status\0".as_ptr() as *mut u8,
};
// SAFETY: cf 由 nginx 传入且有效;name 指向栈上合法 ngx_str_t
let sidx = unsafe { ngx_http_get_variable_index(cf, &mut status_name) };
if sidx == -1 {
return false;
}
UPSTREAM_STATUS_IDX.store(sidx as isize, Ordering::Relaxed);
let mut acct_name = ngx_str_t {
len: "llm_acct".len() as usize,
data: b"llm_acct\0".as_ptr() as *mut u8,
};
// SAFETY: 同上;本插件已在 preconfiguration 用 add_var 注册过 llm_acct
let aidx = unsafe { ngx_http_get_variable_index(cf, &mut acct_name) };
if aidx == -1 {
return false;
}
LLM_ACCT_IDX.store(aidx as isize, Ordering::Relaxed);
true
}
/// LLM 上游健康标记(log 阶段):把上游**真实**状态码写进 `uh:<slot>` 缓存。
///
/// 为什么在 log 阶段:转发决策在 access、响应在 proxy 模块手里,只有 log
/// 阶段能同时拿到「slot 是谁」和「上游实际回了什么」。这相当于让**真实流量
/// 自己当探针**——不需要额外的常驻探测进程(项目红线),健康状态也最真实。
/// 管理台「测试」按钮的探测请求走同一条 `proxy_pass` 链路,天然共用本逻辑。
///
/// 写下的缓存**只用于展示**(列表标红 / 模型发现附状态),转发路径不读它,
/// 误标不影响任何请求的结果。
///
/// ⚠️ 状态码从 `$upstream_status` 变量读,**不能读 `r->upstream`**——
/// `ngx_http_upstream_finalize_request` 在日志阶段之前就把 `r->upstream`
/// 置空了(实测踩过:代码编译通过、跑起来状态永远是 unknown)。
/// access log 模块同款手法:变量在 finalize 时快照,log 阶段仍有效。
pub struct LlmHealthHandler;
impl HttpRequestHandler for LlmHealthHandler {
const PHASE: HttpPhase = HttpPhase::Log;
type Output = Status;
fn handler(request: &mut Request) -> Self::Output {
let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t;
// 两类请求要标记:
// ① LLM server 的真实转发流量(Switch::Llm 开启);
// ② 管理台探测流量——内部重定向到管理 server 的 /_upstream_test location,
// 那里**没有** ipass_llm 指令(有就会重跑 access 鉴权,探测请求只有
// 登录会话没有 API Key),所以只能按 URI 前缀认。
let uri = http::uri(r);
let is_llm = loc::enabled(r, Switch::Llm);
let is_probe = uri.starts_with("/_upstream_test");
if !is_llm && !is_probe {
return Status::NGX_DECLINED;
}
// SAFETY: r 有效;索引在 postconfiguration 已解析(见 prefetch_upstream_status_index)
let code = unsafe {
let idx = UPSTREAM_STATUS_IDX.load(Ordering::Relaxed);
if idx < 0 {
0
} else {
let v = ngx_http_get_indexed_variable(r, idx as ngx_uint_t);
if (*v).not_found() != 0 || (*v).data.is_null() {
0
} else {
let s = core::str::from_utf8(core::slice::from_raw_parts(
(*v).data,
(*v).len() as usize,
))
.unwrap_or("");
// 内部重定向会有多段(如 "502, 200"),取**最后一段** = 最近一次上游尝试
s.rsplit(',').next().unwrap_or("").trim().parse().unwrap_or(0)
}
}
};
// 没有 upstream(本地应答如 /v1/models)或没拿到状态码(客户端中途
// 断连等)→ 无从判断,不写缓存,留给下一次真实转发
if code == 0 {
return Status::NGX_DECLINED;
}
if let Some(slot) = llm::slot_of(r) {
let now = util::now();
// 上游回了头 = 它活着:2xx~4xx 都算正常(4xx 是它对我们请求的意见,
// 不是机器死了);5xx / 连接失败(502) / 等头超时(504) 才算失效
upstreams::mark_health(&slot, (200..500).contains(&code), code);
// 账号级负载:每次真实转发都记到选中的上游账号(负载分布 / 问题发现)。
// 只在这里记一次(read_llm_acct 触发一次 pick_account),绝不放在
// pick_account 里——否则 $llm_target/$llm_host/$llm_auth/$llm_acct
// 四个变量各触发一次,会把同一请求记好几遍。
if let Some(idx) = read_llm_acct(r) {
upstreams::bump_acct_load(&slot, idx, now);
// 额度耗尽检测:状态码命中 或 响应体命中标记 → 标记该账号冷却 + 耗尽计数 +1。
// 状态码来自 `$upstream_status`,标记来自 body filter 的 `take_exhausted`
// (流式也能扫到)。
//
// 探测闭环(1.0.44)的两半边都在这里合流(log 阶段每请求只跑一次,
// 这是副作用只能放这的原因——pick 会被四个变量求值多次):
// * 耗尽信号(状态码或 body marker)→ mark_exhausted:新账号开冷却;
// 冷却中且窗口已到期(= 探测失败)→ re-arm 翻倍关窗;未到期
// (best-effort 撞墙)→ 时间线不动;
// * 2xx 且无耗尽信号 → clear_cool:冷却中的账号被探测/转发验证恢复,
// 立即清键回队(健康账号无键,remove 返回 false、静默)。
//
// is_probe(管理台「测试」按钮的内跳)**不写冷却/耗尽**——
// 测试账号由 pick 随机选,上游回耗尽形态只说明「这个请求过不了」,
// 不能据此认定账号已耗尽。线上事故:13:50 三把好 key 被面板测试轮
// 点进冷却,整池不可用,恢复要走完整退避。mark_health 与
// bump_acct_load 照常(测试也是真转发,有统计意义);
// 2xx clear_cool 也保留——测试成功 = 该账号此刻健康(正向证据)。
let (status_list, _) = upstreams::read_upe(&slot);
let status_exhausted = status_list.iter().any(|&s| s == code);
let body_exhausted = usage_filter::take_exhausted(r);
if !is_probe && (status_exhausted || body_exhausted) {
upstreams::mark_exhausted(&slot, idx, now);
upstreams::bump_acct_exhaust(&slot, idx, now);
} else if (200..300).contains(&code) {
upstreams::clear_cool(&slot, idx);
}
}
}
Status::NGX_DECLINED
}
}
/// 从 `$llm_acct` 索引读本次请求选中的上游账号下标(NOCACHEABLE,读时重算,确定一致)。
///
/// 读不到(未求值/解析失败)返回 None——不标记,避免误伤。
fn read_llm_acct(r: *mut ngx_http_request_t) -> Option<usize> {
let idx = LLM_ACCT_IDX.load(Ordering::Relaxed);
if idx < 0 {
return None;
}
// SAFETY: 索引在 postconfiguration 已解析;变量为 NOCACHEABLE,读即触发 get_handler
unsafe {
let v = ngx_http_get_indexed_variable(r, idx as ngx_uint_t);
if v.is_null() || (*v).not_found() != 0 || (*v).data.is_null() {
return None;
}
let s = core::str::from_utf8(core::slice::from_raw_parts(
(*v).data,
(*v).len() as usize,
))
.ok()?;
s.trim().parse::<usize>().ok()
}
}
// ===========================================================================
// log 阶段:对话审计 + token 入账
// ===========================================================================
/// LLM 对话审计(log 阶段):把被转发请求的 body 临时文件复制进审计目录。
///
/// 捕获机制与清理策略见 `llm_audit` 模块注释与 docs/llm/AUDIT_LOG.md。
/// 关键点:只依赖 `client_body_in_file_only clean` 留下的临时文件,本阶段
/// **不读请求体、不碰内存缓冲**——热路径与 SSE 透传完全无感知。
pub struct AuditHandler;
impl HttpRequestHandler for AuditHandler {
const PHASE: HttpPhase = HttpPhase::Log;
type Output = Status;
fn handler(request: &mut Request) -> Self::Output {
let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t;
if !loc::enabled(r, Switch::Llm) {
return Status::NGX_DECLINED;
}
// 身份在 log 阶段重新解析:ukey shm 查询是纯内存读,代价可忽略;
// 换取 access→log 之间不挂任何请求级状态(无 ctx、无生命周期问题)。
// 请求已被转发过(有临时文件)才查得到 Key——被拒请求天然不入档。
let user = auth::downstream_key(r)
.and_then(|k| auth::identity(&k))
.map(|(u, _, _, _)| u);
let slot = llm::slot_of(r).unwrap_or_default();
// token 计量:body filter 旁路抓到的 usage(见 usage_filter 模块注释)
let (tin, tout) = usage_filter::take(r);
if tin > 0 || tout > 0 {
if let Some(name) = user.as_deref() {
stats::add_tokens(name, &slot, tin, tout, util::now());
}
// 账号级 token 负载(与账号级请求数同一个日桶维度 uda:)
let now = util::now();
if let Some(idx) = read_llm_acct(r) {
upstreams::add_acct_tokens(&slot, idx, tin as i64, tout as i64, now);
}
}
// SAFETY: 同上;capture 内部任何失败只记日志,绝不 panic
unsafe { llm_audit::capture(r, user.as_deref().unwrap_or("-"), &slot, tin, tout) };
Status::NGX_DECLINED
}
}
// 类型占位:NgxStr 在本 crate 被引用但暂未直接使用,保留编译期链接检查
#[allow(dead_code)]
fn _type_witness(_: &NgxStr) {}
+83
View File
@@ -0,0 +1,83 @@
//! plugin-llm —— LLM API 代理插件。
//!
//! 职责:`/<slot>/...` → 上游转发决策、上游 CRUD、OpenAI 兼容模型发现、
//! `rl:`/`st:` 配额执行、token 计量(body filter 旁路)、用量统计与趋势、
//! 对话审计落盘、运行期统计落盘/恢复。数据文件 `data/llm-upstreams.json`
//! (敏感级别等同 users.json)与 `data/llm-stats.json`(统计快照,无凭据)。
//!
//! ## 装配点(gateway)
//!
//! * `preconfig` —— 注册 `$llm_target` / `$llm_host` / `$llm_auth` 三件套
//! * `postconfig` —— 注册 LlmHandler(access)/ LlmHealthHandler、AuditHandler
//! (log)/ body filter 链头插入(token 计量)/ 预取 `$upstream_status` 索引
//! * `zone_load` —— 全量装载 `up:` 上游表
//! * `dispatch_api` —— 认领上游 / 用量类端点(趋势端点留 gateway,需三方名册)
//!
//! ## 进程生命周期钩子(由 gateway 调用,不是插件自己的钩子)
//!
//! * `stats_persist::restore()` 在 `init_process` —— 重启后把统计快照灌回共享内存
//! * `stats_persist::dump_now()` 在 `exit_process` —— 退出前落盘,发版不丢统计
//!
//! ## 与其他插件的关系
//!
//! 下行鉴权与配额执行(`ukey:` / `rl:` / `st:`)在内核 `ipass_core::auth`;
//! 记账原语在内核 `ipass_core::usage`——apix 插件复用同一套下行契约,
//! 与本插件共用同一片用量键空间(apix 的 slot 带 `api/` 前缀天然归组)。
pub mod api;
pub mod config;
pub mod handlers;
pub mod llm;
pub mod llm_audit;
pub mod models;
pub mod stats;
pub mod stats_persist;
pub mod store;
pub mod upstreams;
pub mod usage_filter;
use ngx::core::Status;
use ngx::ffi::{ngx_conf_t, ngx_http_request_t};
use ipass_core::plugin::Plugin;
pub struct LlmPlugin;
impl Plugin for LlmPlugin {
fn name(&self) -> &'static str {
"llm"
}
fn preconfig(&self, cf: *mut ngx_conf_t) -> bool {
// SAFETY: cf 由 nginx 传入且有效
unsafe { llm::preconfig(cf) }
}
fn postconfig(&self, cf: *mut ngx_conf_t) -> bool {
// SAFETY: cf 由 nginx 传入且有效
let cf = unsafe { &mut *cf };
// token 计量:插进 body filter 链头,旁路扫描上游响应的 usage
usage_filter::install();
if ngx::http::add_phase_handler::<handlers::LlmHandler>(cf).is_err() {
return false;
}
if ngx::http::add_phase_handler::<handlers::LlmHealthHandler>(cf).is_err() {
return false;
}
if ngx::http::add_phase_handler::<handlers::AuditHandler>(cf).is_err() {
return false;
}
// 预取 `$upstream_status` 索引(upstream 模块 preconfiguration 已注册该内建变量)
handlers::prefetch_upstream_status_index(cf)
}
fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option<Status> {
api::dispatch(r)
}
fn zone_load(&self) -> usize {
upstreams::reload_shm()
}
}
+458
View File
@@ -0,0 +1,458 @@
//! 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:` 键里,热路径只碰共享内存。取 Key / 查身份 /
//! 限流配额 / OpenAI 兼容错误体已下沉内核 `ipass_core::auth`(LLM 与 apix
//! 两条下行链路共用)。
//! * **access 阶段读不到请求体**,因此这里不解析 `model` 字段,上游由 URL 前缀
//! 决定(原因见 `upstreams` 模块头注释)。
//! * **错误体必须是 OpenAI 兼容格式**(`{"error":{...}}`)。客户端的 SDK 只认这个,
//! 项目自己的 `{"code":400,"msg":...}` 会被 SDK 报成「无法解析的响应」。
use core::ptr;
use ngx::core::{Pool, Status};
use ngx::ffi::{
NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, ngx_conf_t, ngx_http_add_variable,
ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, ngx_str_t, ngx_uint_t,
};
use ngx::http::HTTPStatus;
use ngx::ngx_string;
use serde_json::json;
use crate::config;
use crate::upstreams;
use ipass_core::{auth, http, state, util};
// ===========================================================================
// 变量分派标记
// ===========================================================================
/// `$llm_target`:完整上游 URL(含 path 与 query),直接交给 `proxy_pass`
pub const VAR_TARGET: usize = 1;
/// `$llm_host`:上游 Host 头(`proxy_set_header Host $llm_host`)
///
/// 变量形式的 `proxy_pass` 不会自动推导 Host,必须显式设,
/// 否则打给 OpenAI / Cloudflare 后端会因 Host 不符被拒。
pub const VAR_HOST: usize = 2;
/// `$llm_auth`:上游 Authorization 头值
pub const VAR_AUTH: usize = 3;
/// `$llm_acct`:本次请求选中的上游账号下标(多账号路由用;log 阶段据此标记耗尽)。
/// 由 `pick_account` 在变量求值时计算(与 `$llm_auth` 同源,保证一致)。
pub const VAR_ACCT: usize = 4;
// ===========================================================================
// preconfiguration:注册变量
// ===========================================================================
/// 注册 LLM 四件套只读变量(gateway preconfiguration 经插件循环调用)。
///
/// 名字里的 `llm_` 前缀不要省:nginx 变量名全局唯一,
/// 将来接入别的模块时才不会撞名。
///
/// # Safety
/// `cf` 由 nginx 传入且有效。
pub unsafe fn preconfig(cf: *mut ngx_conf_t) -> bool {
let mut target = ngx_string!("llm_target");
let mut host = ngx_string!("llm_host");
let mut auth_var = ngx_string!("llm_auth");
let mut acct_var = ngx_string!("llm_acct");
unsafe {
add_var(cf, &raw mut target, VAR_TARGET)
&& add_var(cf, &raw mut host, VAR_HOST)
&& add_var(cf, &raw mut auth_var, VAR_AUTH)
&& add_var(cf, &raw mut acct_var, VAR_ACCT)
}
}
/// 注册一个只读变量,值由 [`var_get`] 按 `slot` 分派计算。
///
/// 与 `$proxy_backend_addr` 不同,LLM 三件套**不需要**
/// `ngx_http_get_variable_index`——它们是纯只读的,模块从不主动写,
/// 只有 `proxy_pass` / `proxy_set_header` 求值时触发 get_handler。
unsafe fn add_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> bool {
// SAFETY: cf 由 nginx 传入;name 指向本函数调用方栈上的 ngx_str_t,注册时被拷贝
let var = unsafe {
ngx_http_add_variable(
cf,
name,
(NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t,
)
};
if var.is_null() {
return false;
}
// SAFETY: var 非空且由本函数独占初始化;data 承载分派标记
unsafe {
(*var).get_handler = Some(var_get);
(*var).set_handler = None;
(*var).data = slot;
}
true
}
// ===========================================================================
// 请求解析
// ===========================================================================
/// 上游在共享内存里是否可用(原 `state::get_upstream` 的语义:`get_live`
/// 精确取 `up:<slot>`,过期视为不存在)。**未命中即 404,无回源兜底**。
pub fn upstream_live(slot: &str) -> bool {
state::get_live(config::KEY_UP_PREFIX, slot.as_bytes(), util::now()).is_some()
}
/// 剥掉内部测试前缀:`/_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 = 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())
}
/// 这条请求是不是走 Anthropic 协议:`/<slot>/anthropic/...` 是,其余不是。
///
/// 判定只看 slot **之后**的第一段路径是否 `anthropic`——模型名不在路径里,
/// 不会误判。内部测试 location `/_upstream_test/<slot>/anthropic/...` 同样识别。
pub fn is_anthropic(r: *mut ngx_http_request_t) -> bool {
let raw = http::uri(r);
let uri = strip_internal_prefix(&raw);
let rest = uri.strip_prefix('/').unwrap_or(uri);
// 剥掉 slot 段(第一段),看剩下第一段是否 `anthropic`
let after_slot = match rest.find('/') {
Some(i) => &rest[i..],
None => return false,
};
after_slot
.trim_start_matches('/')
.split('/')
.next()
.map(|s| s.eq_ignore_ascii_case("anthropic"))
.unwrap_or(false)
}
/// 剥掉 slot 段、拼回 query:`/openai/v1/chat/completions?a=1` → `/v1/chat/completions?a=1`
///
/// Anthropic 协议时(`anthropic = true`),额外剥掉路径里紧跟 slot 的
/// `/anthropic` 段——那段是网关替客户端表达的「协议标记」,不属于上游路径;
/// 不剥会让 `base_anthropic`(已以 `/anthropic` 结尾)变成 `…/anthropic/anthropic/...`。
///
/// query 必须在这里拼——变量形式的 `proxy_pass` **不会**自动追加原始 args。
pub fn upstream_uri(r: *mut ngx_http_request_t, anthropic: bool) -> String {
let uri = http::uri(r);
let uri = strip_internal_prefix(&uri);
let rest = uri.strip_prefix('/').unwrap_or(uri);
// 只有 slot、没有后续路径时(如 `/openai`)打到上游根
let path = match rest.find('/') {
Some(i) => &rest[i..],
None => "/",
};
// Anthropic:剥掉紧跟 slot 的 `/anthropic` 段(及其后接的 `/` 由 join_target 处理)
let path = if anthropic {
match path.strip_prefix("/anthropic") {
Some(tail) if tail.is_empty() => "/",
Some(tail) => tail,
None => path,
}
} else {
path
};
let args = http::args_raw(r);
if args.is_empty() {
path.to_owned()
} else {
format!("{}?{}", path, String::from_utf8_lossy(&args))
}
}
/// 从 `https://api.openai.com:443` 取出 `api.openai.com:443`(去掉 scheme 与路径)
fn host_of(base: &str) -> &str {
let rest = match base.find("://") {
Some(i) => &base[i + 3..],
None => base,
};
match rest.find('/') {
Some(i) => &rest[..i],
None => rest,
}
}
/// 拆 base:`https://api.deepseek.com/v1` → `("https://api.deepseek.com", "/v1")`
fn split_origin(base: &str) -> (&str, &str) {
let Some(i) = base.find("://") else {
return (base, "");
};
let after = &base[i + 3..];
match after.find('/') {
Some(j) => (&base[..i + 3 + j], &after[j..]),
None => (base, ""),
}
}
/// 拼上游完整 URL:`base + 客户端路径(已剥掉 slot)`。
///
/// **核心规则(仅 OpenAI 协议生效)**:当 base 自带路径段(如智谱的
/// `…/api/coding/paas/v4`、阿里的 `…/compatible-mode/v1`)而客户端又按
/// OpenAI 习惯带 `/v1` 时,`/v1` 是冗余的,必须剥掉再拼。否则会拼出
/// `…/v4/v1/chat/completions`(智谱严格 404)或 `…/compatible-mode/v1/v1/…`
/// (阿里容忍但脏拼)。
///
/// Anthropic 协议**不**剥 `/v1`:Anthropic 协议 `messages` 前必须有 `/v1`,
/// 上游 base 已是 `…/api/anthropic`(裸 host 后的路径),客户端发的 `/v1/messages`
/// 必须原样保留,剥掉就漏版本段。
///
/// ```text
/// base 裸 host(OpenAI,deepseek/minimax):
/// https://api.deepseek.com + /v1/chat/completions → https://api.deepseek.com/v1/chat/completions (客户端 /v1 保留)
/// base 自带路径段(OpenAI,glm/qwen):
/// …/api/coding/paas/v4 + /v1/chat/completions → …/api/coding/paas/v4/chat/completions (剥客户端 /v1)
/// …/api/coding/paas/v4 + /chat/completions → …/api/coding/paas/v4/chat/completions (客户端没带,照常)
/// Anthropic(base 带 /api/anthropic 段):
/// …/api/anthropic + /v1/messages → …/api/anthropic/v1/messages (/v1 不剥)
/// http://127.0.0.1:18999 + /anthropic/v1/messages → http://127.0.0.1:18999/anthropic/v1/messages (openai 裸 host + Anthropic 路径:不剥)
/// ```
///
/// 这条规则是**实测踩坑换来的**:智谱(glm) 的 OpenAI 基址是 `…/api/coding/paas/v4`、
/// Anthropic 基址是 `…/api/anthropic`;客户端统一带 `/v1` 时,glm 的 OpenAI 路径
/// 会被拼成 `…/v4/v1/chat/completions` 被智谱 404(响应体为空,网关侧看不出是
/// 拼接错)。而 Anthropic 的 `/v1` 必须保留——否则会漏版本段被 Anthropic 协议
/// 上游 404。改后所有厂商只需把文档里的 host 换成网关域名 + 保留厂商原始路径段。
fn join_target(base: &str, path: &str, anthropic: bool) -> String {
let (origin, base_path) = split_origin(base);
// OpenAI:base 是裸 host → 客户端路径原样拼
// Anthropic:始终原样拼,/v1/messages 必须保留版本段
if anthropic || base_path.is_empty() || base_path == "/" {
return format!("{base}{path}");
}
// OpenAI + base 自带路径段:剥掉客户端冗余的 `/v1` 再拼。
let tail = match path.strip_prefix("/v1") {
Some(t) if !t.is_empty() => t, // `/v1/chat/completions` → `/chat/completions`
Some(_) => "/", // 客户端只发了 `/v1` → 打到上游根
None => path, // 客户端没带 `/v1`(如 `/chat/completions`)→ 照常拼
};
format!("{origin}{base_path}{tail}")
}
// ===========================================================================
// 模型发现(本地应答,不去上游)
// ===========================================================================
/// 是不是"列出模型"请求:`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 !http::method_str(r).eq_ignore_ascii_case("GET") {
return false;
}
let uri = http::uri(r);
let uri = uri.trim_end_matches('/');
uri == "/v1/models" || uri == "/models"
}
/// 本地应答模型列表,形状与 OpenAI 的 `/v1/models` 一致。
///
/// 客户端 SDK 只认这个形状,返回项目自己的 `{code,msg,data}` 会让 SDK
/// 报"无法解析的响应"——与错误体必须 OpenAI 兼容是同一个理由。
///
/// 顶层额外挂一个 `x_ipass_upstreams`(OpenAI SDK 忽略未知字段):
/// 每个**该账号可用**的上游一段,给出 OpenAI / Anthropic 两种 base_url、
/// 登记的模型清单与健康状态——客户端拿一把有效 Key 一次就能取齐
/// 「能调哪些地址、哪些模型、哪些上游当前失效」。健康来自真实流量的
/// log 阶段标记(`uh:` 缓存),从没被调用过 = `unknown`。
pub fn respond_models(r: *mut ngx_http_request_t, allowed: &[String]) -> Status {
let data: Vec<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 = 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 _ = http::send(r, HTTPStatus::OK, &body);
Status(HTTPStatus::OK.0 as ngx_int_t)
}
// ===========================================================================
// 变量 get_handler
// ===========================================================================
/// 在请求内存池里分配字符串并写进变量槽。随请求回收,无需手动释放。
///
/// # Safety
/// `r` / `v` 必须由 nginx 传入且在本调用期间有效。
unsafe fn set_value(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
value: &str,
) -> ngx_int_t {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = value.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
(*v).set_not_found(1);
return Status::NGX_ERROR.into();
}
ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
(*v).data = data;
(*v).set_len(bytes.len() as _);
(*v).set_valid(1);
(*v).set_no_cacheable(1);
(*v).set_not_found(0);
Status::NGX_OK.into()
}
/// 四个 LLM 变量共用一个 get_handler,靠 `var.data` 分派(值由 `preconfiguration` 写入)。
///
/// 共用代价:每个变量各调一次 `pick_account`(一次读锁 + 几次 BTreeMap 查找 + 一次
/// 小分配,微秒级),相对一次 LLM 推理完全可忽略;换来不必维护四份相近代码。
///
/// `$llm_acct` 的求值会顺带把「用户 key → 账号」粘性绑定写进共享内存
/// (仅当下行 key 存在且绑定变化),是幂等副作用。log 阶段读取 `$llm_acct` 即得到
/// 本次请求实际打到的账号下标(用于额度耗尽时精确标记那一个账号)。
pub extern "C" fn var_get(
r: *mut ngx_http_request_t,
v: *mut ngx_http_variable_value_t,
data: usize,
) -> ngx_int_t {
// SAFETY: r/v 由 nginx 传入且有效;slot_of/upstream_uri 只读请求结构
unsafe {
let resolved = (|| -> Option<(String, String, String, usize)> {
let slot = slot_of(r)?;
// 协议分流:路径里有没有 `/anthropic` 段决定走 base_anthropic 还是 base
let anthropic = is_anthropic(r);
let key = auth::downstream_key(r);
let now = util::now();
// 选账号:粘性优先 → 到期探测 → FNV 冷分散 → 全冷却 best-effort(见 pick_account)
let (idx, auth, base) =
upstreams::pick_account(&slot, anthropic, key.as_deref(), now)?;
let target = join_target(&base, &upstream_uri(r, anthropic), anthropic);
let host = host_of(&base).to_owned();
Some((target, host, auth, idx))
})();
match resolved {
Some((target, host, auth, idx)) => {
// 四个分支各取一个字段(只有命中分支的 String 被移动出去)
let value = match data {
VAR_TARGET => target,
VAR_HOST => host,
VAR_AUTH => auth,
VAR_ACCT => idx.to_string(),
_ => return Status::NGX_ERROR.into(),
};
set_value(r, v, &value)
}
None => {
(*v).set_not_found(1);
(*v).set_valid(0);
Status::NGX_ERROR.into()
}
}
}
}
#[cfg(test)]
mod tests {
use super::join_target;
#[test]
fn join_target_strips_redundant_v1_when_base_has_path() {
// 智谱:base 自带 /api/coding/paas/v4,OpenAI 客户端带 /v1 → 必须剥掉
assert_eq!(
join_target("https://open.bigmodel.cn/api/coding/paas/v4", "/v1/chat/completions", false),
"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions"
);
// 阿里:base 自带 /compatible-mode/v1,双 /v1 也要收敛成单 /v1
assert_eq!(
join_target("https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", "/v1/chat/completions", false),
"https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions"
);
// 客户端没带 /v1(如 OpenAI SDK 直接拼 /chat/completions)→ 照常
assert_eq!(
join_target("https://open.bigmodel.cn/api/coding/paas/v4", "/chat/completions", false),
"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions"
);
// 裸 host(无路径段)→ OpenAI 客户端 /v1 原样保留(deepseek/minimax)
assert_eq!(
join_target("https://api.deepseek.com", "/v1/chat/completions", false),
"https://api.deepseek.com/v1/chat/completions"
);
assert_eq!(
join_target("https://api.minimaxi.com", "/v1/chat/completions", false),
"https://api.minimaxi.com/v1/chat/completions"
);
// Anthropic:/v1/messages 必须保留版本段,不能剥
assert_eq!(
join_target("https://open.bigmodel.cn/api/anthropic", "/v1/messages", true),
"https://open.bigmodel.cn/api/anthropic/v1/messages"
);
// Anthropic + 裸 host base + 客户端 /anthropic/v1/messages → 原样拼
assert_eq!(
join_target("http://127.0.0.1:18999", "/anthropic/v1/messages", true),
"http://127.0.0.1:18999/anthropic/v1/messages"
);
}
}
+686
View File
@@ -0,0 +1,686 @@
//! LLM 对话审计:把每个**被转发**的 LLM 请求**元数据**落盘存档。
//!
//! 设计要点(详见 docs/llm/AUDIT_LOG.md):
//! * **捕获方式**:LLM location 开 `client_body_in_file_only clean`,nginx 自己把
//! 请求体刷到临时文件;本模块在 **log 阶段**单遍扫描该临时文件 —— **只保留前 N 字节**
//! 作为 `excerpt`,其余边读边喂 SHA256 后丢弃,产出 `body_hash`(全文指纹)与
//! `body_bytes`(全文长度),然后追加一行到 `meta.jsonl`。
//! **1.0.18 起不再复制完整 body 到 audit 目录** —— 旧版每请求 700 KB+(带 tools /
//! 多轮 history),QPS 10 一天 600 GB,10 GB 配额 24 分钟就触发 purge,复盘价值
//! 也不大(前 100 字符就能秒判「用了哪个模型 + 用户问了啥」)。
//! * **目录**:`<审计根>/YYYY-MM-DD/meta.jsonl`。不再有 `<毫秒>_<rand>.json` 子文件。
//! 审计根默认 = data 目录的兄弟目录 `audit/`(`ipass_audit_dir` 指令可覆盖)。
//! * **清理**:按容量触发(`AUDIT_MAX_BYTES`)——写入后节流巡检
//! (≥ `AUDIT_PURGE_MIN_INTERVAL` 秒一次、AtomicBool 单飞),超限时按日期
//! 目录**从旧到新整目录删除**;worker 启动时强制巡检一次(不依赖外部 cron)。
//! * **失败策略**:审计是旁路功能,任何失败只 `log_err`,绝不影响转发结果。
//!
//! ## 1.0.18 行为变更
//!
//! - 不再复制完整 body:单请求审计占用从 ~700 KB 降到 ~500 B(一行 meta),**降约 3 个数量级**
//! - meta 行新增三个字段:`excerpt`(body 前 100 字节,JSON 转义交给序列化器,**不双重编码**)、`body_hash`(**全文** SHA256 前 16 hex)、`body_bytes`(全文字节数)
//! - `AUDIT_MAX_BYTES` 默认从 10 GB 改为 1 GB(旧值在新口径下等于「永远不会 purge」)
use std::fs;
use std::io::{BufReader, Read, 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::{Value, json};
use crate::config;
use ipass_core::state;
use ipass_core::store;
use ipass_core::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);
}
/// 把「body 前 N 字节」解成字符串,供 meta 行的 `excerpt` 字段使用。
///
/// **只做 UTF-8 安全解码,不做 JSON 转义** —— 引号 / 反斜杠 / 控制字符一律交给
/// `json!()`(serde_json)统一转义。这里若自己再转义一遍就是**双重编码**
/// (1.0.18 第一版踩过:落盘成 `"excerpt":"\"{\\\"model\\\"...\""`,读出来多一层
/// 引号,任何按前缀匹配的消费方都解析不到)。
///
/// 把「body 前 N 字节」解成字符串,供 meta 行的 `excerpt` 字段使用。
///
/// **1.0.27 起改为智能摘录**:
/// - body 长度 ≤ `AUDIT_EXCERPT_BYTES` → 保留原文(短 query 整条有诊断价值);
/// - body 长度 > `AUDIT_EXCERPT_BYTES` → 解析 JSON,提取 `model` + 最后一个 user
/// message 的 `content`(按 `AUDIT_CONTENT_CHARS` 截前 N 字),跳过
/// `context_management` / `tools` / `temperature` 等结构噪声,输出
/// `{"model":"…","content":"…"}`。
///
/// 大 body(165 KB / 238 KB 那种)原 100 字节截到的全是 `context_management`
/// 元数据 —— 智能摘录**优先把位置留给 user content**,让 audit 真有复盘价值。
fn excerpt_text(body_bytes_total: u64, raw: &[u8]) -> String {
if body_bytes_total <= config::AUDIT_EXCERPT_BYTES as u64 {
// 短请求体:原文保留(含 model + messages 结构)。`from_utf8_lossy` 把
// 切在多字节字符中间的残缺尾巴换成 U+FFFD,序列化器吃得下。
return String::from_utf8_lossy(raw).into_owned();
}
// 长请求体:仅解析前 N 字节(受 `AUDIT_JSON_PARSE_BYTES` 限制,避免 165 KB
// 大 body 全读进内存)。
let parse_cap = raw.len().min(config::AUDIT_JSON_PARSE_BYTES);
let v: Value = match serde_json::from_slice(&raw[..parse_cap]) {
Ok(v) => v,
Err(_) => return String::new(), // 非 JSON body(罕见,如多模态二进制)→ 空 excerpt
};
let model = v
.get("model")
.and_then(|m| m.as_str())
.unwrap_or("");
let user_content = extract_user_content(&v);
if user_content.is_empty() {
// 没找到 messages / content(异常 body)→ 空 excerpt
return String::new();
}
// 截前 N 字(按 char 而非 byte,避免切断 UTF-8 多字节字符)
let content: String = user_content.chars().take(config::AUDIT_CONTENT_CHARS).collect();
json!({ "model": model, "content": content }).to_string()
}
/// 提取最后一个 user message 的 content 文本。
///
/// 兼容 OpenAI(`messages[-1].content` 是字符串)与 Anthropic
///(`messages[-1].content` 是 `[{type:"text", text:"..."}, ...]` 数组)。
fn extract_user_content(v: &Value) -> String {
let messages = match v.get("messages").and_then(|m| m.as_array()) {
Some(arr) => arr,
None => return String::new(),
};
// 倒序找最后一个 role=user 的消息(避免工具结果 assistant 回复被误算)
for m in messages.iter().rev() {
let role_ok = m.get("role").and_then(|r| r.as_str()) == Some("user");
if !role_ok {
continue;
}
if let Some(content) = m.get("content") {
// OpenAI: content 是字符串
if let Some(s) = content.as_str() {
return s.to_owned();
}
// Anthropic: content 是 [{type:"text", text:"..."}, ...] 数组
if let Some(arr) = content.as_array() {
for item in arr {
if let Some(text) = item.get("text").and_then(|t| t.as_str()) {
return text.to_owned();
}
}
}
}
}
String::new()
}
/// 单遍扫描 body 临时文件:**只把前 N 字节留在内存**,其余边读边喂哈希后丢弃。
///
/// 返回 `(前 N 字节, 全量 SHA256 hex, 全量字节数)`。读失败返回空值(审计是旁路,失败不报错)。
///
/// 为什么扫全文而不是只读前 N 字节:`body_hash` 要当「同一请求」的指纹用,
/// 而所有 OpenAI/Anthropic 请求的前 100 字节都是同一个开头
/// (`{"model":"…","messages":[{"role":`),只哈希前缀 = 全部碰撞,这一列就是废数据。
/// 扫全文只是顺序 IO,不复制、不落盘,成本仍**低于** 1.0.17 的「读全文 + 写全文副本」。
fn scan_body(path: &str, n: usize) -> (Vec<u8>, String, u64) {
let f = match fs::File::open(path) {
Ok(f) => f,
Err(_) => return (Vec::new(), String::new(), 0),
};
let mut r = BufReader::new(f);
let mut prefix: Vec<u8> = Vec::with_capacity(n);
let mut hasher = util::Sha256Stream::new();
let mut total: u64 = 0;
let mut buf = [0u8; 64 * 1024];
loop {
match r.read(&mut buf) {
Ok(0) => break,
Ok(k) => {
if prefix.len() < n {
let need = (n - prefix.len()).min(k);
prefix.extend_from_slice(&buf[..need]);
}
hasher.update(&buf[..k]);
total += k as u64;
}
Err(_) => break,
}
}
(prefix, hasher.finish_hex(), total)
}
/// log 阶段捕获:单遍扫描 body 临时文件,取**前 N 字节**作为 excerpt、全文算 SHA256、
/// 追加一行元数据。**1.0.18 起不再复制完整 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;
}
// 单遍扫描:取前 N 字节作为 excerpt 原文,全文算 SHA256(前 16 hex)。body 可能几 MB,
// 但只有前 N 字节留在内存,且**不再复制完整文件、不再写 `<毫秒>_<rand>.json` 子文件**。
let (prefix, full_hash, body_bytes) = scan_body(&src, config::AUDIT_JSON_PARSE_BYTES);
// 1.0.27 智能摘录:短请求保留原文;长请求解析 JSON → 提取 model + user content
let excerpt = excerpt_text(body_bytes, &prefix);
let hash_hex = &full_hash[..config::AUDIT_HASH_HEX_BYTES.min(full_hash.len())];
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,
"excerpt": excerpt,
"body_hash": hash_hex,
"body_bytes": body_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(())
}
// ===========================================================================
// 按日查询 helper(1.0.27):管理台「小时级趋势」直接读 meta.jsonl 不聚合
// ===========================================================================
/// 列出审计根下所有有 `meta.jsonl` 的日期(字典序 = 时间序)。
///
/// 仅返回目录名符合 `YYYY-MM-DD` 形式(防止「meta 临时文件」等噪声目录干扰)。
pub fn list_days() -> Vec<String> {
let Ok(rd) = fs::read_dir(root()) else { return Vec::new() };
let mut out: Vec<String> = rd
.flatten()
.filter_map(|e| {
let name = e.file_name().to_string_lossy().to_string();
// 8 位 `YYYY-MM-DD` 校验 + 目录里必须有 meta.jsonl
if name.len() == 10
&& name.as_bytes()[4] == b'-'
&& name.as_bytes()[7] == b'-'
&& e.path().join("meta.jsonl").is_file()
{
Some(name)
} else {
None
}
})
.collect();
out.sort_by(|a, b| b.cmp(a)); // 倒序:最近日期在前
out
}
/// 读某天的 meta.jsonl,每行解析为 JSON。
///
/// **剔除 excerpt / body_hash** —— excerpt 含请求体前 100 字节(可能含敏感 prompt),
/// body_hash 不参与小时聚合;剔除省流量(约 60%)且降低敏感数据外泄面。
/// 返回每行 `{user, slot, status, tin, tout, ts, time, body_bytes}` 八个字段。
pub fn read_day(day: &str) -> Result<Vec<Value>, String> {
if day.len() != 10 || day.as_bytes()[4] != b'-' || day.as_bytes()[7] != b'-' {
return Err(format!("日期格式错(期望 YYYY-MM-DD):{day}"));
}
let path = root().join(day).join("meta.jsonl");
let file = fs::File::open(&path).map_err(|e| format!("{} 不存在或不可读:{e}", path.display()))?;
let reader = BufReader::new(file);
let mut out = Vec::new();
for line in std::io::BufRead::lines(reader).flatten() {
if line.is_empty() {
continue;
}
if let Ok(mut v) = serde_json::from_str::<Value>(&line) {
if let Some(obj) = v.as_object_mut() {
// 剔除敏感 / 不需要字段
obj.remove("excerpt");
obj.remove("body_hash");
}
out.push(v);
}
}
Ok(out)
}
// ===========================================================================
// 自服务上线以来累计 token(1.0.32 给 /api/admin/usage 的累计字段用)
// ===========================================================================
/// 全生命周期 token 累计(按 audit meta.jsonl 聚合,不依赖 shm 日桶)。
///
/// audit meta.jsonl 是真源:
/// - `tin` / `tout` 字段来自上游响应体的 usage 块(usage_filter 旁路读),
/// 与 shm `tin_total` 同源 —— 但**不受 stats 落盘/恢复影响**(audit
/// 每条都是 append-only,stats 会被重置,audit 不会)。
/// - 容量上限 `AUDIT_MAX_BYTES`(1GB),超过会从最旧整目录删。
/// 在 1GB 内所有历史都保留,**完全覆盖「自服务上线以来累计」语义**。
///
/// 读所有 `YYYY-MM-DD/meta.jsonl`,sum 出全网总 `tin` / `tout` + `requests`。
/// 失败兜底:审计目录无数据 → 返回空(不阻塞 /usage)。
pub fn all_time_total() -> Value {
let days = list_days();
if days.is_empty() {
return json!({
"requests": 0u64,
"tin": 0u64,
"tout": 0u64,
"since": Value::Null,
"days_scanned": 0u32,
});
}
let mut total_requests: u64 = 0;
let mut total_tin: u64 = 0;
let mut total_tout: u64 = 0;
for d in &days {
let Ok(rows) = read_day(d) else { continue };
for r in rows.iter() {
total_requests += 1;
total_tin += r.get("tin").and_then(|v| v.as_u64()).unwrap_or(0);
total_tout += r.get("tout").and_then(|v| v.as_u64()).unwrap_or(0);
}
}
// since = 最早一天的目录名(list_days 已按字典序排过,最小在最前)
json!({
"requests": total_requests,
"tin": total_tin,
"tout": total_tout,
"since": days.last(), // list_days 是倒序(最近在前),所以 last() 是最早的
"days_scanned": days.len(),
})
}
// ===========================================================================
// 按账号聚合(1.0.29 给 /api/v1/me 用)
// ===========================================================================
/// 单个账号最近 N 天的调用聚合(用于 `/api/v1/me` 的 `recent` 块)。
///
/// **1.0.32 改造**:增量 + 持久化。
///
/// 维护 shm `usum:<username>` 存「自服务上线以来累计 + 上次扫到的 max ts」
/// (dump 走 stats_persist 自动持久化到 llm-stats.json,**跨重启不丢**)。
/// 每次调用只扫 audit delta (`ts > last_ts`),把结果累加进 shm 缓存。
///
/// 关键:
/// - `sum.calls / sum.tin / sum.tout / sum.by_slot` 是**全时间累计**
/// (last_ts 之上 + last_ts 之下被持久化的旧 sum)——**不衰减**
/// - **24h hour / 24h totals / 7d by_slot 是滚动数据,每次重算 24h/7d 范围 audit**
/// (持久化会过期,所以不缓存;audit 容量 1GB = 14 年历史,
/// 24h/7d 范围内的数据**永远在 audit 里**,可放心重算)
///
/// 失败兜底:audit 目录无数据 / 权限问题 → 返回空统计(不让 /me 整个挂掉)。
/// shm 反序列化失败 → 重新扫全部 audit(等价于 cold start)。
pub fn user_recent(username: &str, days: u32) -> Value {
if username.is_empty() {
return empty_recent();
}
let now = util::now();
let cutoff_24h = now - 86400;
let cutoff_7d = now - (days as i64) * 86400;
// 1. 读 shm 持久化累计(仅 calls/tin/tout/by_slot/last_ts,**不**含 hour)
let mut sum = load_user_sum(username).unwrap_or_default();
let all_days = list_days();
// 2. 扫 audit delta(ts > sum.last_ts)→ 累加进 sum
for d in &all_days {
let rows = match read_day(d) {
Ok(r) => r,
Err(_) => continue,
};
for r in rows.iter() {
let u = r.get("user").and_then(|v| v.as_str()).unwrap_or("");
if u != username {
continue;
}
let ts = r.get("ts").and_then(|v| v.as_i64()).unwrap_or(0);
if ts <= sum.last_ts || ts > now {
continue;
}
let slot = r.get("slot").and_then(|v| v.as_str()).unwrap_or("-");
let status = r.get("status").and_then(|v| v.as_u64()).unwrap_or(0);
let tin = r.get("tin").and_then(|v| v.as_u64()).unwrap_or(0);
let tout = r.get("tout").and_then(|v| v.as_u64()).unwrap_or(0);
sum.calls += 1;
sum.tin += tin;
sum.tout += tout;
let entry = sum.by_slot.entry(slot.to_owned()).or_default();
entry.calls += 1;
entry.tin += tin;
entry.tout += tout;
if ts >= sum.last_ts {
sum.last_ts = ts;
sum.last_slot = slot.to_owned();
sum.last_status = status;
}
}
}
// 3. 24h hour / 24h totals / 7d by_slot 都是滚动数据 → 重算 24h/7d 范围 audit
// (不持久化,**每次现算**——audit 永远在,量小几百 KB,可接受)
let mut hour_24 = [0u64; 24];
let mut total_24h: u64 = 0;
let mut total_tin_24h: u64 = 0;
let mut total_tout_24h: u64 = 0;
let mut by_slot_7d: std::collections::BTreeMap<String, SlotStat7d> =
std::collections::BTreeMap::new();
for d in &all_days {
let rows = match read_day(d) {
Ok(r) => r,
Err(_) => continue,
};
for r in rows.iter() {
let u = r.get("user").and_then(|v| v.as_str()).unwrap_or("");
if u != username {
continue;
}
let ts = r.get("ts").and_then(|v| v.as_i64()).unwrap_or(0);
if ts > now {
continue;
}
let slot = r.get("slot").and_then(|v| v.as_str()).unwrap_or("-");
let status = r.get("status").and_then(|v| v.as_u64()).unwrap_or(0);
let tin = r.get("tin").and_then(|v| v.as_u64()).unwrap_or(0);
let tout = r.get("tout").and_then(|v| v.as_u64()).unwrap_or(0);
// 24h 滚动窗口(**左老右新**:hour_24[0] = 23h 前,hour_24[23] = 当前小时)
// age = now - ts,age_h = age / 3600 ∈ [0, 24]
// age_h = 0 → 现在
// age_h = 23 → 23h 前(窗口里最老的整小时桶)
// age_h = 24 → 正好 24h 前(cutoff 边界,clamp 到 0 桶)
if ts >= cutoff_24h {
total_24h += 1;
total_tin_24h += tin;
total_tout_24h += tout;
let age_h = ((now - ts) / 3600) as i64;
let idx = (23 - age_h).max(0) as usize;
hour_24[idx] += 1;
}
// 7d by_slot:last_status 必须用「最大 ts 的那次调用」
// —— list_days() 是倒序(今天 → 昨天),如果无脑 entry.last_status = status
// 覆盖,昨天最后几行的 status 会**覆盖**今天的最新值
// (昨天 9-14 末尾 wugui minimax 全是 429,今天 9-15 末尾是 200,
// 无脑覆盖 → 显示 429 而非 200,1.0.34 现场踩坑)。
if ts >= cutoff_7d {
let entry = by_slot_7d.entry(slot.to_owned()).or_default();
entry.calls += 1;
entry.tin += tin;
entry.tout += tout;
if ts >= cutoff_24h {
entry.calls_24h += 1;
}
// 按 ts 取 max:ts 更大才覆盖(**7d 窗口内最大 ts** 那次的 status)
if ts > entry.max_ts {
entry.max_ts = ts;
entry.last_status = status;
}
}
}
}
// 4. 写回 shm(增量缓存,下一次从 last_ts 继续累加)
save_user_sum(username, &sum);
// 5. by_slot 数组按 calls 降序;7d totals 从 by_slot_7d 求和
let mut slot_vec: Vec<(String, SlotStat7d)> = by_slot_7d.into_iter().collect();
slot_vec.sort_by(|a, b| b.1.calls.cmp(&a.1.calls));
let mut total_7d: u64 = 0;
let mut total_tin_7d: u64 = 0;
let mut total_tout_7d: u64 = 0;
for (_, st) in &slot_vec {
total_7d += st.calls;
total_tin_7d += st.tin;
total_tout_7d += st.tout;
}
json!({
"calls_24h": total_24h,
"calls_7d": total_7d,
"tin_24h": total_tin_24h,
"tout_24h": total_tout_24h,
"tin_7d": total_tin_7d,
"tout_7d": total_tout_7d,
"hour_24h": hour_24.to_vec(),
// hour_24h_labels[i] = 「i 小时前」语义:i=0 → "23h前"(最老),i=23 → "现在"
"hour_24h_labels": (0..24).map(|i| {
let age = 23 - i;
if age == 0 { "现在".to_string() }
else if age == 1 { "1h前".to_string() }
else { format!("{}h前", age) }
}).collect::<Vec<_>>(),
"by_slot": slot_vec.iter().map(|(s, st)| json!({
"slot": s,
"calls_24h": st.calls_24h,
"calls_7d": st.calls,
"tin_7d": st.tin,
"tout_7d": st.tout,
"last_status": st.last_status,
})).collect::<Vec<_>>(),
"last_at": if sum.last_ts > 0 { json!(util::fmt_time(sum.last_ts)) } else { json!(null) },
"last_slot": if sum.last_ts > 0 { json!(sum.last_slot) } else { json!(null) },
// 调试字段:运维可看出缓存命中情况(_cached.last_ts == now 表示无新请求)
"_cached": {
"last_ts": sum.last_ts,
"calls": sum.calls,
"tin": sum.tin,
"tout": sum.tout,
},
})
}
/// 持久化的每用户累计(shm `usum:<username>` 的 value,JSON 序列化)
///
/// 只存「自上次 stats_persist 恢复以来的全时间累计」,**不**存 24h/7d 滚动数据
/// (滚动窗口会衰减,持久化反而错位)。
///
/// `last_ts` 是关键:下次 user_recent 只扫 `ts > last_ts` 的 delta 行。
#[derive(Default, serde::Serialize, serde::Deserialize)]
struct UserSum {
calls: u64,
tin: u64,
tout: u64,
/// 按 slot 累计(last_ts 之上的全时间累计)
by_slot: std::collections::BTreeMap<String, SlotStat>,
last_ts: i64,
last_slot: String,
last_status: u64,
}
/// 7d 范围 by_slot 聚合(user_recent 内每次现算,**不持久化**)
#[derive(Default)]
struct SlotStat7d {
calls: u64,
calls_24h: u64,
tin: u64,
tout: u64,
/// 当前已记下的最大 ts —— last_status 仅在 ts 更大时覆盖(1.0.34 现场)
max_ts: i64,
last_status: u64,
}
/// 持久化累计的 by_slot 单 slot 值
#[derive(Default, serde::Serialize, serde::Deserialize)]
struct SlotStat {
calls: u64,
tin: u64,
tout: u64,
}
fn load_user_sum(username: &str) -> Option<UserSum> {
let (payload, _exp) = state::get(config::KEY_USER_SUM_PREFIX, username.as_bytes())?;
serde_json::from_str(&payload).ok()
}
fn save_user_sum(username: &str, sum: &UserSum) {
if let Ok(payload) = serde_json::to_string(sum) {
// exp = 0 表示永不过期(持久化累计)
state::put(
config::KEY_USER_SUM_PREFIX,
username.as_bytes(),
payload.as_bytes(),
0,
);
}
}
fn empty_recent() -> Value {
json!({
"calls_24h": 0,
"calls_7d": 0,
"tin_24h": 0,
"tout_24h": 0,
"tin_7d": 0,
"tout_7d": 0,
"hour_24h": vec![0u64; 24],
"hour_24h_labels": (0..24).map(|i| {
let age = 23 - i;
if age == 0 { "现在".to_string() }
else if age == 1 { "1h前".to_string() }
else { format!("{}h前", age) }
}).collect::<Vec<_>>(),
"by_slot": Vec::<Value>::new(),
"last_at": null,
"last_slot": null,
})
}
+123
View File
@@ -0,0 +1,123 @@
//! LLM 上游持久化模型(`llm-upstreams.json`:以 slot 名为 key)。
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use crate::config::EXHAUST_STATUS_DEFAULT;
/// 上游表:`slot` 就是 LLM 客户端 URL 的第一段路径:`/openai/v1/chat/completions`
/// 里的 `openai`。**刻意不按 body 里的 `model` 字段路由**——请求体要到
/// content 阶段才读得到,而 access 阶段(转发决策点)读不到,
/// 按 model 分流就得放弃 `proxy_pass` 自己实现 upstream,代价差一个数量级。
pub type UpstreamTable = BTreeMap<String, Upstream>;
/// 单个上游账号:一把上游真 Key + 它的额度重置周期。
///
/// 一个 `slot`(一家厂商)可挂多个账号——不同账号通常是同一厂商的多把免费/付费 Key,
/// 各自有独立的周期性额度。网关按「用户 key → 上游账号」做粘性路由,账号额度耗尽时
/// 自动切到同厂商下一个可用账号(见 `upstreams::pick_account` 与 `handlers` 的耗尽标记)。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpstreamAccount {
/// 完整的 Authorization 头值,如 `Bearer sk-xxx`
pub auth: String,
/// 备注(区分多账号用,如 `minimax-周额度` / `minimax-4h额度`)
#[serde(default)]
pub note: String,
/// **历史字段(1.0.44 起不参与路由)**:原为「额度重置周期(秒)」,供
/// `cool_until_until` 天锚定边界计算——该计算两次算错锚点(见 config.rs 旧注释),
/// 已由「指数退避 + 真实请求探测」闭环取代。字段仍随 JSON 读写(存量兼容、
/// view 回显),但填什么都不再影响冷却与路由;管理台表单已移除该输入。
#[serde(default)]
pub resets: Vec<i64>,
}
/// 单个 LLM 上游。
///
/// 字段名与旧版 `data/llm-upstreams.json` **逐字对应**,以便新版直接接管旧数据文件。
/// 旧文件只有顶层 `auth`(单账号),新版通过 `effective_accounts()` 自动合成单账号,
/// 因此存量数据零改动即可继续工作。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Upstream {
/// OpenAI 兼容协议的真实上游基址(含完整路径段)。
///
/// 例:`https://api.deepseek.com/v1` / `https://open.bigmodel.cn/api/coding/paas/v4`
/// / `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`。
/// 各厂商路径段完全不同,**网关只原样把它拼到 SDK 转发的余下路径前**,
/// 不做任何 `/v1` 猜测(见 `upstreams::base_url` 与 `llm::join_target`)。
pub base: String,
/// Anthropic 协议的真实上游基址(如 `https://api.deepseek.com/anthropic` /
/// `https://open.bigmodel.cn/api/anthropic` / `https://token-plan.../apps/anthropic`)。
///
/// 各家与 OpenAI 路径**完全独立、无法推导**(阿里是 `/apps/anthropic`、
/// 智谱是 `/api/anthropic`、deepseek/minimax 是 `/anthropic`),所以必须显式配。
/// 旧数据只有 `base` 时由 `upstreams::derive_anthropic` 兜底派生(仅对
/// deepseek/minimax 这类「`base` 末尾 `/v1` 或根路径」的厂商正确)。
#[serde(default)]
pub base_anthropic: String,
/// 该上游**挂载的模型名清单**(如 `deepseek-chat` / `deepseek-reasoner`)。
///
/// 一个上游(一家厂商)通常挂多个模型,客户端要能先"列出有什么"再选。
/// 这里只是网关侧的**清单**,用于 `GET /v1/models` 之类的模型发现;
/// 转发本身仍按 URL 里的 slot 走,**不校验 model 字段**(access 阶段读不到 body)。
/// 留空表示"清单未知"——模型发现接口就不列该上游的模型,但转发照常可用。
#[serde(default)]
pub models: Vec<String>,
/// 关闭后该 slot 立即停止转发(保留配置便于恢复)
#[serde(default = "default_true")]
pub enabled: bool,
#[serde(default)]
pub note: String,
#[serde(default)]
pub created_at: i64,
/// 多账号列表。空时由 legacy `auth` 合成单账号(向后兼容旧数据)。
#[serde(default)]
pub accounts: Vec<UpstreamAccount>,
/// 上游级「额度耗尽」探测配置(同一厂商所有账号共享错误形态)。
///
/// 命中下列任一即判该账号额度耗尽、进入冷却:上游返回这些 HTTP 状态码,
/// **或** 响应体(流式也能扫,见 `usage_filter`)含任一 `exhaust_markers` 子串。
/// 空 = 用 `config::EXHAUST_STATUS_DEFAULT`(默认 `[402, 429, 403]`)。
#[serde(default)]
pub exhaust_status: Vec<i64>,
/// 响应体「额度耗尽」标记子串(大小写敏感,逐字节匹配)。
/// 例:MiniMax 余额不足可配 `"status_code":1004` 或 `余额不足`。
#[serde(default)]
pub exhaust_markers: Vec<String>,
/// 兼容旧版单 key 数据:旧 `auth` 字段。
/// `accounts` 非空时忽略;`accounts` 空且 `auth` 非空 → 合成单账号(resets 空 = 不自动切换)。
#[serde(default)]
pub auth: String,
}
fn default_true() -> bool {
true
}
impl Upstream {
/// 实际生效的账号列表。
///
/// `accounts` 非空 → 用它;否则 `auth` 非空 → 合成单账号(resets 空,等同无限额度,
/// 不会因「耗尽」被冷却,单账号时自然也不存在可切换对象)。两者皆空 → 空表(上游不可用)。
pub fn effective_accounts(&self) -> Vec<UpstreamAccount> {
if !self.accounts.is_empty() {
self.accounts.clone()
} else if !self.auth.is_empty() {
vec![UpstreamAccount {
auth: self.auth.clone(),
note: String::new(),
resets: Vec::new(),
}]
} else {
Vec::new()
}
}
/// 生效的「额度耗尽」状态码清单(空 → 默认 `[402, 429, 403]`)。
pub fn effective_exhaust_status(&self) -> Vec<i64> {
if self.exhaust_status.is_empty() {
EXHAUST_STATUS_DEFAULT.to_vec()
} else {
self.exhaust_status.clone()
}
}
}
+382
View File
@@ -0,0 +1,382 @@
//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。
//!
//! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、
//! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。
//!
//! ```text
//! ust:<username> → <日窗id>:<今日数>:<累计数>:<最近调用时间戳>
//! ums:<username>:<slot> → 同 上
//! ```
//!
//! 本模块是**业务解读层**:键前缀(`ust:` / `ums:` / `utt:` / `utms:` /
//! `ud:` / `udu:` / `uds:`)在这里与内核记账原语(`ipass_core::usage`)组合。
//! 原语本身无任何业务语义——「去掉 LLM 还要(趋势图要给 apix 用)、
//! 去掉 apix 还要(趋势图要给 LLM 用)」⇒ 原语放内核,口径与聚合放本 crate。
//!
//! ## 口径:只统计"真的转发出去"的请求
//!
//! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**,
//! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同——
//! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义;
//! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。
//!
//! ## token 级计量(2026-09-12 起)
//!
//! token 数来自上游响应体里的 `usage` 字段:`usage_filter` 模块在 **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 ipass_core::{state, usage, util};
// 内核记账类型与读数结构(re-export 方便 gateway / api 组合使用)
pub use ipass_core::usage::{TokenUsage, Usage};
/// 一个账号的用量 + 其下每个上游的明细
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)>,
}
// ===========================================================================
// 写
// ===========================================================================
/// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。
pub fn record(username: &str, slot: &str, now: i64) {
if username.is_empty() || slot.is_empty() {
return;
}
let day = util::day_id(now);
usage::bump(KEY_UST_PREFIX, username, day, now);
usage::bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now);
// 日桶:趋势图数据源(请求维度)。三个维度各写一次,键名带日窗 id
let delta = usage::DayBucket { requests: 1, ..Default::default() };
usage::bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta, TREND_KEEP_SECS);
usage::bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta, TREND_KEEP_SECS);
usage::bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta, TREND_KEEP_SECS);
// 顺手看一眼要不要把统计落盘(默认 60 秒一次,间隔内只是一次原子比较)。
// 挂在这里而不是各调用点,是因为本函数是 LLM 与 apix **两方唯一的记账入口**
// (apix 复用同一套统计,slot 带 `api/` 前缀)——以后再加一个租户也不会漏。
crate::stats_persist::maybe_dump();
}
/// 累加一次真实 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);
usage::bump_t(KEY_UTT_PREFIX, username, tin, tout, day, now);
usage::bump_t(KEY_UTMS_PREFIX, &format!("{username}:{slot}"), tin, tout, day, now);
// 日桶:趋势图数据源(token 维度)。与 record 写的是同一批键,字段互补
let delta = usage::DayBucket { tin: tin as i64, tout: tout as i64, ..Default::default() };
usage::bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta, TREND_KEEP_SECS);
usage::bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta, TREND_KEEP_SECS);
usage::bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta, TREND_KEEP_SECS);
}
/// 删除账号时清理其全部用量键(`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);
usage::read(KEY_UST_PREFIX, username, day)
}
/// 单账号 × 上游明细,按 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, _)| {
let slot = name.strip_prefix(&prefix)?.to_owned();
Some((slot, usage::read(KEY_UMS_PREFIX, &name, 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, _) 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(), usage::read(KEY_UMS_PREFIX, &name, 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, _)| {
let usage = usage::read(KEY_UST_PREFIX, &username, 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, _) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let u = usage::read(KEY_UMS_PREFIX, &name, 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 (name, _) in state::iter_prefix(KEY_UST_PREFIX) {
sum.merge(&usage::read(KEY_UST_PREFIX, &name, day));
}
sum
}
/// 单账号 token 读数
pub fn tokens_user(username: &str, now: i64) -> TokenUsage {
let day = util::day_id(now);
usage::read_t(KEY_UTT_PREFIX, username, day)
}
/// 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, _) in state::iter_prefix(KEY_UTT_PREFIX) {
let t = usage::read_t(KEY_UTT_PREFIX, &name, day);
by_user.insert(name, t);
}
let mut by_slot: BTreeMap<String, TokenUsage> = BTreeMap::new();
let mut by_pair: BTreeMap<String, BTreeMap<String, TokenUsage>> = BTreeMap::new();
for (name, _) in state::iter_prefix(KEY_UTMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let t = usage::read_t(KEY_UTMS_PREFIX, &name, 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: &[usage::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 + 账号数 + 上游数) 次查表,且不随历史增长。
///
/// 注意:调用方(gateway 的 `/api/admin/trend`)要先给名册——日桶键里
/// 带日窗 id,**扫不出来**,账号/上游名单由 users / upstreams / apix 提供。
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<usage::DayBucket> =
ids.iter().map(|d| usage::day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect();
let by_user: Vec<Value> = users
.iter()
.map(|u| {
let series: Vec<usage::DayBucket> = ids
.iter()
.map(|d| usage::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<usage::DayBucket> = ids
.iter()
.map(|d| usage::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
}
+463
View File
@@ -0,0 +1,463 @@
//! 运行期统计的**落盘 / 恢复**:让用量统计与趋势图熬过一次重启。
//!
//! ## 为什么需要它(1.0.18 之前的实际故障)
//!
//! 共享内存是 nginx 每进程启动时 `mmap` 出来的匿名区,**进程退出即消失**。
//! 而用量统计(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`/`uda:`/`uex:`)
//! 全部只活在共享内存里 —— 于是「每次发版 = 统计与趋势清零」,
//! 用量页与趋势图在发版后从 0 重新长起来。
//!
//! 不引入数据库(项目红线),做法就是**一个 JSON 快照**,与
//! `users.json`/`llm-upstreams.json` 同级落在 `data/` 下;`data/` 是宿主挂载卷,
//! 容器重建也不丢。
//!
//! ## 两个落盘点(互补,不是二选一)
//!
//! | 触发 | 时机 | 覆盖场景 |
//! | --- | --- | --- |
//! | **worker 退出钩子** | `exit_process`(gateway 注册) | 发版 / `docker stop` / `nginx -s quit` ——**零丢失** |
//! | **周期性节流落盘** | log 阶段记账后,默认 60 秒一次 | SIGKILL / OOM / 断电 —— 最多丢一个周期 |
//!
//! 退出钩子是主力:`docker stop` 发的是镜像里声明的 `STOPSIGNAL=SIGQUIT`
//! (优雅停机),`SIGTERM` 也走同一条 worker 退出路径,两者都会调到 `exit_process`。
//! 只有 `SIGKILL` 绕过它,那由周期落盘兜住。
//!
//! ## 恢复语义:**只在键不存在时写入**(put-if-absent)
//!
//! 三个性质一次拿到:
//! * 重启后共享内存是空的 → 所有键都「不存在」→ 全量恢复;
//! * 多 worker 各跑一遍 `init_process` → 第二个起键已存在 → 跳过,**天然幂等**,
//! 不会把计数恢复成 N 倍;
//! * 恢复期间若有新请求已经把某个键写活 → **不覆盖**,宁可少恢复一条,
//! 也不打死刚产生的新数据。
//!
//! 已过期(`exp <= now`)的键不恢复:日桶的 90 天保留期不能因为一次重启被续命。
//!
//! 恢复结果(恢复了多少 / 快照里有多少)**发布到共享内存**(`spr:last`),
//! 而不是放进程内静态量:`init_process` 每 worker 跑一次,只有第一个 worker
//! 真的在写键,其余全部跳过 —— 用静态量的话 `/api/admin/stats/persist` 落到哪个
//! worker 就报哪个数,运维看到的是随机值。
//!
//! **同一类错误在落盘侧也有一份**:`maybe_dump` 由记账路径驱动、每 worker 独立
//! 计数,所以「上次落盘时刻」同样是每 worker 各一个。1.0.18 首次线上验证就撞上
//! 了 —— 日志里 10 次落盘、状态页却说「本进程还没落过」。解法一样:时刻存
//! `spd:last`(见 `publish_dump`);顺带用它把落盘节流从「每 worker 一次」收敛成
//! 「全局一次」(见 `maybe_dump` 的慢路径)。
//!
//! ## 刻意**不**持久化的东西
//!
//! * **配置类** `up:` / `upa:` / `upe:` / `ax:` / `ukey:` / `sub:` —— 它们各自有
//! 数据文件(`data/*.json`),重启时由 `reload_shm` 装载。再存一份会出现两个真源,
//! 「文件是新的、快照是旧的」时互相覆盖,属于自找的故障。
//! * **`ukb:`**(用户 key → 上游账号粘性)—— 设计上就是重启即重绑(见常量注释)。
//! * **`spr:` / `spd:`**(本模块自己的「上次恢复」/「上次落盘」记录)—— 都是过程
//! 元信息,不是统计量,持久化它们只会自我引用。**只在共享内存里**,为的是让
//! 多 worker 报同一份结果。
//! * **内核的** `st:`(配额)/ `rl:`(限流)/ `fail:` / `sess:` —— 语义上重启清零更安全
//! (多送一点额度,好过把用户锁死),且属内核状态,不由本插件代管。
//!
//! ## 容量
//!
//! 一个键一行;键数 = 账号数 × slot 数 + 90 天 × (1 + 账号数 + slot 数 + 账号 × 上游数)。
//! 十来个账号的规模下是几十 KB,写好一次几毫秒 —— 与「每请求都写」的量级完全不同。
//! 详细口径与运维见 `docs/llm/STATS_PERSISTENCE.md`。
use std::collections::BTreeMap;
use std::path::PathBuf;
use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use ipass_core::{state, store, util};
use crate::config::{
KEY_SPD_PREFIX, KEY_SPR_PREFIX, KEY_UDAY_ACCT_PREFIX, KEY_UDAY_PREFIX,
KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UEX_PREFIX, KEY_UH_PREFIX, KEY_UMS_PREFIX,
KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, KEY_USER_SUM_PREFIX, STATS_FILE_NAME,
STATS_PERSIST_INTERVAL_DEFAULT, STATS_SNAPSHOT_VERSION,
};
/// 参与持久化的共享内存前缀(一律以 `:` 结尾,且 `:` 不出现在前缀内部)。
///
/// 顺序无关,但保持一致(状态接口按此顺序统计 key 数)。
/// 排除项的理由见模块注释「刻意不持久化的东西」。
const PREFIXES: &[&[u8]] = &[
KEY_UST_PREFIX, // 账号维度请求数
KEY_UMS_PREFIX, // 账号 × 上游 请求数
KEY_UTT_PREFIX, // 账号维度 token
KEY_UTMS_PREFIX, // 账号 × 上游 token
KEY_UDAY_PREFIX, // 全局日桶(趋势图总览)
KEY_UDAY_USER_PREFIX, // 按账号日桶
KEY_UDAY_SLOT_PREFIX, // 按上游日桶
KEY_UDAY_ACCT_PREFIX, // 按上游账号日桶(「各 Key 负载」)
KEY_UEX_PREFIX, // 账号额度耗尽次数日桶
KEY_UH_PREFIX, // 上游健康展示缓存
KEY_USER_SUM_PREFIX, // 每用户聚合缓存(1.0.32 /api/v1/me 增量)
];
/// 快照值里的分隔符:`<payload>\x1f<exp>`。
///
/// 复用共享内存的 `VAL_SEP`(0x1f)而不是自定义一个:语义完全一样
/// (payload 里不会出现该字节,因为内核写共享内存时就是这么切的),
/// 少一个常量少一处不一致。JSON 序列化时 serde 会把它转义成 `\u001f`。
const SNAP_SEP: char = '\u{1f}';
/// 落盘间隔(秒);`0` = 关闭周期落盘(只保留退出钩子那一次)。
/// 配置阶段由 `ipass_stats_persist` 设置一次,之后只读。
static INTERVAL: AtomicI64 = AtomicI64::new(STATS_PERSIST_INTERVAL_DEFAULT);
/// 本 worker 上次落盘时刻(秒);0 = 本 worker 还没落过盘 → 第一次调用就落。
///
/// 这只是**快路径缓存**(无锁原子比较,热路径几乎免费),**不是真源** ——
/// 真源是共享内存 `spd:last`(跨 worker 一致),见 `publish_dump` / `read_dump_at`。
/// 两者配合的理由见 `maybe_dump`。
static LAST_DUMP_AT: AtomicI64 = AtomicI64::new(0);
/// 单飞标记:并发请求同时到点,只放一个进去落盘。
/// 注意这是**每 worker** 的静态量(跨 worker 不互斥)——多个 worker 同时落盘
/// 只是白写几次同样的内容,`rename` 是原子的,不会有半个文件被人读到。
static DUMPING: AtomicBool = AtomicBool::new(false);
#[derive(Debug, Serialize, Deserialize)]
struct Snapshot {
version: i64,
saved_at: i64,
#[serde(default)]
saved_at_text: String,
#[serde(default)]
keys: BTreeMap<String, String>,
}
// ===========================================================================
// 配置
// ===========================================================================
/// `ipass_stats_persist <秒>`:周期落盘间隔。`0` = 只靠 worker 退出钩子。
pub fn set_interval(secs: i64) {
INTERVAL.store(secs.max(0), Ordering::Relaxed);
}
pub fn interval() -> i64 {
INTERVAL.load(Ordering::Relaxed)
}
fn path() -> PathBuf {
store::path_in_data(STATS_FILE_NAME)
}
// ===========================================================================
// 落盘
// ===========================================================================
/// 原子写:先写 `<path>.tmp.<pid>` 再 `rename`。
///
/// 不复用 `store::write_json` 的原因:它用固定的 `<path>.tmp`,多 worker 同时落盘
/// 会互相踩临时文件(一个 rename 走了,另一个还在往里写同名文件)。
/// 带 pid 后缀后各写各的,`rename` 本身是原子的,最后一个赢 —— 而内容本来就
/// 只是「同一份共享内存的近似快照」,谁赢都对。
///
/// 也**不复用** `state::file_lock()`:那道锁是给「读文件→改→写文件」防丢失用的,
/// 本函数是纯覆盖写、不读旧值,拿锁只会在退出路径上增加卡死风险。
fn write_atomic(path: &PathBuf, text: &str) -> Result<(), String> {
let tmp = PathBuf::from(format!("{}.tmp.{}", path.display(), std::process::id()));
std::fs::write(&tmp, text.as_bytes()).map_err(|e| {
let _ = std::fs::remove_file(&tmp);
format!("写入 {} 失败:{e}", tmp.display())
})?;
std::fs::rename(&tmp, path).map_err(|e| {
let _ = std::fs::remove_file(&tmp);
format!("重命名到 {} 失败:{e}", path.display())
})
}
/// 立刻落盘(不看间隔)。返回写入的键数。
///
/// `reason` 只进日志,用于事后分辨这次是谁触发的(`worker-exit` / `periodic` / `admin`)。
pub fn dump_now(reason: &str) -> Result<usize, String> {
let now = util::now();
let mut keys: BTreeMap<String, String> = BTreeMap::new();
for p in PREFIXES {
// 前缀都是 ASCII 字面量,from_utf8 不会失败
let Some(pfx) = core::str::from_utf8(p).ok() else {
continue;
};
for (name, payload, exp) in state::iter_prefix_ex(p) {
// 已过期的键不带回:日桶的 90 天保留期不能靠重启续命
if exp != 0 && exp <= now {
continue;
}
keys.insert(format!("{pfx}{name}"), format!("{payload}{SNAP_SEP}{exp}"));
}
}
let snap = Snapshot {
version: STATS_SNAPSHOT_VERSION,
saved_at: now,
saved_at_text: util::fmt_time(now),
keys,
};
let text = serde_json::to_string(&snap).map_err(|e| format!("序列化失败:{e}"))?;
let n = snap.keys.len();
let p = path();
write_atomic(&p, &text)?;
// 落盘成功才推进时间戳:失败时下次请求会立刻重试,而不是等满一个周期。
// 静态量是本 worker 的快路径缓存;共享内存那份是跨 worker 的真源(供上报 + 节流)。
LAST_DUMP_AT.store(now, Ordering::Relaxed);
publish_dump(now);
util::log_info(&format!(
"[stats] 落盘 {n} 键({} B,{reason})-> {}",
text.len(),
p.display()
));
Ok(n)
}
/// 把「上次落盘时刻」发布到共享内存,供**所有** worker 一致地上报与节流。
///
/// 与 `publish_restore` 是同一类问题的同一解法(见 `KEY_SPD_PREFIX` 注释)。
/// 与恢复侧唯一不同:落盘**不需要累加**,只要记住最近一次的时刻,
/// 所以取 `max` 而不是相加。
///
/// 这里是「读-改-写」,没有原子性保证:两个 worker 同一瞬间落盘时,理论上可能出现
/// 后写入的是稍早的时刻(差 ≤1 秒)。对本用途(状态页展示 + 分钟级节流)无影响,
/// 不值得为它引入跨 worker 的 CAS —— `state` 层本来也没有这个原语。
fn publish_dump(at: i64) {
let prev = read_dump_at();
let v = at.max(prev).to_string();
if !state::put(KEY_SPD_PREFIX, b"last", v.as_bytes(), 0) {
util::log_err("[stats] 发布落盘时刻到共享内存失败(仅影响状态展示与节流)");
}
}
/// 读回「上次落盘时刻」(跨 worker 共享)。没有记录则 0。
fn read_dump_at() -> i64 {
state::get(KEY_SPD_PREFIX, b"last")
.and_then(|(payload, _)| payload.trim().parse::<i64>().ok())
.unwrap_or(0)
}
/// 按间隔节流落盘。**由记账路径每次请求调用一次**(见 `stats::record`)。
///
/// 两级判断,热路径代价仍是一次原子比较:
/// * **快路径**(绝大多数请求走这里):本 worker 自己在 `iv` 秒内落过 → 直接返回;
/// * **慢路径**(每 worker 每 `iv` 秒最多进一次):本 worker 没落过,但**别的** worker
/// 可能刚落过 —— 读一次 `spd:last` 确认。读到的时刻回填本地缓存,
/// 于是下一个 `iv` 秒内的请求又全部走快路径。
///
/// 慢路径那一下把落盘从「8 个 worker 各写一遍同一个文件」收敛成「全局每 `iv` 秒一次」,
/// 同时也让状态页读到的时刻与节流依据是同一份数据,不会自相矛盾。
///
/// 间隔设为 0 = 关闭周期落盘,此时这里退化为纯判断。
pub fn maybe_dump() {
let iv = interval();
if iv <= 0 {
return;
}
let now = util::now();
let local = LAST_DUMP_AT.load(Ordering::Relaxed);
if local != 0 && now - local < iv {
return;
}
let shared = read_dump_at();
if shared != 0 && now - shared < iv {
LAST_DUMP_AT.store(shared, Ordering::Relaxed); // 回填缓存,别每次请求都读共享内存
return;
}
if DUMPING.swap(true, Ordering::Acquire) {
return; // 同 worker 内已有一个在落盘
}
let r = dump_now("periodic");
DUMPING.store(false, Ordering::Release);
if let Err(e) = r {
util::log_err(&format!("[stats] 周期落盘失败:{e}"));
}
}
// ===========================================================================
// 恢复
// ===========================================================================
/// 拆快照值 `payload \x1f exp`。
///
/// 用 `rposition` 与内核 `split_value` 同款理由:`exp` 是 ASCII 数字串、
/// 不含分隔符,所以**最后一个**分隔符才是真边界。
fn split_value(v: &str) -> Option<(&str, i64)> {
let i = v.rfind(SNAP_SEP)?;
let exp = v[i + SNAP_SEP.len_utf8()..].parse::<i64>().ok()?;
Some((&v[..i], exp))
}
/// 把本次恢复结果发布到共享内存,供**所有** worker 一致地报告(见 `KEY_SPR_PREFIX` 注释)。
///
/// 两个要点:
/// * `restored == 0` 的 worker **不写** —— 它只是「来晚了、键已存在」的观察者,
/// 用自己的 0 覆盖真实结果就等于把这次恢复从记录里抹掉。
/// * 已有记录时**累加**而不是覆盖:master 是顺序 fork 的,但两个 worker 的
/// `init_process` 仍可能重叠,各恢复一半(put-if-absent 决定谁抢到哪批键)。
/// 累加 + `max(total)` 才能拼出完整结果。
fn publish_restore(at: i64, restored: usize, total: usize) {
if restored == 0 {
return;
}
let (prev_at, prev_ok, prev_total) = match state::get(KEY_SPR_PREFIX, b"last") {
Some((payload, _)) => parse_restore(&payload).unwrap_or((0, 0, 0)),
None => (0, 0, 0),
};
let v = format!(
"{}{SNAP_SEP}{}{SNAP_SEP}{}",
at.max(prev_at),
prev_ok + restored,
prev_total.max(total)
);
if !state::put(KEY_SPR_PREFIX, b"last", v.as_bytes(), 0) {
util::log_err("[stats] 发布恢复记录到共享内存失败(仅影响状态展示)");
}
}
/// 解析 `spr:last` 的 payload:`<时刻> \x1f <恢复键数> \x1f <快照键数>`。
fn parse_restore(payload: &str) -> Option<(i64, usize, usize)> {
let mut it = payload.split(SNAP_SEP);
let at = it.next()?.parse::<i64>().ok()?;
let ok = it.next()?.parse::<usize>().ok()?;
let total = it.next()?.parse::<usize>().ok()?;
Some((at, ok, total))
}
/// 读回「上次恢复」记录:`(恢复时刻, 恢复键数, 快照键数)`。没有记录则全 0。
fn read_restore() -> (i64, usize, usize) {
state::get(KEY_SPR_PREFIX, b"last")
.and_then(|(payload, _)| parse_restore(&payload))
.unwrap_or((0, 0, 0))
}
/// worker 启动时把快照灌回共享内存。每个 worker 都会调一次(幂等,见模块注释)。
///
/// 任何异常都只降级:审计/统计都是旁路,绝不能让 worker 起不来。
pub fn restore() {
let p = path();
let text = match std::fs::read_to_string(&p) {
Ok(t) => t,
// 首次部署本来就没有快照,不算错误
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return,
Err(e) => {
util::log_err(&format!("[stats] 读取快照失败 {}:{e}", p.display()));
return;
}
};
if text.trim().is_empty() {
return;
}
let snap: Snapshot = match serde_json::from_str(&text) {
Ok(s) => s,
Err(e) => {
// 解析不了就**改名留档**再走:否则第一个请求到点就会用「空共享内存」
// 覆盖掉这份文件,把唯一的副本抹掉,连现场都没得查。
let bad = PathBuf::from(format!("{}.bad", p.display()));
let moved = std::fs::rename(&p, &bad);
util::log_err(&format!(
"[stats] 快照解析失败({e}),已{},本次不恢复统计",
match moved {
Ok(()) => format!("改名留档到 {}", bad.display()),
Err(me) => format!("尝试改名留档但失败({me})"),
}
));
return;
}
};
if snap.version != STATS_SNAPSHOT_VERSION {
util::log_err(&format!(
"[stats] 快照版本 {} 与当前 {} 不符,不恢复(宁可从零开始)",
snap.version, STATS_SNAPSHOT_VERSION
));
return;
}
let now = util::now();
let total = snap.keys.len();
let mut restored = 0usize;
for (k, v) in &snap.keys {
let kb = k.as_bytes();
let Some(pfx) = PREFIXES.iter().find(|p| kb.starts_with(p)) else {
continue; // 不在白名单(旧版本写的 / 手改的)→ 忽略
};
let Some((payload, exp)) = split_value(v) else {
continue;
};
if exp != 0 && exp <= now {
continue; // 已过期
}
let name = &kb[pfx.len()..];
if name.is_empty() {
continue;
}
if state::get(pfx, name).is_some() {
continue; // 已被新请求写活 → 不覆盖
}
if state::put(pfx, name, payload.as_bytes(), exp) {
restored += 1;
}
}
publish_restore(now, restored, total);
util::log_notice(&format!(
"[stats] 已从快照恢复 {restored}/{total} 键({})",
p.display()
));
}
// ===========================================================================
// 状态(管理接口)
// ===========================================================================
/// `/api/admin/stats/persist` 的响应体:快照文件状态 + 当前共享内存键数。
///
/// 「文件里有多少键」与「共享内存里现在有多少键」分开给:两者长期接近说明
/// 落盘正常;文件远小于内存 = 周期落盘没跑(或刚重启还没到点)。
pub fn status() -> Value {
let p = path();
let text = std::fs::read_to_string(&p).ok();
let (saved_at, saved_at_text, file_keys) = match text.as_deref().map(serde_json::from_str::<Snapshot>) {
Some(Ok(s)) => (s.saved_at, s.saved_at_text, s.keys.len()),
_ => (0, String::new(), 0),
};
let file_bytes = std::fs::metadata(&p).map(|m| m.len()).unwrap_or(0);
let live: usize = PREFIXES
.iter()
.map(|pfx| {
let now = util::now();
state::iter_prefix_ex(pfx)
.into_iter()
.filter(|(_, _, exp)| *exp == 0 || *exp > now)
.count()
})
.sum();
let (restore_at, restore_ok, restore_total) = read_restore();
// 读共享内存而不是本 worker 静态量:落盘是每 worker 各自发生的,
// 用静态量会出现「日志明明落了 10 次、状态页却说本进程还没落过」(见 KEY_SPD_PREFIX)。
let last_dump = read_dump_at();
json!({
"file": p.display().to_string(),
"file_exists": text.is_some(),
"file_bytes": file_bytes,
"file_keys": file_keys,
"saved_at": saved_at,
"saved_at_text": saved_at_text,
"live_keys": live,
"interval_secs": interval(),
"last_dump_at": last_dump,
"last_dump_text": if last_dump > 0 { util::fmt_time(last_dump) } else { String::new() },
"restored_at": restore_at,
"restored_keys": restore_ok,
"restore_total": restore_total,
})
}
+35
View File
@@ -0,0 +1,35 @@
//! 上游表的文件读写(复用内核 store 的原子写 + 全局文件写锁)。
//!
//! `data/llm-upstreams.json` 含上游真实 API Key,**敏感级别等同 `users.json`**。
use std::path::PathBuf;
use ipass_core::{state, store};
use crate::models::UpstreamTable;
fn upstreams_path() -> PathBuf {
store::path_in_data("llm-upstreams.json")
}
pub fn read_upstreams() -> UpstreamTable {
store::read_json(&upstreams_path(), UpstreamTable::new())
}
pub fn write_upstreams(data: &UpstreamTable) -> Result<(), String> {
store::write_json(&upstreams_path(), data)
}
/// 加锁「读-改-写」上游表。
///
/// 闭包返回 `Ok(T)` 表示提交,`Err(msg)` 表示放弃(不写盘)。
pub fn update_upstreams<T, F>(f: F) -> Result<T, String>
where
F: FnOnce(&mut UpstreamTable) -> Result<T, String>,
{
let _guard = state::file_lock().ok_or("内部错误:状态锁不可用")?;
let mut data = read_upstreams();
let out = f(&mut data)?;
write_upstreams(&data)?;
Ok(out)
}
File diff suppressed because it is too large. Load diff
+358
View File
@@ -0,0 +1,358 @@
//! 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`。
//! * **流量识别**:`loc::enabled(r, Switch::Llm)` 为真才建窗口——
//! 管理台 / 子域名转发不经过扫描,零开销。(插件化改造点:原来直接读
//! gateway 私有的 `ModuleConfig.llm`,现改走内核 loc 契约。)
//! * **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};
use ipass_core::loc::{self, Switch};
use ipass_core::plugin;
use crate::llm;
use crate::upstreams;
/// 尾部窗口容量: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 上,请求池分配、随请求回收)
// ===========================================================================
/// 内联缓存「额度耗尽」探测配置的上限(避免每 chunk 查 shm,且不引入堆分配/泄漏)。
/// marker 最长 128 字节、最多 4 个,超出部分截断/忽略(v1 够用,详见 `take_exhausted`)。
const MAX_MARKERS: usize = 4;
const MARKER_CAP: usize = 128;
#[repr(C)]
struct ScanCtx {
tail: [u8; TAIL_CAP],
len: usize,
tin: u64,
tout: u64,
/// 响应体命中「额度耗尽」标记(流式也能扫到,log 阶段据此标记账号冷却)
exhausted: bool,
/// 内联缓存的耗尽探测配置(首次扫描时从 `upe:<slot>` 读入,随请求池整体回收)
status: [i64; 8],
status_n: usize,
markers: [[u8; MARKER_CAP]; MAX_MARKERS],
marker_len: [usize; MAX_MARKERS],
marker_n: usize,
}
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;
}
}
}
}
/// ctx_index 由 gateway 在 postconfiguration 前注入(见 `ipass_core::plugin`)。
/// 未注入(usize::MAX)说明装配异常,返回空指针让调用方放弃计量——
/// **绝不**拿 usize::MAX 去做 `r->ctx.add()`,那是越界写。
unsafe fn ctx_slot(r: *mut ngx_http_request_t) -> *mut *mut ScanCtx {
let idx = plugin::ctx_index();
if idx == usize::MAX {
return core::ptr::null_mut();
}
// SAFETY: idx 是 gateway 模块的 ctx_index,r->ctx 数组必然覆盖该下标
unsafe { (*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 才扫:管理台 / 子域名转发零开销直过
if !loc::enabled(r, Switch::Llm) {
return;
}
let slot = ctx_slot(r);
if slot.is_null() {
return;
}
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;
// 首次扫描:从 `upe:<slot>` 读入耗尽探测配置(状态码 + 响应体标记)
let c = &mut *ctx;
if let Some(s) = llm::slot_of(r) {
let (status, markers) = upstreams::read_upe(&s);
let n = status.len().min(c.status.len());
c.status[..n].copy_from_slice(&status[..n]);
c.status_n = n;
let m = markers.len().min(MAX_MARKERS);
for i in 0..m {
let bytes = markers[i].as_bytes();
let cap = bytes.len().min(MARKER_CAP);
if cap > 0 {
c.markers[i][..cap].copy_from_slice(&bytes[..cap]);
c.marker_len[i] = cap;
}
}
c.marker_n = m;
}
}
// ctx 此刻一定非 null 且指向有效内存;用 &mut 引用操作,避免裸指针隐式自动取引用报错
let c = &mut *ctx;
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);
c.append(data);
// 扫「额度耗尽」标记(逐字节子串匹配,流式响应也能命中)
if !c.exhausted && c.marker_n > 0 {
for i in 0..c.marker_n {
let ml = c.marker_len[i];
if ml == 0 {
continue;
}
let needle = &c.markers[i][..ml];
if data.len() >= needle.len()
&& data.windows(needle.len()).any(|w| w == needle)
{
c.exhausted = true;
break;
}
}
}
}
if (*buf).last_buf() != 0 {
c.finish();
}
}
}
/// log 阶段读取本请求抓到的 token 数(ctx 随请求池整体回收,无需清理钩子)。
pub fn take(r: *mut ngx_http_request_t) -> (u64, u64) {
if r.is_null() {
return (0, 0);
}
unsafe {
let slot = ctx_slot(r);
if slot.is_null() {
return (0, 0);
}
let c = *slot;
if c.is_null() {
(0, 0)
} else {
((*c).tin, (*c).tout)
}
}
}
/// log 阶段读取本请求响应体是否命中「额度耗尽」标记。
///
/// 与 [`take`] 同生命周期:ctx 随请求池回收,无需清理钩子。
/// 仅 LLM location 的 body filter 会置位;其它请求恒为 false(靠状态码判定兜底)。
pub fn take_exhausted(r: *mut ngx_http_request_t) -> bool {
if r.is_null() {
return false;
}
unsafe {
let slot = ctx_slot(r);
if slot.is_null() {
return false;
}
let c = *slot;
if c.is_null() {
false
} else {
(*c).exhausted
}
}
}