1.0.18 首次线上验证暴露:error.log 里有 10 次 [stats] 落盘(来自 6#0/18#0/23#0 多个 worker),GET /api/admin/stats/persist 却报「本进程还没落过」。 根因:LAST_DUMP_AT 是每 worker 的进程内静态量。maybe_dump() 挂在记账路径上, 而记账每 worker 各算各的 → 落盘时刻也就每 worker 一份;接口落到没落过盘的 worker 就报 0。与 1.0.18 已修过的 spr:last(上次恢复)是同一类错误。 修法:发布到共享内存 spd:last(publish_dump 取 max)。一次解决两件事: * 上报一致 —— 所有 worker 报同一份; * 节流收敛 —— maybe_dump 新增慢路径查它,把「8 个 worker 各写一遍同一个文件」 收敛成「全局每间隔一次」。快路径仍是原子比较,热路径代价不变。 顺带: - 新增回归断言「状态页报告的上次落盘时刻非空」(套件开 2 worker,能暴露该分歧) - deploy/agent.sh 加 stats-persist / stats-dump 子命令(线上观测口) - 统一文档里过期的断言条数(90/111/160/179/196/262/298 → 实际值) - 记录审计容量巡检 LAST_PURGE_AT/PURGING 同为每 worker 静态量(另案) 回归:bash tests/run.sh all → 299 条全绿(网关 102 + LLM 197)。
18 KiB
运行期统计的落盘与恢复(发版不再清零用量 / 趋势)
适用版本:
ipass-1.0.18起(插件化后的plugin-llm);spd:last落盘记录自ipass-1.0.19。 涉及文件: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()(那是给「读-改-写」防丢失用的;本函数是纯覆盖写、不读旧值,拿锁只会在退出路径上增加卡死风险)。
节流与「上次落盘」记录(spd:last)
maybe_dump() 由记账路径驱动,而记账是每 worker 各算各的 —— 所以「上次落盘时刻」
如果放进程内静态量,就是每 worker 一份。1.0.18 首次线上验证直接撞上:
error.log : [stats] 落盘 14 键(935 B,periodic)... ← 10 次,来自 6#0 / 18#0 / 23#0
状态页 last_dump: (本进程还没落过) ← 因为请求落到了没落过盘的 worker
解法与恢复侧的 spr:last 完全同构:时刻写共享内存 spd:last。一次解决两件事:
| 用途 | 说明 |
|---|---|
| 上报一致 | /api/admin/stats/persist 的 last_dump_at / last_dump_text 所有 worker 报同一份 |
| 节流收敛 | maybe_dump 慢路径查它 —— 把「8 个 worker 各写一遍同一个文件」收敛成「全局每间隔一次」 |
判断走两级,热路径代价仍是一次原子比较:
快路径(绝大多数请求):本 worker 自己在间隔内落过(LAST_DUMP_AT 静态量)→ 直接返回
慢路径(每 worker 每间隔最多一次):读 spd:last;别的 worker 刚落过 → 回填本地缓存后返回
都没落过 → 落盘
publish_dump 取 max 而非累加(落盘只需记住最近一次);它是「读-改-写」、
无原子性保证,两个 worker 同一瞬间落盘时理论上可能写入稍早的时刻(差 ≤1 秒)——
对状态展示与分钟级节流无影响,不值得为此引入跨 worker CAS(state 层本来也没有该原语)。
退出钩子那一份仍是每 worker 各落一次(内容只是「同一份共享内存的近似快照」,
rename原子、谁赢都对)。收敛的只是周期落盘。
三、恢复语义
启动时每个 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: |
本模块自己的「上次恢复」记录。恢复过程的元信息、不是统计量,持久化它只会自我引用 |
spd: |
本模块自己的「上次落盘」记录。同上——只在共享内存里,为的是让多 worker 报同一份结果并共用一份节流依据 |
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": 200, "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 长期接近 = 落盘正常 |
last_dump_at / last_dump_text |
上次落盘时刻(跨 worker,来自 spd:last) |
0 / 空 = 启动后一次都没落过盘(间隔未到、或 interval_secs=0 且还没退出) |
restored_keys / restore_total |
上次启动恢复了多少 / 快照里有多少 | 两者不等 → 有键被跳过(已过期 / 已被新请求写活 / 不在白名单) |
restored_at |
上次恢复时刻,0 = 本进程没发生过恢复 |
刚发版后应等于启动时刻 |
注意
restored_*与last_dump_*都来自共享内存记录(见 §二 / §三), 所有 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→ 快照文件已产出 - 状态页报告的上次落盘时刻非空(
last_dump_at > 0且last_dump_text非空)—— 本套件开 2 个 worker,正是能暴露「每 worker 各一份时刻」分歧的拓扑 - 快照含
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 各一次」:
maybe_dump的慢路径 查共享内存spd:last(见 §二),所以正常运行时不会出现 8 个 worker 各写一遍;DUMPING单飞标记仍是每 worker 的静态量(跨 worker 不互斥),但配合spd:last后并发落盘的窗口极小 —— 代价最多只是几毫秒重复 IO,rename的原子性保证读侧 永远看到完整文件。 - 不影响鉴权与配额:配额(
st:)走的是另一套键,重启清零是有意的 (见 §四)。所以「发版后配额重置」不是 bug。 - 审计容量巡检仍是「每 worker 各自判断」(
llm_audit::LAST_PURGE_AT/PURGING同样是每 worker 静态量):启动时每个 worker 都会purge(true),理论上可能 一并删掉比预期更多的最旧目录。影响面仅限「审计留档比上限更少」, 与统计落盘无关,按已知问题记录(修它需要跨 worker 互斥原语,另案处理)。