Files
ipass__ipass/docs/llm/STATS_PERSISTENCE.md
admin 1bc316e014 fix(stats): 「上次落盘」记录移入共享内存(1.0.19)
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)。
2026-09-14 20:05:51 +08:00

18 KiB
Raw Permalink Blame History

运行期统计的落盘与恢复(发版不再清零用量 / 趋势)

适用版本: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 带来的三个性质

  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: 本模块自己的「上次恢复」记录。恢复过程的元信息、不是统计量,持久化它只会自我引用
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. 落盘间隔被压到 1 秒(读 /api/admin/stats/persist 的 interval_secs)
  2. 跑几笔请求 + sleep 1.5 → 快照文件已产出
  3. 状态页报告的上次落盘时刻非空(last_dump_at > 0 且 last_dump_text 非空)—— 本套件开 2 个 worker,正是能暴露「每 worker 各一份时刻」分歧的拓扑
  4. 快照含 ust:alice、含 ud: 日桶
  5. 快照不含凭据类配置键(up: / upa: / upe: / ax: / ukey: / sub:)
  6. nginx -s quit(等价于生产 docker stop)→ 重新拉起
  7. 重新登录后:restored_keys > 0、restored_keys == restore_total
  8. alice 累计用量不变;再打一笔后 = 原值 + 1(证明是「接着长」而不是从 0 开始)
  9. 趋势日桶仍在;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 各一次」: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 互斥原语,另案处理)。