feat(deploy): 新增 .11 一键更新脚本 + 上游多模型/模型发现/用量统计

功能(本轮 5 项需求的落地):
- 上游可挂多模型:llm-upstreams.json 每上游新增 models 清单(仅用于模型发现,不参与路由)
- 模型发现:GET /v1/models(OpenAI {object:list} 形状,网关本地应答)+ /api/v1/models + /api/v1/upstreams
- 用量统计:/api/admin/usage(管理台「用量统计」Tab)+ /api/v1/usage + /me 的 llm_usage 摘要
  口径:只统计真正转发出去的请求,401/403/404/429 不计;与配额计数 st: 刻意分开
- 账号展示名 display_name(纯展示,不进 ukey:)
- 修复 /v1 版本段重复拼接(llm::join_target)→ 上游 base 自带 /v1 时不再 404 空体
- 修复删账号未清用量键(stats::forget)

部署脚本 deploy/update-ipass.sh:
- 拉镜像 → tar 备份数据 → 删旧容器 → 按旧容器复刻端口/挂载/网络起新容器 → 自检
- 参数从 docker inspect 静态配置读取(docker port 对停止态容器返回空,会让端口静默回落)
- 端口按 host:container 去重(inspect 同一映射含 IPv4/IPv6 两项,重复 -p 会 address already in use)
- --bg 用 setsid/start_new_session 真正脱离会话(仅 nohup & 会被父进程组连带杀掉)
- 旧镜像自动打 rollback-<时间> 标签,收尾打印回滚命令

回归:bash tests/run.sh all → 网关 78 + LLM 75 = 153 条断言全绿。
文档:readme §12.4 / §15 / §16、CLAUDE.md 常用操作 + 排障速查已同步。
This commit is contained in:
admin committed 2026-09-12 10:09:56 +08:00
1 parent 94a48bef6e
commit e38237dc4a
22 files changed
+1719 -93

No files matched your search

+165 -25
View File
@@ -24,6 +24,7 @@ use crate::http;
use crate::models::User;
use crate::session;
use crate::state;
use crate::stats;
use crate::upstreams;
use crate::users;
use crate::util;
@@ -77,6 +78,7 @@ fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> {
("POST", "/api/admin/users/delete") => (Guard::Admin, h_admin_user_delete),
("POST", "/api/admin/users/models") => (Guard::Admin, h_admin_user_models),
("POST", "/api/admin/users/limits") => (Guard::Admin, h_admin_user_limits),
("POST", "/api/admin/users/display") => (Guard::Admin, h_admin_user_display),
("GET", "/api/admin/domains") => (Guard::Admin, h_admin_domains),
("POST", "/api/admin/domains/review") => (Guard::Admin, h_admin_domain_review),
("POST", "/api/admin/domains/create") => (Guard::Admin, h_admin_domain_create),
@@ -85,7 +87,10 @@ fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> {
("GET", "/api/admin/upstreams") => (Guard::Admin, h_admin_upstreams),
("POST", "/api/admin/upstreams/save") => (Guard::Admin, h_admin_upstream_save),
("POST", "/api/admin/upstreams/delete") => (Guard::Admin, h_admin_upstream_delete),
("GET", "/api/admin/usage") => (Guard::Admin, h_admin_usage),
("GET", "/api/v1/me") => (Guard::User, h_me),
("GET", "/api/v1/models") => (Guard::User, h_my_models),
("GET", "/api/v1/usage") => (Guard::User, h_my_usage),
("GET", "/api/v1/upstreams") => (Guard::User, h_my_upstreams),
("GET", "/api/v1/domains") => (Guard::User, h_my_domains),
("POST", "/api/v1/domains/apply") => (Guard::User, h_apply),
@@ -217,24 +222,31 @@ fn h_admin_users(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
*counts.entry(d.owner).or_insert(0) += 1;
}
let now = util::now();
// 一次扫表拿到所有人的 LLM 用量(含各自的上游明细),避免逐账号查共享内存
let usage: HashMap<String, stats::UserUsage> =
stats::all_users(now).into_iter().map(|u| (u.username.clone(), u)).collect();
let items: Vec<Value> = users::all()
.iter()
.map(|u| {
let mut v = users::view(u);
let mut usage_json = json!({ "today": 0, "total": 0, "last_ts": 0, "last_ts_text": "" });
if let Some(uu) = usage.get(&u.username) {
usage_json = uu.usage.json();
}
if let Value::Object(ref mut m) = v {
m.insert(
"domain_count".to_owned(),
json!(counts.get(&u.username).copied().unwrap_or(0)),
);
// 今日 LLM 用量:读 shm 的日窗计数(与热路径同一数据源)
// 今日 LLM 用量:与热路径同一数据源(共享内存)——注意口径是
// **已转发**的请求,不含被限流/越权拒掉的那些
m.insert(
"llm_today".to_owned(),
json!(state::window_count(
config::KEY_ST_PREFIX,
&u.username,
util::day_id(util::now())
)),
json!(usage.get(&u.username).map(|x| x.usage.today).unwrap_or(0)),
);
m.insert("llm_usage".to_owned(), usage_json);
}
v
})
@@ -249,14 +261,15 @@ fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
match users::create(
p.get("username").map(String::as_str).unwrap_or(""),
p.get("display_name").map(String::as_str).unwrap_or(""),
p.get("password").map(String::as_str).unwrap_or(""),
p.get("role").map(String::as_str).unwrap_or("user"),
grant_temp,
) {
Ok(user) => {
util::log_notice(&format!(
"[api] 创建账号 {} role={} temp_grant={grant_temp}",
user.username, user.role
"[api] 创建账号 {} name={} role={} temp_grant={grant_temp}",
user.username, user.display_name, user.role
));
http::ok(r, users::view(&user), "账号创建成功")
}
@@ -264,6 +277,17 @@ fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
}
}
/// 设置展示名(中文姓名等)。传空串 = 清空,前端回落到账号名。
fn h_admin_user_display(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default();
match users::set_display_name(&username, p.get("display_name").map(String::as_str).unwrap_or("")) {
Ok(u) => http::ok(r, users::view(&u), "已更新展示名"),
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
fn h_admin_user_key(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default();
@@ -399,6 +423,8 @@ fn h_me(r: *mut ngx_http_request_t, actor: Actor) -> Status {
"domains".to_owned(),
json!(domains::view_all(&domains::by_owner(&user.username))),
);
// 用量摘要(明细走 /api/v1/usage)——让客户端一个请求就能决定要不要自我节流
m.insert("llm_usage".to_owned(), stats::user(&user.username, util::now()).json());
m.insert(
"policy".to_owned(),
json!({
@@ -493,11 +519,16 @@ fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
Some(v) => util::to_bool(Some(v)),
};
// models 缺省 = 保持原清单;显式传(哪怕是空串)= 覆盖。
// 分隔符同时接受换行/逗号/顿号/分号——粘一份厂商文档里的模型列表是常见操作。
let models = p.get("models").map(|raw| parse_model_list(raw));
let slot_raw = p.get("slot").map(String::as_str).unwrap_or("");
match upstreams::upsert(
slot_raw,
p.get("base").map(String::as_str).unwrap_or(""),
models,
p.get("auth"),
enabled,
p.get("note"),
@@ -505,13 +536,26 @@ fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
Ok(up) => {
// 用校验后的 slot 回显;直接拿原始入参会把大小写差异带进响应
let slot = upstreams::validate_slot(slot_raw).unwrap_or_default();
util::log_notice(&format!("[api] 保存 LLM 上游 {slot} enabled={enabled}"));
util::log_notice(&format!(
"[api] 保存 LLM 上游 {slot} enabled={enabled} models={}",
up.models.len()
));
http::ok(r, upstreams::view(&slot, &up), "已保存")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 把管理台/接口传入的模型列表串拆成模型名数组。
///
/// 允许的写法(混用也认):`a,b` / `a、b` / `a;b` / 一行一个。
pub fn parse_model_list(raw: &str) -> Vec<String> {
raw.split(|c: char| c == ',' || c == '、' || c == ';' || c == '\n' || c == '\r' || c == '\t')
.map(|s| util::trim(s).to_owned())
.filter(|s| !s.is_empty())
.collect()
}
fn h_admin_upstream_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
match upstreams::remove(p.get("slot").map(String::as_str).unwrap_or("")) {
@@ -523,7 +567,18 @@ fn h_admin_upstream_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status
}
}
/// 设置某账号可用的 LLM 上游白名单。`models` 传空串 = 解除限制。
/// 管理员:LLM 用量总览(每人 / 每上游 / 合计)。
///
/// 口径是**请求数**,且只统计真正转发出去的请求(见 `stats` 模块头注释)。
/// 想看 token 级用量得改架构(自建 upstream 拦响应体),不在本项目范围。
fn h_admin_usage(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
http::ok(r, stats::overview(util::now()), "ok")
}
/// 设置某账号可用的 LLM 上游白名单(`models` 字段 = 上游 slot 列表,传空串 = 解除限制)。
///
/// 注意与**上游登记模型清单**(`Upstream.models`)是两件事:这里管"这个账号能用哪几家
/// 上游",那里管"这家上游提供哪些模型"。白名单按 slot 生效,模型发现再按白名单过滤。
fn h_admin_user_models(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default();
@@ -589,30 +644,35 @@ fn h_admin_user_limits(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
}
}
/// 账号态:看看自己能用哪些上游。
///
/// 刻意只回显 slot 与拼接好的 base_url——**不回显任何密钥**(连脱敏都不给,
/// 上游密钥与调用方无关,没有知道的必要)。
fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status {
let Actor::User(user) = actor else {
return http::fail(
/// 账号态接口的公共前置:取账号身份,取不到就回 401。
fn user_or_401(r: *mut ngx_http_request_t, actor: Actor) -> Result<User, Status> {
match actor {
Actor::User(u) => Ok(u),
_ => Err(http::fail(
r,
HTTPStatus::UNAUTHORIZED,
"API Key 无效或缺失,请在请求头携带 X-API-Key",
);
)),
}
}
/// 账号态:看看自己能用哪些上游。
///
/// 刻意只回显 slot / base_url / **模型清单**——**不回显任何密钥**(连脱敏都不给,
/// 上游密钥与调用方无关,没有知道的必要)。
fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status {
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let items: Vec<Value> = upstreams::all()
let items: Vec<Value> = upstreams::available(&user.allowed_models)
.into_iter()
.filter(|(slot, up)| {
up.enabled
&& (user.allowed_models.is_empty()
|| user.allowed_models.iter().any(|s| s == slot))
})
.map(|(slot, up)| {
json!({
"slot": slot,
"base_url": format!("https://llm.yourdomain.com/{slot}"),
"base_url": upstreams::base_url(&slot, &up),
"models": up.models,
"note": up.note,
})
})
@@ -620,3 +680,83 @@ fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status {
http::ok(r, json!({ "items": items }), "ok")
}
/// 账号态:列出自己**可用的模型**(上游登记的模型清单,按白名单过滤)。
///
/// 与 LLM 域名下的 `GET /v1/models` 是同一份数据:那边给 OpenAI SDK 用
/// (形状 `{object:"list",data:[{id,...}]}`),这边给管理/自研客户端用
/// (形状 `{code,msg,data}`,带 base_url 便于直接拼请求)。
fn h_my_models(r: *mut ngx_http_request_t, actor: Actor) -> Status {
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let available = upstreams::available(&user.allowed_models);
let mut items: Vec<Value> = Vec::new();
for (slot, up) in &available {
for model in &up.models {
items.push(json!({
"model": model,
"slot": slot,
"base_url": upstreams::base_url(slot, up),
"note": up.note,
}));
}
}
http::ok(
r,
json!({
"items": items,
"upstreams": available
.iter()
.map(|(slot, up)| json!({
"slot": slot,
"base_url": upstreams::base_url(slot, up),
"models": up.models,
}))
.collect::<Vec<_>>(),
}),
"ok",
)
}
/// 账号态:查自己的 LLM 用量(今日 / 累计 / 最近调用 + 分上游明细)。
fn h_my_usage(r: *mut ngx_http_request_t, actor: Actor) -> Status {
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let now = util::now();
let usage = stats::user(&user.username, now);
let models: Vec<Value> = stats::user_models(&user.username, now)
.into_iter()
.map(|(slot, u)| {
json!({
"slot": slot,
"today": u.today,
"total": u.total,
"last_ts": u.last_ts,
"last_ts_text": if u.last_ts > 0 { util::fmt_time(u.last_ts) } else { String::new() },
})
})
.collect();
http::ok(
r,
json!({
"username": user.username,
"display_name": user.display_name,
"today": usage.today,
"total": usage.total,
"last_ts": usage.last_ts,
"last_ts_text": if usage.last_ts > 0 { util::fmt_time(usage.last_ts) } else { String::new() },
"models": models,
// 限额一起回显:客户端可据此自我节流,不必等 429
"limits": { "rpm": user.llm_rpm, "daily": user.llm_daily },
}),
"ok",
)
}
+21
View File
@@ -27,6 +27,8 @@ pub const UPSTREAM_SLOT_MAX_LEN: usize = 32;
pub const UPSTREAM_BASE_MAX_LEN: usize = 200;
pub const USERNAME_MIN_LEN: usize = 2;
pub const USERNAME_MAX_LEN: usize = 32;
/// 展示名(中文姓名等)长度上限。按**字符数**算,一个汉字算 1。
pub const DISPLAY_NAME_MAX_LEN: usize = 32;
/// 子域名总长上限:首字符 + 最多 61 个后续字符
pub const SUBDOMAIN_MAX_LEN: usize = 62;
@@ -86,6 +88,25 @@ pub const KEY_RL_PREFIX: &[u8] = b"rl:";
/// 键前缀:LLM 每日配额计数。键 = `st:<username>`,value = `<日窗id>:<计数>`。
/// 同时是管理台「今日用量」的数据源。
pub const KEY_ST_PREFIX: &[u8] = b"st:";
/// 键前缀:LLM **每用户**用量统计(口径 = 已放行的请求)。
///
/// 键 = `ust:<username>`,value = `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。
/// 与 `st:` 的区别:`st:` 是**配额执行**用的计数(先增后判,被拒的请求也计入),
/// 这里统计的是**真的转发出去**的请求——两者在超限时会差几个数,属预期。
pub const KEY_UST_PREFIX: &[u8] = b"ust:";
/// 键前缀:LLM **每用户 × 每上游**用量统计。
///
/// 键 = `ums:<username>:<slot>`(username 与 slot 都不含 `:`,切分安全),
/// value 同 `ust:`。管理台的「每个模型用量」就是把这些键按 slot 聚合出来的。
pub const KEY_UMS_PREFIX: &[u8] = b"ums:";
/// LLM 代理对外域名,用于账号态 API 回显 `base_url`。
/// 改域名只改这里(`conf/nginx.conf` 的 LLM server_name 要同步改)。
pub const LLM_PUBLIC_HOST: &str = "lm.mayishangshu.cn";
/// 单个模型名长度上限
pub const MODEL_NAME_MAX_LEN: usize = 128;
/// 单个上游可登记的模型数量上限(挡住把整个模型库灌进 shm/JSON 的手滑)
pub const UPSTREAM_MODELS_MAX: usize = 200;
/// 共享内存 value 内部分隔符(ASCII US)。
/// 后端地址只含 `[A-Za-z0-9._-]` 与 `:`,用户名只含 `[A-Za-z0-9_-]`,
/// 都不可能包含该字节,所以切分是安全的。
+12
View File
@@ -45,6 +45,7 @@ mod llm;
mod models;
mod session;
mod state;
mod stats;
mod store;
mod upstreams;
mod util;
@@ -268,6 +269,12 @@ impl HttpRequestHandler for LlmHandler {
);
};
// 「列出可用模型」是网关自己的元信息接口(OpenAI 兼容形状),
// 在查上游之前就地应答——否则 `/v1/models` 会被当成 slot=v1 → 404。
if llm::is_models_probe(r) {
return llm::respond_models(r, &allowed);
}
if state::get_upstream(&slot).is_none() {
return llm::fail(
r,
@@ -295,6 +302,11 @@ impl HttpRequestHandler for LlmHandler {
return resp;
}
// 用量统计:走到这里说明请求**真的会被转发**,才计入。
// 被拒的请求(401/403/404/429)不进统计——那是给人看的数字,
// 把拒绝也算进"用量"只会误导(与配额计数 st: 的语义刻意不同)。
stats::record(&username, &slot, util::now());
Status::NGX_DECLINED
}
}
+79 -1
View File
@@ -157,6 +157,46 @@ fn host_of(base: &str) -> &str {
}
}
/// 拆 base:`https://api.deepseek.com/v1` → `("https://api.deepseek.com", "/v1")`
fn split_origin(base: &str) -> (&str, &str) {
let Some(i) = base.find("://") else {
return (base, "");
};
let after = &base[i + 3..];
match after.find('/') {
Some(j) => (&base[..i + 3 + j], &after[j..]),
None => (base, ""),
}
}
/// 拼上游完整 URL:`base + 客户端路径(已剥掉 slot)`。
///
/// **唯一的例外是版本段重复**:上游 base 自带路径(如 DeepSeek 的
/// `https://api.deepseek.com/v1`)而客户端路径又正好以同一段开头时,
/// 只保留一份。否则会拼出 `/v1/v1/chat/completions`。
///
/// ```text
/// base .../v1 + /v1/chat/completions → .../v1/chat/completions (去重)
/// base .../v1 + /chat/completions → .../v1/chat/completions (照常前缀)
/// base .../llm + /v1/chat/completions → .../llm/v1/chat/completions
/// ```
///
/// 这条规则是**实测踩坑换来的**:厂商文档里的 base_url 通常自带 `/v1`
/// (`https://api.deepseek.com/v1`),管理员照抄进 `llm-upstreams.json`,
/// 客户端又按 OpenAI 习惯把 `/v1` 带上 → 上游 404 且**响应体为空**,
/// 从网关侧完全看不出是拼接问题。去重后两种写法都通,
/// base_url 也就能做到「把厂商文档里的 host 换成网关域名」的逐个字符替换。
fn join_target(base: &str, path: &str) -> String {
let (origin, base_path) = split_origin(base);
if !base_path.is_empty() {
let with_slash = format!("{base_path}/");
if path == base_path || path.starts_with(&with_slash) {
return format!("{origin}{path}");
}
}
format!("{base}{path}")
}
// ===========================================================================
// 响应
// ===========================================================================
@@ -253,6 +293,44 @@ pub unsafe fn check_quota(
None
}
// ===========================================================================
// 模型发现(本地应答,不去上游)
// ===========================================================================
/// 是不是"列出模型"请求:`GET /v1/models`(OpenAI SDK 的 `client.models.list()`)。
///
/// **必须在查 slot 之前判断**:URL 第一段被当作 slot,`/v1/models` 天然会被
/// 解析成 `slot=v1` → 「上游不存在」404。这两个路径是本网关自己的元信息接口,
/// 与"某个上游的模型清单"(`GET /<slot>/v1/models`,照常透传给厂商)互不干扰。
pub fn is_models_probe(r: *mut ngx_http_request_t) -> bool {
if !crate::http::method_str(r).eq_ignore_ascii_case("GET") {
return false;
}
let uri = crate::http::uri(r);
let uri = uri.trim_end_matches('/');
uri == "/v1/models" || uri == "/models"
}
/// 本地应答模型列表,形状与 OpenAI 的 `/v1/models` 一致。
///
/// 客户端 SDK 只认这个形状,返回项目自己的 `{code,msg,data}` 会让 SDK
/// 报"无法解析的响应"——与错误体必须 OpenAI 兼容是同一个理由。
pub fn respond_models(r: *mut ngx_http_request_t, allowed: &[String]) -> Status {
let data: Vec<serde_json::Value> = upstreams::models_flat(allowed)
.into_iter()
.map(|(model, slot)| {
json!({ "id": model, "object": "model", "created": 0, "owned_by": slot })
})
.collect();
let body = json!({ "object": "list", "data": data }).to_string();
// 与错误路径同一手法:自己把响应发出去,再把状态码交回 nginx。
// 注意**不能**返回 NGX_OK——access 阶段的 OK 语义是"放行、继续走 content",
// 那样 `proxy_pass` 照样会执行,客户端拿到模型列表的同时上游被真调一次。
let _ = crate::http::send(r, HTTPStatus::OK, &body);
Status(HTTPStatus::OK.0 as ngx_int_t)
}
// ===========================================================================
// 变量 get_handler
// ===========================================================================
@@ -299,7 +377,7 @@ pub extern "C" fn var_get(
let payload = state::get_upstream(&slot)?;
let (base, auth) = upstreams::split_payload(&payload);
Some(match data {
VAR_TARGET => format!("{}{}", base, upstream_uri(r)),
VAR_TARGET => join_target(base, &upstream_uri(r)),
VAR_HOST => host_of(base).to_owned(),
VAR_AUTH => auth.to_owned(),
_ => return None,
+14
View File
@@ -16,6 +16,12 @@ pub type UserTable = BTreeMap<String, User>;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
pub username: String,
/// 中文姓名等展示名。**只用于展示**,不参与鉴权、不参与热路径查询。
///
/// `username` 规则是 ASCII(`valid_username`),中文名塞不进账号名,
/// 所以「吴桂荣」这类实名单独放这里;留空时前端回落到 `username`。
#[serde(default)]
pub display_name: String,
/// `admin` | `user`
pub role: String,
pub salt: String,
@@ -67,6 +73,14 @@ pub type UpstreamTable = BTreeMap<String, Upstream>;
pub struct Upstream {
/// 上游基址,含 scheme,如 `https://api.openai.com`(可带端口)
pub base: String,
/// 该上游**挂载的模型名清单**(如 `deepseek-chat` / `deepseek-reasoner`)。
///
/// 一个上游(一家厂商)通常挂多个模型,客户端要能先"列出有什么"再选。
/// 这里只是网关侧的**清单**,用于 `GET /v1/models` 之类的模型发现;
/// 转发本身仍按 URL 里的 slot 走,**不校验 model 字段**(access 阶段读不到 body)。
/// 留空表示"清单未知"——模型发现接口就不列该上游的模型,但转发照常可用。
#[serde(default)]
pub models: Vec<String>,
/// 完整的 Authorization 头值,如 `Bearer sk-xxx`。
/// 留空表示不透传鉴权头(本地免鉴权后端,如 vLLM / Ollama)
#[serde(default)]
+23
View File
@@ -219,6 +219,29 @@ pub fn clear_prefix(prefix: &[u8]) {
}
}
/// 遍历某前缀下的全部条目,返回 `(去掉前缀的键名, payload)`。
///
/// 这是**低频读**接口(管理台聚合用量统计),不是热路径——每次都会克隆一份
/// 字符串出来,别拿它做每请求调用。`expires_at` 刻意不返回:统计键永不过期,
/// 调用方用 payload 里的日窗 id 自行判断"今日"。
pub fn iter_prefix(prefix: &[u8]) -> Vec<(String, String)> {
let Some(root) = root() else {
return Vec::new();
};
let guard = root.map.read();
guard
.iter()
.filter_map(|(k, v)| {
let name = k.as_bytes().strip_prefix(prefix)?;
let (payload, _) = split_value(v.as_bytes())?;
Some((
String::from_utf8_lossy(name).into_owned(),
String::from_utf8_lossy(payload).into_owned(),
))
})
.collect()
}
// ===========================================================================
// 业务语义封装
// ===========================================================================
+282
View File
@@ -0,0 +1,282 @@
//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。
//!
//! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、
//! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。
//!
//! ```text
//! ust:<username> → <日窗id>:<今日数>:<累计数>:<最近调用时间戳>
//! ums:<username>:<slot> → 同 上
//! ```
//!
//! ## 口径:只统计"真的转发出去"的请求
//!
//! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**,
//! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同——
//! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义;
//! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。
//!
//! ## 为什么不做 token 级
//!
//! token 数在上游响应体里,而 SSE 必须关缓冲透传(`proxy_buffering off`),
//! 网关不缓冲就解析不到 `usage` 字段。要做 token 级计费得自建 upstream
//! 把响应拦下来重组流,与「不引入额外常驻进程 / 不改 nginx 原生转发」冲突。
//! 因此口径统一为**请求数**,并在文档里写明。
use std::collections::BTreeMap;
use serde_json::{Value, json};
use crate::config::{KEY_UMS_PREFIX, KEY_UST_PREFIX};
use crate::state;
use crate::util;
/// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Usage {
/// 今日(本地自然日)请求数
pub today: i64,
/// 累计请求数(自该计数键建立以来,不随跨天归零)
pub total: i64,
/// 最近一次调用时间戳;0 = 从未调用
pub last_ts: i64,
}
impl Usage {
/// 累加(聚合用)。`last_ts` 取最大。
fn merge(&mut self, other: &Usage) {
self.today += other.today;
self.total += other.total;
if other.last_ts > self.last_ts {
self.last_ts = other.last_ts;
}
}
pub fn json(&self) -> Value {
json!({
"today": self.today,
"total": self.total,
"last_ts": self.last_ts,
"last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() },
})
}
}
/// 一个账号的用量 + 其下每个上游的明细
pub struct UserUsage {
pub username: String,
pub usage: Usage,
pub models: Vec<(String, Usage)>,
}
/// 一个上游的用量 + 用它的每个账号的明细
pub struct ModelUsage {
pub slot: String,
pub usage: Usage,
pub users: Vec<(String, Usage)>,
}
// ===========================================================================
// 编解码
// ===========================================================================
/// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。
/// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。
fn encode(day: i64, u: &Usage) -> String {
format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts)
}
/// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。
fn decode(payload: &str, day: i64) -> Usage {
let mut it = payload.split(':');
let stored_day = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let today = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let total = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
let last_ts = it.next().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0);
Usage { today: if stored_day == day { today } else { 0 }, total, last_ts }
}
fn bump(prefix: &[u8], name: &str, day: i64, now: i64) {
let current = state::get(prefix, name.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default();
let next = Usage {
today: current.today + 1,
total: current.total + 1,
last_ts: now,
};
// 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次),
// 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。
state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0);
}
// ===========================================================================
// 写
// ===========================================================================
/// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。
pub fn record(username: &str, slot: &str, now: i64) {
if username.is_empty() || slot.is_empty() {
return;
}
let day = util::day_id(now);
bump(KEY_UST_PREFIX, username, day, now);
bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now);
}
/// 删除账号时清理其全部用量键(`ust:<user>` 与 `ums:<user>:*`)。
///
/// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让
/// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的
/// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。
pub fn forget(username: &str) {
if username.is_empty() {
return;
}
state::remove(KEY_UST_PREFIX, username.as_bytes());
// 先物化键名再删,避免"遍历中改表"
let prefix = format!("{username}:");
let keys: Vec<String> = state::iter_prefix(KEY_UMS_PREFIX)
.into_iter()
.map(|(name, _)| name)
.filter(|name| name.starts_with(&prefix))
.collect();
for name in keys {
state::remove(KEY_UMS_PREFIX, name.as_bytes());
}
}
// ===========================================================================
// 读
// ===========================================================================
/// 单账号读数(不含模型明细)
pub fn user(username: &str, now: i64) -> Usage {
let day = util::day_id(now);
state::get(KEY_UST_PREFIX, username.as_bytes())
.map(|(payload, _)| decode(&payload, day))
.unwrap_or_default()
}
/// 单账号 × 上游明细,按 slot 升序
pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> {
let day = util::day_id(now);
let prefix = format!("{username}:");
let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX)
.into_iter()
.filter_map(|(name, payload)| {
let slot = name.strip_prefix(&prefix)?.to_owned();
Some((slot, decode(&payload, day)))
})
.collect();
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
/// 全部账号的用量(含各自的模型明细),按账号名升序。
///
/// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。
pub fn all_users(now: i64) -> Vec<UserUsage> {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, Vec<(String, Usage)>> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
by_user
.entry(username.to_owned())
.or_default()
.push((slot.to_owned(), decode(&payload, day)));
}
for models in by_user.values_mut() {
models.sort_by(|a, b| a.0.cmp(&b.0));
}
state::iter_prefix(KEY_UST_PREFIX)
.into_iter()
.map(|(username, payload)| {
let usage = decode(&payload, day);
let models = by_user.remove(&username).unwrap_or_default();
UserUsage { username, usage, models }
})
.collect()
}
/// 全部上游的用量(含用到它的账号明细),按 slot 升序。
pub fn all_models(now: i64) -> Vec<ModelUsage> {
let day = util::day_id(now);
// slot → (总量, 各账号)
let mut by_slot: BTreeMap<String, (Usage, Vec<(String, Usage)>)> = BTreeMap::new();
for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) {
let Some((username, slot)) = name.split_once(':') else {
continue;
};
let u = decode(&payload, day);
let entry = by_slot.entry(slot.to_owned()).or_default();
entry.0.merge(&u);
entry.1.push((username.to_owned(), u));
}
by_slot
.into_iter()
.map(|(slot, (usage, mut users))| {
users.sort_by(|a, b| a.0.cmp(&b.0));
ModelUsage { slot, usage, users }
})
.collect()
}
/// 全局合计
pub fn totals(now: i64) -> Usage {
let day = util::day_id(now);
let mut sum = Usage::default();
for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) {
sum.merge(&decode(&payload, day));
}
sum
}
/// 管理台用量页的完整投影
pub fn overview(now: i64) -> Value {
let users: Vec<Value> = all_users(now)
.into_iter()
.map(|u| {
json!({
"username": u.username,
"today": u.usage.today,
"total": u.usage.total,
"last_ts": u.usage.last_ts,
"last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() },
"models": u.models.iter().map(|(slot, usage)| {
json!({ "slot": slot, "today": usage.today, "total": usage.total })
}).collect::<Vec<_>>(),
})
})
.collect();
let models: Vec<Value> = all_models(now)
.into_iter()
.map(|m| {
json!({
"slot": m.slot,
"today": m.usage.today,
"total": m.usage.total,
"last_ts": m.usage.last_ts,
"last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() },
"users": m.users.iter().map(|(name, usage)| {
json!({ "username": name, "today": usage.today, "total": usage.total })
}).collect::<Vec<_>>(),
})
})
.collect();
let sum = totals(now);
json!({
"total": sum.json(),
"users": users,
"models": models,
})
}
+96 -3
View File
@@ -15,7 +15,10 @@
use serde_json::{Value, json};
use crate::config::{KEY_UP_PREFIX, UPSTREAM_BASE_MAX_LEN, UPSTREAM_SLOT_MAX_LEN};
use crate::config::{
KEY_UP_PREFIX, LLM_PUBLIC_HOST, MODEL_NAME_MAX_LEN, UPSTREAM_BASE_MAX_LEN,
UPSTREAM_MODELS_MAX, UPSTREAM_SLOT_MAX_LEN,
};
use crate::models::Upstream;
use crate::state;
use crate::store;
@@ -51,6 +54,34 @@ pub fn validate_slot(raw: &str) -> Result<String, String> {
Ok(s)
}
/// 模型名清单:去空白、去空项、去重、限长。
///
/// 刻意**允许** `/` `.` `:` 等字符——`Qwen/Qwen2.5-7B`(HF 风格)、
/// `llama3:8b`(Ollama 标签)都是合法模型名。只挡空白与控制字符,
/// 因为模型名要出现在 URL/JSON/HTML 里,空白只会带来歧义。
fn check_models(raw: &[String]) -> Result<Vec<String>, String> {
let mut out: Vec<String> = Vec::new();
for item in raw {
let m = util::trim(item);
if m.is_empty() {
continue;
}
if m.chars().count() > MODEL_NAME_MAX_LEN {
return Err(format!("模型名「{m}」超过 {MODEL_NAME_MAX_LEN} 个字符"));
}
if m.chars().any(char::is_whitespace) || m.chars().any(char::is_control) {
return Err(format!("模型名「{m}」不能包含空格或控制字符"));
}
if !out.iter().any(|x| x == m) {
out.push(m.to_owned());
}
}
if out.len() > UPSTREAM_MODELS_MAX {
return Err(format!("单个上游最多登记 {UPSTREAM_MODELS_MAX} 个模型"));
}
Ok(out)
}
/// 上游基址:必须显式带 `http://` 或 `https://`。
///
/// 比子域名的 `backend`(纯 host:port)宽——LLM 上游常挂在网关路径下
@@ -139,6 +170,55 @@ pub fn get(slot: &str) -> Option<Upstream> {
store::read_upstreams().remove(slot)
}
/// 某账号**可用**的上游(已启用,且在白名单内;`allowed` 为空 = 不限)。
///
/// 账号态接口与模型发现都用它,避免"能看见但不能用"或反之的两套判定。
pub fn available(allowed: &[String]) -> Vec<(String, Upstream)> {
all()
.into_iter()
.filter(|(slot, up)| {
up.enabled && (allowed.is_empty() || allowed.iter().any(|s| s == slot))
})
.collect()
}
/// 客户端应当使用的 base_url。
///
/// 规则:**把上游 base 的 scheme+host 换成网关域名,路径原样保留**——
/// 这样它才真的能和厂商文档里的 base_url 逐个字符替换:
///
/// ```text
/// https://api.deepseek.com/v1 → https://lm.mayishangshu.cn/deepseek/v1
/// https://api.openai.com → https://lm.mayishangshu.cn/openai
/// ```
///
/// 反过来(不管上游 base 的路径、一律拼 `/v1`)会让「base 自带 /v1」的上游
/// 变成 `/v1/v1/chat/completions` → 上游 404,且客户端拿到的是空响应体,
/// 排查起来完全看不出是网关拼错了。**实测踩过,别再改回去。**
pub fn base_url(slot: &str, up: &Upstream) -> String {
let rest = up.base.split("://").nth(1).unwrap_or("");
let path = match rest.find('/') {
Some(i) => &rest[i..],
None => "",
};
format!("https://{LLM_PUBLIC_HOST}/{slot}{path}")
}
/// 模型发现:把可用上游挂载的模型摊平成 `(模型名, slot)` 列表。
///
/// 没登记 `models` 的上游不产出任何条目(清单未知 ≠ 有 0 个模型),
/// 但它的转发能力不受影响——模型发现只是"告诉你有什么",
/// 不是"允许你用什么"。
pub fn models_flat(allowed: &[String]) -> Vec<(String, String)> {
let mut out = Vec::new();
for (slot, up) in available(allowed) {
for model in &up.models {
out.push((model.clone(), slot.clone()));
}
}
out
}
// ===========================================================================
// 写入
// ===========================================================================
@@ -146,16 +226,22 @@ pub fn get(slot: &str) -> Option<Upstream> {
/// 新增或覆盖一个上游。
///
/// `auth = None` 表示**保持原值**(表单只改 base 时不必回填密钥);
/// `Some("")` 表示显式清空。`enabled = false` 会立刻从共享内存移除。
/// `Some("")` 表示显式清空。`models = None` 同款语义(保持原清单)。
/// `enabled = false` 会立刻从共享内存移除。
pub fn upsert(
slot_raw: &str,
base_raw: &str,
models: Option<Vec<String>>,
auth_raw: Option<&String>,
enabled: bool,
note: Option<&String>,
) -> Result<Upstream, String> {
let slot = validate_slot(slot_raw)?;
let base = validate_base(base_raw)?;
let models = match models {
Some(list) => Some(check_models(&list)?),
None => None,
};
let key = slot.clone();
let up = store::update_upstreams(move |table| {
@@ -170,13 +256,17 @@ pub fn upsert(
Some(n) => util::trim(n).to_owned(),
None => existing.as_ref().map(|e| e.note.clone()).unwrap_or_default(),
};
let models = match models {
Some(m) => m,
None => existing.as_ref().map(|e| e.models.clone()).unwrap_or_default(),
};
let created_at = existing
.as_ref()
.map(|e| e.created_at)
.filter(|&t| t > 0)
.unwrap_or_else(util::now);
let item = Upstream { base, auth, enabled, note, created_at };
let item = Upstream { base, models, auth, enabled, note, created_at };
table.insert(key.clone(), item.clone());
Ok(item)
})?;
@@ -213,6 +303,9 @@ pub fn view(slot: &str, up: &Upstream) -> Value {
json!({
"slot": slot,
"base": up.base,
"base_url": base_url(slot, up),
"models": up.models,
"model_count": up.models.len(),
"auth_set": !up.auth.is_empty(),
"auth_mask": if up.auth.is_empty() { "-".to_owned() } else { util::mask_key(&up.auth) },
"enabled": up.enabled,
+46 -5
View File
@@ -15,11 +15,12 @@
use serde_json::{Value, json};
use crate::config::{
INIT_ADMIN_PASSWORD_DEFAULT, INIT_ADMIN_PASSWORD_ENV, INIT_ADMIN_USER, KEY_UKEY_PREFIX,
PASSWORD_MIN_LEN, TEMP_GRANT_TTL, USERNAME_MAX_LEN, USERNAME_MIN_LEN,
DISPLAY_NAME_MAX_LEN, INIT_ADMIN_PASSWORD_DEFAULT, INIT_ADMIN_PASSWORD_ENV, INIT_ADMIN_USER,
KEY_UKEY_PREFIX, PASSWORD_MIN_LEN, TEMP_GRANT_TTL, USERNAME_MAX_LEN, USERNAME_MIN_LEN,
};
use crate::models::{User, UserTable};
use crate::state;
use crate::stats;
use crate::store;
use crate::util;
@@ -36,6 +37,19 @@ fn valid_username(name: &str) -> bool {
name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
}
/// 展示名:允许中文/空格,但**不允许换行或制表等控制字符**——
/// 它会被塞进管理台 HTML(已转义)与 JSON,控制字符只会造成排版错乱。
fn check_display_name(raw: &str) -> Result<String, String> {
let v = util::trim(raw).to_owned();
if v.chars().count() > DISPLAY_NAME_MAX_LEN {
return Err(format!("展示名不能超过 {DISPLAY_NAME_MAX_LEN} 个字"));
}
if v.chars().any(|c| c.is_control()) {
return Err("展示名不能包含换行或控制字符".to_owned());
}
Ok(v)
}
// ===========================================================================
// 共享内存同步(Key 索引)
// ===========================================================================
@@ -108,11 +122,18 @@ pub fn find_by_key(key: &str) -> Option<User> {
// 写入
// ===========================================================================
fn build_user(username: &str, password: &str, role: &str, grant_temp: bool) -> User {
fn build_user(
username: &str,
display_name: &str,
password: &str,
role: &str,
grant_temp: bool,
) -> User {
let salt = util::gen_salt();
let now = util::now();
User {
username: username.to_owned(),
display_name: display_name.to_owned(),
role: role.to_owned(),
pwd_hash: util::hash_password(password, &salt),
salt,
@@ -137,7 +158,7 @@ pub fn seed_admin() -> Result<bool, String> {
if !users.is_empty() {
return Ok(());
}
let admin = build_user(INIT_ADMIN_USER, &password, "admin", false);
let admin = build_user(INIT_ADMIN_USER, "", &password, "admin", false);
users.insert(admin.username.clone(), admin.clone());
created = Some(admin);
Ok(())
@@ -157,6 +178,7 @@ pub fn seed_admin() -> Result<bool, String> {
pub fn create(
username: &str,
display_name: &str,
password: &str,
role: &str,
grant_temp: bool,
@@ -167,6 +189,7 @@ pub fn create(
"账号名只能是 {USERNAME_MIN_LEN}-{USERNAME_MAX_LEN} 位字母、数字、下划线或短横线"
));
}
let display_name = check_display_name(display_name)?;
if password.len() < PASSWORD_MIN_LEN {
return Err(format!("密码至少 {PASSWORD_MIN_LEN} 位"));
}
@@ -177,7 +200,7 @@ pub fn create(
return Err(format!("账号 {username} 已存在"));
}
let user = build_user(&username, password, role, grant_temp);
let user = build_user(&username, &display_name, password, role, grant_temp);
let created = user.clone();
store::update_users(move |users| {
if users.contains_key(&username) {
@@ -191,6 +214,18 @@ pub fn create(
Ok(created)
}
/// 设置展示名(中文姓名等)。只影响管理台显示,不碰 Key / 口令 / 白名单。
pub fn set_display_name(username: &str, display_name: &str) -> Result<User, String> {
let display_name = check_display_name(display_name)?;
let updated = store::update_users(move |users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
user.display_name = display_name;
Ok(user.clone())
})?;
// 展示名不在 ukey payload 里(热路径不需要它),无需同步共享内存
Ok(updated)
}
/// 重置 API Key,返回新 Key。
///
/// **必须同时摘掉旧索引**:LLM 热路径查的是 `ukey:`,若只加新的不删旧的,
@@ -297,6 +332,7 @@ pub fn delete(username: &str, operator: &str) -> Result<(), String> {
return Err("不能删除当前登录的账号".to_owned());
}
let username = username.to_owned();
let stats_name = username.clone();
let removed_key = store::update_users(move |users| {
let user = users.get(&username).ok_or("账号不存在")?;
@@ -312,6 +348,8 @@ pub fn delete(username: &str, operator: &str) -> Result<(), String> {
if !removed_key.is_empty() {
state::remove_ukey(&removed_key);
}
// 用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上
stats::forget(&stats_name);
Ok(())
}
@@ -327,6 +365,9 @@ pub fn view(user: &User) -> Value {
json!({
"username": user.username,
"display_name": user.display_name,
// 前端统一用 name 渲染——展示名优先,没有就回落到账号名
"name": if user.display_name.is_empty() { user.username.clone() } else { user.display_name.clone() },
"role": user.role,
"api_key": user.api_key,
"api_key_masked": util::mask_key(&user.api_key),