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

+6 -4
View File
@@ -201,7 +201,7 @@ POST /openai/v1/chat/completions Authorization: Bearer sk_<本网关签
| `crates/plugin-llm/src/llm.rs` | 热路径:slot 解析、Bearer 提取、身份查询、OpenAI 兼容错误体、三个变量的 get_handler |
| `crates/plugin-llm/src/upstreams.rs` | 上游校验/读写/写穿共享内存,是域名插件在 LLM 侧的翻版;`models` 登记 + `available()` / `models_flat()` 模型发现;**多账号路由**(`pick_account` 粘性 + FNV-1a 冷分散 + 天锚定冷却 `cool_until_until`)、**账号级负载**(`uda:`/`uex:` 日桶,`view()` 投影)、**`normalize_auth`**(裸 key 自动补 `Bearer `,写入 `upsert` + 读出 `read_upa` 双处应用) |
| `crates/plugin-llm/src/stats.rs` | 用量账本(`ust:` 每账号 / `ums:` 每账号×上游,请求级、只读 shm)与 `overview()` 投影;**唯一写点在 `LlmHandler` 鉴权全通过之后** |
| `crates/plugin-llm/src/stats_persist.rs` | 统计落盘/恢复(1.0.18):快照 `data/llm-stats.json`、白名单 `PREFIXES`、退出钩子 + 周期落盘、put-if-absent 恢复、`spr:last` 恢复记录 |
| `crates/plugin-llm/src/stats_persist.rs` | 统计落盘/恢复(1.0.18):快照 `data/llm-stats.json`、白名单 `PREFIXES`、退出钩子 + 周期落盘、put-if-absent 恢复、`spr:last` 恢复记录 / `spd:last` 落盘记录(**都在 shm、都别放进程内静态量**) |
| `data/llm-upstreams.json` | 上游表(**含真实密钥**);`base` 可带路径,`auth` 是完整的 Authorization 值,`models` 仅供模型发现 |
| `conf/nginx.conf` | `lm.mayishangshu.cn:18098` server;SSE 三件套 + `proxy_ssl_server_name` |
| `users.json` → `allowed_models` | 上游白名单;**空 = 不限**(老数据没有该字段,反序列化即空表) |
@@ -246,6 +246,8 @@ token 计费与零依赖红线冲突,别轻易许诺。
启动时 `gateway::init_process` 调 `restore()`,**put-if-absent** → 多 worker 天然幂等、绝不把计数恢复成 N 倍。
⚠️ **新增统计类键前缀必须同步 `stats_persist::PREFIXES`**,漏加不报错、只在发版后表现为「这一列从 0 开始」。
恢复结果发布到 shm(`spr:last`)而不是进程内静态量——否则接口落到哪个 worker 就报哪个数。
**「上次落盘时刻」同理**(`spd:last`,1.0.19):`maybe_dump` 挂在记账路径、每 worker 各算各的,
用静态量会出现「日志落了 10 次、状态页说本进程还没落过」;放 shm 后顺带把周期落盘收敛成「全局每间隔一次」。
接口:`GET /api/admin/stats/persist`(状态)、`POST /api/admin/stats/dump`(强制落一次);
指令 `ipass_stats_persist <秒>`(**生产 conf 刻意不写**,用默认 60,避免旧镜像 unknown directive 起不来)。
**新增统计前缀 = 改 `PREFIXES`**;详情与 runbook 见 `docs/llm/STATS_PERSISTENCE.md`。
@@ -302,7 +304,7 @@ location 与 80 端口 LLM server 是两份拷贝,改一处记得同步另一
| query 参数丢失 | 变量形式的 `proxy_pass` 不会自动追加 args,靠 `llm::upstream_uri` 拼好 |
**本机验证夹具**:`tests/llm/`,由 `bash tests/run.sh llm` 一并起假上游(18999)、LLM 网关(18090)
与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **102 条** + LLM **196 条**
与**管理端口 18091**(跑 `/api/v1/*` 账号态断言)后跑断言。当前规模:网关 **102 条** + LLM **197 条**
(`bash tests/run.sh all`,期望失败 0)。
`tests/llm/upstream.py` 会把收到的 `path` / `auth` / `host` / `body` 记到 `.run/llm/upstream.log`
@@ -619,7 +621,7 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback
夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。
```bash
bash tests/run.sh # 全部 262 项:域名网关 102 条 + LLM 代理 160 条
bash tests/run.sh # 全部 299 项:域名网关 102 条 + LLM 代理 197 条
bash tests/run.sh gateway # 只跑域名网关
bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游)
```
@@ -632,7 +634,7 @@ bash tests/run.sh llm # 只跑 LLM 代理(自动起假上游)
| --- | --- |
| `tests/run.sh` | 统一入口:编译 + 渲染配置 + 起停 + 跑断言 |
| `tests/gateway/e2e.sh` | **102 条断言**:鉴权会话 / 账号(含展示名)/ 申请审核 / 免审 / 越权隔离 / Key 重置 / 上游多模型与用量 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理端与清理 |
| `tests/llm/e2e.sh` | **160 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** |
| `tests/llm/e2e.sh` | **197 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / 限流 / HTTPS / **模型发现** / **账号态用量** / **管理员用量与删账号清用量** /**base_url 端口自适应** / **统计落盘与重启恢复** |
| `tests/.run/` | 运行目录(渲染出的配置、`data/`、`logs/`、cookie)——**已 gitignore,随时可删** |
**两条不许破的线**:
+70
View File
@@ -274,6 +274,72 @@ if body:
'
}
# 统计落盘/恢复状态(1.0.18+)。登录后读 /api/admin/stats/persist。
#
# 为什么值得有:这是「发版后统计还在不在」的唯一线上观测口。
# file_keys ≈ live_keys → 落盘正常(周期落盘在跑)
# file_keys 远小于 live_keys → 周期落盘没跑(查 interval_secs / last_dump_text)
# restored_keys / restore_total → 上次启动恢复情况(不等 = 有键被跳过)
# 首版没有历史快照时 file_exists=false、全都 0,属正常(跑一次 stats-dump 即可造出来)。
# 用法:bash deploy/agent.sh stats-persist
cmd_stats_persist() {
local jar
jar="$(mktemp -t ipass-stats.XXXXXX)"
if ! live_login "$jar"; then
echo "✗ 登录失败"; rm -f "$jar"; return 1
fi
local body
body="$(live_curl -b "$jar" "https://$LIVE_HOST:$LIVE_PORT/api/admin/stats/persist")"
rm -f "$jar"
if [ -z "$PY" ]; then printf '%s\n' "$body"; return 0; fi
printf '%s' "$body" | "$PY" -c '
import json, sys
d = json.load(sys.stdin)
# 统一响应体是 {code,msg,data},成功码 = 200(见 core http::ok)
if d.get("code") not in (200, "200", 0, "0"):
print(" ✗", d.get("msg")); sys.exit(1)
x = d.get("data") or {}
fk, lk = x.get("file_keys", 0), x.get("live_keys", 0)
print(" 快照文件 : %s%s" % (x.get("file") or "-",
"(%s B)" % x.get("file_bytes", 0) if x.get("file_exists") else "(不存在)"))
print(" 落盘间隔 : %s 秒%s" % (x.get("interval_secs"),
"(0=只靠退出钩子)" if x.get("interval_secs") == 0 else ""))
print(" 上次落盘 : %s" % (x.get("last_dump_text") or "(还没落过盘)"))
print(" 键数 : 快照 %d / 内存 %d%s" % (fk, lk,
"" if fk and lk and fk == lk else " <-- 两者长期不等要查原因"))
print(" 上次恢复 : %s(%s/%s 键)" % (x.get("restored_at") and "有" or "无",
x.get("restored_keys", 0), x.get("restore_total", 0)))
if not x.get("file_exists"):
print(" · 提示:尚无快照 —— 跑 `bash deploy/agent.sh stats-dump` 立即造一份")
'
}
# 立刻落盘一次(POST /api/admin/stats/dump),并回读状态确认文件真的写了。
# 用来在不重启、不等 60 秒周期的情况下验证落盘链路。
# 用法:bash deploy/agent.sh stats-dump
cmd_stats_dump() {
local jar body
jar="$(mktemp -t ipass-dump.XXXXXX)"
if ! live_login "$jar"; then
echo "✗ 登录失败"; rm -f "$jar"; return 1
fi
body="$(live_curl -b "$jar" -X POST "https://$LIVE_HOST:$LIVE_PORT/api/admin/stats/dump")"
rm -f "$jar"
if [ -n "$PY" ]; then
printf '%s' "$body" | "$PY" -c '
import json, sys
d = json.load(sys.stdin)
if d.get("code") not in (200, "200", 0, "0"):
print(" ✗ 落盘失败:", d.get("msg")); sys.exit(1)
print(" ✓ 已落盘 %s 键(%s)" % ((d.get("data") or {}).get("keys", "?"), d.get("msg", "")))
' || return 1
else
printf '%s\n' "$body"
fi
echo " · 回读状态:"
cmd_stats_persist
}
CMD="${1:-}"; shift || true
case "$CMD" in
@@ -288,6 +354,8 @@ case "$CMD" in
upstreams) cmd_upstreams ;;
upstream-test) [ -n "${1:-}" ] || { echo "用法: bash deploy/agent.sh upstream-test <slot>" >&2; exit 2; }
cmd_upstream_test "$1" ;;
stats-persist) cmd_stats_persist ;;
stats-dump) cmd_stats_dump ;;
pull) IMG="$(resolve_image "${1:-}")"; echo "· 拉取 $IMG"
post "/pull" "{\"image\":\"$IMG\"}" | pretty ;;
update) IMG="$(resolve_image "${1:-}")"; echo "· 更新到 $IMG"
@@ -326,6 +394,8 @@ iPass 控制面包装(凭据只从 .env 读,命令行里不出现任何 key
bash deploy/agent.sh data users|domains|upstreams
bash deploy/agent.sh upstreams # 上游排障:逐账号掩码/冷却/今日负载
bash deploy/agent.sh upstream-test <slot> # 上游连通性:调测试接口并打印厂商真实响应
bash deploy/agent.sh stats-persist # 统计落盘状态(快照/内存键数、上次恢复)
bash deploy/agent.sh stats-dump # 立即落盘一次并回读状态
变更
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
+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 互斥原语,另案处理)。
+22 -5
View File
@@ -602,7 +602,7 @@ cp -a data /path/to/backup/
夹具在仓库里 `tests/`,**不进 Docker**,直接在本机跑(秒级):
```bash
bash tests/run.sh # 全部:域名网关 102 条 + LLM 代理 179 条
bash tests/run.sh # 全部:域名网关 102 条 + LLM 代理 197 条
bash tests/run.sh gateway # 只跑域名网关
bash tests/run.sh llm # 只跑 LLM 代理
```
@@ -1136,7 +1136,24 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签
`admin.css` + `upstreams.js` 渲染路径做无头浏览器断言(比例条成比例、条块数、悬停日期、无溢出)。
- 专章:`docs/llm/MULTI_ACCOUNT_ROUTING.md`(数据模型 / 路由 / 冷却数学 / shm 布局 / 负载统计)。
- **2026-09-14(续16)统计落盘/恢复 + 审计口径收口(`ipass-1.0.18`,未发版)**
- **2026-09-14(续17)「上次落盘」记录移入共享内存(`ipass-1.0.19`)**
- **起因**:1.0.18 首次线上验证时发现 —— `error.log` 里明明有 10 次 `[stats] 落盘`
(来自 `6#0` / `18#0` / `23#0` 多个 worker),`/api/admin/stats/persist` 却报
「上次落盘:(本进程还没落过)」。
- **根因**:`LAST_DUMP_AT` 是**每 worker 的进程内静态量**。`maybe_dump()` 挂在记账路径上,
记账每 worker 各算各的 → 「上次落盘时刻」也就每 worker 一份;接口落到没落过盘的
worker 就报 0。**与 1.0.18 已修过的 `spr:last`(上次恢复)是同一类错误**。
- **修法**:时刻发布到共享内存 `spd:last`(`publish_dump` 取 `max`;读-改-写无原子性保证、
理论差 ≤1 秒,对状态展示与分钟级节流无影响)。一次解决两件事 —— **上报一致**
(所有 worker 报同一份)+ **节流收敛**(`maybe_dump` 新增慢路径查它,把「8 个 worker
各写一遍同一个文件」收敛成「全局每间隔一次」)。快路径仍是原子比较,热路径代价不变。
- 回归 **299 条全绿**(网关 102 + LLM 197):新增「状态页报告的上次落盘时刻非空」断言 ——
测试套件开 **2 个 worker**,正是能暴露该分歧的拓扑。
- 已知问题(另案):审计容量巡检的 `LAST_PURGE_AT` / `PURGING` 同样是每 worker 静态量,
启动时每个 worker 都会 `purge(true)`,理论上可能多删最旧审计目录;影响面仅「留档比上限更少」,
修它需要跨 worker 互斥原语。见 `docs/llm/STATS_PERSISTENCE.md` §十。
- **2026-09-14(续16)统计落盘/恢复 + 审计口径收口(`ipass-1.0.18`,已发版)**
- **起因**:发版后管理台「用量」与「趋势」从 0 重新长起来。根因是这两类数据
(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`/`uda:`/`uex:`/`uh:`)**只活在共享内存**,
进程退出即消失;而上游/账号/域名/用户都有 `data/*.json` 所以不丢 —— 这个反差是定位关键。
@@ -1159,9 +1176,9 @@ GET /apix/search?q=nginx Authorization: Bearer sk_<本网关签
- **「上次恢复」计数不再放进程内静态量**:`init_process` 每 worker 跑一次、只有第一个 worker 真在写键,
否则接口落到哪个 worker 就报哪个数(运维看到随机值)→ 发布到 shm `spr:last`
(`restored==0` 不写、已有则**累加** + `max(total)`,覆盖 worker 间恢复重叠)。
- 回归 **298 条全绿**(网关 102 + LLM 196;新增【15】段 13 条:间隔压 1 秒 → 快照产出与白名单 →
`nginx -s quit` → 重启后恢复键数 > 0 且 == 快照键数、alice 累计用量不变、再打一笔为 **+1**
而非从 0 重来、趋势日桶仍在、`uda:` 账号负载仍可读)。
- 回归 **299 条全绿**(网关 102 + LLM 197;【15】段 14 条:间隔压 1 秒 → 快照产出与白名单 →
状态页上次落盘时刻非空 → `nginx -s quit` → 重启后恢复键数 > 0 且 == 快照键数、
alice 累计用量不变、再打一笔为 **+1** 而非从 0 重来、趋势日桶仍在、`uda:` 账号负载仍可读)。
- 测试踩坑(**已写进 `CLAUDE.md`**):本机 `safe-delete` 钩子在「同一 turn 累计删除 > 50 个文件」后
会**静默拦掉**后续所有删除(`rm -rf` 与 python `rmtree` 同样被拦),导致清不掉上一轮的
`llm-stats.json` → 被 `restore()` 灌进本轮(carol 用量 2 变 6、上游健康 `unknown` 变 `ok`),
+17
View File
@@ -193,3 +193,20 @@ pub const STATS_SNAPSHOT_VERSION: i64 = 1;
/// —— 管理接口落到哪个 worker 就报哪个数,运维看到的是随机值。放共享内存后
/// 所有 worker 报同一份,`/api/admin/stats/persist` 才可信。
pub const KEY_SPR_PREFIX: &[u8] = b"spr:";
/// 键前缀:统计落盘模块的「上次落盘」记录(键 = `spd:last`,value = `<时刻>`)。
///
/// 与 `KEY_SPR_PREFIX` **同类问题的同一解法**:落盘是每个 worker **各自发生**
/// 的(`maybe_dump` 由记账路径驱动,每个 worker 独立计数),记录若放进程内
/// 静态量,`/api/admin/stats/persist` 落到哪个 worker 就报哪个 worker 自己的
/// 时刻 —— 刚落下盘的 worker 报「刚刚」,另一个没落过的报「还没落过」,
/// 运维看到的是随机值(1.0.18 线上实测就是这个现象)。
///
/// 落在共享内存里一次解决两件事:
/// * **上报一致**:所有 worker 读同一个时刻;
/// * **节流收敛**:`maybe_dump` 慢路径查这一条,把「8 个 worker 各写一遍文件」
/// 收敛成「全局每间隔一次」。见 `stats_persist::maybe_dump`。
///
/// 同样**刻意不在 `stats_persist::PREFIXES` 白名单里**(不是统计量,持久化只会
/// 自我引用)。
pub const KEY_SPD_PREFIX: &[u8] = b"spd:";
+67 -12
View File
@@ -38,14 +38,21 @@
//! 真的在写键,其余全部跳过 —— 用静态量的话 `/api/admin/stats/persist` 落到哪个
//! worker 就报哪个数,运维看到的是随机值。
//!
//! **同一类错误在落盘侧也有一份**:`maybe_dump` 由记账路径驱动、每 worker 独立
//! 计数,所以「上次落盘时刻」同样是每 worker 各一个。1.0.18 首次线上验证就撞上
//! 了 —— 日志里 10 次落盘、状态页却说「本进程还没落过」。解法一样:时刻存
//! `spd:last`(见 `publish_dump`);顺带用它把落盘节流从「每 worker 一次」收敛成
//! 「全局一次」(见 `maybe_dump` 的慢路径)。
//!
//! ## 刻意**不**持久化的东西
//!
//! * **配置类** `up:` / `upa:` / `upe:` / `ax:` / `ukey:` / `sub:` —— 它们各自有
//! 数据文件(`data/*.json`),重启时由 `reload_shm` 装载。再存一份会出现两个真源,
//! 「文件是新的、快照是旧的」时互相覆盖,属于自找的故障。
//! * **`ukb:`**(用户 key → 上游账号粘性)—— 设计上就是重启即重绑(见常量注释)。
//! * **`spr:`**(本模块自己的「上次恢复」记录)—— 恢复过程的元信息,不是统计量,
//! 持久化它只会自我引用。它**只在共享内存里**,为的是让多 worker 报同一份结果。
//! * **`spr:` / `spd:`**(本模块自己的「上次恢复」/「上次落盘」记录)—— 都是过程
//! 元信息,不是统计量,持久化它们只会自我引用。**只在共享内存里**,为的是让
//! 多 worker 报同一份结果。
//! * **内核的** `st:`(配额)/ `rl:`(限流)/ `fail:` / `sess:` —— 语义上重启清零更安全
//! (多送一点额度,好过把用户锁死),且属内核状态,不由本插件代管。
//!
@@ -65,10 +72,10 @@ use serde_json::{Value, json};
use ipass_core::{state, store, util};
use crate::config::{
KEY_SPR_PREFIX, KEY_UDAY_ACCT_PREFIX, KEY_UDAY_PREFIX, KEY_UDAY_SLOT_PREFIX,
KEY_UDAY_USER_PREFIX, KEY_UEX_PREFIX, KEY_UH_PREFIX, KEY_UMS_PREFIX, KEY_UTMS_PREFIX,
KEY_UST_PREFIX, KEY_UTT_PREFIX, STATS_FILE_NAME, STATS_PERSIST_INTERVAL_DEFAULT,
STATS_SNAPSHOT_VERSION,
KEY_SPD_PREFIX, KEY_SPR_PREFIX, KEY_UDAY_ACCT_PREFIX, KEY_UDAY_PREFIX,
KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UEX_PREFIX, KEY_UH_PREFIX, KEY_UMS_PREFIX,
KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, STATS_FILE_NAME,
STATS_PERSIST_INTERVAL_DEFAULT, STATS_SNAPSHOT_VERSION,
};
/// 参与持久化的共享内存前缀(一律以 `:` 结尾,且 `:` 不出现在前缀内部)。
@@ -99,7 +106,11 @@ const SNAP_SEP: char = '\u{1f}';
/// 配置阶段由 `ipass_stats_persist` 设置一次,之后只读。
static INTERVAL: AtomicI64 = AtomicI64::new(STATS_PERSIST_INTERVAL_DEFAULT);
/// 本进程上次落盘时刻(秒);0 = 本进程还没落过盘 → 第一次调用就落。
/// 本 worker 上次落盘时刻(秒);0 = 本 worker 还没落过盘 → 第一次调用就落。
///
/// 这只是**快路径缓存**(无锁原子比较,热路径几乎免费),**不是真源** ——
/// 真源是共享内存 `spd:last`(跨 worker 一致),见 `publish_dump` / `read_dump_at`。
/// 两者配合的理由见 `maybe_dump`。
static LAST_DUMP_AT: AtomicI64 = AtomicI64::new(0);
/// 单飞标记:并发请求同时到点,只放一个进去落盘。
@@ -190,8 +201,10 @@ pub fn dump_now(reason: &str) -> Result<usize, String> {
let n = snap.keys.len();
let p = path();
write_atomic(&p, &text)?;
// 落盘成功才推进时间戳:失败时下次请求会立刻重试,而不是等满一个周期
// 落盘成功才推进时间戳:失败时下次请求会立刻重试,而不是等满一个周期。
// 静态量是本 worker 的快路径缓存;共享内存那份是跨 worker 的真源(供上报 + 节流)。
LAST_DUMP_AT.store(now, Ordering::Relaxed);
publish_dump(now);
util::log_info(&format!(
"[stats] 落盘 {n} 键({} B,{reason})-> {}",
text.len(),
@@ -200,9 +213,41 @@ pub fn dump_now(reason: &str) -> Result<usize, String> {
Ok(n)
}
/// 把「上次落盘时刻」发布到共享内存,供**所有** worker 一致地上报与节流。
///
/// 与 `publish_restore` 是同一类问题的同一解法(见 `KEY_SPD_PREFIX` 注释)。
/// 与恢复侧唯一不同:落盘**不需要累加**,只要记住最近一次的时刻,
/// 所以取 `max` 而不是相加。
///
/// 这里是「读-改-写」,没有原子性保证:两个 worker 同一瞬间落盘时,理论上可能出现
/// 后写入的是稍早的时刻(差 ≤1 秒)。对本用途(状态页展示 + 分钟级节流)无影响,
/// 不值得为它引入跨 worker 的 CAS —— `state` 层本来也没有这个原语。
fn publish_dump(at: i64) {
let prev = read_dump_at();
let v = at.max(prev).to_string();
if !state::put(KEY_SPD_PREFIX, b"last", v.as_bytes(), 0) {
util::log_err("[stats] 发布落盘时刻到共享内存失败(仅影响状态展示与节流)");
}
}
/// 读回「上次落盘时刻」(跨 worker 共享)。没有记录则 0。
fn read_dump_at() -> i64 {
state::get(KEY_SPD_PREFIX, b"last")
.and_then(|(payload, _)| payload.trim().parse::<i64>().ok())
.unwrap_or(0)
}
/// 按间隔节流落盘。**由记账路径每次请求调用一次**(见 `stats::record`)。
///
/// 间隔内直接返回:一次原子 load + 比较,热路径代价可忽略。
/// 两级判断,热路径代价仍是一次原子比较:
/// * **快路径**(绝大多数请求走这里):本 worker 自己在 `iv` 秒内落过 → 直接返回;
/// * **慢路径**(每 worker 每 `iv` 秒最多进一次):本 worker 没落过,但**别的** worker
/// 可能刚落过 —— 读一次 `spd:last` 确认。读到的时刻回填本地缓存,
/// 于是下一个 `iv` 秒内的请求又全部走快路径。
///
/// 慢路径那一下把落盘从「8 个 worker 各写一遍同一个文件」收敛成「全局每 `iv` 秒一次」,
/// 同时也让状态页读到的时刻与节流依据是同一份数据,不会自相矛盾。
///
/// 间隔设为 0 = 关闭周期落盘,此时这里退化为纯判断。
pub fn maybe_dump() {
let iv = interval();
@@ -210,10 +255,18 @@ pub fn maybe_dump() {
return;
}
let now = util::now();
let last = LAST_DUMP_AT.load(Ordering::Relaxed);
if last != 0 && now - last < iv {
let local = LAST_DUMP_AT.load(Ordering::Relaxed);
if local != 0 && now - local < iv {
return;
}
let shared = read_dump_at();
if shared != 0 && now - shared < iv {
LAST_DUMP_AT.store(shared, Ordering::Relaxed); // 回填缓存,别每次请求都读共享内存
return;
}
if DUMPING.swap(true, Ordering::Acquire) {
return; // 同 worker 内已有一个在落盘
}
@@ -387,7 +440,9 @@ pub fn status() -> Value {
.sum();
let (restore_at, restore_ok, restore_total) = read_restore();
let last_dump = LAST_DUMP_AT.load(Ordering::Relaxed);
// 读共享内存而不是本 worker 静态量:落盘是每 worker 各自发生的,
// 用静态量会出现「日志明明落了 10 次、状态页却说本进程还没落过」(见 KEY_SPD_PREFIX)。
let last_dump = read_dump_at();
json!({
"file": p.display().to_string(),
+5 -5
View File
@@ -3,9 +3,9 @@
改完 `rust/` 或 `conf/` 后跑这里,别靠手敲 curl 试。
```bash
bash tests/run.sh # 全部(域名网关 + LLM 代理)
bash tests/run.sh gateway # 只跑域名网关(90 条断言)
bash tests/run.sh llm # 只跑 LLM 代理(111 条断言)
bash tests/run.sh # 全部(域名网关 102 条 + LLM 代理 197 条 = 299)
bash tests/run.sh gateway # 只跑域名网关(102 条断言)
bash tests/run.sh llm # 只跑 LLM 代理(197 条断言)
```
脚本会自动 `cargo build`,起 nginx,跑断言,收尾停进程。**期望输出「失败 0」。**
@@ -16,12 +16,12 @@ bash tests/run.sh llm # 只跑 LLM 代理(111 条断言)
| --- | --- |
| `run.sh` | 统一入口:编译 → 渲染配置 → 起进程 → 跑断言 → 收尾 |
| `gateway/nginx.conf.in` | 域名网关测试配置**模板**(占位符 `@MODULE@` / `@REPO@` / `@RUN@`) |
| `gateway/e2e.sh` | **90 条断言**:鉴权会话 / 账号 / 申请审核 / 免审 / 越权隔离 / Key 重置 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理台与清理 |
| `gateway/e2e.sh` | **102 条断言**:鉴权会话 / 账号 / 申请审核 / 免审 / 越权隔离 / Key 重置 / **自动子域名(`i`+8位+`dm`)与点击复制** / 管理台与清理 |
| `gateway/backend/index.html` | 转发靶机内容(断言里检查 `"from":"backend"`) |
| `llm/nginx.conf.in` | LLM 代理测试配置模板(18090 网关 + **18091 管理端口**,供账号态 `/api/v1/*` 断言) |
| `llm/upstream.py` | 假上游(18999):**记录它实际收到的 path / auth / host / body**;`/<slot>/v1/models` 原样透传 |
| `llm/sse_test.py` | 流式探针:输出 `CHUNKS` / `FIRST` / `TOTAL`,判断 SSE 有没有被缓冲 |
| `llm/e2e.sh` | **111 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / **模型发现** / **账号态用量** / **管理员用量总览与删账号清用量** |
| `llm/e2e.sh` | **197 条断言**:鉴权 / 白名单 / 停用摘除 / **Key 替换** / 路径拼接(含版本段去重)/ SSE / **模型发现** / **账号态用量** / **管理员用量总览与删账号清用量** / **统计落盘与重启恢复** |
| `llm/fixtures/*.json` | 固定账号与上游表(**合成数据**,见下) |
| `.run/` | 运行目录(生成的 `nginx.conf`、`data/`、`logs/`、`cookie.jar`)—— 已 gitignore |
+1 -1
View File
@@ -1,6 +1,6 @@
#!/bin/bash
# ============================================================================
# 域名网关 · 端到端回归(90 条断言)
# 域名网关 · 端到端回归(102 条断言)
#
# 一般不用直接跑,走统一入口: bash tests/run.sh gateway
# 直接跑需自行保证 nginx 已按 tests/gateway/nginx.conf.in 渲染并启动,且
+9
View File
@@ -713,6 +713,15 @@ done
sleep 1.5 # > 间隔 1 秒:保证周期性落盘已经跑过一次
ck "★周期落盘已产出快照文件" yes "$([ -s "$STATS" ] && echo yes || echo no)"
# 落盘时刻必须从共享内存读(`spd:last`),而不是各 worker 自己的静态量 —— 否则
# 「日志明明落了 N 次、状态页却说本进程还没落过」(1.0.18 首次线上验证实测)。
# 本套件开 2 个 worker,正是能暴露该分歧的拓扑;断言看的是「任意 worker 都报得出」。
ck "★状态页报告的上次落盘时刻非空(跨 worker 一致)" yes \
"$(curl -s -b "$JAR" "$API/api/admin/stats/persist" | "$PY" -c "
import json, sys
d = json.load(sys.stdin)['data']
print('yes' if d.get('last_dump_at', 0) > 0 and d.get('last_dump_text') else 'no')
" 2>/dev/null)"
ck "★快照含账号级用量键(ust:alice)" yes \
"$("$PY" -c "
import json, sys
+1 -1
View File
@@ -3,7 +3,7 @@
# 本机回归 · 统一入口
#
# bash tests/run.sh # 跑全部(域名网关 + LLM 代理)
# bash tests/run.sh gateway # 只跑域名网关(90 条断言)
# bash tests/run.sh gateway # 只跑域名网关(102 条断言)
# bash tests/run.sh llm # 只跑 LLM 代理
#
# 前置:本机 nginx 已编译好(默认 /Users/xs/Desktop/workspace/iPass/build/ngxbuild/nginx-1.30.4/objs/nginx),