Files
ipass__ipass/rust/crates/plugin-llm/src/llm_audit.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

256 lines
10 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::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\\\"...\""`,读出来多一层
/// 引号,任何按前缀匹配的消费方都解析不到)。
///
/// 截断是按**字节**做的,可能切在多字节字符中间;`from_utf8_lossy` 会把残缺尾巴
/// 换成 U+FFFD(合法 JSON 字符),绝不产出非法 UTF-8 让序列化失败。
fn excerpt_text(bytes: &[u8]) -> String {
String::from_utf8_lossy(bytes).into_owned()
}
/// 单遍扫描 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_EXCERPT_BYTES);
let excerpt = excerpt_text(&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(())
}