//! 运行期统计的**落盘 / 恢复**:让用量统计与趋势图熬过一次重启。 //! //! ## 为什么需要它(1.0.18 之前的实际故障) //! //! 共享内存是 nginx 每进程启动时 `mmap` 出来的匿名区,**进程退出即消失**。 //! 而用量统计(`ust:`/`ums:`/`utt:`/`utms:`/`ud:`/`udu:`/`uds:`/`uda:`/`uex:`) //! 全部只活在共享内存里 —— 于是「每次发版 = 统计与趋势清零」, //! 用量页与趋势图在发版后从 0 重新长起来。 //! //! 不引入数据库(项目红线),做法就是**一个 JSON 快照**,与 //! `users.json`/`llm-upstreams.json` 同级落在 `data/` 下;`data/` 是宿主挂载卷, //! 容器重建也不丢。 //! //! ## 两个落盘点(互补,不是二选一) //! //! | 触发 | 时机 | 覆盖场景 | //! | --- | --- | --- | //! | **worker 退出钩子** | `exit_process`(gateway 注册) | 发版 / `docker stop` / `nginx -s quit` ——**零丢失** | //! | **周期性节流落盘** | log 阶段记账后,默认 60 秒一次 | SIGKILL / OOM / 断电 —— 最多丢一个周期 | //! //! 退出钩子是主力:`docker stop` 发的是镜像里声明的 `STOPSIGNAL=SIGQUIT` //! (优雅停机),`SIGTERM` 也走同一条 worker 退出路径,两者都会调到 `exit_process`。 //! 只有 `SIGKILL` 绕过它,那由周期落盘兜住。 //! //! ## 恢复语义:**只在键不存在时写入**(put-if-absent) //! //! 三个性质一次拿到: //! * 重启后共享内存是空的 → 所有键都「不存在」→ 全量恢复; //! * 多 worker 各跑一遍 `init_process` → 第二个起键已存在 → 跳过,**天然幂等**, //! 不会把计数恢复成 N 倍; //! * 恢复期间若有新请求已经把某个键写活 → **不覆盖**,宁可少恢复一条, //! 也不打死刚产生的新数据。 //! //! 已过期(`exp <= now`)的键不恢复:日桶的 90 天保留期不能因为一次重启被续命。 //! //! 恢复结果(恢复了多少 / 快照里有多少)**发布到共享内存**(`spr:last`), //! 而不是放进程内静态量:`init_process` 每 worker 跑一次,只有第一个 worker //! 真的在写键,其余全部跳过 —— 用静态量的话 `/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:` / `spd:`**(本模块自己的「上次恢复」/「上次落盘」记录)—— 都是过程 //! 元信息,不是统计量,持久化它们只会自我引用。**只在共享内存里**,为的是让 //! 多 worker 报同一份结果。 //! * **内核的** `st:`(配额)/ `rl:`(限流)/ `fail:` / `sess:` —— 语义上重启清零更安全 //! (多送一点额度,好过把用户锁死),且属内核状态,不由本插件代管。 //! //! ## 容量 //! //! 一个键一行;键数 = 账号数 × slot 数 + 90 天 × (1 + 账号数 + slot 数 + 账号 × 上游数)。 //! 十来个账号的规模下是几十 KB,写好一次几毫秒 —— 与「每请求都写」的量级完全不同。 //! 详细口径与运维见 `docs/llm/STATS_PERSISTENCE.md`。 use std::collections::BTreeMap; use std::path::PathBuf; use std::sync::atomic::{AtomicBool, AtomicI64, Ordering}; use serde::{Deserialize, Serialize}; use serde_json::{Value, json}; use ipass_core::{state, store, util}; use crate::config::{ 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, KEY_USER_SUM_PREFIX, STATS_FILE_NAME, STATS_PERSIST_INTERVAL_DEFAULT, STATS_SNAPSHOT_VERSION, }; /// 参与持久化的共享内存前缀(一律以 `:` 结尾,且 `:` 不出现在前缀内部)。 /// /// 顺序无关,但保持一致(状态接口按此顺序统计 key 数)。 /// 排除项的理由见模块注释「刻意不持久化的东西」。 const PREFIXES: &[&[u8]] = &[ KEY_UST_PREFIX, // 账号维度请求数 KEY_UMS_PREFIX, // 账号 × 上游 请求数 KEY_UTT_PREFIX, // 账号维度 token KEY_UTMS_PREFIX, // 账号 × 上游 token KEY_UDAY_PREFIX, // 全局日桶(趋势图总览) KEY_UDAY_USER_PREFIX, // 按账号日桶 KEY_UDAY_SLOT_PREFIX, // 按上游日桶 KEY_UDAY_ACCT_PREFIX, // 按上游账号日桶(「各 Key 负载」) KEY_UEX_PREFIX, // 账号额度耗尽次数日桶 KEY_UH_PREFIX, // 上游健康展示缓存 KEY_USER_SUM_PREFIX, // 每用户聚合缓存(1.0.32 /api/v1/me 增量) ]; /// 快照值里的分隔符:`\x1f`。 /// /// 复用共享内存的 `VAL_SEP`(0x1f)而不是自定义一个:语义完全一样 /// (payload 里不会出现该字节,因为内核写共享内存时就是这么切的), /// 少一个常量少一处不一致。JSON 序列化时 serde 会把它转义成 `\u001f`。 const SNAP_SEP: char = '\u{1f}'; /// 落盘间隔(秒);`0` = 关闭周期落盘(只保留退出钩子那一次)。 /// 配置阶段由 `ipass_stats_persist` 设置一次,之后只读。 static INTERVAL: AtomicI64 = AtomicI64::new(STATS_PERSIST_INTERVAL_DEFAULT); /// 本 worker 上次落盘时刻(秒);0 = 本 worker 还没落过盘 → 第一次调用就落。 /// /// 这只是**快路径缓存**(无锁原子比较,热路径几乎免费),**不是真源** —— /// 真源是共享内存 `spd:last`(跨 worker 一致),见 `publish_dump` / `read_dump_at`。 /// 两者配合的理由见 `maybe_dump`。 static LAST_DUMP_AT: AtomicI64 = AtomicI64::new(0); /// 单飞标记:并发请求同时到点,只放一个进去落盘。 /// 注意这是**每 worker** 的静态量(跨 worker 不互斥)——多个 worker 同时落盘 /// 只是白写几次同样的内容,`rename` 是原子的,不会有半个文件被人读到。 static DUMPING: AtomicBool = AtomicBool::new(false); #[derive(Debug, Serialize, Deserialize)] struct Snapshot { version: i64, saved_at: i64, #[serde(default)] saved_at_text: String, #[serde(default)] keys: BTreeMap, } // =========================================================================== // 配置 // =========================================================================== /// `ipass_stats_persist <秒>`:周期落盘间隔。`0` = 只靠 worker 退出钩子。 pub fn set_interval(secs: i64) { INTERVAL.store(secs.max(0), Ordering::Relaxed); } pub fn interval() -> i64 { INTERVAL.load(Ordering::Relaxed) } fn path() -> PathBuf { store::path_in_data(STATS_FILE_NAME) } // =========================================================================== // 落盘 // =========================================================================== /// 原子写:先写 `.tmp.` 再 `rename`。 /// /// 不复用 `store::write_json` 的原因:它用固定的 `.tmp`,多 worker 同时落盘 /// 会互相踩临时文件(一个 rename 走了,另一个还在往里写同名文件)。 /// 带 pid 后缀后各写各的,`rename` 本身是原子的,最后一个赢 —— 而内容本来就 /// 只是「同一份共享内存的近似快照」,谁赢都对。 /// /// 也**不复用** `state::file_lock()`:那道锁是给「读文件→改→写文件」防丢失用的, /// 本函数是纯覆盖写、不读旧值,拿锁只会在退出路径上增加卡死风险。 fn write_atomic(path: &PathBuf, text: &str) -> Result<(), String> { let tmp = PathBuf::from(format!("{}.tmp.{}", path.display(), std::process::id())); std::fs::write(&tmp, text.as_bytes()).map_err(|e| { let _ = std::fs::remove_file(&tmp); format!("写入 {} 失败:{e}", tmp.display()) })?; std::fs::rename(&tmp, path).map_err(|e| { let _ = std::fs::remove_file(&tmp); format!("重命名到 {} 失败:{e}", path.display()) }) } /// 立刻落盘(不看间隔)。返回写入的键数。 /// /// `reason` 只进日志,用于事后分辨这次是谁触发的(`worker-exit` / `periodic` / `admin`)。 pub fn dump_now(reason: &str) -> Result { let now = util::now(); let mut keys: BTreeMap = BTreeMap::new(); for p in PREFIXES { // 前缀都是 ASCII 字面量,from_utf8 不会失败 let Some(pfx) = core::str::from_utf8(p).ok() else { continue; }; for (name, payload, exp) in state::iter_prefix_ex(p) { // 已过期的键不带回:日桶的 90 天保留期不能靠重启续命 if exp != 0 && exp <= now { continue; } keys.insert(format!("{pfx}{name}"), format!("{payload}{SNAP_SEP}{exp}")); } } let snap = Snapshot { version: STATS_SNAPSHOT_VERSION, saved_at: now, saved_at_text: util::fmt_time(now), keys, }; let text = serde_json::to_string(&snap).map_err(|e| format!("序列化失败:{e}"))?; 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(), p.display() )); 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`)。 /// /// 两级判断,热路径代价仍是一次原子比较: /// * **快路径**(绝大多数请求走这里):本 worker 自己在 `iv` 秒内落过 → 直接返回; /// * **慢路径**(每 worker 每 `iv` 秒最多进一次):本 worker 没落过,但**别的** worker /// 可能刚落过 —— 读一次 `spd:last` 确认。读到的时刻回填本地缓存, /// 于是下一个 `iv` 秒内的请求又全部走快路径。 /// /// 慢路径那一下把落盘从「8 个 worker 各写一遍同一个文件」收敛成「全局每 `iv` 秒一次」, /// 同时也让状态页读到的时刻与节流依据是同一份数据,不会自相矛盾。 /// /// 间隔设为 0 = 关闭周期落盘,此时这里退化为纯判断。 pub fn maybe_dump() { let iv = interval(); if iv <= 0 { return; } let now = util::now(); 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 内已有一个在落盘 } let r = dump_now("periodic"); DUMPING.store(false, Ordering::Release); if let Err(e) = r { util::log_err(&format!("[stats] 周期落盘失败:{e}")); } } // =========================================================================== // 恢复 // =========================================================================== /// 拆快照值 `payload \x1f exp`。 /// /// 用 `rposition` 与内核 `split_value` 同款理由:`exp` 是 ASCII 数字串、 /// 不含分隔符,所以**最后一个**分隔符才是真边界。 fn split_value(v: &str) -> Option<(&str, i64)> { let i = v.rfind(SNAP_SEP)?; let exp = v[i + SNAP_SEP.len_utf8()..].parse::().ok()?; Some((&v[..i], exp)) } /// 把本次恢复结果发布到共享内存,供**所有** worker 一致地报告(见 `KEY_SPR_PREFIX` 注释)。 /// /// 两个要点: /// * `restored == 0` 的 worker **不写** —— 它只是「来晚了、键已存在」的观察者, /// 用自己的 0 覆盖真实结果就等于把这次恢复从记录里抹掉。 /// * 已有记录时**累加**而不是覆盖:master 是顺序 fork 的,但两个 worker 的 /// `init_process` 仍可能重叠,各恢复一半(put-if-absent 决定谁抢到哪批键)。 /// 累加 + `max(total)` 才能拼出完整结果。 fn publish_restore(at: i64, restored: usize, total: usize) { if restored == 0 { return; } let (prev_at, prev_ok, prev_total) = match state::get(KEY_SPR_PREFIX, b"last") { Some((payload, _)) => parse_restore(&payload).unwrap_or((0, 0, 0)), None => (0, 0, 0), }; let v = format!( "{}{SNAP_SEP}{}{SNAP_SEP}{}", at.max(prev_at), prev_ok + restored, prev_total.max(total) ); if !state::put(KEY_SPR_PREFIX, b"last", v.as_bytes(), 0) { util::log_err("[stats] 发布恢复记录到共享内存失败(仅影响状态展示)"); } } /// 解析 `spr:last` 的 payload:`<时刻> \x1f <恢复键数> \x1f <快照键数>`。 fn parse_restore(payload: &str) -> Option<(i64, usize, usize)> { let mut it = payload.split(SNAP_SEP); let at = it.next()?.parse::().ok()?; let ok = it.next()?.parse::().ok()?; let total = it.next()?.parse::().ok()?; Some((at, ok, total)) } /// 读回「上次恢复」记录:`(恢复时刻, 恢复键数, 快照键数)`。没有记录则全 0。 fn read_restore() -> (i64, usize, usize) { state::get(KEY_SPR_PREFIX, b"last") .and_then(|(payload, _)| parse_restore(&payload)) .unwrap_or((0, 0, 0)) } /// worker 启动时把快照灌回共享内存。每个 worker 都会调一次(幂等,见模块注释)。 /// /// 任何异常都只降级:审计/统计都是旁路,绝不能让 worker 起不来。 pub fn restore() { let p = path(); let text = match std::fs::read_to_string(&p) { Ok(t) => t, // 首次部署本来就没有快照,不算错误 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return, Err(e) => { util::log_err(&format!("[stats] 读取快照失败 {}:{e}", p.display())); return; } }; if text.trim().is_empty() { return; } let snap: Snapshot = match serde_json::from_str(&text) { Ok(s) => s, Err(e) => { // 解析不了就**改名留档**再走:否则第一个请求到点就会用「空共享内存」 // 覆盖掉这份文件,把唯一的副本抹掉,连现场都没得查。 let bad = PathBuf::from(format!("{}.bad", p.display())); let moved = std::fs::rename(&p, &bad); util::log_err(&format!( "[stats] 快照解析失败({e}),已{},本次不恢复统计", match moved { Ok(()) => format!("改名留档到 {}", bad.display()), Err(me) => format!("尝试改名留档但失败({me})"), } )); return; } }; if snap.version != STATS_SNAPSHOT_VERSION { util::log_err(&format!( "[stats] 快照版本 {} 与当前 {} 不符,不恢复(宁可从零开始)", snap.version, STATS_SNAPSHOT_VERSION )); return; } let now = util::now(); let total = snap.keys.len(); let mut restored = 0usize; for (k, v) in &snap.keys { let kb = k.as_bytes(); let Some(pfx) = PREFIXES.iter().find(|p| kb.starts_with(p)) else { continue; // 不在白名单(旧版本写的 / 手改的)→ 忽略 }; let Some((payload, exp)) = split_value(v) else { continue; }; if exp != 0 && exp <= now { continue; // 已过期 } let name = &kb[pfx.len()..]; if name.is_empty() { continue; } if state::get(pfx, name).is_some() { continue; // 已被新请求写活 → 不覆盖 } if state::put(pfx, name, payload.as_bytes(), exp) { restored += 1; } } publish_restore(now, restored, total); util::log_notice(&format!( "[stats] 已从快照恢复 {restored}/{total} 键({})", p.display() )); } // =========================================================================== // 状态(管理接口) // =========================================================================== /// `/api/admin/stats/persist` 的响应体:快照文件状态 + 当前共享内存键数。 /// /// 「文件里有多少键」与「共享内存里现在有多少键」分开给:两者长期接近说明 /// 落盘正常;文件远小于内存 = 周期落盘没跑(或刚重启还没到点)。 pub fn status() -> Value { let p = path(); let text = std::fs::read_to_string(&p).ok(); let (saved_at, saved_at_text, file_keys) = match text.as_deref().map(serde_json::from_str::) { Some(Ok(s)) => (s.saved_at, s.saved_at_text, s.keys.len()), _ => (0, String::new(), 0), }; let file_bytes = std::fs::metadata(&p).map(|m| m.len()).unwrap_or(0); let live: usize = PREFIXES .iter() .map(|pfx| { let now = util::now(); state::iter_prefix_ex(pfx) .into_iter() .filter(|(_, _, exp)| *exp == 0 || *exp > now) .count() }) .sum(); let (restore_at, restore_ok, restore_total) = read_restore(); // 读共享内存而不是本 worker 静态量:落盘是每 worker 各自发生的, // 用静态量会出现「日志明明落了 10 次、状态页却说本进程还没落过」(见 KEY_SPD_PREFIX)。 let last_dump = read_dump_at(); json!({ "file": p.display().to_string(), "file_exists": text.is_some(), "file_bytes": file_bytes, "file_keys": file_keys, "saved_at": saved_at, "saved_at_text": saved_at_text, "live_keys": live, "interval_secs": interval(), "last_dump_at": last_dump, "last_dump_text": if last_dump > 0 { util::fmt_time(last_dump) } else { String::new() }, "restored_at": restore_at, "restored_keys": restore_ok, "restore_total": restore_total, }) }