Files
ssw__ipass/rust/gateway/src/upstreams.rs
T
admin 74aeefee58 refactor(plugin): P0-P2 插件化落地 —— workspace 化 + ipass-core + plugin-domain
- P0: rust/ 改 workspace(ipass-core 内核 + gateway 唯一 cdylib),
  [profile.release] 上移根、依赖收敛 workspace.dependencies;
  users::delete 的 stats::forget 依赖改为 on_delete 钩子注册表
- P1: 契约层 core/plugin.rs(Plugin trait)+ core/loc.rs(Switch 并集 +
  set_switch_fn,未实现变体保守 false);gateway PLUGINS 分发循环,
  不认领统一 404(插件绝不自行 404)
- P2: 身份端点下沉 core/api.rs(CorePlugin + CoreExt 扩展注册表,
  gateway 作装配根回填域名数/用量/连带回收/白名单校验);
  plugin-domain crate(domains + DomainEntry + sub: 前缀 + ResolveHandler
  + $proxy_backend_addr + 域名类端点含 purge)
- 行为等价:conf/nginx.conf、Dockerfile、tests 零改动,262 回归全绿
- 方案文档 docs/plugin/PLUGINIZATION_PLAN.md
2026-09-13 11:43:22 +08:00

398 lines
15 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.
//! LLM 上游配置与共享内存同步。
//!
//! 这是「转发映射」机制在 LLM 侧的翻版:`domains.rs` 管
//! `子域名 → 后端`,本模块管 `路径前缀(slot) → 上游(基址 + 密钥)`。
//! 两者都**写穿共享内存**,理由相同——热路径未命中即失败,不回源读文件。
//!
//! ## 为什么按 URL 前缀分上游,而不是按请求体里的 `model`
//!
//! 转发决策点在 access 阶段,而请求体要到 content 阶段才读得到
//! (见 `http::collect_body` 的调用前提)。按 `model` 字段分流就必须放弃
//! `proxy_pass`、自己实现 upstream 转发,代码量与出错面差一个数量级。
//! 代价只是客户端 base_url 需要带上 slot 段,可接受。
//!
//! `data/llm-upstreams.json` 含上游真实 API Key,**敏感级别等同 `users.json`**。
use serde_json::{Value, json};
use crate::config::{KEY_UH_PREFIX, 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;
use crate::util;
/// 共享内存 payload 的内部分隔符:base 与 auth 之间。
///
/// 与 `config::VAL_SEP`(0x1f,负责切 payload / expires_at)是两层不同的
/// 分隔,不能混用。base 是 URL、auth 是 `Bearer <token>`,都不可能含换行。
pub const PAYLOAD_SEP: char = '\n';
// ===========================================================================
// 校验
// ===========================================================================
/// slot:小写字母/数字开头,其后可含短横线、下划线,总长 ≤ 32。
///
/// 允许下划线(`azure_openai` 这类厂牌写法很常见),这点比子域名规则宽。
pub fn validate_slot(raw: &str) -> Result<String, String> {
let s = util::trim(raw).to_ascii_lowercase();
if s.is_empty() {
return Err("缺少 slot 参数".to_owned());
}
if s.len() > UPSTREAM_SLOT_MAX_LEN {
return Err(format!("slot 长度不能超过 {UPSTREAM_SLOT_MAX_LEN} 个字符"));
}
let bytes = s.as_bytes();
let head_ok = matches!(bytes[0], b'a'..=b'z' | b'0'..=b'9');
let tail_ok = bytes[1..].iter().all(|&b| matches!(b, b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_'));
if !head_ok || !tail_ok {
return Err("slot 只能是小写字母、数字、短横线或下划线,且不能以符号开头".to_owned());
}
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 上游常挂在网关路径下
/// (如 `https://gw.corp.com/llm`),所以要允许尾随路径。
pub fn validate_base(raw: &str) -> Result<String, String> {
let s = util::trim(raw).trim_end_matches('/').to_owned();
if s.is_empty() {
return Err("缺少 base 参数".to_owned());
}
if s.len() > UPSTREAM_BASE_MAX_LEN {
return Err(format!("base 长度不能超过 {UPSTREAM_BASE_MAX_LEN} 个字符"));
}
let rest = if let Some(r) = s.strip_prefix("https://") {
r
} else if let Some(r) = s.strip_prefix("http://") {
r
} else {
return Err("base 必须以 http:// 或 https:// 开头,例如 https://api.openai.com".to_owned());
};
if rest.is_empty() {
return Err("base 缺少主机名".to_owned());
}
if rest.chars().any(char::is_whitespace) || rest.contains('@') {
return Err("base 不允许包含空格或用户信息(user@host)".to_owned());
}
if rest.split('/').next().unwrap_or("").is_empty() {
return Err("base 缺少主机名".to_owned());
}
Ok(s)
}
// ===========================================================================
// 共享内存同步(写穿 / 装载)
// ===========================================================================
/// 把一条上游配置同步进共享内存。**所有写操作之后必须调用它**。
///
/// 关闭(`enabled=false`)时是**删除**而不是写入空值——热路径
/// 「查不到 = 不可用」,这样停用即刻生效,且不留残留条目。
pub fn sync_shm(slot: &str, up: &Upstream) {
if up.enabled {
if !state::put_upstream(slot, &payload_of(up)) {
util::log_err(&format!(
"[upstreams] 上游配置写共享内存失败 slot={slot} —— 该上游会 404(共享内存可能已满)"
));
}
} else {
state::remove_upstream(slot);
}
}
fn payload_of(up: &Upstream) -> String {
format!("{}{}{}", up.base, PAYLOAD_SEP, up.auth)
}
/// 全量重载上游表(启动装载 / 批量变更后)。返回装载条数。
///
/// 只清 `up:` 前缀,不会误伤转发映射与管理会话。
pub fn reload_shm() -> usize {
state::clear_prefix(KEY_UP_PREFIX);
let mut expected = 0;
let mut loaded = 0;
for (slot, up) in store::read_upstreams() {
if up.enabled {
expected += 1;
}
if up.enabled && state::put_upstream(&slot, &payload_of(&up)) {
loaded += 1;
}
}
if loaded != expected {
util::log_err(&format!(
"[upstreams] 上游装载不全:{loaded}/{expected} —— 有上游会 404"
));
}
loaded
}
/// 拆 payload:`base \n auth` → `(base, auth)`。
///
/// 无分隔符时视为「只有 base、无鉴权头」——兼容手工编辑文件时漏写分隔的情况。
pub fn split_payload(payload: &str) -> (&str, &str) {
match payload.split_once(PAYLOAD_SEP) {
Some((b, a)) => (b, a),
None => (payload, ""),
}
}
// ===========================================================================
// 查询
// ===========================================================================
/// 全部上游,按 slot 升序
pub fn all() -> Vec<(String, Upstream)> {
store::read_upstreams().into_iter().collect()
}
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:88/deepseek/v1
/// https://api.openai.com → https://lm.mayishangshu.cn:88/openai
/// ```
///
/// `port` 由调用方从请求 Host 头取(`http::host_port`),**不要写死**:
/// 部署在 88 时客户端必须带 `:88` 才连得到,而放在 443 反代后面时又必须不带端口。
/// 写死任何一种,都会在另一种部署里给出一个「看着对、实际打不通」的地址。
///
/// 反过来(不管上游 base 的路径、一律拼 `/v1`)会让「base 自带 /v1」的上游
/// 变成 `/v1/v1/chat/completions` → 上游 404,且客户端拿到的是空响应体,
/// 排查起来完全看不出是网关拼错了。**实测踩过,别再改回去。**
pub fn base_url(slot: &str, up: &Upstream, port: &str) -> 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}{port}/{slot}{path}")
}
/// Anthropic 客户端(Claude Code / Claude SDK)应当使用的 `ANTHROPIC_BASE_URL`。
///
/// 协议段由**客户端**负责表达(网关不猜协议),但这段路径是网关替客户端拼好的,
/// 所以要处理重合:上游 `base` 若已钉在 `…/anthropic`(协议钉死型记录),其
/// `base_url` 末尾已经带 `/anthropic`,再无脑追加会得到 `…/anthropic/anthropic`。
pub fn anthropic_base_url(slot: &str, up: &Upstream, port: &str) -> String {
let b = base_url(slot, up, port);
if b.ends_with("/anthropic") {
b
} else {
format!("{b}/anthropic")
}
}
/// 模型发现:把可用上游挂载的模型摊平成 `(模型名, 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
}
// ===========================================================================
// 写入
// ===========================================================================
/// 新增或覆盖一个上游。
///
/// `auth = None` 表示**保持原值**(表单只改 base 时不必回填密钥);
/// `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| {
// 先克隆出来:下面 insert 需要可变借用,不能与这里的不可变借用并存
let existing = table.get(&key).cloned();
let auth = match auth_raw {
Some(a) => util::trim(a).to_owned(),
None => existing.as_ref().map(|e| e.auth.clone()).unwrap_or_default(),
};
let note = match note {
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, models, auth, enabled, note, created_at };
table.insert(key.clone(), item.clone());
Ok(item)
})?;
sync_shm(&slot, &up);
Ok(up)
}
/// 删除上游,并立刻从共享内存摘掉
pub fn remove(slot_raw: &str) -> Result<String, String> {
let slot = validate_slot(slot_raw)?;
let key = slot.clone();
store::update_upstreams(move |table| {
if table.remove(&key).is_none() {
return Err(format!("上游 {key} 不存在"));
}
Ok(())
})?;
state::remove_upstream(&slot);
Ok(slot)
}
// ===========================================================================
// 对外投影
// ===========================================================================
/// 转成管理台可见的字段。
///
/// **绝不回显完整 auth**——管理台页面会被截图、被浏览器插件读取,
/// 回显上游真 Key 等于把公司所有厂商密钥摆在一个 HTML 里。
pub fn view(slot: &str, up: &Upstream, port: &str) -> Value {
let (status, code, checked_at) = match health(slot) {
Some((ok, c, ts)) => (if ok { "ok" } else { "failed" }, c, ts),
None => ("unknown", 0, 0),
};
json!({
"slot": slot,
"base": up.base,
"base_url": base_url(slot, up, port),
"anthropic_base_url": anthropic_base_url(slot, up, port),
"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,
"note": up.note,
"created_at": up.created_at,
"created_at_text": util::fmt_time(up.created_at),
"status": status,
"status_code": if code > 0 { json!(code) } else { Value::Null },
"checked_at": checked_at,
"checked_at_text": if checked_at > 0 { util::fmt_time(checked_at) } else { String::new() },
})
}
pub fn view_all(list: &[(String, Upstream)], port: &str) -> Vec<Value> {
list.iter().map(|(slot, up)| view(slot, up, port)).collect()
}
// ===========================================================================
// 上游健康缓存(uh:)
// ===========================================================================
/// 记录一次上游真实响应结果。**只读端不会用它做任何决策**——转发路径
/// 从不查这份缓存,所以误标最多影响展示,不会误杀请求。
///
/// 写失败必须出声(热路径无回源兜底是转发侧的事,这里出声是为了
/// 别让「列表永远显示未探测」这种静默怪象无人解释)。
pub fn mark_health(slot: &str, ok: bool, code: i64) {
let ts = util::now();
let payload = format!("{}\n{}\n{}", if ok { 1 } else { 0 }, code, ts);
if !state::put(
KEY_UH_PREFIX,
slot.as_bytes(),
payload.as_bytes(),
ts + 30 * 86400,
) {
util::log_err(&format!("[upstreams] 健康状态写共享内存失败 slot={slot}"));
}
}
/// 读健康缓存:`Some((是否正常, 上游状态码, 记录时刻))`,没探测过 = `None`。
pub fn health(slot: &str) -> Option<(bool, i64, i64)> {
let (payload, _) = state::get(KEY_UH_PREFIX, slot.as_bytes())?;
let mut it = payload.split('\n');
let ok = it.next().unwrap_or("0").trim() == "1";
let code = it
.next()
.and_then(|s| s.trim().parse::<i64>().ok())
.unwrap_or(0);
let ts = it
.next()
.and_then(|s| s.trim().parse::<i64>().ok())
.unwrap_or(0);
Some((ok, code, ts))
}