# 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/<毫秒>_.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 + 全文字节数。 - 追加一行到 `<审计根>//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/` | | `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 ` | | 日期分目录 | `<审计根>/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"' /$(date +%F)/meta.jsonl | tail -20 | python3 -m json.tool --json-lines # 只看模型 + 前 100 字节摘录 jq -r 'select(.user=="alice") | "\(.time) \(.status) \(.excerpt)"' /$(date +%F)/meta.jsonl ``` ### 找「同一个请求被重复转发了几次」(`body_hash` 的用途) ```bash jq -r '.body_hash' /*/meta.jsonl | sort | uniq -c | sort -rn | head ``` ### 看审计占了多少空间 / 是否需要 purge ```bash du -sh du -sh /* | tail -5 # 按天分布 ``` ### 按 token 找最贵的请求(复盘成本) ```bash jq -r 'select(.tin+.tout > 10000) | "\(.time) \(.user) \(.slot) in=\(.tin) out=\(.tout) \(.body_bytes)B"' \ /$(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 及更早写下的 `<毫秒>_.json` 不会被新代码清理 (purge 只按日期整目录删,会在超限时连带清掉)。升级后如果磁盘吃紧, 手动清一次 `audit/*/*.json`。