起因:发版后管理台「用量」与「趋势」从 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)
15 KiB
运行期统计的落盘与恢复(发版不再清零用量 / 趋势)
适用版本:
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 带来的三个性质
- 重启后可全量恢复:共享内存是空的 → 所有键都「不存在」→ 逐个写回。
- 多 worker 天然幂等:第二个 worker 起跳过,不会把计数恢复成 N 倍。
- 不打死新数据:若恢复进行时已有新请求把某个键写活 → 不覆盖。 宁可少恢复一条,也不把刚产生的真实计数抹掉。
其它规则
- 过期键(
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 开始」。
五、文件格式
{
"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 退出钩子这一次 |
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 响应:
{
"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
确认功能生效(发版前)
# 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
发版前后对照(验证「不再清零」)
# 发版前:记下 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 秒(读
/api/admin/stats/persist的interval_secs) - 跑几笔请求 +
sleep 1.5→ 快照文件已产出 - 快照含
ust:alice、含ud:日桶 - 快照不含凭据类配置键(
up:/upa:/upe:/ax:/ukey:/sub:) nginx -s quit(等价于生产docker stop)→ 重新拉起- 重新登录后:
restored_keys > 0、restored_keys == restore_total - alice 累计用量不变;再打一笔后 = 原值 + 1(证明是「接着长」而不是从 0 开始)
- 趋势日桶仍在;
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/ pythonrmtree:本机装了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变了就不恢复(宁可从零开始)。升级时若希望保留统计, 需同步 bumpSTATS_SNAPSHOT_VERSION并写转换逻辑(当前不需要)。 - 多 worker 落盘是「白写几次」:
DUMPING单飞标记是每 worker 的静态量, 跨 worker 不互斥。代价只是几毫秒重复 IO,rename的原子性保证读侧永远看到完整文件。 - 不影响鉴权与配额:配额(
st:)走的是另一套键,重启清零是有意的 (见 §四)。所以「发版后配额重置」不是 bug。