Files
ipass__ipass/docs/llm/AUDIT_LOG.md
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

226 lines
9.4 KiB
Markdown
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 对话审计(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 字节都是同一个开头:
```json
{"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` 行格式
```json
{
"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 启动。
---
## 六、怎么用
### 复盘「某个用户当时问了什么」
```bash
# 今天 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` 的用途)
```bash
jq -r '.body_hash' <audit>/*/meta.jsonl | sort | uniq -c | sort -rn | head
```
### 看审计占了多少空间 / 是否需要 purge
```bash
du -sh <audit>
du -sh <audit>/* | tail -5 # 按天分布
```
### 按 token 找最贵的请求(复盘成本)
```bash
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`。