From 1bc316e014f9814d332e43633faee1b1f40cba41 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 14 Sep 2026 20:05:51 +0800 Subject: [PATCH] =?UTF-8?q?fix(stats):=20=E3=80=8C=E4=B8=8A=E6=AC=A1?= =?UTF-8?q?=E8=90=BD=E7=9B=98=E3=80=8D=E8=AE=B0=E5=BD=95=E7=A7=BB=E5=85=A5?= =?UTF-8?q?=E5=85=B1=E4=BA=AB=E5=86=85=E5=AD=98=EF=BC=881.0.19=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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)。 --- CLAUDE.md | 10 +-- deploy/agent.sh | 70 ++++++++++++++++++ docs/llm/MULTI_ACCOUNT_ROUTING.md | 3 +- docs/llm/STATS_PERSISTENCE.md | 67 +++++++++++++---- readme.md | 27 +++++-- rust/crates/plugin-llm/src/config.rs | 17 +++++ rust/crates/plugin-llm/src/stats_persist.rs | 79 +++++++++++++++++---- tests/README.md | 10 +-- tests/gateway/e2e.sh | 2 +- tests/llm/e2e.sh | 9 +++ tests/run.sh | 2 +- 11 files changed, 255 insertions(+), 41 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ed25be4..3d38b6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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,随时可删** | **两条不许破的线**: diff --git a/deploy/agent.sh b/deploy/agent.sh index 013307e..ba66624 100755 --- a/deploy/agent.sh +++ b/deploy/agent.sh @@ -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 " >&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 # 上游连通性:调测试接口并打印厂商真实响应 + bash deploy/agent.sh stats-persist # 统计落盘状态(快照/内存键数、上次恢复) + bash deploy/agent.sh stats-dump # 立即落盘一次并回读状态 变更 bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG) diff --git a/docs/llm/MULTI_ACCOUNT_ROUTING.md b/docs/llm/MULTI_ACCOUNT_ROUTING.md index 6d669a2..e24e729 100644 --- a/docs/llm/MULTI_ACCOUNT_ROUTING.md +++ b/docs/llm/MULTI_ACCOUNT_ROUTING.md @@ -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 仅存临时目录、测完即删,不入库。 diff --git a/docs/llm/STATS_PERSISTENCE.md b/docs/llm/STATS_PERSISTENCE.md index c38a789..273b847 100644 --- a/docs/llm/STATS_PERSISTENCE.md +++ b/docs/llm/STATS_PERSISTENCE.md @@ -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://: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..json`(留档,不删)—— @@ -311,7 +347,14 @@ curl -s -b /tmp/cookie.jar 'http://: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 互斥原语,另案处理)。 diff --git a/readme.md b/readme.md index bf43f45..e9ef942 100755 --- a/readme.md +++ b/readme.md @@ -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`), diff --git a/rust/crates/plugin-llm/src/config.rs b/rust/crates/plugin-llm/src/config.rs index 465ef51..13b2c6a 100644 --- a/rust/crates/plugin-llm/src/config.rs +++ b/rust/crates/plugin-llm/src/config.rs @@ -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:"; diff --git a/rust/crates/plugin-llm/src/stats_persist.rs b/rust/crates/plugin-llm/src/stats_persist.rs index dbae24c..7980554 100644 --- a/rust/crates/plugin-llm/src/stats_persist.rs +++ b/rust/crates/plugin-llm/src/stats_persist.rs @@ -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 { 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 { 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::().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(), diff --git a/tests/README.md b/tests/README.md index 6c2a18a..0a54c29 100644 --- a/tests/README.md +++ b/tests/README.md @@ -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**;`//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 | diff --git a/tests/gateway/e2e.sh b/tests/gateway/e2e.sh index 90a0aa0..b966937 100755 --- a/tests/gateway/e2e.sh +++ b/tests/gateway/e2e.sh @@ -1,6 +1,6 @@ #!/bin/bash # ============================================================================ -# 域名网关 · 端到端回归(90 条断言) +# 域名网关 · 端到端回归(102 条断言) # # 一般不用直接跑,走统一入口: bash tests/run.sh gateway # 直接跑需自行保证 nginx 已按 tests/gateway/nginx.conf.in 渲染并启动,且 diff --git a/tests/llm/e2e.sh b/tests/llm/e2e.sh index 56a40ff..79121b0 100755 --- a/tests/llm/e2e.sh +++ b/tests/llm/e2e.sh @@ -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 diff --git a/tests/run.sh b/tests/run.sh index 90a210e..313d516 100755 --- a/tests/run.sh +++ b/tests/run.sh @@ -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),