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
This commit is contained in:
admin committed 2026-09-13 11:43:22 +08:00
1 parent 1fb83e4dda
commit 74aeefee58
35 files changed
+2513 -1360

No files matched your search

+485
View File
@@ -0,0 +1,485 @@
//! 插件路由表(过渡期):LLM 上游 / 用量 / API 代理类端点。
//!
//! 身份类端点已下沉 `ipass-core::api`(CorePlugin),域名类端点已下沉
//! `plugin-domain::api`(DomainPlugin)。本表随 P3 / P4 把 llm 与 apix
//! 端点迁入各自插件后逐步清空、最终删除。
//!
//! 鉴权语义与内核共用一套:`ipass_core::api::{Guard, Actor, run_guarded}`。
use ngx::core::{Pool, Status};
use ngx::ffi::ngx_http_request_t;
use ngx::http::HTTPStatus;
use serde_json::{Value, json};
use ipass_core::api::{Actor, Guard, run_guarded, user_or_401};
use crate::apix;
use crate::config;
use crate::http;
use crate::state;
use crate::stats;
use crate::upstreams;
use crate::users;
use crate::util;
// ===========================================================================
// 路由
// ===========================================================================
/// 路由表。刻意用精确匹配而非正则——接口路径是固定的,
/// 正则只会引入「写错锚点导致前缀误匹配」的风险。
fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> {
let entry: (Guard, Handler) = match (method, uri) {
("GET", "/api/admin/upstreams") => (Guard::Admin, h_admin_upstreams),
("POST", "/api/admin/upstreams/save") => (Guard::Admin, h_admin_upstream_save),
("POST", "/api/admin/upstreams/test") => (Guard::Admin, h_admin_upstream_test),
("POST", "/api/admin/upstreams/delete") => (Guard::Admin, h_admin_upstream_delete),
("GET", "/api/admin/usage") => (Guard::Admin, h_admin_usage),
("GET", "/api/admin/trend") => (Guard::Admin, h_admin_trend),
("GET", "/api/admin/apix") => (Guard::Admin, h_admin_apix),
("POST", "/api/admin/apix/save") => (Guard::Admin, h_admin_apix_save),
("POST", "/api/admin/apix/delete") => (Guard::Admin, h_admin_apix_delete),
("POST", "/api/admin/apix/test") => (Guard::Admin, h_admin_apix_test),
("GET", "/api/v1/apix") => (Guard::User, h_my_apix),
("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),
_ => return None,
};
Some(entry)
}
type Handler = fn(*mut ngx_http_request_t, Actor) -> Status;
/// 本表分发:认领则返回响应状态,不认领返回 `None`(交给下一个插件)。
pub fn dispatch(r: *mut ngx_http_request_t) -> Option<Status> {
let method = http::method_str(r);
let uri = http::uri(r);
let Some((guard, handler)) = route(&method, &uri) else {
return None;
};
Some(run_guarded(r, guard, handler))
}
// ===========================================================================
// 管理员:LLM 上游
// ===========================================================================
fn h_admin_upstreams(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
http::ok(
r,
json!({ "items": upstreams::view_all(&upstreams::all(), &http::host_port(r)) }),
"ok",
)
}
fn h_admin_upstream_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
// 表单没提交 enabled 字段时视为「启用」——否则改个备注就会把上游改停,
// 这种误伤在管理台上极难自查
let enabled = match p.get("enabled") {
None => true,
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"),
) {
Ok(up) => {
// 用校验后的 slot 回显;直接拿原始入参会把大小写差异带进响应
let slot = upstreams::validate_slot(slot_raw).unwrap_or_default();
util::log_notice(&format!(
"[api] 保存 LLM 上游 {slot} enabled={enabled} models={}",
up.models.len()
));
// base_url 带「调用方正在用的端口」:见 upstreams::base_url 的说明
http::ok(r, upstreams::view(&slot, &up, &http::host_port(r)), "已保存")
}
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("")) {
Ok(slot) => {
util::log_notice(&format!("[api] 删除 LLM 上游 {slot}"));
http::ok(r, json!({ "slot": slot }), "已删除")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:上游连通性测试(管理台「测试」按钮)。
///
/// 面板把 slot 放在 query(`?slot=x`),把**要发给上游的探测 JSON**(真实
/// chat/completions 请求,max_tokens=1)放在请求体——模块对体零改写。
/// 实现上校验 slot 存在后 `ngx_http_internal_redirect` 到管理 server 的
/// 内部 location `/_upstream_test/<slot>/v1/chat/completions`:
///
/// * `proxy_pass $llm_target` 原样复用 LLM 链路的取 slot / 拼路径 / 换真 Key
/// 逻辑(见 `llm::slot_of` 对 `/_upstream_test` 前缀的识别);
/// * 请求体在 API 两段式读取里已经进 `r->request_body`,内部重定向后由
/// proxy 原样转发;
/// * 上游的真实状态码与响应体直接透传给面板——通不通、错在哪个厂商,
/// 面板看到的就是厂商原话。
///
/// 为什么不能在浏览器里直测:上游真 Key 只存在服务端(面板只有掩码),
/// 且 lm 域名与 mdm 不同源,fetch 会被 CORS 拦住——测试必须在服务端发起。
fn h_admin_upstream_test(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let slot_raw = http::params(r).get("slot").cloned().unwrap_or_default();
let slot = match upstreams::validate_slot(&slot_raw) {
Ok(s) => s,
Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e),
};
if state::get_upstream(&slot).is_none() {
return http::fail(r, HTTPStatus::NOT_FOUND, &format!("上游 {slot} 不存在"));
}
let uri = format!("/_upstream_test/{slot}/v1/chat/completions");
util::log_notice(&format!("[api] 测试 LLM 上游 {slot}"));
// ⚠️ nginx 的 internal_redirect 只**浅拷贝 ngx_str_t 结构体**(data 指针 + len),
// 不拷贝字节内容。若把栈上 String 的指针直接递过去,函数一返回堆内存就被回收,
// 之后 log 阶段读 r->uri 全是 NUL——健康标记、slot 解析全部静默失效(实测踩过)。
// 必须把 URI 字节拷进**请求池**,让它活到请求结束。
//
// SAFETY: r 有效;池内存在整个请求生命周期内有效。
unsafe {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = uri.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
return http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, "内存分配失败");
}
core::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
let mut u = nginx_sys::ngx_str_t {
len: bytes.len(),
data,
};
let mut args = nginx_sys::ngx_str_t {
len: 0,
data: std::ptr::null_mut(),
};
nginx_sys::ngx_http_internal_redirect(r, &mut u, &mut args);
}
Status::NGX_DONE
}
/// 管理员: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 用量趋势(图表数据源)。
///
/// `days` 缺省 14 天,上限由 `config::TREND_DAYS_MAX` 兜住。
/// 按账号 / 按上游两个维度需要**先知道有哪些名字**(键里带日窗 id,扫不出来),
/// 所以这里把 users / upstreams 的名册传进去,由 stats 逐个精确取键。
fn h_admin_trend(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let days = p
.get("days")
.and_then(|v| util::trim(v).parse::<i64>().ok())
.unwrap_or_else(stats::trend_default_days);
let usernames: Vec<String> = users::all().into_iter().map(|u| u.username).collect();
// API 代理与 LLM 上游共用同一片用量键空间,只是 slot 带 `api/` 前缀
// (见 `config::APIX_STATS_PREFIX`)——这里一起列出,趋势图才会出现它们
let slots: Vec<String> = upstreams::all()
.into_iter()
.map(|(slot, _)| slot)
.chain(apix::all().into_iter().map(|(slug, _)| format!("{}{}", config::APIX_STATS_PREFIX, slug)))
.collect();
http::ok(r, stats::trend(util::now(), days, &usernames, &slots), "ok")
}
// ===========================================================================
// API 代理管理
// ===========================================================================
/// 管理员:API 代理清单
fn h_admin_apix(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let port = http::host_port(r);
let list = apix::all();
http::ok(
r,
json!({
"items": apix::view_all(&list, &port),
"count": list.len(),
}),
"ok",
)
}
/// 管理员:新增/修改一个 API 代理条目
fn h_admin_apix_save(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
let slug = p.get("slug").cloned().unwrap_or_default();
let asset = p.get("asset_id").cloned().unwrap_or_default();
// 参数清单允许两种写法:逗号分隔(`q,format`)或 JSON 数组(`["q"]`)
let params = p.get("params").and_then(|v| {
let v = util::trim(v);
if v.is_empty() {
return None;
}
Some(if let Ok(Value::Array(arr)) = serde_json::from_str::<Value>(v) {
arr.into_iter()
.filter_map(|x| x.as_str().map(str::to_owned))
.collect::<Vec<String>>()
} else {
v.split(',').map(str::to_owned).collect::<Vec<String>>()
})
});
// 不带 enabled 视为「启用」:新建表单里漏勾是常见手滑,默认值取更安全的一侧
let enabled = match p.get("enabled") {
Some(v) => util::to_bool(Some(v)),
None => true,
};
match apix::upsert(
&slug,
&asset,
p.get("base"),
p.get("key"),
p.get("supplier"),
p.get("name"),
p.get("desc"),
params,
enabled,
p.get("note"),
) {
Ok(item) => {
util::log_notice(&format!("[api] 保存 API 代理 {slug} → {asset}"));
http::ok(r, json!({ "slug": slug, "asset_id": item.asset_id }), "已保存")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:删除一个 API 代理条目
fn h_admin_apix_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let p = http::params(r);
match apix::remove(p.get("slug").map(String::as_str).unwrap_or("")) {
Ok(slug) => {
util::log_notice(&format!("[api] 删除 API 代理 {slug}"));
http::ok(r, json!({ "slug": slug }), "已删除")
}
Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e),
}
}
/// 管理员:探测供应商 Key 是否可用(管理台「测试」按钮)。
///
/// 走供应商的**免费预估**接口(`/api/v1/ai/estimate`):它不执行资产、不扣费,
/// 响应里还带 `current_balance_usd` —— 一次调用同时拿到「Key 通不通」和
/// 「还剩多少钱」。实现上内部重定向到管理 server 的 `/_apix_probe/<slug>`,
/// 复用 `$apix_probe_*` 变量(拼体、换 Key 与真实转发同一套逻辑)。
fn h_admin_apix_test(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let slug_raw = http::params(r).get("slug").cloned().unwrap_or_default();
let slug = match apix::validate_slug(&slug_raw) {
Ok(s) => s,
Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e),
};
if apix::lookup(&slug).is_none() {
return http::fail(r, HTTPStatus::NOT_FOUND, &format!("代理 {slug} 不存在或已停用"));
}
let uri = format!("{}{}", apix::PROBE_URI_PREFIX, slug);
util::log_notice(&format!("[api] 测试 API 代理 {slug}"));
// ⚠️ 与 h_admin_upstream_test 同一个坑:internal_redirect 只浅拷贝 ngx_str_t,
// 必须把字节拷进请求池,否则函数返回后 r->uri 全是 NUL。
// SAFETY: r 有效;池内存在整个请求生命周期内有效。
unsafe {
let pool = Pool::from_ngx_pool((*r).pool);
let bytes = uri.as_bytes();
let data = pool.alloc(bytes.len()) as *mut u8;
if data.is_null() {
return http::fail(r, HTTPStatus::INTERNAL_SERVER_ERROR, "内存分配失败");
}
core::ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len());
let mut u = nginx_sys::ngx_str_t { len: bytes.len(), data };
let mut args = nginx_sys::ngx_str_t {
len: 0,
data: core::ptr::null_mut(),
};
nginx_sys::ngx_http_internal_redirect(r, &mut u, &mut args);
}
Status::NGX_DONE
}
/// 账号态:列出当前可用的 API 代理及调用地址
fn h_my_apix(r: *mut ngx_http_request_t, _actor: Actor) -> Status {
let port = http::host_port(r);
let items: Vec<Value> = apix::all()
.into_iter()
.filter(|(_, it)| it.enabled)
.map(|(slug, it)| apix::view(&slug, &it, &port))
.collect();
http::ok(r, json!({ "items": items, "count": items.len() }), "ok")
}
/// 账号态:看看自己能用哪些上游。
///
/// 刻意只回显 slot / base_url / **模型清单**——**不回显任何密钥**(连脱敏都不给,
/// 上游密钥与调用方无关,没有知道的必要)。
fn h_my_upstreams(r: *mut ngx_http_request_t, actor: Actor) -> Status {
// 回显的 base_url 必须带「调用方正在用的端口」,否则客户端照着拼会打不通
let port = http::host_port(r);
let user = match user_or_401(r, actor) {
Ok(u) => u,
Err(e) => return e,
};
let items: Vec<Value> = upstreams::available(&user.allowed_models)
.into_iter()
.map(|(slot, up)| {
let (status, code, checked_at) = match upstreams::health(&slot) {
Some((ok, c, ts)) => (if ok { "ok" } else { "failed" }, c, ts),
None => ("unknown", 0, 0),
};
json!({
"slot": slot,
"base_url": upstreams::base_url(&slot, &up, &port),
"anthropic_base_url": upstreams::anthropic_base_url(&slot, &up, &port),
"models": up.models,
"note": up.note,
"status": status,
"status_code": if code > 0 { json!(code) } else { Value::Null },
"checked_at": checked_at,
})
})
.collect();
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 {
// 同 h_my_upstreams:base_url 跟随调用方所用的端口
let port = http::host_port(r);
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, &port),
"note": up.note,
}));
}
}
http::ok(
r,
json!({
"items": items,
"upstreams": available
.iter()
.map(|(slot, up)| {
let (status, code, checked_at) = match upstreams::health(slot) {
Some((ok, c, ts)) => (if ok { "ok" } else { "failed" }, c, ts),
None => ("unknown", 0, 0),
};
json!({
"slot": slot,
"base_url": upstreams::base_url(slot, up, &port),
"anthropic_base_url": upstreams::anthropic_base_url(slot, up, &port),
"models": up.models,
"status": status,
"status_code": if code > 0 { json!(code) } else { Value::Null },
"checked_at": checked_at,
})
})
.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);
// token 计量(body filter 从上游 usage 抓的;抓不到 = 0,不补估)
let tin = stats::tokens_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() },
"tokens": tin.json(),
"models": models,
// 限额一起回显:客户端可据此自我节流,不必等 429
"limits": { "rpm": user.llm_rpm, "daily": user.llm_daily },
}),
"ok",
)
}