Files
ssw__ipass/rust/crates/plugin-llm/src/stats.rs
T
admin 16cf68d132 feat(stats): 运行期统计落盘/恢复 + 审计口径收口 (1.0.18)
起因:发版后管理台「用量」与「趋势」从 0 重新长起来。根因是统计类键
(ust:/ums:/utt:/utms:/ud:/udu:/uds:/uda:/uex:/uh:)只活在共享内存,
进程退出即消失;而上游/账号/域名/用户都有 data/*.json 所以不丢。

统计落盘(新 stats_persist.rs):
- 快照 data/llm-stats.json(与 users.json 同级),原子写 <path>.tmp.<pid> + rename
- 两个落盘点互补:worker 退出钩子 exit_process(发版/docker stop,零丢失)
  + 记账后按间隔节流落盘(默认 60s,覆盖 SIGKILL/OOM/断电)
- 启动 init_process 恢复,put-if-absent → 多 worker 幂等、不覆盖新数据
- 白名单 10 个统计前缀;刻意排除配置类/ukb:/内核态(各有数据文件或重启清零更安全)
- 恢复结果发布 shm spr:last(不再放进程内静态量,否则接口落到哪个 worker 报哪个数)
- 接口 GET /api/admin/stats/persist + POST /api/admin/stats/dump
- 指令 ipass_stats_persist <秒>(0=只留退出钩子);生产 conf 刻意不写

fix(audit): excerpt 双重编码
- json_quote_bytes(手工转义+两侧引号)塞进 json!() 被二次转义,落盘成
  "excerpt":"\"{\\\"model\\\"…",解码后多一层引号,消费方全解析不到
- 改为 excerpt_text():只 from_utf8_lossy,转义交给 serde

docs: 新增 docs/llm/STATS_PERSISTENCE.md(含 runbook)、docs/llm/AUDIT_LOG.md
  (两者此前被代码注释与 Dockerfile 引用但文件并不存在)

tests:
- 新增【15】统计落盘/重启恢复 13 条(间隔压 1s → 快照产出与白名单 →
  nginx -s quit → 恢复键数 == 快照键数、用量不变、再打一笔 +1、趋势仍在)
- 【13】「不再生成 body 副本」改断言本轮增量 = 0(对历史残留免疫);
  选择器改 body_bytes>400 且取最后一条匹配(目录里有首版的双重编码行)
- run.sh 复位改用 mv(rename 不算删除)——本机 safe-delete 钩子在累计删除
  超 50 个文件后会静默拦掉后续删除,rm -rf 与 python rmtree 同样被拦
- 回归 298 全绿(网关 102 + LLM 196)
2026-09-14 19:32:17 +08:00

383 lines
15 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 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
}