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)。
This commit is contained in:
admin committed 2026-09-14 20:05:51 +08:00
1 parent 16cf68d132
commit 1bc316e014
11 files changed
+255 -41

No files matched your search

+2 -1
View File
@@ -186,7 +186,8 @@ log : read_llm_acct(r) 取本次选中账号(NOCACHEABLE,与 access 同
## 九、验证
- **本机回归**:`tests/llm/e2e.sh` 多账号组(粘性 + 耗尽自动切换 + 靶机真收 Key + 账号级负载分布),
全量 `bash tests/run.sh all` 期望 **279 条断言全绿**(gateway 102 + llm 177)。
全量 `bash tests/run.sh all` 期望**全绿**(写这段时是 279 条;条数随迭代增长,
当前见 `CLAUDE.md`「本机验证夹具」一节)。
假上游 `upstream.py` 支持 `UPSTREAM_FAIL_AUTH` 环境变量模拟「账号额度耗尽」。
- **真 MiniMax 双 Key 实测**:key1 稳定 200 + 粘性 `acct=0`;key1 失效 → 自动切 key2(`acct=1`,200)。
真 Key 仅存临时目录、测完即删,不入库。
+55 -12
View File
@@ -1,6 +1,6 @@
# 运行期统计的落盘与恢复(发版不再清零用量 / 趋势)
> 适用版本:`ipass-1.0.18`(插件化后的 `plugin-llm`)。
> 适用版本:`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`。
@@ -64,6 +64,38 @@ data/llm-stats.json # 与 users.json / llm-upstreams.json 同级
> 刻意**不复用** `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` 原子、谁赢都对)。收敛的只是**周期**落盘。
---
## 三、恢复语义
@@ -131,6 +163,7 @@ worker 2 再来一遍 → 键已存在 → 全部跳过
| `up:` / `upa:` / `upe:` / `ax:` / `ukey:` / `sub:` | **各自有数据文件**(`data/*.json`),重启由 `reload_shm` 装载。再存一份会出现**两个真源**——「文件是新的、快照是旧的」时互相覆盖,属于自找的故障 |
| `ukb:` | 用户 Key → 上游账号粘性,设计上就是**重启即重绑** |
| `spr:` | 本模块自己的「上次恢复」记录。恢复过程的元信息、不是统计量,持久化它只会自我引用 |
| `spd:` | 本模块自己的「上次落盘」记录。同上——**只在共享内存里**,为的是让多 worker 报同一份结果并共用一份节流依据 |
| `st:` / `rl:` / `fail:` / `sess:` | 内核状态(配额 / 限流 / 登录会话)。语义上重启清零**更安全**(多送一点额度好过把用户锁死),且不由本插件代管 |
> ⚠️ 新增统计类键前缀时,**必须同步 `stats_persist::PREFIXES`**,否则该维度发版即清零——
@@ -200,7 +233,7 @@ http {
```json
{
"code": 0, "msg": "ok",
"code": 200, "msg": "ok",
"data": {
"file": "/usr/local/nginx/data/llm-stats.json",
"file_exists": true,
@@ -225,11 +258,12 @@ http {
|---|---|---|
| `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_*` 来自共享内存记录(见 §三),**所有 worker 报同一份**,
> 不会因为请求落到哪个 worker 而变。
> 注意 `restored_*` 与 `last_dump_*` 都来自共享内存记录(见 §二 / §三),
> **所有 worker 报同一份**,不会因为请求落到哪个 worker 而变。
---
@@ -282,12 +316,14 @@ curl -s -b /tmp/cookie.jar 'http://<host>:18099/api/admin/trend?days=7'
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:` 账号级负载仍可读
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`(留档,不删)——
@@ -311,7 +347,14 @@ curl -s -b /tmp/cookie.jar 'http://<host>:18099/api/admin/trend?days=7'
- **不是备份**:快照只有一份、覆盖写。要长期归档请自行拷走 `data/llm-stats.json`。
- **不跨版本迁移**:`version` 变了就不恢复(宁可从零开始)。升级时若希望保留统计,
需同步 bump `STATS_SNAPSHOT_VERSION` 并写转换逻辑(当前不需要)。
- **多 worker 落盘是「白写几次」**:`DUMPING` 单飞标记是**每 worker** 的静态量,
跨 worker 不互斥。代价只是几毫秒重复 IO,`rename` 的原子性保证读侧永远看到完整文件。
- **周期落盘收敛成「全局一次」,退出钩子仍是「每 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 互斥原语,另案处理)。