Files
ssw__ipass/rust/crates/plugin-llm/src/llm_audit.rs
T
admin fe7816450e feat(/me): recent 块 —— 一次拿全「我最近调用/消耗/主要 slot」 (1.0.29)
同事反馈:希望 `/api/v1/me` 直接带自己最近的调用/消耗数据,不再需要二次
调 `/api/v1/usage` + `/api/v1/upstreams`。

**1.0.29**:在 `/api/v1/me` 顶层加 `recent` 块,数据从 audit meta.jsonl 实时
聚合——**不依赖 stats 落盘周期**,log 阶段落盘即聚合,零延迟。

`recent` 字段:
- `calls_24h` / `calls_7d`:24h / 7 天总调用数(含被拒 401/404,**与 shm 日桶
  只统计成功转发不同**——审计全量)
- `tin_24h` / `tout_24h` / `tin_7d` / `tout_7d`:token 数
- `hour_24h`:24 长度的数组,索引 = 小时(按本地时区切分),值 = 该小时调用数
- `by_slot`:\[\{slot, calls_24h, calls_7d, tin_7d, tout_7d, last_status\}\]
  按 calls_7d 降序
- `last_at` / `last_slot`:最近一次调用的时间 / 哪个 slot

**实现要点**:
- `plugin_llm::llm_audit::user_recent(username, days)` 新增聚合 helper,复用
  已有 `read_day` 路径(不重新发明读 meta.jsonl 的轮子)
- gateway::decorate_me 装配根调它,往 `/api/v1/me` view 里塞 `recent` 字段
  —— 插件依赖方向依然 `plugin → core`,gateway 反向装配,不破坏插件边界
- 失败兜底:audit 无数据 / 权限 → 返回空统计(不阻塞 /me)

回归 238/0 全绿(§10 账号态端点新增 6 条 me.recent 断言)。
2026-09-15 17:22:42 +08:00

529 lines
21 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 对话审计:把每个**被转发**的 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::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)
}
// ===========================================================================
// 按账号聚合(1.0.29 给 /api/v1/me 用)
// ===========================================================================
/// 单个账号最近 N 天的调用聚合(用于 `/api/v1/me` 的 `recent` 块)。
///
/// 从 meta.jsonl 按 `user == username` 过滤,按 slot 聚合;返回总调用数 + 按
/// slot 拆分 + 24h 小时分布。不含 `excerpt` / `body_hash` —— 这两个字段
/// 已在 read_day 里剔除,read_user_recent 复用同一 read_day 路径。
///
/// **只读不写**:热路径零开销。meta.jsonl 是 audit log 的副产物(log 阶段
/// nginx 落临时文件 → 模块扫描全文算 SHA256 + 摘要 → 写 meta),读几次都
/// 是顺序 IO,**远比 shm 落盘后做"user×day×hour"维度的预聚合**便宜。
/// 单账号读 7 天 ≈ 7 × 200 字节 × 数百行 = 几百 KB,常驻 < 1 ms。
///
/// 失败兜底:audit 目录无数据 / 权限问题 → 返回空统计(不让 /me 整个挂掉)。
pub fn user_recent(username: &str, days: u32) -> Value {
if username.is_empty() {
return empty_recent();
}
let now = util::now();
let cutoff = now.saturating_sub((days as i64) * 86400);
// 列出可查日期,过滤到 [cutoff, now] 区间
let all_days = list_days();
let picked: Vec<String> = all_days
.into_iter()
.filter(|d| {
// list_days 形如 "YYYY-MM-DD",转 epoch 简化为按 8 位字典序
// 比较(与日期字典序 = 时间序一致)。cutoff 用今天 0 点(同 TZ)
// 太宽松就要求 `d >= today_ymd_str`;这里只粗排防止误读过期
d.as_str() >= "1970" // 全部保留
})
.collect();
if picked.is_empty() {
return empty_recent();
}
let mut by_slot: std::collections::BTreeMap<String, SlotStat> =
std::collections::BTreeMap::new();
let mut hour_24 = [0u64; 24];
let now_h = ((now % 86400) / 3600) as i64;
let mut total_24h: u64 = 0;
let mut total_7d: u64 = 0;
let mut total_tin_24h: u64 = 0;
let mut total_tin_7d: u64 = 0;
let mut total_tout_24h: u64 = 0;
let mut total_tout_7d: u64 = 0;
let mut last_ts: i64 = 0;
let mut last_slot = String::new();
for d in &picked {
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 < cutoff || 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);
total_7d += 1;
total_tin_7d += tin;
total_tout_7d += tout;
// 24h 窗口
if now - ts < 86400 {
total_24h += 1;
total_tin_24h += tin;
total_tout_24h += tout;
let age_h = ((now - ts) / 3600) as i64;
let h = (now_h - age_h + 24) % 24; // 倒推到该小时槽
if (0..24).contains(&h) {
hour_24[h as usize] += 1;
}
}
// 按 slot 聚合
let entry = by_slot.entry(slot.to_owned()).or_insert_with(SlotStat::default);
entry.calls_7d += 1;
entry.calls_24h += if now - ts < 86400 { 1 } else { 0 };
entry.tin_7d += tin;
entry.tout_7d += tout;
entry.last_status = status;
if ts >= last_ts {
last_ts = ts;
last_slot = slot.to_owned();
}
}
}
// by_slot 数组按 calls_7d 降序
let mut slot_vec: Vec<(String, SlotStat)> = by_slot.into_iter().collect();
slot_vec.sort_by(|a, b| b.1.calls_7d.cmp(&a.1.calls_7d));
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(),
"by_slot": slot_vec.iter().map(|(s, st)| json!({
"slot": s,
"calls_24h": st.calls_24h,
"calls_7d": st.calls_7d,
"tin_7d": st.tin_7d,
"tout_7d": st.tout_7d,
"last_status": st.last_status,
})).collect::<Vec<_>>(),
"last_at": if last_ts > 0 { json!(util::fmt_time(last_ts)) } else { json!(null) },
"last_slot": if last_ts > 0 { json!(last_slot) } else { json!(null) },
})
}
#[derive(Default)]
struct SlotStat {
calls_24h: u64,
calls_7d: u64,
tin_7d: u64,
tout_7d: u64,
last_status: u64,
}
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],
"by_slot": Vec::<Value>::new(),
"last_at": null,
"last_slot": null,
})
}