Files
ipass-plugin-cache/rust/crates/plugin-llm/src/stats_persist.rs
T
ssw 43718bd0c4 iPass cache gateway 源码
容量管理: zones.rs 直读 nginx file_cache 共享内存记账(双轴: 磁盘 + keys_zone 索引内存), ?scan=1 扫盘上限 20 万文件; POST /api/admin/cache/purge 整区清理(只删文件不删目录, 根治 [crit] mkdir failed); POST /api/admin/cache/invalidate 按制品精准失效(预览->确认两步式, glob/子串, 删除上限 5000/扫描上限 20 万); GET /api/admin/cache 新增 capacity 块; 前端容量面板 + 按制品失效工具条; 测试 test-cache-capacity.sh 48/48(容量 27 + 精准失效 21, 含 EXPECT_MIN 护栏与前端静态契约); docs 容量管理章节
2026-09-21 09:25:11 +08:00

464 lines
20 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 运行期统计的**落盘 / 恢复**:让用量统计与趋势图熬过一次重启。
//!
//! ## 为什么需要它(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 增量)
];
/// 快照值里的分隔符:`<payload>\x1f<exp>`。
///
/// 复用共享内存的 `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<String, String>,
}
// ===========================================================================
// 配置
// ===========================================================================
/// `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)
}
// ===========================================================================
// 落盘
// ===========================================================================
/// 原子写:先写 `<path>.tmp.<pid>` 再 `rename`。
///
/// 不复用 `store::write_json` 的原因:它用固定的 `<path>.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<usize, String> {
let now = util::now();
let mut keys: BTreeMap<String, String> = 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::<i64>().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::<i64>().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::<i64>().ok()?;
let ok = it.next()?.parse::<usize>().ok()?;
let total = it.next()?.parse::<usize>().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::<Snapshot>) {
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,
})
}