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)
This commit is contained in:
1 parent
6b8d694c54
commit
16cf68d132
15 files changed
+1498
-43
No files matched your search
@@ -0,0 +1,225 @@
|
||||
# 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`。
|
||||
@@ -0,0 +1,317 @@
|
||||
# 运行期统计的落盘与恢复(发版不再清零用量 / 趋势)
|
||||
|
||||
> 适用版本:`ipass-1.0.18`(插件化后的 `plugin-llm`)。
|
||||
> 涉及文件:`rust/crates/plugin-llm/src/stats_persist.rs`(主体)、
|
||||
> `rust/crates/plugin-llm/src/{config,stats,api}.rs`、`rust/gateway/src/lib.rs`(两个生命周期钩子)、
|
||||
> `tests/llm/{nginx.conf.in,e2e.sh}`、`tests/run.sh`。
|
||||
|
||||
---
|
||||
|
||||
## 一、解决什么问题
|
||||
|
||||
### 症状
|
||||
|
||||
**每次发版(容器重建)后,管理台的「用量」与「趋势」从 0 重新长起来**:
|
||||
- 「用量」页所有人的累计请求数 / token 数回到 0;
|
||||
- 「趋势」图最近 14 天的柱子在发版当天全部塌成 0。
|
||||
|
||||
而上游配置、账号、域名、用户都**不丢**——这个反差是定位问题的关键线索。
|
||||
|
||||
### 根因
|
||||
|
||||
| 数据 | 存放位置 | 发版后 |
|
||||
|---|---|---|
|
||||
| `up:` / `upa:` / `upe:`(上游与账号) | 共享内存 **+ `data/llm-upstreams.json`** | 不丢(启动由 `reload_shm` 从文件装载) |
|
||||
| `ax:`(API 代理) | 共享内存 **+ `data/api-proxies.json`** | 不丢(同上) |
|
||||
| `ukey:` / `sub:`(用户与 Key) | 共享内存 **+ `data/users.json`** | 不丢(同上) |
|
||||
| `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uda:` `uex:` `uh:`(**用量 / 趋势 / 负载 / 健康**) | **只有共享内存** | **全丢** |
|
||||
|
||||
共享内存是 nginx **每进程**启动时 mmap 出来的匿名区,**进程退出即消失**。
|
||||
统计类数据此前没有任何落盘,于是「重启 = 统计归零」。
|
||||
|
||||
### 做法(不引入数据库)
|
||||
|
||||
项目红线禁止数据库 / Redis / MQ(见 `CLAUDE.md`)。所以方案是**一个 JSON 快照**:
|
||||
|
||||
```
|
||||
data/llm-stats.json # 与 users.json / llm-upstreams.json 同级
|
||||
```
|
||||
|
||||
`data/` 是宿主机挂载卷(容器内 `/usr/local/nginx/data`),容器重建不影响它。
|
||||
|
||||
---
|
||||
|
||||
## 二、两个落盘点(互补,不是二选一)
|
||||
|
||||
| 触发 | 时机 | 覆盖场景 |
|
||||
|---|---|---|
|
||||
| **worker 退出钩子** `exit_process` | 优雅停机(`docker stop` → `STOPSIGNAL SIGQUIT`;`SIGTERM` 同路径;`nginx -s quit`) | 发版 / 手动重启 —— **零丢失** |
|
||||
| **周期性节流落盘** `maybe_dump()` | log 阶段记账之后,默认每 60 秒一次 | `SIGKILL` / OOM / 断电 —— 最多丢一个周期 |
|
||||
|
||||
- 退出钩子是**主力**:镜像 `Dockerfile` 里声明了 `STOPSIGNAL SIGQUIT`,
|
||||
`docker stop` 走的就是优雅停机路径,worker 退出前会调到该钩子。
|
||||
- 只有 `SIGKILL` 会绕过退出钩子(`docker kill`、OOM killer、宿主机断电),
|
||||
由周期落盘兜住。
|
||||
- **周期落盘挂在记账路径**(`stats::record` 末尾调 `maybe_dump()`),
|
||||
所以 apix 复用同一入口时也天然覆盖,不必单独挂。
|
||||
|
||||
### 原子写
|
||||
|
||||
`写 <path>.tmp.<pid> → rename`。带 pid 后缀是必要的:多 worker 同时到点落盘时,
|
||||
固定的 `.tmp` 会互相踩(一个已经 rename 走了,另一个还在往同名文件里写)。
|
||||
`rename` 本身是原子的,最后写完的那个赢——内容本来就只是「同一份共享内存的近似快照」,谁赢都对。
|
||||
|
||||
> 刻意**不复用** `store::write_json`(它用固定 `.tmp`)与 `state::file_lock()`
|
||||
> (那是给「读-改-写」防丢失用的;本函数是纯覆盖写、不读旧值,拿锁只会在退出路径上增加卡死风险)。
|
||||
|
||||
---
|
||||
|
||||
## 三、恢复语义
|
||||
|
||||
启动时每个 worker 的 `init_process` 都会调一次 `stats_persist::restore()`(由 gateway 注册)。
|
||||
共享内存是**跨 worker 共享**的,所以:
|
||||
|
||||
```
|
||||
worker 1 恢复全部键(共享内存是空的,全部「不存在」)
|
||||
worker 2 再来一遍 → 键已存在 → 全部跳过
|
||||
```
|
||||
|
||||
### put-if-absent 带来的三个性质
|
||||
|
||||
1. **重启后可全量恢复**:共享内存是空的 → 所有键都「不存在」→ 逐个写回。
|
||||
2. **多 worker 天然幂等**:第二个 worker 起跳过,**不会把计数恢复成 N 倍**。
|
||||
3. **不打死新数据**:若恢复进行时已有新请求把某个键写活 → **不覆盖**。
|
||||
宁可少恢复一条,也不把刚产生的真实计数抹掉。
|
||||
|
||||
### 其它规则
|
||||
|
||||
- **过期键(`exp <= now`)不恢复**:日桶 90 天保留期不能因为一次重启被续命。
|
||||
(落盘侧同样跳过过期键,两侧口径一致。)
|
||||
- **版本不符不恢复**:`snap.version != STATS_SNAPSHOT_VERSION` → 只 `log_err`,宁可从零开始,
|
||||
也不把语义不明的旧数据灌进共享内存。
|
||||
- **解析失败改名留档**:文件改成 `llm-stats.json.bad` 再放弃本次恢复。
|
||||
否则第一个请求到点就会用「空共享内存」覆盖掉这份文件,把唯一的现场抹掉、连查都没得查。
|
||||
- **任何异常都只降级**:统计与审计都是旁路,绝不能让 worker 起不来。
|
||||
|
||||
### 恢复结果的可见性(`spr:last`)
|
||||
|
||||
恢复结果(时刻 / 恢复键数 / 快照键数)**发布到共享内存** `spr:last`,
|
||||
而不是放进程内静态量:
|
||||
|
||||
- `init_process` 是**每 worker 跑一次**,只有第一个 worker 真的在写键;
|
||||
- 用静态量的话,`/api/admin/stats/persist` 落到哪个 worker 就报哪个数
|
||||
—— 运维看到的是**随机值**;
|
||||
- 发布规则:`restored == 0` 的 worker **不写**(它只是「来晚了」的观察者,
|
||||
用 0 覆盖真实结果等于把这次恢复从记录里抹掉);已有记录时**累加 + `max(total)`**
|
||||
(两个 worker 的 `init_process` 可能重叠、各恢复一半,累加才拼得出完整结果)。
|
||||
|
||||
---
|
||||
|
||||
## 四、什么被持久化,什么不被
|
||||
|
||||
### 持久化(`PREFIXES` 白名单,10 个)
|
||||
|
||||
| 前缀 | 含义 |
|
||||
|---|---|
|
||||
| `ust:` | 账号维度请求数 |
|
||||
| `ums:` | 账号 × 上游 请求数 |
|
||||
| `utt:` | 账号维度 token |
|
||||
| `utms:` | 账号 × 上游 token |
|
||||
| `ud:` | 全局日桶(趋势图总览) |
|
||||
| `udu:` | 按账号日桶 |
|
||||
| `uds:` | 按上游(API 组)日桶 |
|
||||
| `uda:` | 按上游账号日桶(「各 Key 负载」) |
|
||||
| `uex:` | 账号额度耗尽次数日桶 |
|
||||
| `uh:` | 上游健康展示缓存 |
|
||||
|
||||
### 刻意不持久化
|
||||
|
||||
| 键 | 理由 |
|
||||
|---|---|
|
||||
| `up:` / `upa:` / `upe:` / `ax:` / `ukey:` / `sub:` | **各自有数据文件**(`data/*.json`),重启由 `reload_shm` 装载。再存一份会出现**两个真源**——「文件是新的、快照是旧的」时互相覆盖,属于自找的故障 |
|
||||
| `ukb:` | 用户 Key → 上游账号粘性,设计上就是**重启即重绑** |
|
||||
| `spr:` | 本模块自己的「上次恢复」记录。恢复过程的元信息、不是统计量,持久化它只会自我引用 |
|
||||
| `st:` / `rl:` / `fail:` / `sess:` | 内核状态(配额 / 限流 / 登录会话)。语义上重启清零**更安全**(多送一点额度好过把用户锁死),且不由本插件代管 |
|
||||
|
||||
> ⚠️ 新增统计类键前缀时,**必须同步 `stats_persist::PREFIXES`**,否则该维度发版即清零——
|
||||
> 而且不会报错,只会在发版后表现为「这一列从 0 开始」。
|
||||
|
||||
---
|
||||
|
||||
## 五、文件格式
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"saved_at": 1789384321,
|
||||
"saved_at_text": "2026-09-14 19:12:01",
|
||||
"keys": {
|
||||
"ust:alice": "0:3:3:1789384321\u001f0",
|
||||
"ud:0": "12:3456:789\u001f0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 键 = **完整键名**(前缀 + name)。
|
||||
- 值 = `<payload>\u001f<exp>`,分隔符是共享内存同款 `VAL_SEP`(0x1f),
|
||||
解析用 `rfind`(`exp` 是 ASCII 数字串、不含分隔符,所以**最后一个**才是真边界)——
|
||||
与内核 `split_value` 同源。
|
||||
- 整份文件覆盖写,**不做历史轮转**:它只是「当前共享内存的近似快照」,
|
||||
不是时间序列存档。要看历史趋势请用日桶(`ud:` / `udu:` / `uds:`,TTL 90 天,本身也在快照里)。
|
||||
|
||||
### 容量
|
||||
|
||||
键数 ≈ 账号数 × slot 数 + 90 天 × (1 + 账号数 + slot 数 + 账号 × 上游数)。
|
||||
十来个账号的规模下是**几十 KB**,写一次几毫秒——与「每请求都写」的量级完全不同。
|
||||
(对比:1.0.17 及更早的对话审计每请求复制 700 KB+ 请求体,见 `AUDIT_LOG.md`。)
|
||||
|
||||
---
|
||||
|
||||
## 六、配置:`ipass_stats_persist <秒>`
|
||||
|
||||
| 值 | 行为 |
|
||||
|---|---|
|
||||
| 默认(指令**不写**) | 60 秒 |
|
||||
| `0` | 关闭周期落盘,**只靠 worker 退出钩子**这一次 |
|
||||
|
||||
```nginx
|
||||
http {
|
||||
ipass_stats_persist 0; # 例:完全关掉周期落盘
|
||||
}
|
||||
```
|
||||
|
||||
**生产 `conf/nginx.conf` 刻意不写这条指令**:老镜像不认识它会起不来
|
||||
(unknown directive → 直接启动失败),而默认值 60 秒已经够用。
|
||||
只有当确实需要调整间隔时才加,且要保证**镜像里已经有这条指令**。
|
||||
|
||||
> 测试套件把它压到 `1` 秒(`tests/llm/nginx.conf.in`),
|
||||
> 这样「周期落盘已产出快照」这条断言才能确定性地验证。
|
||||
|
||||
---
|
||||
|
||||
## 七、管理接口
|
||||
|
||||
| 接口 | 作用 |
|
||||
|---|---|
|
||||
| `GET /api/admin/stats/persist` | 快照文件状态 + 共享内存现状 + 上次恢复结果(只读) |
|
||||
| `POST /api/admin/stats/dump` | **立刻落盘一次**(不看间隔),返回写入键数 |
|
||||
|
||||
`GET /api/admin/stats/persist` 响应:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0, "msg": "ok",
|
||||
"data": {
|
||||
"file": "/usr/local/nginx/data/llm-stats.json",
|
||||
"file_exists": true,
|
||||
"file_bytes": 20480,
|
||||
"file_keys": 137,
|
||||
"saved_at": 1789384321,
|
||||
"saved_at_text": "2026-09-14 19:12:01",
|
||||
"live_keys": 137,
|
||||
"interval_secs": 60,
|
||||
"last_dump_at": 1789384321,
|
||||
"last_dump_text": "2026-09-14 19:12:01",
|
||||
"restored_at": 1789384100,
|
||||
"restored_keys": 137,
|
||||
"restore_total": 137
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
字段怎么读:
|
||||
|
||||
| 字段 | 含义 | 异常时的含义 |
|
||||
|---|---|---|
|
||||
| `file_keys` | 快照里有多少键 | 长期远小于 `live_keys` → 周期落盘没跑起来(查 `interval_secs` / `last_dump_at`) |
|
||||
| `live_keys` | 共享内存里当前有多少(已剔除过期) | 与 `file_keys` 长期接近 = 落盘正常 |
|
||||
| `restored_keys` / `restore_total` | 上次启动**恢复了多少** / 快照里**有多少** | 两者不等 → 有键被跳过(已过期 / 已被新请求写活 / 不在白名单) |
|
||||
| `restored_at` | 上次恢复时刻,`0` = 本进程没发生过恢复 | 刚发版后应等于启动时刻 |
|
||||
|
||||
> 注意 `restored_*` 来自共享内存记录(见 §三),**所有 worker 报同一份**,
|
||||
> 不会因为请求落到哪个 worker 而变。
|
||||
|
||||
---
|
||||
|
||||
## 八、运维 Runbook
|
||||
|
||||
### 确认功能生效(发版前)
|
||||
|
||||
```bash
|
||||
# 1) 有没有快照、键数是否与内存接近
|
||||
curl -s -b /tmp/cookie.jar http://<host>:18099/api/admin/stats/persist | python3 -m json.tool
|
||||
|
||||
# 2) 强制落一次,看返回值
|
||||
curl -s -b /tmp/cookie.jar -X POST http://<host>:18099/api/admin/stats/dump
|
||||
|
||||
# 3) 宿主机上看文件确实存在且在变大
|
||||
ls -l <data>/llm-stats.json
|
||||
```
|
||||
|
||||
### 发版前后对照(验证「不再清零」)
|
||||
|
||||
```bash
|
||||
# 发版前:记下 alice 的累计用量与趋势总数
|
||||
curl -s -b /tmp/cookie.jar http://<host>:18099/api/admin/usage | grep -o '"username": *"alice".*"total":[0-9]*'
|
||||
curl -s -b /tmp/cookie.jar 'http://<host>:18099/api/admin/trend?days=7'
|
||||
|
||||
# 发版:bash deploy/agent.sh release <tag> && bash deploy/agent.sh verify
|
||||
|
||||
# 发版后:重新登录(登录会话在共享内存里,重启即失效),比对
|
||||
# - 用量累计数应**持平**(不是回到 0)
|
||||
# - 趋势最近 7 天的柱子应**仍在**
|
||||
# - /api/admin/stats/persist 的 restored_keys 应 > 0 且 == restore_total
|
||||
```
|
||||
|
||||
### 常见故障
|
||||
|
||||
| 现象 | 原因 | 处理 |
|
||||
|---|---|---|
|
||||
| 发版后统计仍然清零 | `data/llm-stats.json` 不存在或为空 | 检查 `data/` 挂载是否可写(容器内 `/usr/local/nginx/data`,需对 worker 可写);查 error log 有无 `[stats]` 前缀的报错 |
|
||||
| `restored_keys == 0` 但 `file_keys > 0` | 快照版本不符 / 解析失败(已改名 `.bad`)/ 所有键都过期 | 看 error log 的 `[stats]` 行;`.bad` 文件留着可人工核对 |
|
||||
| 磁盘上出现 `llm-stats.json.bad` | 上一次启动解析失败 | 保留排查(结构被手改过 / 写到一半断电);确认当前快照正常后可删 |
|
||||
| 统计「丢了几十秒」 | `SIGKILL` / OOM(绕过了退出钩子) | 属预期,最多丢一个 `interval_secs`;要更小就把间隔调小 |
|
||||
| 某些维度清零、其它维度不丢 | 新加的统计前缀**漏加进 `PREFIXES`** | 补 `stats_persist.rs` 的白名单(见 §四 末尾的警告) |
|
||||
|
||||
---
|
||||
|
||||
## 九、测试覆盖
|
||||
|
||||
`tests/llm/e2e.sh` 的【15】段(刻意放在**最后**:它要停掉再拉起 nginx,
|
||||
之后的断言环境会变——会话丢、共享内存重建):
|
||||
|
||||
1. 落盘间隔被压到 1 秒(读 `/api/admin/stats/persist` 的 `interval_secs`)
|
||||
2. 跑几笔请求 + `sleep 1.5` → 快照文件已产出
|
||||
3. 快照含 `ust:alice`、含 `ud:` 日桶
|
||||
4. 快照**不含**凭据类配置键(`up:` / `upa:` / `upe:` / `ax:` / `ukey:` / `sub:`)
|
||||
5. `nginx -s quit`(等价于生产 `docker stop`)→ 重新拉起
|
||||
6. 重新登录后:`restored_keys > 0`、`restored_keys == restore_total`
|
||||
7. alice 累计用量**不变**;再打一笔后 = 原值 + 1(证明是「接着长」而不是从 0 开始)
|
||||
8. 趋势日桶仍在;`uda:` 账号级负载仍可读
|
||||
|
||||
`tests/run.sh` 在跑套件前会把上一轮的 `tests/.run/llm/data/llm-stats.json`
|
||||
**挪到** `tests/.run/llm/stale/llm-stats.<epoch>.json`(留档,不删)——
|
||||
清不掉快照的话,上一轮的 `ust:` / `ud:` / `uh:` 会被启动时的 `restore()`
|
||||
灌进本轮,症状极具欺骗性:carol 用量期望 2 变 6、「上游健康初始状态」期望
|
||||
`unknown` 变 `ok`,看起来像统计功能有 bug,实际是测试间的状态泄漏。
|
||||
|
||||
> ⚠️ **必须用 `mv`,不能用 `rm` / python `rmtree`**:本机装了 `safe-delete` 钩子 ——
|
||||
> 同一个 agent turn 里累计删除超过 **50** 个文件后,后续所有删除都被**静默拦掉**
|
||||
> (error log 里可见 `SAFE_DELETE_BULK_CONFIRM_REQUIRED`)。
|
||||
> `mv` 是 rename、不算删除,在沙箱下稳定生效。
|
||||
>
|
||||
> 同理,`tests/.run/llm/audit/` 里的历史残留**不做清理**:「不再生成请求体副本」
|
||||
> 那条断言改成校验**本轮增量 = 0**,从而对历史残留免疫(见 `AUDIT_LOG.md` §七)。
|
||||
> 1.0.17 及更早写下的上千个 `*.json`(每个 700 KB+)需要时**手动清一次**。
|
||||
|
||||
---
|
||||
|
||||
## 十、边界与已知限制
|
||||
|
||||
- **不是备份**:快照只有一份、覆盖写。要长期归档请自行拷走 `data/llm-stats.json`。
|
||||
- **不跨版本迁移**:`version` 变了就不恢复(宁可从零开始)。升级时若希望保留统计,
|
||||
需同步 bump `STATS_SNAPSHOT_VERSION` 并写转换逻辑(当前不需要)。
|
||||
- **多 worker 落盘是「白写几次」**:`DUMPING` 单飞标记是**每 worker** 的静态量,
|
||||
跨 worker 不互斥。代价只是几毫秒重复 IO,`rename` 的原子性保证读侧永远看到完整文件。
|
||||
- **不影响鉴权与配额**:配额(`st:`)走的是另一套键,重启清零是**有意的**
|
||||
(见 §四)。所以「发版后配额重置」不是 bug。
|
||||
Reference in new issue
Block a user