Files
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

9.4 KiB
Raw Permalink Blame History

LLM 对话审计(meta.jsonl)

适用版本:ipass-1.0.18(1.0.17 及更早是「全量请求体副本」口径)。 涉及文件:rust/crates/plugin-llm/src/llm_audit.rs(实现)、 rust/crates/plugin-llm/src/{config,handlers}.rs、conf/nginx.conf(LLM location)、 tests/llm/e2e.sh(【9】【13】)、Dockerfile(审计目录与权限)。


一、解决什么问题

旧口径(1.0.17 及更早):把完整请求体复制一份存档

每个被转发的 LLM 请求,在 log 阶段把 body 临时文件整个复制成 <审计根>/YYYY-MM-DD/<毫秒>_<rand>.json。

代价:

请求类型 单请求审计占用
简单对话 ~2 KB
带 tools / 多轮 history(实际生产常见) 700 KB+

按 QPS 10 估算 = 一天 600 GB。而 AUDIT_MAX_BYTES 当时是 10 GB → 24 分钟就触发一次 purge,审计留存时长实际是「分钟级」,复盘价值几乎为零。 更糟的是它掩盖了容量真相:10 GB 的配额在新口径(~400 B/条)下等于「永远不会 purge」, 这个数字本身就是误导。

新口径(1.0.18):元数据 + 前 100 字节摘录

不再复制 body。改为单遍扫描 body 临时文件,产出一行元数据:

<审计根>/YYYY-MM-DD/meta.jsonl      ← 一行一个请求,追加写

单请求占用 ~400 B(一行 meta),比旧口径降约 3 个数量级。 AUDIT_MAX_BYTES 相应从 10 GB 改为 1 GB(够约 250 万条,约 7 天 @ QPS 4)。

为什么先扫全文,而不是只读前 100 字节

body_hash 要当「同一请求」的指纹用(查重、对齐上游账目)。而所有 OpenAI / Anthropic 请求的前 100 字节都是同一个开头:

{"model":"gpt-4o","messages":[{"role":"user","content":"...
{"model":"claude-3-5-sonnet","messages":[{"role":"user","con...

只哈希前 N 字节 → 全部碰撞,这一列就是废数据。 所以:只把前 N 字节留在内存,其余边读边喂 SHA256 后丢弃, body_hash 用全文、body_bytes 记全文字节数。

成本仍然低于 1.0.17 的「读全文 + 写全文副本」——那是读 + 写, 这是只读一遍顺序 IO,不复制、不落盘。


二、捕获机制

  1. LLM location 开 client_body_in_file_only clean —— nginx 自己把请求体刷到临时文件。
  2. 本模块在 log 阶段(handlers.rs 的日志处理器)调 capture():
    • 取 r->request_body->temp_file;为空直接返回(本地应答 / 被拒请求 / 无 body → 不审计)。
    • scan_body() 单遍扫描:拿前 100 字节 + 全文 SHA256 + 全文字节数。
    • 追加一行到 <审计根>/<YYYY-MM-DD>/meta.jsonl。
    • 顺带触发一次容量巡检(节流)。
  3. 只有真正转发出去的请求才入档:401 / 403 / 404 / 429 在 log 阶段拿不到 temp_file (路径不同、body 没落盘),自然不入档。这与用量统计口径一致。

三、meta.jsonl 行格式

{
  "ts": 1789384310,
  "time": "2026-09-14 19:11:50",
  "user": "alice",
  "slot": "openai",
  "status": 200,
  "tin": 7,
  "tout": 3,
  "excerpt": "{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"AAAA…",
  "body_hash": "172d7d031d91d02e",
  "body_bytes": 472
}
字段 含义
ts / time 落档时刻(秒 / 可读文本)。注意这是 log 阶段时刻,不是请求开始时刻
user 下游账号(ust: 同一套用户名);取不到时为 -
slot 上游 slot;取不到时为 -。apix 的条目是 api/<slug>
status 转发后回给客户端的 HTTP 状态码
tin / tout 上游 usage 里的 input / output token(body filter 旁路抓的,见 STREAMING_USAGE.md)。0 = 上游没给 usage(如 OpenAI 流式未开 include_usage)
excerpt 请求体前 100 字节。JSON 转义由 serde 统一做
body_hash 全文 SHA256 的前 16 hex(64 bit)
body_bytes 全文字节数(不是 excerpt 的长度)

⚠️ excerpt 只转义一次

excerpt 的值是裸字符串,转义由 json!()(serde_json)统一处理。 实现里不要自己再手工转义一遍 —— 那样会双重编码,落盘成 "excerpt":"\"{\\\"model\\\"…",读出来多一层引号, 任何按前缀匹配的消费方(含测试断言)都解析不到。

(1.0.18 首版踩过这个坑:原来有个 json_quote_bytes() 手工转义 + 加引号, 再塞进 json! 又被转义一次。已删除,改为 excerpt_text() 只做 UTF-8 安全解码。)

截断按字节做,可能切在多字节字符中间;String::from_utf8_lossy 会把残缺尾巴 换成 U+FFFD(合法 JSON 字符),不会产出非法 UTF-8。

摘录的取舍

  • 100 字节覆盖:模型名 + 首条消息的 role + 首句用户内容(短 query 整条保留)。
  • 大 body(带 tools / 多轮 history)只看得到头,看不到尾 —— 这是有意的: 复盘 90% 的场景「当时用户问了什么 + 用了哪个模型」够用。 要看全文请走 hot path 日志或实时抓包,不要指望 audit。

四、目录与配置

项 值 / 指令
审计根(默认) data 目录的兄弟目录 audit/(容器内 /usr/local/nginx/audit)
覆盖 ipass_audit_dir <path>
日期分目录 <审计根>/YYYY-MM-DD/(字典序 = 时间序,purge 依赖这一点)
文件名 meta.jsonl(追加写,一行一条)
容量上限 AUDIT_MAX_BYTES = 1 GB(1.0.18 起;旧值 10 GB)
巡检节流 AUDIT_PURGE_MIN_INTERVAL = 60 秒(AtomicBool 单飞)
启动巡检 worker 启动时强制巡检一次(不依赖外部 cron)

purge 策略:扫审计根下各日期目录算总字节;超限就按目录名(= 日期) 从旧到新整目录删除,直到回到上限内。

容器里首次启动会 mkdir -p /usr/local/nginx/audit 并 chown -R nobody:nogroup(见 Dockerfile)——worker 默认是 nobody,目录必须对它可写, 否则审计静默失效(只写 error log)。生产建议把 audit 挂到宿主机卷, 否则容器重建即丢(与 data/ 同等对待)。


五、失败策略

审计是旁路功能:

  • body 没落盘 / temp_file 为空 → 静默返回(不报错、不影响转发);
  • 建目录失败 → log_err + 该次跳过(并在启动时标记「审计停用」);
  • 写 meta 失败 → log_err;
  • 容量巡检失败 → log_err。

任何情况下都不影响转发结果,也不阻塞 worker 启动。


六、怎么用

复盘「某个用户当时问了什么」

# 今天 alice 的最近 20 条
grep '"user":"alice"' <audit>/$(date +%F)/meta.jsonl | tail -20 | python3 -m json.tool --json-lines

# 只看模型 + 前 100 字节摘录
jq -r 'select(.user=="alice") | "\(.time) \(.status) \(.excerpt)"' <audit>/$(date +%F)/meta.jsonl

找「同一个请求被重复转发了几次」(body_hash 的用途)

jq -r '.body_hash' <audit>/*/meta.jsonl | sort | uniq -c | sort -rn | head

看审计占了多少空间 / 是否需要 purge

du -sh <audit>
du -sh <audit>/* | tail -5        # 按天分布

按 token 找最贵的请求(复盘成本)

jq -r 'select(.tin+.tout > 10000) | "\(.time) \(.user) \(.slot) in=\(.tin) out=\(.tout) \(.body_bytes)B"' \
   <audit>/$(date +%F)/meta.jsonl | sort -k4 -rn | head

七、测试覆盖

tests/llm/e2e.sh:

  • 【9】 容量巡检 / purge 行为(purge_once 依赖 nginx 运行时符号, cargo test --lib 会 SIGABRT —— 行为只能由 e2e 覆盖)。
  • 【13】 元数据口径:
    1. 转发的请求都落了 meta 行;
    2. 本轮没有新增 *.json 副本(断言的是增量,机器上可能还压着 1.0.17 及更早写下的上千个文件 —— 且本机的 safe-delete 钩子在累计删除 超过 50 个文件后会拦掉后续删除,清不掉);
    3. meta 行记录账号 / 上游 / 状态;
    4. excerpt 恰好等于请求体前 100 字节(用 472 字节的长 body 验证, 选择器是 body_bytes > 400 而不是「excerpt 前缀匹配」—— 后者在 excerpt 被转义坏掉时连行都选不中,会把「内容不对」伪装成「找不到行」);
    5. body_bytes = 请求体真实长度(472);
    6. body_hash 是 16 位 hex;
    7. 全量目录里搜不到长 body 的尾部标记(ZZ_TAIL_MARK)→ 证明真的只截了 100 字节;
    8. 被拒请求(401)不入档。

断言取最后一条匹配的 meta 行(不是第一条):审计目录里可能留着 1.0.18 首版写下的双重编码行,它排序在前会把第一条位置占掉。


八、已知限制

  • 不是全量归档:只留前 100 字节 + 全文指纹。要看全文请另建链路。
  • 一行一条、无索引:日文件是纯追加的 JSONL,量大时用 jq / grep 流式扫; 没有数据库(项目红线)。
  • ts 是 log 阶段时刻:与「客户端发出请求的时刻」有差(流式请求尤其明显, 差值 ≈ 响应耗时)。
  • 陈旧残留:1.0.17 及更早写下的 <毫秒>_<rand>.json 不会被新代码清理 (purge 只按日期整目录删,会在超限时连带清掉)。升级后如果磁盘吃紧, 手动清一次 audit/*/*.json。