Files
ipass/rust/crates/plugin-llm/src/lib.rs
T
admin 16cf68d132 feat(stats): 运行期统计落盘/恢复 + 审计口径收口 (1.0.18)
起因:发版后管理台「用量」与「趋势」从 0 重新长起来。根因是统计类键
(ust:/ums:/utt:/utms:/ud:/udu:/uds:/uda:/uex:/uh:)只活在共享内存,
进程退出即消失;而上游/账号/域名/用户都有 data/*.json 所以不丢。

统计落盘(新 stats_persist.rs):
- 快照 data/llm-stats.json(与 users.json 同级),原子写 <path>.tmp.<pid> + rename
- 两个落盘点互补:worker 退出钩子 exit_process(发版/docker stop,零丢失)
  + 记账后按间隔节流落盘(默认 60s,覆盖 SIGKILL/OOM/断电)
- 启动 init_process 恢复,put-if-absent → 多 worker 幂等、不覆盖新数据
- 白名单 10 个统计前缀;刻意排除配置类/ukb:/内核态(各有数据文件或重启清零更安全)
- 恢复结果发布 shm spr:last(不再放进程内静态量,否则接口落到哪个 worker 报哪个数)
- 接口 GET /api/admin/stats/persist + POST /api/admin/stats/dump
- 指令 ipass_stats_persist <秒>(0=只留退出钩子);生产 conf 刻意不写

fix(audit): excerpt 双重编码
- json_quote_bytes(手工转义+两侧引号)塞进 json!() 被二次转义,落盘成
  "excerpt":"\"{\\\"model\\\"…",解码后多一层引号,消费方全解析不到
- 改为 excerpt_text():只 from_utf8_lossy,转义交给 serde

docs: 新增 docs/llm/STATS_PERSISTENCE.md(含 runbook)、docs/llm/AUDIT_LOG.md
  (两者此前被代码注释与 Dockerfile 引用但文件并不存在)

tests:
- 新增【15】统计落盘/重启恢复 13 条(间隔压 1s → 快照产出与白名单 →
  nginx -s quit → 恢复键数 == 快照键数、用量不变、再打一笔 +1、趋势仍在)
- 【13】「不再生成 body 副本」改断言本轮增量 = 0(对历史残留免疫);
  选择器改 body_bytes>400 且取最后一条匹配(目录里有首版的双重编码行)
- run.sh 复位改用 mv(rename 不算删除)——本机 safe-delete 钩子在累计删除
  超 50 个文件后会静默拦掉后续删除,rm -rf 与 python rmtree 同样被拦
- 回归 298 全绿(网关 102 + LLM 196)
2026-09-14 19:32:17 +08:00

84 lines
3.0 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.
//! plugin-llm —— LLM API 代理插件。
//!
//! 职责:`/<slot>/...` → 上游转发决策、上游 CRUD、OpenAI 兼容模型发现、
//! `rl:`/`st:` 配额执行、token 计量(body filter 旁路)、用量统计与趋势、
//! 对话审计落盘、运行期统计落盘/恢复。数据文件 `data/llm-upstreams.json`
//! (敏感级别等同 users.json)与 `data/llm-stats.json`(统计快照,无凭据)。
//!
//! ## 装配点(gateway)
//!
//! * `preconfig` —— 注册 `$llm_target` / `$llm_host` / `$llm_auth` 三件套
//! * `postconfig` —— 注册 LlmHandler(access)/ LlmHealthHandler、AuditHandler
//! (log)/ body filter 链头插入(token 计量)/ 预取 `$upstream_status` 索引
//! * `zone_load` —— 全量装载 `up:` 上游表
//! * `dispatch_api` —— 认领上游 / 用量类端点(趋势端点留 gateway,需三方名册)
//!
//! ## 进程生命周期钩子(由 gateway 调用,不是插件自己的钩子)
//!
//! * `stats_persist::restore()` 在 `init_process` —— 重启后把统计快照灌回共享内存
//! * `stats_persist::dump_now()` 在 `exit_process` —— 退出前落盘,发版不丢统计
//!
//! ## 与其他插件的关系
//!
//! 下行鉴权与配额执行(`ukey:` / `rl:` / `st:`)在内核 `ipass_core::auth`;
//! 记账原语在内核 `ipass_core::usage`——apix 插件复用同一套下行契约,
//! 与本插件共用同一片用量键空间(apix 的 slot 带 `api/` 前缀天然归组)。
pub mod api;
pub mod config;
pub mod handlers;
pub mod llm;
pub mod llm_audit;
pub mod models;
pub mod stats;
pub mod stats_persist;
pub mod store;
pub mod upstreams;
pub mod usage_filter;
use ngx::core::Status;
use ngx::ffi::{ngx_conf_t, ngx_http_request_t};
use ipass_core::plugin::Plugin;
pub struct LlmPlugin;
impl Plugin for LlmPlugin {
fn name(&self) -> &'static str {
"llm"
}
fn preconfig(&self, cf: *mut ngx_conf_t) -> bool {
// SAFETY: cf 由 nginx 传入且有效
unsafe { llm::preconfig(cf) }
}
fn postconfig(&self, cf: *mut ngx_conf_t) -> bool {
// SAFETY: cf 由 nginx 传入且有效
let cf = unsafe { &mut *cf };
// token 计量:插进 body filter 链头,旁路扫描上游响应的 usage
usage_filter::install();
if ngx::http::add_phase_handler::<handlers::LlmHandler>(cf).is_err() {
return false;
}
if ngx::http::add_phase_handler::<handlers::LlmHealthHandler>(cf).is_err() {
return false;
}
if ngx::http::add_phase_handler::<handlers::AuditHandler>(cf).is_err() {
return false;
}
// 预取 `$upstream_status` 索引(upstream 模块 preconfiguration 已注册该内建变量)
handlers::prefetch_upstream_status_index(cf)
}
fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option<Status> {
api::dispatch(r)
}
fn zone_load(&self) -> usize {
upstreams::reload_shm()
}
}