Files
ipass__ipass/rust/crates/ipass-core/src/users.rs
T
admin db99ce1521 docs: 文档与注释系统性对齐插件化现状 + 清理前身实现引用
- readme §16 补 1.0.10-1.0.13 四条变更记录;§12.6 tag 表补 1.0.9-1.0.13
- readme §5 架构图更新为插件化结构(PLUGINS 注册表/四开关/四表)
- readme §11 补 api-proxies.json 数据模型小节;§8 管理台表格补 API 代理行
- readme/CLAUDE.md 测试断言数对齐 262(102+160);三个 JSON 改四个
- CLAUDE.md LLM 落点表改 crates/plugin-llm 路径;发版补 git push 前置教训
- 清理全部前身实现引用(readme 三处、CLAUDE.md 性能章节、util.rs 注释)
- PLUGIN_ARCHITECTURE.md 增补 1.0.13 sso 合流记录
2026-09-13 18:27:28 +08:00

464 lines
17 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.
//! 账号体系:管理员与普通账号共用一张表。
//!
//! 账号数据见 `models::User`。
//!
//! 「临时授权权限」= 该账号申请**临时域名**时可跳过管理员审核、直接放行。
//! 注意它只对 temp 生效,long 域名无论谁申请都要审核。
//!
//! ## 与 LLM 代理共用同一把 Key
//!
//! `api_key` 同时是域名接口(`X-API-Key`)与 LLM 代理
//! (`Authorization: Bearer`)的凭据——这正是「用同一套 Key 验证」的落点。
//! 代价是**任何改动 `api_key` 的操作都必须同步共享内存索引**,
//! 且重置 Key 时必须**先摘掉旧索引**,否则被换掉的 Key 依然能用。
use std::collections::BTreeMap;
use std::sync::Mutex;
use serde_json::{Value, json};
use crate::config::{
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::store;
use crate::util;
// ===========================================================================
// 账号删除钩子
// ===========================================================================
/// 「账号被删除时我需要清理什么」的回调注册表。
///
/// 内核只负责自己的键(`ukey:` / `sess:` / `fail:`),插件的键空间(用量账本、
/// 代理索引……)内核**不认识**——删除账号要摘几个前缀,取决于装了哪些插件,
/// 所以只能由插件在装载阶段调用 [`on_delete`] 注册清理器(如 plugin-llm 注册
/// `stats::forget`)。**重复注册同一函数会被去重**(nginx reload 会多次走到注册点)。
static ON_DELETE: Mutex<Vec<fn(&str)>> = Mutex::new(Vec::new());
/// 插件注册「账号被删除时我需要清理什么」。在 zone 装载后、接请求前调用一次。
pub fn on_delete(f: fn(&str)) {
if let Ok(mut hooks) = ON_DELETE.lock() {
if !hooks.contains(&f) {
hooks.push(f);
}
}
}
/// 账号删除成功后执行全部钩子。单个钩子没有失败语义(清理动作自身幂等)。
fn run_delete_hooks(username: &str) {
if let Ok(hooks) = ON_DELETE.lock() {
for f in hooks.iter() {
f(username);
}
}
}
// ===========================================================================
// 校验
// ===========================================================================
/// 账号名:2-32 位字母、数字、下划线或短横线
fn valid_username(name: &str) -> bool {
let n = name.chars().count();
if n < USERNAME_MIN_LEN || n > USERNAME_MAX_LEN {
return false;
}
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 索引)
// ===========================================================================
/// 身份 payload:`<username> \n <allowed_models> \n <llm_rpm> \n <llm_daily>`。
///
/// 一次查表同时拿到「是谁 / 能用哪些上游 / 限流多少」——LLM 热路径因此完全
/// 不必回读 `users.json`(那是同步文件 I/O + 全表 JSON 解码)。
/// 行数固定为 4;旧版 2 行 payload 由读取方按缺省值兜底。
fn identity_payload(user: &User) -> String {
format!(
"{}\n{}\n{}\n{}",
user.username,
user.allowed_models.join(","),
user.llm_rpm,
user.llm_daily
)
}
/// 把账号的 Key 索引写进共享内存。**所有改动 `api_key` 的写操作都必须调用**。
///
/// 写失败(共享内存 zone 满 / 分配失败)会让这个 Key **静默失效**:热路径查不到
/// 就是 401,且没有任何回源兜底。所以这里必须自己出声——「新建了 Key 却调不通、
/// 日志里什么都没有」是这类问题最难查的形态。调用方是否检查返回值不影响本日志。
pub fn sync_shm(user: &User) -> bool {
let ok = state::put_ukey(&user.api_key, &identity_payload(user));
if !ok {
util::log_err(&format!(
"[users] Key 索引写共享内存失败 user={} —— 该 Key 调 LLM 会 401(共享内存可能已满)",
user.username
));
}
ok
}
/// 全量重载 Key 索引(启动装载 / 批量变更后)。返回装载条数。
///
/// 只清 `ukey:` 前缀,不会误伤转发映射、上游表与管理会话。
/// `loaded < total` 时单独报一条 error:单个账号的失败已在 `sync_shm` 里出声,
/// 这里再汇总一次,避免「装载了 3/5 却只在滚动日志里淹没」。
pub fn reload_shm() -> usize {
state::clear_prefix(KEY_UKEY_PREFIX);
let table = store::read_users();
let total = table.len();
let mut loaded = 0;
for user in table.into_values() {
if sync_shm(&user) {
loaded += 1;
}
}
if loaded != total {
util::log_err(&format!(
"[users] Key 索引装载不全:{loaded}/{total} —— 有账号将无法调用 LLM"
));
}
loaded
}
// ===========================================================================
// 查询
// ===========================================================================
pub fn get(username: &str) -> Option<User> {
if username.is_empty() {
return None;
}
store::read_users().remove(username)
}
/// 全部账号,按账号名升序
pub fn all() -> Vec<User> {
store::read_users().into_values().collect()
}
/// 按 API Key 反查账号(常量时间比较,避免时序侧信道)。
///
/// **函数名里没有「快」字**:它每次都同步读 `users.json` 并全表解码,
/// 只适合管理接口这类低频调用方。LLM 转发热路径请用 `llm::identity`,
/// 那条路只查共享内存。
pub fn find_by_key(key: &str) -> Option<User> {
if key.is_empty() {
return None;
}
store::read_users()
.into_values()
.find(|u| util::ct_eq(&u.api_key, key))
}
// ===========================================================================
// 写入
// ===========================================================================
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,
api_key: util::gen_key(),
allowed_models: Vec::new(),
llm_rpm: crate::config::LLM_RPM_DEFAULT,
llm_daily: crate::config::LLM_DAILY_DEFAULT,
temp_grant_until: if grant_temp { now + TEMP_GRANT_TTL } else { 0 },
created_at: now,
extra: BTreeMap::new(),
}
}
/// 首次启动播种管理员。已有数据时原样返回,**不会覆盖**。
///
/// 返回 `Ok(true)` 表示「本次真的创建了」,用于打一条提醒日志。
pub fn seed_admin() -> Result<bool, String> {
let password =
std::env::var(INIT_ADMIN_PASSWORD_ENV).unwrap_or_else(|_| INIT_ADMIN_PASSWORD_DEFAULT.to_owned());
let mut created: Option<User> = None;
store::update_users(|users| {
if !users.is_empty() {
return Ok(());
}
let admin = build_user(INIT_ADMIN_USER, "", &password, "admin", false);
users.insert(admin.username.clone(), admin.clone());
created = Some(admin);
Ok(())
})?;
match created {
Some(u) => {
// 播种发生在 init_process(每个 worker 各一次),这里必须写穿,
// 否则「第一个 worker 建了账号、第二个 worker 覆盖索引」这类竞态
// 会让新建的 Key 时灵时不灵。
sync_shm(&u);
Ok(true)
}
None => Ok(false),
}
}
pub fn create(
username: &str,
display_name: &str,
password: &str,
role: &str,
grant_temp: bool,
) -> Result<User, String> {
let username = util::trim(username).to_owned();
if !valid_username(&username) {
return Err(format!(
"账号名只能是 {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} 位"));
}
let role = if role == "admin" { "admin" } else { "user" };
// 先做一次存在性预检,省掉白算 1000 轮哈希;真正的判定仍在锁内
if store::read_users().contains_key(&username) {
return Err(format!("账号 {username} 已存在"));
}
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) {
return Err(format!("账号 {username} 已存在"));
}
users.insert(username.clone(), user);
Ok(())
})?;
sync_shm(&created);
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:`,若只加新的不删旧的,
/// 被重置掉的 Key 仍然能调通模型——用户以为「换钥匙就安全了」,实际没有。
pub fn regenerate_key(username: &str) -> Result<String, String> {
let (old_key, new_key, updated) = store::update_users(|users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
let old = user.api_key.clone();
user.api_key = util::gen_key();
Ok((old, user.api_key.clone(), user.clone()))
})?;
state::remove_ukey(&old_key);
sync_shm(&updated);
Ok(new_key)
}
/// 设置账号可用的 LLM 上游白名单。传空表表示不限。
pub fn set_allowed_models(username: &str, slots: Vec<String>) -> Result<User, String> {
let updated = store::update_users(move |users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
user.allowed_models = slots;
Ok(user.clone())
})?;
sync_shm(&updated);
Ok(updated)
}
/// 修改账号的插件扩展字段(`User.extra`)。
///
/// 闭包拿到 `&mut User`——可同时改内核字段与 `extra`,由调用方决定语义。
/// 走 `store::update_users` 的「读-改-写 + 写穿 shm」统一路径,保证 shm
/// `ukey:` 索引与 `users.json` 同步刷新。
///
/// 配套 [`crate::models::User::extra`] 的 `#[serde(flatten)]`——上游
/// sso 收敛时提议(A1),按插件字段透传通道走。
pub fn update_extra<T, F>(username: &str, f: F) -> Result<T, String>
where
F: FnOnce(&mut User) -> Result<T, String>,
{
// 闭包内拿到 user 引用 → 调 f 修改 → f 返回后借用释放 → clone 出 owned
// user 给 sync_shm。`update_users` 的闭包签名是 `&mut UserTable`,把
// UserTable 的可变借用拆借给 &mut User 是 OK 的(Rust 借用分裂)。
let (out, updated) = store::update_users(move |users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
let out = f(user)?;
Ok((out, user.clone()))
})?;
sync_shm(&updated);
Ok(out)
}
/// 设置账号的 LLM 限流参数。`None` = 保持现值;`0` = 不限;正数 = 上限。
///
/// 改动的是 `ukey:` payload 的组成部分,所以**必须写穿**——
/// 否则表现为「改完限额,热路径还按旧额度放行」。
pub fn set_llm_limits(username: &str, rpm: Option<i64>, daily: Option<i64>) -> Result<User, String> {
if let Some(v) = rpm {
if v < 0 {
return Err("每分钟上限不能为负数(0 表示不限)".to_owned());
}
}
if let Some(v) = daily {
if v < 0 {
return Err("每日上限不能为负数(0 表示不限)".to_owned());
}
}
let updated = store::update_users(move |users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
if let Some(v) = rpm {
user.llm_rpm = v;
}
if let Some(v) = daily {
user.llm_daily = v;
}
Ok(user.clone())
})?;
sync_shm(&updated);
Ok(updated)
}
/// 授予临时授权权限(默认 6 小时),返回到期时间戳
pub fn grant_temp(username: &str, hours: Option<&String>) -> Result<i64, String> {
let ttl = hours
.and_then(|h| h.parse::<i64>().ok())
.map(|h| h * 3600)
.unwrap_or(TEMP_GRANT_TTL);
store::update_users(|users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
user.temp_grant_until = util::now() + ttl;
Ok(user.temp_grant_until)
})
}
pub fn revoke_temp(username: &str) -> Result<(), String> {
store::update_users(|users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
user.temp_grant_until = 0;
Ok(())
})
}
pub fn set_password(username: &str, password: &str) -> Result<(), String> {
if password.len() < PASSWORD_MIN_LEN {
return Err(format!("密码至少 {PASSWORD_MIN_LEN} 位"));
}
let salt = util::gen_salt();
let hash = util::hash_password(password, &salt);
// 改口令不动 api_key,因此不需要同步 Key 索引
store::update_users(move |users: &mut UserTable| {
let user = users.get_mut(username).ok_or("账号不存在")?;
user.salt = salt;
user.pwd_hash = hash;
Ok(())
})
}
/// 删除账号。两条红线:不能删自己、必须至少保留一个管理员。
///
/// 顺带摘掉 Key 索引——否则删掉的账号仍能通过 LLM 代理调用模型。
pub fn delete(username: &str, operator: &str) -> Result<(), String> {
if username == operator {
return Err("不能删除当前登录的账号".to_owned());
}
let username = username.to_owned();
let deleted = username.clone();
let removed_key = store::update_users(move |users| {
let user = users.get(&username).ok_or("账号不存在")?;
if user.role == "admin" {
let admins = users.values().filter(|u| u.role == "admin").count();
if admins <= 1 {
return Err("至少需要保留一个管理员账号".to_owned());
}
}
Ok(users.remove(&username).map(|u| u.api_key).unwrap_or_default())
})?;
if !removed_key.is_empty() {
state::remove_ukey(&removed_key);
}
// 内核自己的键已摘掉;用量账本等插件键空间由 on_delete 钩子清理
// (谁装了谁清——钩子为空说明对应插件未装配,自然也无键可清)
run_delete_hooks(&deleted);
Ok(())
}
// ===========================================================================
// 对外投影
// ===========================================================================
/// 转成前端可见的字段(**绝不包含 salt / pwd_hash**)
pub fn view(user: &User) -> Value {
let now = util::now();
let until_ts = user.temp_grant_until;
let active = until_ts > now;
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),
"allowed_models": user.allowed_models,
"llm_rpm": user.llm_rpm,
"llm_daily": user.llm_daily,
"created_at": user.created_at,
"created_at_text": util::fmt_time(user.created_at),
"temp_grant": active,
"temp_grant_until": until_ts,
"temp_grant_until_text": if active { util::fmt_time(until_ts) } else { String::new() },
"temp_grant_left": if active { until_ts - now } else { 0 },
"temp_grant_left_text": if active { util::fmt_left(until_ts - now) } else { String::new() },
})
}