Files
ssw__ipass/rust/gateway/src/stats.rs
T
admin 74aeefee58 refactor(plugin): P0-P2 插件化落地 —— workspace 化 + ipass-core + plugin-domain
- P0: rust/ 改 workspace(ipass-core 内核 + gateway 唯一 cdylib),
  [profile.release] 上移根、依赖收敛 workspace.dependencies;
  users::delete 的 stats::forget 依赖改为 on_delete 钩子注册表
- P1: 契约层 core/plugin.rs(Plugin trait)+ core/loc.rs(Switch 并集 +
  set_switch_fn,未实现变体保守 false);gateway PLUGINS 分发循环,
  不认领统一 404(插件绝不自行 404)
- P2: 身份端点下沉 core/api.rs(CorePlugin + CoreExt 扩展注册表,
  gateway 作装配根回填域名数/用量/连带回收/白名单校验);
  plugin-domain crate(domains + DomainEntry + sub: 前缀 + ResolveHandler
  + $proxy_backend_addr + 域名类端点含 purge)
- 行为等价:conf/nginx.conf、Dockerfile、tests 零改动,262 回归全绿
- 方案文档 docs/plugin/PLUGINIZATION_PLAN.md
2026-09-13 11:43:22 +08:00

586 lines
22 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> → 同 上
//! ```
//!
//! ## 口径:只统计"真的转发出去"的请求
//!
//! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**,
//! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同——
//! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义;
//! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。
//!
//! ## token 级计量(2026-09-12 起)
//!
//! token 数来自上游响应体里的 `usage` 字段:`llm_usage` 模块在 **body filter 链**
//! 旁路扫描响应(SSE 尾部 / 非 stream JSON 尾部),零缓冲、不影响透传;
//! log 阶段统一入账到 `utt:` / `utms:` 两个键前缀,编码与本文件同款格式。
//! 抓不到 usage(如 OpenAI 流式客户端没带 `include_usage`)= 记 0,不补估。
//! 计数口径与请求数一致:**只算真的转发出去且上游给了 usage 的**。
use std::collections::BTreeMap;
use serde_json::{Value, json};
use crate::config::{
KEY_UDAY_PREFIX, KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UMS_PREFIX,
KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, TREND_DAYS_DEFAULT, TREND_DAYS_MAX,
TREND_KEEP_SECS,
};
use crate::state;
use crate::util;
/// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Usage {
/// 今日(本地自然日)请求数
pub today: i64,
/// 累计请求数(自该计数键建立以来,不随跨天归零)
pub total: i64,
/// 最近一次调用时间戳;0 = 从未调用
pub last_ts: i64,
}
impl Usage {
/// 累加(聚合用)。`last_ts` 取最大。
fn merge(&mut self, other: &Usage) {
self.today += other.today;
self.total += other.total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"today": self.today,
"total": self.total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// token 计量读数。日窗语义与 [`Usage`] 相同:跨天 today 归零、累计保留。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct TokenUsage {
/// 今日入 token(prompt / input)
pub tin_today: i64,
/// 累计入 token
pub tin_total: i64,
/// 今日出 token(completion / output)
pub tout_today: i64,
/// 累计出 token
pub tout_total: i64,
/// 最近一次有 token 记账的调用时间戳;0 = 从未
pub last_ts: i64,
}
impl TokenUsage {
/// 累加(聚合用)。`last_ts` 取最大。
fn merge(&mut self, other: &TokenUsage) {
self.tin_today += other.tin_today;
self.tin_total += other.tin_total;
self.tout_today += other.tout_today;
self.tout_total += other.tout_total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"in_today": self.tin_today,
"in_total": self.tin_total,
"out_today": self.tout_today,
"out_total": self.tout_total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// 一个账号的用量 + 其下每个上游的明细
pub struct UserUsage {
pub username: String,
pub usage: Usage,
pub models: Vec<(String, Usage)>,
}
/// 一个上游的用量 + 用它的每个账号的明细
pub struct ModelUsage {
pub slot: String,
pub usage: Usage,
pub users: Vec<(String, Usage)>,
}
// ===========================================================================
// 编解码
// ===========================================================================
/// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。
/// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。
fn encode(day: i64, u: &Usage) -> String {
format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts)
}
/// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。
fn decode(payload: &str, day: i64) -> Usage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
Usage { today: if stored_day == day { today } else { 0 }, total, last_ts }
}
fn bump(prefix: &[u8], name: &str, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default();
let next = Usage {
today: current.today + 1,
total: current.total + 1,
last_ts: now,
};
// 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次),
// 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。
state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0);
}
// ===========================================================================
// 写
// ===========================================================================
/// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。
pub fn record(username: &str, slot: &str, now: i64) {
if username.is_empty() || slot.is_empty() {
return;
}
let day = util::day_id(now);
bump(KEY_UST_PREFIX, username, day, now);
bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now);
// 日桶:趋势图数据源(请求维度)。三个维度各写一次,键名带日窗 id
let delta = DayBucket { requests: 1, ..Default::default() };
bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta);
bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta);
bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta);
}
// ===========================================================================
// 日桶(趋势图数据源)
// ===========================================================================
//
// `ust:` / `utt:` 只留「今日 + 累计」两个数:今日跨天归零、累计不区分日期,
// 都画不出历史曲线。所以另开一组**以自然日为键**的桶:一个桶一天,
// 读取时按日窗 id **精确取键**(`get_live`),不做前缀扫描——
// 键数随时间增长也不会拖慢任何热路径。
/// 一天的聚合值
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DayBucket {
/// 请求数(已放行并真正转发)
pub requests: i64,
/// 入 token
pub tin: i64,
/// 出 token
pub tout: i64,
}
impl DayBucket {
fn merge(&mut self, other: &DayBucket) {
self.requests += other.requests;
self.tin += other.tin;
self.tout += other.tout;
}
}
/// `<请求数>:<入token>:<出token>`
fn encode_day(b: &DayBucket) -> String {
format!("{}:{}:{}", b.requests, b.tin, b.tout)
}
fn decode_day(payload: &str) -> DayBucket {
let mut it = payload.split(':');
let num = |v: Option<&str>| v.and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
DayBucket {
requests: num(it.next()),
tin: num(it.next()),
tout: num(it.next()),
}
}
/// 累加一日桶。TTL = `TREND_KEEP_SECS`,到期由共享内存自然淘汰
/// (`get_live` 视为不存在),不需要额外的清理任务。
fn bump_day(prefix: &[u8], name: &str, delta: &DayBucket) {
// 用共享内存的 TTL 而不是读时比对——日桶是「写一次、读很多次」,
// 让它自己过期比每次算保留窗口更省事,也避免键无限堆积。
let mut next = state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default();
next.merge(delta);
// 写入失败只记日志:统计是旁路功能,绝不影响转发
if !state::put(
prefix,
name.as_bytes(),
encode_day(&next).as_bytes(),
util::now() + TREND_KEEP_SECS,
) {
util::log_err("[stats] 日桶写入失败(共享内存不足?)");
}
}
/// 读一个日桶(不存在 = 全 0)
fn day_bucket(prefix: &[u8], name: &str) -> DayBucket {
state::get_live(prefix, name.as_bytes(), util::now())
.map(|p| decode_day(&p))
.unwrap_or_default()
}
/// `<日窗id>:<入今日>:<入累计>:<出今日>:<出累计>:<最近时间戳>`
fn encode_t(day: i64, t: &TokenUsage) -> String {
format!(
"{}:{}:{}:{}:{}:{}",
day, t.tin_today, t.tin_total, t.tout_today, t.tout_total, t.last_ts
)
}
fn decode_t(payload: &str, day: i64) -> TokenUsage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let in_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let out_total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let live = stored_day == day;
TokenUsage {
tin_today: if live { in_today } else { 0 },
tin_total: in_total,
tout_today: if live { out_today } else { 0 },
tout_total: out_total,
last_ts,
}
}
fn bump_t(prefix: &[u8], name: &str, tin: u64, tout: u64, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default();
// 与 bump 同款读-增-写近似语义(并发下偶发少计),计量用途可接受
let next = TokenUsage {
tin_today: current.tin_today + tin as i64,
tin_total: current.tin_total + tin as i64,
tout_today: current.tout_today + tout as i64,
tout_total: current.tout_total + tout as i64,
last_ts: now,
};
state::put(prefix, name.as_bytes(), encode_t(day, &next).as_bytes(), 0);
}
/// 累加一次真实 token 消耗(来源:body filter 从上游响应抓到的 usage)。
/// 口径:只有抓到 usage 才记账;抓不到不补估。
pub fn add_tokens(username: &str, slot: &str, tin: u64, tout: u64, now: i64) {
if username.is_empty() || slot.is_empty() || (tin == 0 && tout == 0) {
return;
}
let day = util::day_id(now);
bump_t(KEY_UTT_PREFIX, username, tin, tout, day, now);
bump_t(KEY_UTMS_PREFIX, &format!("{username}:{slot}"), tin, tout, day, now);
// 日桶:趋势图数据源(token 维度)。与 record 写的是同一批键,字段互补
let delta = DayBucket { tin: tin as i64, tout: tout as i64, ..Default::default() };
bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta);
bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta);
bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta);
}
/// 删除账号时清理其全部用量键(`ust:<user>` 与 `ums:<user>:*`)。
///
/// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让
/// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的
/// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。
pub fn forget(username: &str) {
if username.is_empty() {
return;
}
// 先物化键名再删,避免"遍历中改表"(四个键前缀同一套路)
let prefix = format!("{username}:");
for p in [KEY_UST_PREFIX, KEY_UTT_PREFIX] {
state::remove(p, username.as_bytes());
}
// 日桶两个维度也要清:`udu:<user>:<day>` 是按前缀扫不到的(键里还带日窗 id),
// 靠 TTL 自然淘汰也能收敛,但删账号后趋势图仍会挂着幽灵账号 90 天
for p in [KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UDAY_USER_PREFIX] {
let keys: Vec<String> = state::iter_prefix(p)
.into_iter()
.map(|(name, _)| name)
.filter(|name| name.starts_with(&prefix))
.collect();
for name in keys {
state::remove(p, name.as_bytes());
}
}
}
// ===========================================================================
// 读
// ===========================================================================
/// 单账号读数(不含模型明细)
pub fn user(username: &str, now: i64) -> Usage {
let day = util::day_id(now);
state::get(KEY_UST_PREFIX, username.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default()
}
/// 单账号 × 上游明细,按 slot 升序
pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> {
let day = util::day_id(now);
let prefix = format!("{username}:");
let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX)
.into_iter()
.filter_map(|(name, payload)| {
let slot = name.strip_prefix(&prefix)?.to_owned();
Some((slot, decode(&payload, day)))
})
.collect();
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
/// 全部账号的用量(含各自的模型明细),按账号名升序。
///
/// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。
pub fn all_users(now: i64) -> Vec<UserUsage> {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, Vec<(String, Usage)>> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
by_user
.entry(username.to_owned())
.or_default()
.push((slot.to_owned(), decode(&payload, day)));
}
for models in by_user.values_mut() {
models.sort_by(|a, b| a.0.cmp(&b.0));
}
state::iter_prefix(KEY_UST_PREFIX)
.into_iter()
.map(|(username, payload)| {
let usage = decode(&payload, day);
let models = by_user.remove(&username).unwrap_or_default();
UserUsage { username, usage, models }
})
.collect()
}
/// 全部上游的用量(含用到它的账号明细),按 slot 升序。
pub fn all_models(now: i64) -> Vec<ModelUsage> {
let day = util::day_id(now);
// slot → (总量, 各账号)
let mut by_slot: BTreeMap<String, (Usage, Vec<(String, Usage)>)> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let u = decode(&payload, day);
let entry = by_slot.entry(slot.to_owned()).or_default();
entry.0.merge(&u);
entry.1.push((username.to_owned(), u));
}
by_slot
.into_iter()
.map(|(slot, (usage, mut users))| {
users.sort_by(|a, b| a.0.cmp(&b.0));
ModelUsage { slot, usage, users }
})
.collect()
}
/// 全局合计
pub fn totals(now: i64) -> Usage {
let day = util::day_id(now);
let mut sum = Usage::default();
for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) {
sum.merge(&decode(&payload, day));
}
sum
}
/// 单账号 token 读数
pub fn tokens_user(username: &str, now: i64) -> TokenUsage {
let day = util::day_id(now);
state::get(KEY_UTT_PREFIX, username.as_bytes())
.map(|(payload, _)| decode_t(&payload, day))
.unwrap_or_default()
}
/// token 全表一次扫齐:`(按账号, 按上游, 按 账号→上游)`。
/// utt/utms 各扫一遍,避免报表页多次遍历共享内存。
fn tokens_scan(
now: i64,
) -> (
BTreeMap<String, TokenUsage>,
BTreeMap<String, TokenUsage>,
BTreeMap<String, BTreeMap<String, TokenUsage>>,
) {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, TokenUsage> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UTT_PREFIX) {
by_user.insert(name, decode_t(&payload, day));
}
let mut by_slot: BTreeMap<String, TokenUsage> = BTreeMap::new();
let mut by_pair: BTreeMap<String, BTreeMap<String, TokenUsage>> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UTMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let t = decode_t(&payload, day);
by_slot.entry(slot.to_owned()).or_default().merge(&t);
by_pair.entry(username.to_owned()).or_default().insert(slot.to_owned(), t);
}
(by_user, by_slot, by_pair)
}
/// 管理台用量页的完整投影
pub fn overview(now: i64) -> Value {
let (t_by_user, t_by_slot, t_by_pair) = tokens_scan(now);
let users: Vec<Value> = all_users(now)
.into_iter()
.map(|u| {
let tin = t_by_pair.get(&u.username);
json!({
"username": u.username,
"today": u.usage.today,
"total": u.usage.total,
"last_ts": u.usage.last_ts,
"last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() },
"tokens": t_by_user.get(&u.username).cloned().unwrap_or_default().json(),
"models": u.models.iter().map(|(slot, usage)| {
json!({ "slot": slot, "today": usage.today, "total": usage.total,
"tokens": tin.and_then(|m| m.get(slot)).cloned().unwrap_or_default().json() })
}).collect::<Vec<_>>(),
})
})
.collect();
let models: Vec<Value> = all_models(now)
.into_iter()
.map(|m| {
json!({
"slot": m.slot,
"today": m.usage.today,
"total": m.usage.total,
"last_ts": m.usage.last_ts,
"last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() },
"tokens": t_by_slot.get(&m.slot).cloned().unwrap_or_default().json(),
"users": m.users.iter().map(|(name, usage)| {
json!({ "username": name, "today": usage.today, "total": usage.total })
}).collect::<Vec<_>>(),
})
})
.collect();
let sum = totals(now);
let mut tsum = TokenUsage::default();
for t in t_by_user.values() {
tsum.merge(t);
}
json!({
"total": sum.json(),
"tokens": tsum.json(),
"users": users,
"models": models,
})
}
// ===========================================================================
// 趋势(图表数据源)
// ===========================================================================
/// 把一串日桶摊成图表直接能吃的三条等长数组
fn buckets_json(v: &[DayBucket]) -> Value {
json!({
"requests": v.iter().map(|b| b.requests).collect::<Vec<_>>(),
"in": v.iter().map(|b| b.tin).collect::<Vec<_>>(),
"out": v.iter().map(|b| b.tout).collect::<Vec<_>>(),
})
}
/// 最近 `days_req` 天的趋势序列(全局 / 按账号 / 按上游)。
///
/// `days_req` 会被夹到 `[1, TREND_DAYS_MAX]`——URL 里塞个 99999 也不会把
/// 共享内存扫爆。三个维度都是**按键精确取**(键名带日窗 id),
/// 成本 = 天数 × (1 + 账号数 + 上游数) 次查表,且不随历史增长。
pub fn trend(now: i64, days_req: i64, users: &[String], slots: &[String]) -> Value {
let days = days_req.clamp(1, TREND_DAYS_MAX);
// 往前推 N 天:每个采样点一个时间戳,日窗 id 现算(本地自然日,不用 UTC)
let stamps: Vec<i64> = (0..days).rev().map(|i| now - i * 86400).collect();
let labels: Vec<String> = stamps.iter().map(|t| util::fmt_day(*t)).collect();
let ids: Vec<i64> = stamps.iter().map(|t| util::day_id(*t)).collect();
let total: Vec<DayBucket> = ids.iter().map(|d| day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect();
let by_user: Vec<Value> = users
.iter()
.map(|u| {
let series: Vec<DayBucket> = ids
.iter()
.map(|d| day_bucket(KEY_UDAY_USER_PREFIX, &format!("{u}:{d}")))
.collect();
let mut o = buckets_json(&series);
// 全 0 的账号不回传:趋势图里一堆积零的线只会把图例挤爆
let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0);
if let Value::Object(ref mut m) = o {
m.insert("username".to_owned(), json!(u));
m.insert("empty".to_owned(), json!(empty));
}
o
})
.collect();
let by_slot: Vec<Value> = slots
.iter()
.map(|s| {
let series: Vec<DayBucket> = ids
.iter()
.map(|d| day_bucket(KEY_UDAY_SLOT_PREFIX, &format!("{s}:{d}")))
.collect();
let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0);
let mut o = buckets_json(&series);
if let Value::Object(ref mut m) = o {
m.insert("slot".to_owned(), json!(s));
m.insert("empty".to_owned(), json!(empty));
}
o
})
.collect();
json!({
"days": days,
"labels": labels,
"total": buckets_json(&total),
"users": by_user,
"slots": by_slot,
})
}
/// 趋势接口的默认天数(URL 没给 `days` 时用)
pub fn trend_default_days() -> i64 {
TREND_DAYS_DEFAULT
}