diff --git a/docs/plugin/PLUGINIZATION_PLAN.md b/docs/plugin/PLUGINIZATION_PLAN.md new file mode 100644 index 0000000..1e18ad3 --- /dev/null +++ b/docs/plugin/PLUGINIZATION_PLAN.md @@ -0,0 +1,528 @@ +# iPass 插件化改造方案(core + 编译期插件) + +> 参照实现:`ssw/sso`(`git@192.168.1.18:13300/ssw/sso.git`)——它是从本项目衍生的插件式版本, +> 已跑通「内核 + 插件 + 单 `.so` 装配」并留有两份可直接复用的文档: +> `docs/plugin-architecture-analysis.md`(为什么不拆多 `.so`)与 +> `.workbuddy/skills/ipass-core-add-plugin/SKILL.md`(怎么加一个插件)。 +> +> **本方案只做 iPass 自身的插件化**(已拍板):与 `ssw/sso` 的仓库归属、身份插件是否并入, +> 留到 P5 再定。**身份端点(登录 / 会话 / 账号管理)由 `ipass-core` 直接收口**(已拍板)。 +> +> 目标:**行为完全等价**重构——`data/*.json` 一个字节不改、`conf/nginx.conf` 一条指令不改、 +> 现有 262 项回归全绿;换来的是「加一个能力 = 加一个 crate + 在 gateway 加 5 处装配」。 + +--- + +## 0. 一句话判据:什么进内核 + +> **去掉这个插件,网关还能不能跑?** 能 → 它不是内核。 + +推论: + +| 能力 | 归属 | 理由 | +| --- | --- | --- | +| 共享内存唯一 zone / 文件写锁 | **core** | 只能有一份,多份就失去「热路径零文件 I/O」的意义 | +| `data/users.json` 读写、`ukey:` Key 索引 | **core** | 一处吊销处处生效;插件各写一份等于没共用 | +| 账号模型 `User` | **core** | 域名审批、LLM 配额、API 代理都要挂在同一账号上 | +| 会话 / 登录失败锁定 | **core** | 与账号强绑定;且是**所有插件端点的公共前置** | +| 身份类 HTTP 端点(`/api/admin/login`、`/api/admin/users*`、`/api/v1/me`) | **core** | 同上;已拍板由 core 收口 | +| `sk_` Key 下行鉴权 + `rl:` 配额 | **core** | **两条下行链路(LLM + API 代理)共用**,见 §4② | +| 动态域名映射与审批 | plugin-domain | 独立业务 | +| LLM 路由 / 上游 / 配额计费 / 对话审计 / 用量趋势 | plugin-llm | 独立业务 | +| 外部 API 供应商资产代理 | plugin-apix | 独立业务 | + +--- + +## 1. 现状量测(改造前) + +``` +rust/ 单 crate,7035 行,产出 libipass_gateway.so +├── Cargo.toml [package] ipass-gateway v2.0.0 +│ [lib] crate-type = ["cdylib","rlib"] ← 必须留 cdylib(nginx 要) +├── build.rs +├── vendor/ngx-rust/ path 依赖(不可走 crates.io / git,见 Cargo.toml 注释) +└── src/ 17 个模块 +``` + +| 文件 | 行 | 依赖(`use crate::`) | +| --- | --- | --- | +| `config.rs` | 232 | — | +| `models.rs` | 219 | — | +| `state.rs` | 362 | config | +| `store.rs` | 196 | config models state | +| `session.rs` | 57 | config state util | +| `util.rs` | 354 | config | +| `http.rs` | 223 | util | +| `users.rs` | 405 | config models state **stats** store util | +| `domains.rs` | 485 | config models state store util | +| `upstreams.rs` | 397 | config models state store util | +| `llm.rs` | 442 | config state upstreams util | +| `llm_usage.rs` | 275 | — | +| `llm_audit.rs` | 200 | config store util | +| `stats.rs` | 585 | config state util | +| `apix.rs` | 563 | config http models state store util | +| `api.rs` | 1018 | **除 lib 外全部**(apix config domains http models session state stats upstreams users util) | +| `lib.rs` | 1022 | 模块壳:7 条指令 + 6 个 phase handler + 10 个变量注册 | + +**三条热路径 + 一条管理通道**(全部注册在 `lib.rs`,靠 location 开关收敛): + +| 入口 | 阶段 | 开关 | handler | 现状落点 | +| --- | --- | --- | --- | --- | +| `*dm./*` | access | `ipass_proxy` | `ResolveHandler` | `lib.rs` + `domains.rs` | +| `lm.//*` | access | `ipass_llm` | `LlmHandler` | `lib.rs` + `llm.rs` | +| `lm./apix/` | access | `ipass_apix` | `ApiProxyHandler` | `lib.rs:323` + `apix.rs` | +| `mdm./api/*` | content | `ipass_api` | `ApiHandler` | `lib.rs` + `api.rs` | + +另有 log 阶段两个旁路 handler:`LlmHealthHandler`(上游健康标记)、`AuditHandler`(对话审计 + +token 计量);以及 `llm_usage::install()`(body filter 抓上游响应里的 usage)。 + +**共享内存键前缀全景**(`config.rs:78-166`)——已天然按域分片,是插件划分的现成依据: + +| 前缀 | 归属 | 含义 | +| --- | --- | --- | +| `sess:` `fail:` `ukey:` | **core** | 会话 / 登录失败计数 / Key→身份索引 | +| `rl:` | **core**(本方案调整,见 §4②) | 配额窗口 | +| `sub:` | plugin-domain | 子域名 → 后端 | +| `up:` `st:` `ust:` `ums:` `utt:` `utms:` `ud:` `udu:` `uds:` `uh:` | plugin-llm | 上游 / 上游状态 / 用量账本 / 趋势日桶 / 健康标记 | +| `ax:` | plugin-apix | 代理 slug → 供应商资产 | + +--- + +## 2. 目标结构 + +``` +rust/ +├── Cargo.toml # [workspace](成员 + 统一依赖 + [profile.release]) +├── vendor/ngx-rust/ # 保持不动(path 依赖) +├── crates/ +│ ├── ipass-core/ # 内核:状态 / 账号 / 装配契约 / 身份端点 +│ │ └── src/ +│ │ ├── config.rs # 仅共性常量 + sess:/fail:/ukey:/rl: 前缀 +│ │ ├── models.rs # User(全字段 serde(default)) +│ │ ├── state.rs # 唯一 shm zone + 泛型原语 +│ │ ├── store.rs # JSON 原子写 + 文件写锁 + data_dir +│ │ ├── usage.rs # 【拆自 stats.rs】通用记账原语(无 LLM 语义) +│ │ ├── auth.rs # 【新】下行 sk_ 鉴权 + rl: 配额(两条链路共用) +│ │ ├── users.rs # 账号唯一写入口 + on_delete 钩子 +│ │ ├── session.rs # 会话 +│ │ ├── plugin.rs # 【新】Plugin 契约 +│ │ ├── loc.rs # 【新】Switch 枚举 + 注入式开关查询 +│ │ ├── http.rs / util.rs # 请求响应原语 / 通用工具 +│ │ └── api.rs # 【拆自 api.rs】身份类端点 + CorePlugin +│ ├── plugin-domain/ # 动态域名 +│ │ └── src/{lib,keys,models,domains,resolve,api}.rs +│ ├── plugin-llm/ # LLM 路由 / 配额计费 / 审计 / 用量趋势 +│ │ └── src/{lib,keys,models,llm,upstreams,usage_filter,audit,stats,resolve,api}.rs +│ └── plugin-apix/ # 外部 API 供应商资产代理 +│ └── src/{lib,keys,models,apix,resolve,api}.rs +└── gateway/ # 唯一 cdylib:模块壳 + PLUGINS 注册表 + └── src/lib.rs +``` + +**关键不变式:仓库里只有一个 `cdylib`(gateway)。** 插件一律 `crate-type = ["rlib"]`。 +理由(已在 nginx 1.30.4 源码层面核对,详见 sso 的 `plugin-architecture-analysis.md`): +动态模块 `ngx_module_t` 带编译期签名,必须与 nginx 同源;共享内存 zone 的 tag 不同会在 +`ngx_cycle.c` 直接 EMERG 启动失败;同名变量会被后加载者劫持 `get_handler`(不报错、 +只在某些部署下身份错);Rust 无稳定 ABI,跨 `.so` 传 `String` 即双重 free。 + +### 2.1 规模预估 + +| 目标 crate | 行数(约) | 说明 | +| --- | --- | --- | +| `ipass-core` | ~2350 | 含身份端点 | +| `plugin-domain` | ~650 | | +| `plugin-llm` | ~2100 | 最大的一块 | +| `plugin-apix` | ~700 | | +| `gateway` | ~450 | 只留壳 | +| **合计** | **~6250 + 契约胶水 ≈ 7000** | 与现状 7035 吻合,无逻辑膨胀 | + +--- + +## 3. 逐文件归属(改造清单) + +| 现文件 | 行 | 目标 | 备注 | +| --- | --- | --- | --- | +| `config.rs` | 232 | **拆** | 共性(`SESSION_TTL` `HASH_ROUNDS` `COOKIE_NAME` `LOGIN_MAX_FAIL` `INIT_ADMIN_*` `USERNAME_*` `PASSWORD_MIN_LEN` `DISPLAY_NAME_MAX_LEN` `DEFAULT_DATA_DIR`)→ core;`TEMP_DOMAIN_TTL` `SUBDOMAIN_*` `RESERVED_SUBDOMAINS` → domain;`UPSTREAM_*` `LLM_*` `AUDIT_*` `TREND_*` → llm;`APIX_*` → apix | +| `models.rs` | 219 | **拆** | `User` → core;`Upstream`(73-115)→ llm;`ApiProxy`/`ApiProxyStore`(117-165)→ apix;`DomainEntry`(167-)→ domain | +| `state.rs` | 362 | core | 原样 | +| `store.rs` | 196 | core | 原样 | +| `session.rs` | 57 | core | 原样 | +| `util.rs` | 354 | core | 原样 | +| `http.rs` | 223 | core | 原样 | +| `users.rs` | 405 | core | **摘掉 `stats::forget` 依赖**(§4①),`&mut pub` 化为 `on_delete` 钩子 | +| `stats.rs` | 585 | **拆** | 记账原语 → `core/usage.rs`;`trend`/`overview`/`user_models`/`tokens_user` 等解读 → `plugin-llm/stats.rs`(§4③) | +| `domains.rs` | 485 | plugin-domain | 含 `sync_shm`/`reload_shm` | +| `llm.rs` | 442 | plugin-llm | `downstream_key` / `identity` / `check_quota` 移出 → `core/auth.rs`(§4②) | +| `upstreams.rs` | 397 | plugin-llm | 原样 | +| `llm_usage.rs` | 275 | plugin-llm | 改名 `usage_filter.rs`;`install()` 无参,可在插件 `postconfig` 内直接调 | +| `llm_audit.rs` | 200 | plugin-llm | 原样 | +| `apix.rs` | 563 | plugin-apix | 管理 API 部分拆到 `api.rs` | +| `api.rs` | 1018 | **拆四处** | 见下表 | +| `lib.rs` | 1022 | gateway + 各插件 | 壳留 gateway;6 个 handler 与 10 个变量注册下放 | + +### `api.rs` 的端点归属(1018 行拆四处) + +| 端点 | 归属 | 依据 | +| --- | --- | --- | +| `/api/admin/login` `/logout` `/session` | **core** `api.rs` | 会话是内核职责 | +| `/api/admin/users` `/users/{create,display,key,grant,password,delete,models,limits}` | **core** | 账号是内核职责 | +| `/api/admin/purge` | **core** | 清理的是会话/失败计数 | +| `/api/v1/me` | **core** | 账号态自我查询 | +| `/api/admin/domains` `/domains/{review,create,delete}`、`/api/v1/domains` `/domains/{apply,delete}` | plugin-domain | | +| `/api/admin/upstreams` `/upstreams/{save,delete,test}`、`/api/admin/usage` `/trend`、`/api/v1/upstreams` `/models` `/usage` | plugin-llm | | +| `/api/admin/apix` `/apix/{save,delete,test}`、`/api/v1/apix` | plugin-apix | | + +`Guard`(`Public`/`User`/`Admin`)与 `Actor` 是**四份 route 表共用**的类型 → 连同 +`user_or_401`、`admin_or_403` 之类守卫一起下沉到 `core/auth.rs`,各插件引用而非各写一份。 + +--- + +## 4. 三个必须先解决的边界问题 + +这三处是「直接按目录切文件」会撞墙的地方,也是本方案与 sso 参考实现**刻意不同**的地方。 + +### ① `users::delete` → `stats::forget`:内核反向依赖插件 + +`users.rs:372` 在删除账号时调用 `stats::forget(&stats_name)` 摘掉用量索引。 +若 `stats` 随 plugin-llm 走,就形成 **core → plugin-llm 的循环依赖**(cargo 会直接报错)。 + +**修法:内核开「账号删除钩子」注册表。** + +```rust +// crates/ipass-core/src/users.rs +static ON_DELETE: Mutex> = Mutex::new(Vec::new()); + +/// 插件注册「账号被删除时我需要清理什么」。在 zone 装载后、接请求前调用一次。 +pub fn on_delete(f: fn(&str)) { /* push */ } + +pub fn delete(username: &str, operator: &str) -> Result<(), String> { + // ... 原有逻辑:文件 + ukey:/sess:/fail: 写穿(core 自己的键,不需要钩子) + for f in hooks() { f(username); } // 插件各清各的键空间 + Ok(()) +} +``` + +plugin-llm 暴露 `pub fn install_hooks() { users::on_delete(stats::forget); }`, +由 `gateway` 的 `state_zone_init` 在插件 `zone_load` 之后统一调用。 + +> 这条钩子同时解决了「键按前缀分域」惯例下的一个通用问题:**删除账号要摘几个前缀, +> 取决于装了哪些插件**——只有注册表能让内核在不认识插件的前提下做对。 + +### ② `ApiProxyHandler` 复用 `llm::identity` / `llm::check_quota`:插件间依赖 + +`lib.rs:344/352/383`——API 代理热路径调用 LLM 的三个函数完成「取下行 Key → 查身份 → +查配额」。若 llm 与 apix 平级,就是 plugin-apix → plugin-llm 的依赖,破坏「插件平级」。 + +**判据**:`ukey:` 鉴权与 `rl:` 配额,是「**去掉 llm 还要(apix 要)、去掉 apix 还要(llm 要)、 +两个都去掉才不要**」——典型的**共用 ⇒ 放内核**。 + +**修法:新建 `crates/ipass-core/src/auth.rs`**,下沉三件套: + +```rust +pub fn downstream_key(r: *mut ngx_http_request_t) -> Option; // 原 llm::downstream_key +pub fn identity(key: &str) -> Option<(String, Vec, i64, i64)>; // 原 llm::identity,读 ukey: +pub fn check_quota(r: *mut ngx_http_request_t, user: &str, rpm: i64, daily: i64) + -> Option; // 原 llm::check_quota,读 rl: +``` + +同时把 `rl:` 前缀从 `config.rs` 的 LLM 段移到 core 段。 + +> sso 的参考实现把 `rl:` 划给 plugin-llm,是因为 sso **没有 apix 这条链路**。 +> iPass 有两条共用配额的下行链路,所以这里必须与 sso 不同——这是本方案对参考实现的 +> 第一处有意偏离。 + +### ③ `stats.rs` 585 行:记账原语 vs 业务解读 + +整块搬进 plugin-llm 会让 core 的 `users` 钩子无处落(见①),整块留 core 又会让内核长出 +LLM 语义(`token` / `模型` / `趋势` 这些词不该出现在内核里)。 + +**修法:按「回答什么问题」切开。** + +| 部分 | 目标 | 回答的问题 | +| --- | --- | --- | +| `record` / `add_tokens` / `forget` / 前缀扫描薄封装 | `core/usage.rs` | 「给这个键 +1」「这个键还有什么」——**纯键值操作,不含业务语义** | +| `trend()` / `overview()` / `user_models()` / `tokens_user()` / `all_users()`、日桶聚合 | `plugin-llm/stats.rs` | 「这些数字代表什么」——**业务解读** | + +`core/usage.rs` 只认「前缀 + 名字 + 计数」,不认识 `ust:` 与 `ums:` 的区别;日桶 +(`ud:`/`udu:`/`uds:`)的 TTL 与保留策略由 plugin-llm 传入。 + +--- + +## 5. 契约层(内核与插件之间唯一的接口) + +### 5.1 `Plugin` trait + +沿用 sso 的形态,**签名保持一致**(P5 若与 sso 合流,trait 不用再改): + +```rust +// crates/ipass-core/src/plugin.rs +pub trait Plugin: Sync { + fn name(&self) -> &'static str; + fn preconfig(&self, cf: *mut ngx_conf_t) -> bool { true } // 注册 nginx 变量 + fn postconfig(&self, cf: *mut ngx_conf_t) -> bool { true } // 注册 phase handler + fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { None } + fn zone_load(&self) -> usize { 0 } // fork 前预装载 + fn log_handler(&self, _r: *mut ngx_http_request_t) -> bool { true } // 保留(与 sso 对齐) +} +``` + +**刻意没有 `commands()`**:nginx 的 `ngx_module_t.commands` 是 null 结尾的**连续**数组, +不同 crate 的 `static` 数组无法拼接。配置指令由 gateway 集中声明,插件通过 `loc::Switch` +查询自己所在 location 是否开启——**指令解析归壳、行为归插件**。 + +`dispatch_api` 的语义是「不认领就返回 `None`,让下一个插件试」,**绝不自行 404** +(否则后注册的插件永远收不到请求)。404 由 gateway 在全部插件都返回 `None` 后统一发出。 + +### 5.2 `loc::Switch`:取并集 + +```rust +pub enum Switch { + Api, // 该 location 暴露管理 API + 身份端点 + Iap, // 预留(iPass 无用,sso 用;合流时不用改 core) + Domain, // 预留(同上) + Proxy, // 该 location 走「子域名 → 后端」转发 ← iPass 用 + Llm, // 该 location 走 LLM 代理 ← iPass 用 + Apix, // 该 location 走 API 代理 ← iPass 用 +} +``` + +`Switch` 是内核与插件之间**唯一的契约点**,宁可多留两个变体,也不要在 P5 合流时做破坏性改动。 +gateway 注入查询实现(`set_switch_fn`),**未实现的变体一律保守返回 `false`** +(sso 已踩过这个坑:`Switch::Llm => false`,绝不能误开)。 + +### 5.3 gateway 的 5 处装配(少任一处 = 「代码全对但功能不生效」) + +```rust +// gateway/src/lib.rs +use plugin_apix::ApixPlugin; // ① +use plugin_domain::DomainPlugin; +use plugin_llm::LlmPlugin; + +static PLUGINS: &[&dyn Plugin] = &[ + &ipass_core::api::CorePlugin, // 身份端点必须先认领 + &DomainPlugin, &LlmPlugin, &ApixPlugin, +]; // ② 顺序 = 装配顺序 + +struct ModuleConfig { api: bool, proxy: bool, llm: bool, apix: bool } // ③ +// Merge::merge 里补 4 个 if;指令数组长度不变(7 + empty = 8)+ set_flag_* 4 个 + +fn loc_switch(r: &mut Request, s: Switch) -> bool { // ④ + match s { + Switch::Api => c.api, Switch::Proxy => c.proxy, + Switch::Llm => c.llm, Switch::Apix => c.apix, + Switch::Iap | Switch::Domain => false, // 未实现:保守 false + } +} +// ⑤ preconfiguration 里只留 loc::set_switch_fn(loc_switch),其余全部下放插件 +``` + +### 5.4 指令名与 conf:**一个字都不用改** + +iPass 现有 7 条指令 `ipass_state` / `ipass_data_dir` / `ipass_audit_dir` / `ipass_proxy` / +`ipass_api` / `ipass_llm` / `ipass_apix`,**与插件划分恰好 1:1**,全部保持原名, +数组长度仍是 8。模块名仍是 `ngx_http_ipass_module`,`.so` 仍是 `libipass_gateway.so`。 + +> 这是 iPass 相对 sso 参考实现的**结构性优势**:sso 的指令都叫 `sso_*`(`sso_api` / +> `sso_iap` / `sso_domain`),搬到 iPass 要全部改名并同步 conf;iPass 侧零改动。 +> 连带收益:`conf/nginx.conf`、`tests/gateway/nginx.conf.in`、`tests/llm/nginx.conf.in` +> **全部不动**,回归基线直接可比。 + +### 5.5 变量注册下放 + +| 变量 | 现位置 | 目标 | +| --- | --- | --- | +| `$proxy_backend_addr` | `lib.rs:660-676` | plugin-domain `preconfig` | +| `$llm_target` `$llm_host` `$llm_auth` | `lib.rs:680-691` | plugin-llm `preconfig` | +| `$apix_target` `$apix_host` `$apix_key` `$apix_body` `$apix_probe_target` `$apix_probe_body` | `lib.rs:694-711` | plugin-apix `preconfig` | + +> 下放后天然更安全:三组变量分属三个 crate,不会像 sso 那样两个 `.so` 注册同名 +> `$auth_*` 再互相劫持 get_handler。 + +**`$upstream_status` 的索引预取**(`lib.rs:739-747`,依赖 `upstream` 内建模块已注册该变量) +→ plugin-llm 的 `postconfig`。插件 `postconfig` 在 gateway 自己的 `postconfig` 之前执行, +而内建模块的 `preconfiguration` 早已跑完,时序安全。 + +### 5.6 phase handler 下放 + +| handler | 阶段 | 目标 | +| --- | --- | --- | +| `ResolveHandler` | access | plugin-domain `postconfig` | +| `LlmHandler` | access | plugin-llm `postconfig` | +| `ApiProxyHandler` | access | plugin-apix `postconfig` | +| `LlmHealthHandler` | log | plugin-llm `postconfig` | +| `AuditHandler` | log | plugin-llm `postconfig`(同处调 `usage_filter::install()`) | +| `ApiHandler` | content | **留 gateway**——统一收口后按 `PLUGINS` 顺序分发 | + +### 5.7 shm 装载 + +```rust +extern "C" fn state_zone_init(zone, _data) -> ngx_int_t { + state::init_zone(zone)?; + users::reload_shm(); // ① 内核自有的 ukey: 索引(不是插件能力) + for p in PLUGINS { p.zone_load(); } // ② 各插件装自己的表 + plugin_llm::install_hooks(); // ③ 注册 on_delete 钩子(§4①) + NGX_OK +} +``` + +> `users::reload_shm()`(`users.rs:93`)装的是 `ukey:` Key → 身份索引,**属内核**, +> 不能靠某个插件的 `zone_load` 顺带完成——否则「核心索引是否装载」会依赖插件是否装配。 + +--- + +## 6. 与 sso 参考实现的差异(有意偏离) + +| # | sso 做法 | iPass 做法 | 原因 | +| --- | --- | --- | --- | +| 1 | `rl:` 配额归 plugin-llm | 归 **core** `auth.rs` | iPass 有 LLM + apix **两条**共用配额的链路(§4②) | +| 2 | `stats` 整体在插件 | **拆**:原语进 core `usage.rs`,解读进 plugin-llm | 内核删账号要摘用量索引(§4①③) | +| 3 | 身份端点全在 plugin-sso | 身份端点在 **core**(`CorePlugin`) | 已拍板;iPass 无 SSO 插件(§0) | +| 4 | 指令 `sso_*`,迁移需改名 | 保持 `ipass_*` | 指令与插件 1:1,conf 零改动(§5.4) | +| 5 | `Switch { Api, Iap, Domain, Llm }` | 取**并集** `{Api, Iap, Domain, Proxy, Llm, Apix}` | 契约点一次到位,避免 P5 破坏性改动 | +| 6 | 无 | 新增 `users::on_delete` 钩子 | 内核不认识插件的键空间(§4①) | +| 7 | 无 `plugin-llm`(明确不迁入) | **要** plugin-llm | iPass 的本体就是域名 + LLM + apix | +| 8 | `libsso_gateway.dylib` | 仍是 `libipass_gateway.so` | Dockerfile 产物路径不变 | + +--- + +## 7. 落地路径(每阶段独立可回滚) + +### P0 · 建 workspace,内核落地(**行为零变化**) + +1. `rust/Cargo.toml` → 变 workspace 根:`members = ["crates/ipass-core", "gateway"]`, + `exclude = ["vendor/ngx-rust"]`,依赖全部上移到 `[workspace.dependencies]`。 +2. 建 `crates/ipass-core`,迁入 `config`(共性裁剪)/ `models`(仅 `User`)/ `state` / + `store` / `session` / `util` / `http` / `users`。 +3. 建 `gateway`,`lib.rs` 整体搬过去——**此时所有业务模块仍留在 gateway**, + 先证明「产物名、路径、行为全部不变」。 + +**验收**:`target/release/libipass_gateway.so` 同名同路径; +`bash deploy/... ` 容器可起;`bash tests/run.sh all` **262 项全绿**。 + +> ⚠️ 最容易漏的一处:`[profile.release]`(`opt-level`/`lto`/`codegen-units`/`panic="abort"`/ +> `strip`)**必须在 workspace 根**——member 里写会被 cargo 忽略。`panic="abort"` 丢了 +> 就意味着 panic 可能跨 FFI 边界展开。 + +### P1 · 契约层 + +新增 `core/plugin.rs`(`Plugin` trait)与 `core/loc.rs`(`Switch` + `set_switch_fn`/`enabled`); +gateway 实现 `loc_switch`、把 `PLUGINS` 数组与分发循环接上(此时 `PLUGINS` 只有 `CorePlugin`)。 + +**验收**:编译通过、262 全绿(契约层不改变行为)。 + +### P2 · 拆 plugin-domain(最小、最独立,用来验证流程) + +迁 `domains.rs` + `DomainEntry` + `sub:` 前缀 + 域名类端点 + `ResolveHandler` + +`$proxy_backend_addr` 注册 + `TEMP_DOMAIN_TTL`/`SUBDOMAIN_*`/`RESERVED_SUBDOMAINS`。 + +**验收**:`tests/gateway` 102 项全绿(含域名审批 / 写穿生效 / 通配符转发)。 + +### P3 · 拆 plugin-llm(最大,前置换算在下沉 core) + +前置三件事:**`auth.rs` 下沉**(§4②)、**`usage.rs` 拆分**(§4③)、**`on_delete` 钩子**(§4①)。 +然后迁 `llm` / `upstreams` / `llm_usage` / `llm_audit` / `stats`(解读部分)+ LLM 类端点 + +三个 handler + `up:`…`uh:` 全部前缀 + `llm_*` 三变量。 + +**验收**:`tests/llm` 160 项全绿(含流式、模型发现、配额、用量趋势、审计落盘)。 + +### P4 · 拆 plugin-apix + +迁 `apix.rs` + `ax:` 前缀 + apix 类端点 + `ApiProxyHandler` + `apix_*` 六变量。 + +**验收**:apix 用例全绿(现混在 `tests/llm` 内);手工确认两点—— +`/apix/` 用 **lm host**、`/_apix_probe/` 在 **mdm server**(`mdm` 上打 `/apix/` 应是 nginx 404)。 + +### P5 · 收尾 + 文档 + 技能;**(可选)**与 ssw/sso 的关系 + +- 文档:`CLAUDE.md`(crate 清单 + 目录地图 + 回归套数)、`readme.md` §6 目录结构、 + 本文件转正为 `docs/plugin/PLUGIN_ARCHITECTURE.md`(P2 的论证部分直接引用 sso 的 + `plugin-architecture-analysis.md`,不重复写)。 +- 技能:把 sso 的 `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` 改造为 iPass 版 + (改 crate 名、指令名、e2e 路径;保留「5 处装配缺一不可」「症状 → 根因」两张表)。 +- **待定**:是否把 `sww/sso` 的 `plugin-sso` 并入 iPass(届时 `CorePlugin` 的身份端点 + 移交 plugin-sso,或 plugin-sso 直接实现同一批路由)。P0–P4 的设计已为此留好口子 + (`Switch` 并集、`Plugin` trait 签名与 sso 一致)。 + +--- + +## 8. 周边影响面 + +| 文件 | 是否要改 | 说明 | +| --- | --- | --- | +| `Dockerfile` | **不改** | `COPY rust/ ./` + 在 workspace 根 `cargo build --release`,产物仍是 `target/release/libipass_gateway.so` | +| `conf/nginx.conf` | **不改** | 指令名与 `.so` 名不变(§5.4) | +| `compose.yml` | **不改** | | +| `deploy/release.sh` `deploy/agent.sh` `deploy/ipass-agent.py` | **不改** | 镜像 tag / 产物路径 / 端口不变 | +| `tests/run.sh` + `tests/*/nginx.conf.in` | **不改** | 套数与端口不变 | +| `tests/*/fixtures/*.json` | **不改** | 持久化格式零变化(§9⑤) | +| `.gitignore` `.dockerignore` | **不改** | `vendor/` 仍在 `rust/vendor/` | +| `www/` 管理台 | **不改** | API 路径全部保持原样 | +| 迭代命令 | **变** | 单 crate 快速迭代:`cargo build -p plugin-llm`(几十秒 vs 全量 ~1.5 分钟) | + +--- + +## 9. 风险与纪律 + +1. **P3 是主战场**。边界切错会让内核长出 LLM 语义(难事后拆),或形成 core↔plugin 循环 + (cargo 直接报错,不会静默——这点比运行时问题好排查)。开工前先按 §4 三条把 + `auth.rs` / `usage.rs` / `on_delete` 建好,再动搬移。 +2. **`[profile.release]` 只能在 workspace 根**。`panic="abort"`(防 panic 跨 FFI)、 + `lto`、`codegen-units=1`、`strip` 一项丢了都是线上隐患。 +3. **`[features] export-modules` + `ngx::ngx_modules!` 宏属于 gateway**。`[lib] crate-type` + 的 `"cdylib"` 也只给 gateway;插件一律 `["rlib"]`(不要为了「顺便能测」给插件加 cdylib)。 +4. **`loc::Switch` 未实现的变体必须保守 `false`**。返回 `true` 会让未装配的能力意外开门。 +5. **`data/*.json` 零格式变化**:已核对 `User`/`Upstream`/`ApiProxy`/`ApiProxyStore`/ + `DomainEntry` 的字段全部带 `#[serde(default)]`(含 `default_llm_rpm` / `default_llm_daily` / + `default_true` 三个函数缺省),存量文件可直接被新 `.so` 接管。**但要在 P0 单独做一次 + 「新旧解析对拍」**(同一份 `data/` 跑改造前/后的构建,比对内存装载条数与账号数), + 这是唯一可能出现「账号全部消失」类事故的地方。 +6. **热路径永不回源**:插件的每请求决策只能读共享内存;任何写操作必须**先落文件、 + 再写穿 shm**,且写 shm 失败必须 `log_err`。迁移时逐插件核对 `sync_shm` 调用点, + 漏一处 = 「刚配好却 404」。 +7. **`ngx` 依赖必须走 `vendor/ngx-rust` 的 path 依赖**:crates.io 的 `ngx = "0.5"` 没有请求阶段 + API(`add_phase_handler`/`HttpPhase` 未发版);git 依赖会去克隆 submodule 而卡死。 + workspace 化后统一放 `[workspace.dependencies]`,各 crate 用 `.workspace = true`。 +8. **别在 P2 顺手把 plugin-llm 建一半**:`members` 里列了但目录缺 `Cargo.toml`/`lib.rs` + 会让整个 workspace 编不过。要么做完,要么从 `members` 摘掉并把目录移到 `/tmp` 备份。 + +--- + +## 10. 已拍板 / 待拍板 + +**已拍板(2026-09-13)** + +- [x] 只做 iPass 自身插件化;`ssw/sso` 的仓库归属留到 P5 +- [x] 身份端点(登录 / 会话 / 账号管理 / `me`)由 `ipass-core` 直接收口,经 `CorePlugin` 装配 +- [x] 单 `.so` + crate 级插件(不做运行时多 `.so`) +- [x] `ukey:` 鉴权与 `rl:` 配额下沉 core(两条下行链路共用) +- [x] `stats` 按「记账原语 / 业务解读」切开,原语进 core +- [x] 指令名与 `.so` 名保持不变(conf 与测试零改动) + +**待拍板** + +- [ ] P5:是否把 `plugin-sso` 并入 iPass(并入后身份端点移交,`CorePlugin` 退化为纯库) +- [ ] 是否同步把 `ssw/sso` 的 core 与本项目的 `ipass-core` 收敛为同一份( + 需先确认两边 `Switch` 并集与 `Plugin` trait 已对齐——本方案已按对齐设计) + +--- + +## 附:查证位置 + +| 论断 | 位置 | +| --- | --- | +| 17 模块 / 7035 行 | `rust/src/*.rs`(`wc -l`) | +| 模块依赖图 | 各文件 `use crate::` 汇总(§1 表) | +| 7 条指令 + 长度 8 | `rust/src/lib.rs:752-810` | +| `ModuleConfig` 四开关 + `Merge` | `rust/src/lib.rs:563-594` | +| 6 个 phase handler 注册点 | `rust/src/lib.rs:716-749` | +| 10 个变量注册 | `rust/src/lib.rs:655-711` | +| `$upstream_status` 索引预取 | `rust/src/lib.rs:739-747` | +| `state_zone_init` 三表装载 | `rust/src/lib.rs:956-975` | +| `ApiProxyHandler` 调 llm 三件套 | `rust/src/lib.rs:344` `:352` `:383` | +| `users::delete` → `stats::forget` | `rust/src/users.rs:372` | +| `users::reload_shm` 装 `ukey:` | `rust/src/users.rs:93-113` | +| `llm_usage::install()` 无参 | `rust/src/llm_usage.rs:59-64` | +| 键前缀全景 | `rust/src/config.rs:78-166` | +| 持久化结构全部 `serde(default)` | `rust/src/models.rs`(`User` 23-48、`Upstream` 82-93、`ApiProxy` 135-161、`DomainEntry` 179-187) | +| 为什么不拆多 `.so` | `ssw/sso` → `docs/plugin-architecture-analysis.md` | +| 加插件的 5 处装配 / 排错表 | `ssw/sso` → `.workbuddy/skills/ipass-core-add-plugin/SKILL.md` | diff --git a/rust/Cargo.lock b/rust/Cargo.lock index 1a3d57f..3f18bbd 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -173,7 +173,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b" [[package]] -name = "ipass-gateway" +name = "ipass-core" version = "2.0.0" dependencies = [ "getrandom", @@ -185,6 +185,21 @@ dependencies = [ "sha2", ] +[[package]] +name = "ipass-gateway" +version = "2.0.0" +dependencies = [ + "getrandom", + "ipass-core", + "libc", + "nginx-sys", + "ngx", + "plugin-domain", + "serde", + "serde_json", + "sha2", +] + [[package]] name = "itertools" version = "0.13.0" @@ -274,6 +289,16 @@ dependencies = [ "minimal-lexical", ] +[[package]] +name = "plugin-domain" +version = "2.0.0" +dependencies = [ + "ipass-core", + "ngx", + "serde", + "serde_json", +] + [[package]] name = "prettyplease" version = "0.2.37" diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 9153737..9a22611 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -1,25 +1,19 @@ -# 独立 workspace:vendored 的 ngx-rust 本身是 workspace 根,需显式排除以免歧义 +# iPass workspace:内核(crates/ipass-core)+ 唯一 cdylib(gateway)。 +# 插件(plugin-domain / plugin-llm / plugin-apix)按 docs/plugin/PLUGINIZATION_PLAN.md 逐步迁入。 +# +# ⚠️ [profile.release] 只能放 workspace 根:member 里写会被 cargo 静默忽略, +# panic="abort" 丢了就意味着 panic 可能跨 FFI 边界展开进 nginx。 [workspace] +resolver = "2" +members = ["crates/ipass-core", "gateway"] +# 独立 workspace:vendored 的 ngx-rust 本身是 workspace 根,需显式排除以免歧义 exclude = ["vendor/ngx-rust"] -[package] -name = "ipass-gateway" -version = "2.0.0" +[workspace.package] edition = "2021" publish = false -description = "尚数网 统一网关(iPass 山海关)—— nginx + Rust 扩展模块实现" -[lib] -name = "ipass_gateway" -# cdylib 给 nginx 加载;rlib 便于单元测试 -crate-type = ["cdylib", "rlib"] - -[features] -default = ["export-modules"] -# 脱离 nginx 构建系统、单独产出动态模块时必须开启(生成 ngx_modules 表) -export-modules = [] - -[dependencies] +[workspace.dependencies] # ⚠️ 依赖必须用 vendored 源码,不能走 crates.io,也不能走 git: # # 1) `ngx = "0.5"`(crates.io 0.5.1)只发布了配置阶段接口(HttpModule), @@ -43,6 +37,10 @@ sha2 = "0.10" # 替代 resty.sha256;算法与旧版逐位一致( getrandom = "0.2" # 替代 resty.random;不可退化成可预测伪随机(API Key 由它生成) libc = "0.2" # 仅用于 localtime_r / time(旧版由 os.date / ngx.time 提供) +# 内核 crate(插件/gateway 一律引用它,方向只能是 plugin → core) +ipass-core = { path = "crates/ipass-core" } +plugin-domain = { path = "crates/plugin-domain" } + [profile.release] opt-level = 3 lto = true diff --git a/rust/crates/ipass-core/Cargo.toml b/rust/crates/ipass-core/Cargo.toml new file mode 100644 index 0000000..4064ede --- /dev/null +++ b/rust/crates/ipass-core/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "ipass-core" +version = "2.0.0" +edition.workspace = true +publish = false +description = "iPass 内核:共享内存 / 账号 / 会话 / 存储 / 通用原语(不含任何插件业务语义)" + +[lib] +# 只有 gateway 是 cdylib;内核与插件一律 rlib(动态模块的 ngx_module_t 签名 +# 必须与 nginx 同源,且跨 .so 传 Rust 类型会双重 free,见 sso 的架构分析文档) +crate-type = ["rlib"] + +[dependencies] +ngx.workspace = true +nginx-sys.workspace = true +serde.workspace = true +serde_json.workspace = true +sha2.workspace = true +getrandom.workspace = true +libc.workspace = true diff --git a/rust/crates/ipass-core/src/api.rs b/rust/crates/ipass-core/src/api.rs new file mode 100644 index 0000000..88b4972 --- /dev/null +++ b/rust/crates/ipass-core/src/api.rs @@ -0,0 +1,465 @@ +//! 身份类端点(登录 / 会话 / 账号管理)+ API 分发的公共契约。 +//! +//! 会话与账号是内核职责(所有插件端点的公共前置),所以这批端点由 +//! `CorePlugin` 直接认领,gateway 把它排在 `PLUGINS` 最前。 +//! +//! ## `CoreExt`:身份端点的插件扩展点 +//! +//! 身份端点偶尔需要**插件侧数据**(账号列表要带域名数与用量、删账号要连带 +//! 回收域名、白名单要校验上游存在)。内核不认识插件,这些数据一律通过 +//! [`CoreExt`] 反转:gateway 作为**装配根**实现并注册([`set_ext`]), +//! 没注册时端点仍可工作(缺装饰、零回收),只是功能变素。 +//! +//! 路由与鉴权原语([`Guard`] / [`Actor`] / [`run_guarded`] / [`user_or_401`]) +//! 同时供各插件的路由表复用——四份 route 表共用一套鉴权语义。 + +use std::sync::Mutex; + +use ngx::core::Status; +use ngx::ffi::ngx_http_request_t; +use ngx::http::HTTPStatus; +use serde_json::{Value, json}; + +use crate::config; +use crate::http; +use crate::models::User; +use crate::plugin::Plugin; +use crate::session; +use crate::state; +use crate::users; +use crate::util; + +// =========================================================================== +// 鉴权契约(供内核与各插件的路由表共用) +// =========================================================================== + +/// 鉴权后传给处理器的身份 +pub enum Actor { + /// 公开接口,无身份 + None, + /// 账号态(X-API-Key) + User(User), + /// 管理员态(登录会话) + Admin(User), +} + +impl Actor { + /// 操作者名称:审核记录 `reviewed_by`、审计日志都用它 + pub fn admin_name(&self) -> &str { + match self { + Actor::Admin(u) => &u.username, + Actor::User(u) => &u.username, + Actor::None => "", + } + } +} + +#[derive(Clone, Copy, PartialEq)] +pub enum Guard { + Public, + User, + Admin, +} + +pub type Handler = fn(*mut ngx_http_request_t, Actor) -> Status; + +/// 账号态接口的公共前置:取账号身份,取不到就回 401(响应已发出)。 +pub fn user_or_401(r: *mut ngx_http_request_t, actor: Actor) -> Result { + match actor { + Actor::User(u) => Ok(u), + _ => Err(http::fail( + r, + HTTPStatus::UNAUTHORIZED, + "API Key 无效或缺失,请在请求头携带 X-API-Key", + )), + } +} + +/// 账号态鉴权(X-API-Key → users.json 反查)。失败只记日志,由调用方回 401。 +pub fn authenticate_user(r: *mut ngx_http_request_t) -> Option { + let key = http::header(r, "x-api-key").unwrap_or_default(); + match users::find_by_key(&key) { + Some(u) => Some(u), + None => { + util::log_warn(&format!( + "[api] API Key 校验失败 client={}", + http::remote_addr(r) + )); + None + } + } +} + +/// 管理员态鉴权(会话 Cookie → 账号)。会话有效但非管理员回 403 而不是 401, +/// 便于前端区分;两种失败都已把响应写进 r,调用方直接终止即可。 +pub fn authenticate_admin(r: *mut ngx_http_request_t) -> Result { + let cookie = http::header(r, "cookie"); + match session::authenticate(cookie.as_deref()).and_then(|name| users::get(&name)) { + Some(u) if u.is_admin() => Ok(u), + Some(_) => Err(http::fail(r, HTTPStatus::FORBIDDEN, "需要管理员权限")), + None => Err(http::fail( + r, + HTTPStatus::UNAUTHORIZED, + "未登录或会话已过期,请重新登录", + )), + } +} + +/// 鉴权 + 执行:按 Guard 求出 Actor 后调用 handler。 +pub fn run_guarded(r: *mut ngx_http_request_t, guard: Guard, handler: Handler) -> Status { + let actor = match guard { + Guard::Public => Actor::None, + Guard::User => match authenticate_user(r) { + Some(u) => Actor::User(u), + None => { + return http::fail( + r, + HTTPStatus::UNAUTHORIZED, + "API Key 无效或缺失,请在请求头携带 X-API-Key", + ); + } + }, + Guard::Admin => match authenticate_admin(r) { + Ok(u) => Actor::Admin(u), + Err(status) => return status, + }, + }; + handler(r, actor) +} + +// =========================================================================== +// 插件扩展点 +// =========================================================================== + +/// 身份端点的插件扩展点。gateway 实现并注册;**方法都给缺省实现**, +/// 没注册扩展时端点仍可用(账号列表缺装饰、删账号不连带回收)。 +pub trait CoreExt: Sync { + /// 管理台账号列表:插件侧装饰(域名数 / 用量摘要),一次批量给全部账号 + fn decorate_admin_users(&self, _views: &mut [Value]) {} + /// `/api/v1/me`:插件侧装饰(我的域名 / 用量摘要 / 策略 TTL) + fn decorate_me(&self, _username: &str, _view: &mut Value) {} + /// 删除账号:连带回收该账号名下资源(域名),返回条数 + fn reclaim_on_delete(&self, _username: &str) -> usize { + 0 + } + /// 账号「可用上游」白名单校验:slot 必须真实存在(plugin-llm 提供) + fn validate_slots(&self, _slots: &[String]) -> Result<(), String> { + Ok(()) + } +} + +static EXT: Mutex> = Mutex::new(None); + +/// gateway 在配置解析前注册(装配根是唯一注册方) +pub fn set_ext(e: &'static dyn CoreExt) { + if let Ok(mut slot) = EXT.lock() { + *slot = Some(e); + } +} + +fn ext() -> Option<&'static dyn CoreExt> { + let guard = EXT.lock().ok()?; + guard.as_ref().copied() +} + +// =========================================================================== +// 路由 +// =========================================================================== + +/// 路由表。刻意用精确匹配而非正则——接口路径是固定的, +/// 正则只会引入「写错锚点导致前缀误匹配」的风险。 +fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> { + let entry: (Guard, Handler) = match (method, uri) { + ("POST", "/api/admin/login") => (Guard::Public, h_login), + ("POST", "/api/admin/logout") => (Guard::Admin, h_logout), + ("GET", "/api/admin/session") => (Guard::Admin, h_session), + ("GET", "/api/admin/users") => (Guard::Admin, h_admin_users), + ("POST", "/api/admin/users/create") => (Guard::Admin, h_admin_user_create), + ("POST", "/api/admin/users/key") => (Guard::Admin, h_admin_user_key), + ("POST", "/api/admin/users/grant") => (Guard::Admin, h_admin_user_grant), + ("POST", "/api/admin/users/password") => (Guard::Admin, h_admin_user_password), + ("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/v1/me") => (Guard::User, h_me), + _ => return None, + }; + Some(entry) +} + +/// 本表分发:认领则返回响应状态,不认领返回 `None`(交给下一个插件)。 +pub fn dispatch(r: *mut ngx_http_request_t) -> Option { + 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)) +} + +// =========================================================================== +// 管理员:登录 / 会话 +// =========================================================================== + +fn h_login(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let ip = http::remote_addr(r); + let now = util::now(); + + if state::get_login_fail(&ip, now) >= config::LOGIN_MAX_FAIL { + return http::fail(r, HTTPStatus::TOO_MANY_REQUESTS, "登录失败次数过多,请 5 分钟后再试"); + } + + let p = http::params(r); + let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default(); + let password = p.get("password").cloned().unwrap_or_default(); + + if username.is_empty() || password.is_empty() { + return http::fail(r, HTTPStatus::BAD_REQUEST, "请输入账号和密码"); + } + + let Some(user) = users::get(&username) else { + state::bump_login_fail(&ip, now); + util::log_warn(&format!("[api] 登录失败 user={username} client={ip}")); + return http::fail(r, HTTPStatus::UNAUTHORIZED, "账号或密码错误"); + }; + + if !util::verify_password(&password, &user.salt, &user.pwd_hash) { + state::bump_login_fail(&ip, now); + util::log_warn(&format!("[api] 登录失败 user={username} client={ip}")); + return http::fail(r, HTTPStatus::UNAUTHORIZED, "账号或密码错误"); + } + + if !user.is_admin() { + return http::fail(r, HTTPStatus::FORBIDDEN, "该账号不是管理员,无法登录管理台"); + } + + state::clear_login_fail(&ip); + let token = session::create(&username); + let cookie = session::set_cookie(&token); + util::log_notice(&format!("[api] 管理员登录 user={username} client={ip}")); + + http::ok_with(r, users::view(&user), "登录成功", &[("Set-Cookie", &cookie)]) +} + +fn h_logout(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let cookie = http::header(r, "cookie"); + session::destroy(cookie.as_deref()); + let cleared = session::clear_cookie(); + http::ok_with(r, json!({}), "已退出登录", &[("Set-Cookie", &cleared)]) +} + +fn h_session(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let Actor::Admin(user) = actor else { + return http::fail(r, HTTPStatus::UNAUTHORIZED, "未登录或会话已过期,请重新登录"); + }; + http::ok(r, users::view(&user), "ok") +} + +// =========================================================================== +// 管理员:账号管理 +// =========================================================================== + +fn h_admin_users(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let mut items: Vec = users::all().iter().map(|u| users::view(u)).collect(); + // 域名数 / 用量等插件数据由装配根装饰(见 CoreExt::decorate_admin_users) + if let Some(e) = ext() { + e.decorate_admin_users(&mut items); + } + http::ok(r, json!({ "items": items }), "ok") +} + +fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let p = http::params(r); + let grant_temp = util::to_bool(p.get("grant_temp")); + + 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] 创建账号 {} name={} role={} temp_grant={grant_temp}", + user.username, user.display_name, user.role + )); + http::ok(r, users::view(&user), "账号创建成功") + } + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +/// 设置展示名(中文姓名等)。传空串 = 清空,前端回落到账号名。 +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(); + + match users::regenerate_key(&username) { + Ok(key) => http::ok(r, json!({ "username": username, "api_key": key }), "已重置 API Key"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_user_grant(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(); + + if util::to_bool(p.get("revoke")) { + if let Err(e) = users::revoke_temp(&username) { + return http::fail(r, HTTPStatus::BAD_REQUEST, &e); + } + let view = users::get(&username).map(|u| users::view(&u)).unwrap_or(Value::Null); + return http::ok(r, view, "已取消临时授权权限"); + } + + match users::grant_temp(&username, p.get("hours")) { + Ok(_) => { + let view = users::get(&username).map(|u| users::view(&u)).unwrap_or(Value::Null); + http::ok(r, view, "已授予临时授权权限") + } + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_user_password(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(); + let password = p.get("password").map(String::as_str).unwrap_or(""); + + match users::set_password(&username, password) { + Ok(()) => http::ok(r, json!({}), "密码已重置"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_user_delete(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(); + + if let Err(e) = users::delete(&username, actor.admin_name()) { + return http::fail(r, HTTPStatus::BAD_REQUEST, &e); + } + + // 连带回收该账号名下的资源(域名等),避免出现无主映射—— + // 装了哪些插件就回收哪些(CoreExt::reclaim_on_delete) + let removed = ext().map(|e| e.reclaim_on_delete(&username)).unwrap_or(0); + util::log_notice(&format!("[api] 删除账号 {username},连带域名 {removed} 条")); + http::ok(r, json!({ "removed_domains": removed }), "账号已删除") +} + +/// 设置某账号可用的 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(); + + let slots: Vec = p + .get("models") + .map(|s| { + s.split(',') + .map(|x| x.trim().to_owned()) + .filter(|x| !x.is_empty()) + .collect() + }) + .unwrap_or_default(); + + // 上游必须先存在:否则白名单里会存进永远匹配不上的死名字, + // 表现为「账号被授权了却一直 403」,排查起来很绕。 + // 上游表属 plugin-llm,经 CoreExt 校验。 + if let Err(e) = ext().map(|e| e.validate_slots(&slots)).unwrap_or(Ok(())) { + return http::fail(r, HTTPStatus::BAD_REQUEST, &e); + } + + match users::set_allowed_models(&username, slots) { + Ok(u) => http::ok(r, users::view(&u), "已更新可用上游"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +/// 设置账号的 LLM 限流参数。字段缺省 = 保持现值,`0` = 不限。 +fn h_admin_user_limits(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(); + + let parse_limit = |key: &str| -> Result, String> { + match p.get(key) { + None => Ok(None), + Some(v) if util::trim(v).is_empty() => Ok(None), + Some(v) => util::trim(v) + .parse::() + .map(Some) + .map_err(|_| format!("{key} 必须是非负整数(0 表示不限)")), + } + }; + + let rpm = match parse_limit("rpm") { + Ok(v) => v, + Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), + }; + let daily = match parse_limit("daily") { + Ok(v) => v, + Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), + }; + if rpm.is_none() && daily.is_none() { + return http::fail(r, HTTPStatus::BAD_REQUEST, "至少提供 rpm 或 daily 之一"); + } + + util::log_notice(&format!( + "[api] 设置账号 {username} LLM 限流 rpm={rpm:?} daily={daily:?}" + )); + match users::set_llm_limits(&username, rpm, daily) { + Ok(u) => http::ok(r, users::view(&u), "已更新限流参数"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +// =========================================================================== +// 账号态 +// =========================================================================== + +fn h_me(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 mut v = users::view(&user); + // 我的域名 / 用量摘要 / 策略 TTL 都是插件侧数据,由装配根装饰 + if let Some(e) = ext() { + e.decorate_me(&user.username, &mut v); + } + http::ok(r, v, "ok") +} + +// =========================================================================== +// 装配 +// =========================================================================== + +/// 内核插件:认领身份类端点。必须排在 gateway 的 `PLUGINS` **最前**。 +pub struct CorePlugin; + +impl Plugin for CorePlugin { + fn name(&self) -> &'static str { + "core" + } + + fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { + dispatch(r) + } +} diff --git a/rust/src/config.rs b/rust/crates/ipass-core/src/config.rs similarity index 87% rename from rust/src/config.rs rename to rust/crates/ipass-core/src/config.rs index b7c4946..f6067f8 100644 --- a/rust/src/config.rs +++ b/rust/crates/ipass-core/src/config.rs @@ -5,8 +5,6 @@ /// 管理员授予的「临时授权权限」有效时长(秒) pub const TEMP_GRANT_TTL: i64 = 6 * 3600; -/// 临时域名审批通过后的有效期(秒)。到期仅停止转发,记录保留供查阅。 -pub const TEMP_DOMAIN_TTL: i64 = 6 * 3600; /// 管理员登录会话时长(秒) pub const SESSION_TTL: i64 = 8 * 3600; /// 口令哈希迭代轮数。**必须与旧版一致**,否则存量用户口令全部失效。 @@ -29,11 +27,6 @@ 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; - -/// 系统保留名:不允许用户申请,避免抢占管理入口 -pub const RESERVED_SUBDOMAINS: [&str; 4] = ["proxy-api", "admin", "www", "api"]; /// 管理会话 Cookie 名(HttpOnly + SameSite=Strict) pub const COOKIE_NAME: &str = "ipass_admin_session"; @@ -43,9 +36,6 @@ pub const LOGIN_MAX_FAIL: i64 = 10; /// 登录失败计数窗口(秒) pub const LOGIN_FAIL_TTL: i64 = 300; -/// 驳回记录保留时长,超期由 purge 清理(秒) -pub const REJECTED_PURGE_TTL: i64 = 7 * 86400; - /// LLM 每 Key 限流默认值:每分钟请求数。账号未显式配置时取此值;0 = 不限 pub const LLM_RPM_DEFAULT: i64 = 60; /// LLM 每 Key 限流默认值:每日请求数。账号未显式配置时取此值;0 = 不限。 @@ -74,8 +64,6 @@ pub const AUDIT_PURGE_MIN_INTERVAL: i64 = 60; // 共享内存键/值编码 // =========================================================================== -/// 键前缀:子域名 → 后端映射 -pub const KEY_SUB_PREFIX: &[u8] = b"sub:"; /// 键前缀:管理会话 token → 用户名 pub const KEY_SESS_PREFIX: &[u8] = b"sess:"; /// 键前缀:登录失败计数(按 IP) @@ -200,25 +188,6 @@ pub const APIX_STATS_PREFIX: &str = "api/"; /// 改域名只改这里(`conf/nginx.conf` 的 LLM server_name 要同步改)。 pub const LLM_PUBLIC_HOST: &str = "lm.mayishangshu.cn"; -/// 企业域名(业务域名)的 zone:**子域名 + `.` + 此后缀 = 完整对外域名**。 -/// -/// ⚠️ 与 `conf/nginx.conf` 的「企业域名 server」严格耦合: -/// `server_name ~^(?.+dm)\.mayishangshu\.cn$;` -/// 改这里必须同步改那条正则(反之亦然)。 -pub const ENTERPRISE_ZONE: &str = "mayishangshu.cn"; - -/// 自动生成子域名的形状:`<前缀><后缀>` —— 例如 `i12345678dm`。 -/// -/// 后缀**必须是 `dm`**:企业域名 server 的正则要求捕获组以 `dm` 结尾 -/// (`^(.+dm)\.mayishangshu\.cn$`),否则域名建出来也转发不到。 -/// 这是「规则」的实质约束,不是命名偏好。 -pub const SUBDOMAIN_PREFIX: &str = "i"; -pub const SUBDOMAIN_SUFFIX: &str = "dm"; -/// 随机数字位数。10^8 的空间,撞车概率极低 -pub const SUBDOMAIN_RAND_DIGITS: usize = 8; -/// 自动生成子域名时的最大重试次数(真撞上已占用的就换一个再试) -pub const SUBDOMAIN_GEN_ATTEMPTS: usize = 5; - /// 单个模型名长度上限 pub const MODEL_NAME_MAX_LEN: usize = 128; /// 单个上游可登记的模型数量上限(挡住把整个模型库灌进 shm/JSON 的手滑) diff --git a/rust/src/http.rs b/rust/crates/ipass-core/src/http.rs similarity index 100% rename from rust/src/http.rs rename to rust/crates/ipass-core/src/http.rs diff --git a/rust/crates/ipass-core/src/lib.rs b/rust/crates/ipass-core/src/lib.rs new file mode 100644 index 0000000..18a61fc --- /dev/null +++ b/rust/crates/ipass-core/src/lib.rs @@ -0,0 +1,33 @@ +//! ipass-core —— iPass 内核。 +//! +//! 承担「去掉任何插件,网关还能跑」的部分: +//! +//! * `state` —— 唯一共享内存 zone(`RwLock`)+ 文件写锁 +//! * `store` —— JSON 原子写 + 跨 worker 互斥(状态就是几个 JSON 文件,无数据库) +//! * `users` —— 账号唯一写入口(`ukey:` Key 索引、播种管理员、删除钩子) +//! * `session` —— 管理会话 +//! * `auth`(P3 起)—— 下行 `sk_` 鉴权 + `rl:` 配额(LLM 与 API 代理两条链路共用) +//! * `config` / `models` / `util` / `http` —— 常量、账号模型与通用原语 +//! +//! 插件(plugin-domain / plugin-llm / plugin-apix)只允许**单向依赖**本 crate; +//! 内核不认识任何插件。插件通过 `Plugin` trait(P1 引入)与 gateway 装配。 +//! +//! ## 关键实现约束(均为实测/查证确认,详见 CLAUDE.md) +//! +//! * 共享内存只有 `RwLock, _>` 一种安全形态; +//! `SlabPool` 只能在 zone 初始化回调里取出,锁本身也必须用 +//! `ngx::allocator::allocate` 放进共享内存,否则各 worker 拿到的是各自的副本。 +//! * 热路径**永不回源**:每请求决策只读共享内存;任何写操作必须 +//! 先落文件、再写穿 shm,写 shm 失败必须 `log_err`。 + +pub mod api; +pub mod config; +pub mod http; +pub mod loc; +pub mod models; +pub mod plugin; +pub mod session; +pub mod state; +pub mod store; +pub mod users; +pub mod util; diff --git a/rust/crates/ipass-core/src/loc.rs b/rust/crates/ipass-core/src/loc.rs new file mode 100644 index 0000000..17ef011 --- /dev/null +++ b/rust/crates/ipass-core/src/loc.rs @@ -0,0 +1,56 @@ +//! Location 开关契约 —— 内核与插件之间**唯一的契约点**。 +//! +//! 配置指令(`ipass_api` / `ipass_proxy` / `ipass_llm` / `ipass_apix`)由 gateway +//! 集中解析进 `ModuleConfig`;插件不认识 gateway,只通过 [`Switch`] 问一句 +//! 「我所在的 location 开了吗」。gateway 在 preconfiguration 注入查询实现 +//! ([`set_switch_fn`]),**未注入或未实现的变体一律保守返回 `false`** +//! ——返回 `true` 会让未装配的能力意外开门(sso 踩过的坑)。 + +use core::sync::atomic::{AtomicUsize, Ordering}; + +use ngx::ffi::ngx_http_request_t; +use ngx::http::Request; + +/// location 能力的枚举。取 iPass 与 sso 的**并集**: +/// iPass 用 `Api / Proxy / Llm / Apix`;`Iap / Domain` 为 sso 预留, +/// 合流时不用改本枚举。 +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Switch { + /// 该 location 暴露管理 API + 身份端点 + Api, + /// 预留(sso 用;iPass 未实现,恒 false) + Iap, + /// 预留(sso 用;iPass 未实现,恒 false) + Domain, + /// 该 location 走「子域名 → 后端」转发 + Proxy, + /// 该 location 走 LLM 代理 + Llm, + /// 该 location 走 API 代理 + Apix, +} + +/// gateway 注入的查询实现:`(请求, 开关) -> 是否开启` +pub type SwitchFn = fn(&mut Request, Switch) -> bool; + +// fn 指针按 usize 原子存取(热路径上 access handler 每请求都要查,不能用 Mutex) +static SWITCH_FN: AtomicUsize = AtomicUsize::new(0); + +/// gateway 在 preconfiguration 阶段注入查询实现(早于任何请求) +pub fn set_switch_fn(f: SwitchFn) { + SWITCH_FN.store(f as *const () as usize, Ordering::Relaxed); +} + +/// 插件查询所在 location 是否开启自己的能力。 +/// **未注入实现时保守返回 `false`**——宁可关着,不可误开。 +pub fn enabled(r: *mut ngx_http_request_t, s: Switch) -> bool { + let p = SWITCH_FN.load(Ordering::Relaxed); + if p == 0 { + return false; + } + // SAFETY: p 来自 set_switch_fn 存入的合法 fn 指针 + let f: SwitchFn = unsafe { core::mem::transmute(p) }; + // SAFETY: r 由 nginx 传入且有效;Request 只在本调用存续期内使用 + let mut req = unsafe { Request::from_ngx_http_request(r) }; + f(&mut req, s) +} diff --git a/rust/src/models.rs b/rust/crates/ipass-core/src/models.rs similarity index 78% rename from rust/src/models.rs rename to rust/crates/ipass-core/src/models.rs index 712f4a9..3dafaf2 100644 --- a/rust/src/models.rs +++ b/rust/crates/ipass-core/src/models.rs @@ -161,59 +161,3 @@ pub struct ApiProxy { #[serde(default)] pub created_at: i64, } - -/// 域名表(`domains.json`):一条记录 = 一个子域名。 -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct DomainEntry { - pub id: String, - pub subdomain: String, - /// `host:port` - pub backend: String, - /// `temp`(临时,到时自动停止转发) | `long`(长期) - #[serde(rename = "type")] - pub dtype: String, - /// 归属账号 - pub owner: String, - /// `pending` | `approved` | `rejected` - pub status: String, - #[serde(default)] - pub created_at: i64, - /// 仅 temp 有意义;long 恒为 0 - #[serde(default)] - pub expires_at: i64, - /// `auto` 表示凭临时授权权限免审放行 - #[serde(default)] - pub reviewed_by: String, - #[serde(default)] - pub reviewed_at: i64, -} - -impl DomainEntry { - /// 实际状态:approved 的临时域名过期后视为 `expired`。 - /// - /// 这是「到期不等于删除」语义的落点——记录保留,只是不再转发。 - pub fn effective_status(&self, now: i64) -> &'static str { - if self.status == "approved" && self.dtype == "temp" { - if self.expires_at > 0 && self.expires_at <= now { - return "expired"; - } - } - match self.status.as_str() { - "approved" => "approved", - "rejected" => "rejected", - _ => "pending", - } - } - - /// 转发侧判定:返回该域名当前是否可转发(已放行且未过期) - pub fn is_forwardable(&self, now: i64) -> bool { - if self.status != "approved" { - return false; - } - if self.dtype == "temp" { - // 临时域名必须有明确的、尚未到达的到期时刻 - return self.expires_at > now; - } - true - } -} diff --git a/rust/crates/ipass-core/src/plugin.rs b/rust/crates/ipass-core/src/plugin.rs new file mode 100644 index 0000000..c1ff811 --- /dev/null +++ b/rust/crates/ipass-core/src/plugin.rs @@ -0,0 +1,51 @@ +//! 插件装配契约 —— 内核与插件之间唯一的接口。 +//! +//! 沿用 ssw/sso 的形态,签名保持一致(若将来与 sso 合流,trait 不用再改)。 +//! +//! ## 刻意没有 `commands()` +//! +//! nginx 的 `ngx_module_t.commands` 是 null 结尾的**连续**数组,不同 crate 的 +//! `static` 数组无法拼接。配置指令由 gateway 集中声明(`ipass_*` 七条不变), +//! 插件通过 [`crate::loc::Switch`] 查询自己所在 location 是否开启—— +//! **指令解析归壳、行为归插件**。 +//! +//! ## `dispatch_api` 语义 +//! +//! 「不认领就返回 `None`,让下一个插件试」,**绝不自行 404**——否则后注册的 +//! 插件永远收不到请求。404 由 gateway 在全部插件都返回 `None` 后统一发出。 + +use ngx::core::Status; +use ngx::ffi::{ngx_conf_t, ngx_http_request_t}; + +pub trait Plugin: Sync { + /// 插件名(日志与排障用) + fn name(&self) -> &'static str; + + /// 配置解析前:注册本插件自己的 nginx 变量。 + /// 返回 false = 注册失败,gateway 会 EMERG 退出。 + fn preconfig(&self, _cf: *mut ngx_conf_t) -> bool { + true + } + + /// 配置解析后:注册 phase handler / body filter。 + /// 返回 false = 注册失败,gateway 会 EMERG 退出。 + fn postconfig(&self, _cf: *mut ngx_conf_t) -> bool { + true + } + + /// 管理 API 分发:认领则返回响应状态,不认领返回 `None`。 + fn dispatch_api(&self, _r: *mut ngx_http_request_t) -> Option { + None + } + + /// fork 前预装载共享内存(zone init 回调里调用一次)。 + /// 返回装载条数(gateway 汇总打日志)。 + fn zone_load(&self) -> usize { + 0 + } + + /// log 阶段旁路处理器(与 sso 对齐保留;返回 true 表示已处理)。 + fn log_handler(&self, _r: *mut ngx_http_request_t) -> bool { + true + } +} diff --git a/rust/src/session.rs b/rust/crates/ipass-core/src/session.rs similarity index 100% rename from rust/src/session.rs rename to rust/crates/ipass-core/src/session.rs diff --git a/rust/src/state.rs b/rust/crates/ipass-core/src/state.rs similarity index 95% rename from rust/src/state.rs rename to rust/crates/ipass-core/src/state.rs index e3d9288..24e287e 100644 --- a/rust/src/state.rs +++ b/rust/crates/ipass-core/src/state.rs @@ -246,21 +246,6 @@ pub fn iter_prefix(prefix: &[u8]) -> Vec<(String, String)> { // 业务语义封装 // =========================================================================== -/// 转发映射:子域名 → 后端 -pub fn put_backend(subdomain: &[u8], backend: &[u8], expires_at: i64) -> bool { - put(crate::config::KEY_SUB_PREFIX, subdomain, backend, expires_at) -} - -/// 转发映射查询。返回 `(backend, expires_at)`。 -pub fn get_backend(subdomain: &[u8]) -> Option<(String, i64)> { - get(crate::config::KEY_SUB_PREFIX, subdomain) -} - -/// 失效一个子域名的转发映射(写操作后调用,保证「审核一通过、立刻可访问」) -pub fn invalidate(subdomain: &[u8]) -> bool { - remove(crate::config::KEY_SUB_PREFIX, subdomain) -} - /// 管理会话写入 pub fn put_session(token: &str, username: &str, expires_at: i64) -> bool { put(crate::config::KEY_SESS_PREFIX, token.as_bytes(), username.as_bytes(), expires_at) diff --git a/rust/src/store.rs b/rust/crates/ipass-core/src/store.rs similarity index 86% rename from rust/src/store.rs rename to rust/crates/ipass-core/src/store.rs index 5f079a5..d286b70 100644 --- a/rust/src/store.rs +++ b/rust/crates/ipass-core/src/store.rs @@ -28,7 +28,7 @@ use std::path::PathBuf; use std::sync::Mutex; use crate::config::DEFAULT_DATA_DIR; -use crate::models::{ApiProxyStore, DomainEntry, UpstreamTable, UserTable}; +use crate::models::{ApiProxyStore, UpstreamTable, UserTable}; use crate::state; /// 状态目录。配置阶段由 `ipass_data_dir` 指令设置一次,之后只读。 @@ -56,10 +56,6 @@ pub fn users_path() -> PathBuf { path_of("users.json") } -pub fn domains_path() -> PathBuf { - path_of("domains.json") -} - pub fn upstreams_path() -> PathBuf { path_of("llm-upstreams.json") } @@ -68,12 +64,18 @@ pub fn api_proxies_path() -> PathBuf { path_of("api-proxies.json") } +/// data 目录下任意文件的路径(插件用它管理自己的数据文件, +/// 如 plugin-domain 的 `domains.json`) +pub fn path_in_data(name: &str) -> PathBuf { + path_of(name) +} + // =========================================================================== // 读写 // =========================================================================== /// 读取并反序列化;文件缺失或损坏时回退 `default`(不抛错,保证转发侧可用) -fn read_json(path: &PathBuf, default: T) -> T { +pub fn read_json(path: &PathBuf, default: T) -> T { let Ok(text) = std::fs::read_to_string(path) else { return default; }; @@ -94,7 +96,7 @@ fn read_json(path: &PathBuf, default: T) -> T { } /// 原子写:先写 `.tmp` 再 rename,避免读到写了一半的内容 -fn write_json(path: &PathBuf, value: &T) -> Result<(), String> { +pub fn write_json(path: &PathBuf, value: &T) -> Result<(), String> { let text = serde_json::to_string(value).map_err(|e| format!("序列化失败:{e}"))?; let tmp = PathBuf::from(format!("{}.tmp", path.display())); @@ -117,10 +119,6 @@ pub fn read_users() -> UserTable { read_json(&users_path(), UserTable::new()) } -pub fn read_domains() -> Vec { - read_json(&domains_path(), Vec::new()) -} - pub fn read_upstreams() -> UpstreamTable { read_json(&upstreams_path(), UpstreamTable::new()) } @@ -133,10 +131,6 @@ pub fn write_users(data: &UserTable) -> Result<(), String> { write_json(&users_path(), data) } -pub fn write_domains(data: &[DomainEntry]) -> Result<(), String> { - write_json(&domains_path(), &data.to_vec()) -} - pub fn write_upstreams(data: &UpstreamTable) -> Result<(), String> { write_json(&upstreams_path(), data) } @@ -159,18 +153,6 @@ where Ok(out) } -/// 加锁「读-改-写」域名表 -pub fn update_domains(f: F) -> Result -where - F: FnOnce(&mut Vec) -> Result, -{ - let _guard = state::file_lock().ok_or("内部错误:状态锁不可用")?; - let mut data = read_domains(); - let out = f(&mut data)?; - write_domains(&data)?; - Ok(out) -} - /// 加锁「读-改-写」LLM 上游表 pub fn update_upstreams(f: F) -> Result where diff --git a/rust/src/users.rs b/rust/crates/ipass-core/src/users.rs similarity index 90% rename from rust/src/users.rs rename to rust/crates/ipass-core/src/users.rs index 2f249f6..2aa4696 100644 --- a/rust/src/users.rs +++ b/rust/crates/ipass-core/src/users.rs @@ -12,6 +12,8 @@ //! 代价是**任何改动 `api_key` 的操作都必须同步共享内存索引**, //! 且重置 Key 时必须**先摘掉旧索引**,否则被换掉的 Key 依然能用。 +use std::sync::Mutex; + use serde_json::{Value, json}; use crate::config::{ @@ -20,10 +22,39 @@ use crate::config::{ }; use crate::models::{User, UserTable}; use crate::state; -use crate::stats; use crate::store; use crate::util; +// =========================================================================== +// 账号删除钩子 +// =========================================================================== + +/// 「账号被删除时我需要清理什么」的回调注册表。 +/// +/// 内核只负责自己的键(`ukey:` / `sess:` / `fail:`),插件的键空间(用量账本、 +/// 代理索引……)内核**不认识**——删除账号要摘几个前缀,取决于装了哪些插件, +/// 所以只能由插件在装载阶段调用 [`on_delete`] 注册清理器(如 plugin-llm 注册 +/// `stats::forget`)。**重复注册同一函数会被去重**(nginx reload 会多次走到注册点)。 +static ON_DELETE: Mutex> = 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); + } + } +} + // =========================================================================== // 校验 // =========================================================================== @@ -352,7 +383,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 deleted = username.clone(); let removed_key = store::update_users(move |users| { let user = users.get(&username).ok_or("账号不存在")?; @@ -368,8 +399,9 @@ pub fn delete(username: &str, operator: &str) -> Result<(), String> { if !removed_key.is_empty() { state::remove_ukey(&removed_key); } - // 用量键是按前缀扫出来出报表的,不清就会让已删账号继续挂在用量榜上 - stats::forget(&stats_name); + // 内核自己的键已摘掉;用量账本等插件键空间由 on_delete 钩子清理 + // (谁装了谁清——钩子为空说明对应插件未装配,自然也无键可清) + run_delete_hooks(&deleted); Ok(()) } diff --git a/rust/src/util.rs b/rust/crates/ipass-core/src/util.rs similarity index 100% rename from rust/src/util.rs rename to rust/crates/ipass-core/src/util.rs diff --git a/rust/crates/plugin-domain/Cargo.toml b/rust/crates/plugin-domain/Cargo.toml new file mode 100644 index 0000000..11404e3 --- /dev/null +++ b/rust/crates/plugin-domain/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "plugin-domain" +version = "2.0.0" +edition.workspace = true +publish = false +description = "iPass 插件:动态域名(子域名映射、申请审批、转发决策)" + +[lib] +# 只有 gateway 是 cdylib;插件一律 rlib(跨 .so 传 Rust 类型会双重 free) +crate-type = ["rlib"] + +[dependencies] +ngx.workspace = true +serde.workspace = true +serde_json.workspace = true +ipass-core.workspace = true diff --git a/rust/crates/plugin-domain/src/api.rs b/rust/crates/plugin-domain/src/api.rs new file mode 100644 index 0000000..f67ee32 --- /dev/null +++ b/rust/crates/plugin-domain/src/api.rs @@ -0,0 +1,191 @@ +//! 域名类端点:管理员审核/创建/删除/清理 + 账号态申请/查询/删除。 +//! +//! 路由表只认领**本插件**的路径;不认领的返回 `None` 交给下一个插件。 +//! `/api/admin/purge` 清理的是过期域名与陈旧驳回记录,属域名职责。 + +use ngx::core::Status; +use ngx::ffi::ngx_http_request_t; +use ngx::http::HTTPStatus; +use serde_json::json; + +use ipass_core::api::{Actor, Guard, run_guarded, user_or_401}; +use ipass_core::http; +use ipass_core::util; + +use crate::config; +use crate::domains; + +// =========================================================================== +// 路由 +// =========================================================================== + +type Handler = fn(*mut ngx_http_request_t, Actor) -> Status; + +fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> { + let entry: (Guard, Handler) = match (method, uri) { + ("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), + ("POST", "/api/admin/domains/delete") => (Guard::Admin, h_admin_domain_delete), + ("POST", "/api/admin/purge") => (Guard::Admin, h_admin_purge), + ("GET", "/api/v1/domains") => (Guard::User, h_my_domains), + ("POST", "/api/v1/domains/apply") => (Guard::User, h_apply), + ("POST", "/api/v1/domains/delete") => (Guard::User, h_my_delete), + _ => return None, + }; + Some(entry) +} + +/// 本表分发:认领则返回响应状态,不认领返回 `None`。 +pub fn dispatch(r: *mut ngx_http_request_t) -> Option { + 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)) +} + +// =========================================================================== +// 管理员:域名审核 +// =========================================================================== + +fn h_admin_domains(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + http::ok( + r, + json!({ + "items": domains::view_all(&domains::all()), + "pending": domains::count_pending(), + // 子域名命名规则:前端据此渲染「i + 8位数字 + dm」输入框, + // 避免前后端各写一份前缀/后缀/zone 而漂移(真源 = 本插件 config.rs) + "subdomain_rule": { + "zone": config::ENTERPRISE_ZONE, + "prefix": config::SUBDOMAIN_PREFIX, + "suffix": config::SUBDOMAIN_SUFFIX, + "digits": config::SUBDOMAIN_RAND_DIGITS, + }, + }), + "ok", + ) +} + +fn h_admin_domain_review(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let p = http::params(r); + let id = p.get("id").map(String::as_str).unwrap_or(""); + let action = p.get("action").map(String::as_str).unwrap_or(""); + match domains::review(id, action, actor.admin_name()) { + Ok(entry) => { + let msg = if action == "approve" { "已通过审核" } else { "已驳回" }; + http::ok(r, domains::view(&entry), msg) + } + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_domain_create(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let p = http::params(r); + + // subdomain 缺省(或空串)= 由网关按规则自动生成 `i<8位随机数字>dm`, + // 与面板上「i + 8位随机数 + dm」是同一套规则(见 domains::gen_subdomain)。 + match domains::create_by_admin( + p.get("subdomain").map(String::as_str).unwrap_or(""), + p.get("backend").map(String::as_str).unwrap_or(""), + p.get("type"), + p.get("owner"), + actor.admin_name(), + ) { + Ok(entry) => http::ok(r, domains::view(&entry), "已创建并直接放行"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_domain_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + let p = http::params(r); + let id = p.get("id").map(String::as_str).unwrap_or(""); + + match domains::remove(id) { + Ok(sub) => http::ok(r, json!({ "subdomain": sub }), "已删除"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +fn h_admin_purge(r: *mut ngx_http_request_t, _actor: Actor) -> Status { + match domains::purge() { + Ok(removed) => http::ok( + r, + json!({ "removed": removed }), + &format!("已清理 {removed} 条过期/陈旧记录"), + ), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} + +// =========================================================================== +// 账号态 +// =========================================================================== + +fn h_my_domains(r: *mut ngx_http_request_t, actor: Actor) -> Status { + let user = match user_or_401(r, actor) { + Ok(u) => u, + Err(e) => return e, + }; + http::ok( + r, + json!({ "items": domains::view_all(&domains::by_owner(&user.username)) }), + "ok", + ) +} + +fn h_apply(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 p = http::params(r); + let entry = match domains::apply( + &user.username, + p.get("subdomain").map(String::as_str).unwrap_or(""), + p.get("backend").map(String::as_str).unwrap_or(""), + p.get("type"), + ) { + Ok(e) => e, + Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), + }; + + let view = domains::view(&entry); + util::log_notice(&format!( + "[api] {} 申请 {} type={} status={}", + user.username, + entry.subdomain, + entry.dtype, + entry.effective_status(util::now()) + )); + + let msg = if entry.status == "approved" { + format!( + "已直接放行(临时授权权限生效),{} 小时后自动失效", + config::TEMP_DOMAIN_TTL / 3600 + ) + } else { + "已提交申请,等待管理员审核".to_owned() + }; + http::ok(r, view, &msg) +} + +fn h_my_delete(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 p = http::params(r); + let id = p.get("id").map(String::as_str).unwrap_or(""); + + match domains::remove_own(id, &user.username) { + Ok(sub) => http::ok(r, json!({ "subdomain": sub }), "已删除"), + Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), + } +} diff --git a/rust/crates/plugin-domain/src/config.rs b/rust/crates/plugin-domain/src/config.rs new file mode 100644 index 0000000..6157c61 --- /dev/null +++ b/rust/crates/plugin-domain/src/config.rs @@ -0,0 +1,35 @@ +//! 域名插件策略常量(自内核 config.rs 迁入;改策略只改这里)。 + +/// 临时域名审批通过后的有效期(秒)。到期仅停止转发,记录保留供查阅。 +pub const TEMP_DOMAIN_TTL: i64 = 6 * 3600; + +/// 子域名总长上限:首字符 + 最多 61 个后续字符 +pub const SUBDOMAIN_MAX_LEN: usize = 62; + +/// 系统保留名:不允许用户申请,避免抢占管理入口 +pub const RESERVED_SUBDOMAINS: [&str; 4] = ["proxy-api", "admin", "www", "api"]; + +/// 驳回记录保留时长,超期由 purge 清理(秒) +pub const REJECTED_PURGE_TTL: i64 = 7 * 86400; + +/// 键前缀:子域名 → 后端映射 +pub const KEY_SUB_PREFIX: &[u8] = b"sub:"; + +/// 企业域名(业务域名)的 zone:**子域名 + `.` + 此后缀 = 完整对外域名**。 +/// +/// ⚠️ 与 `conf/nginx.conf` 的「企业域名 server」严格耦合: +/// `server_name ~^(?.+dm)\.mayishangshu\.cn$;` +/// 改这里必须同步改那条正则(反之亦然)。 +pub const ENTERPRISE_ZONE: &str = "mayishangshu.cn"; + +/// 自动生成子域名的形状:`<前缀><后缀>` —— 例如 `i12345678dm`。 +/// +/// 后缀**必须是 `dm`**:企业域名 server 的正则要求捕获组以 `dm` 结尾 +/// (`^(.+dm)\.mayishangshu\.cn$`),否则域名建出来也转发不到。 +/// 这是「规则」的实质约束,不是命名偏好。 +pub const SUBDOMAIN_PREFIX: &str = "i"; +pub const SUBDOMAIN_SUFFIX: &str = "dm"; +/// 随机数字位数。10^8 的空间,撞车概率极低 +pub const SUBDOMAIN_RAND_DIGITS: usize = 8; +/// 自动生成子域名时的最大重试次数(真撞上已占用的就换一个再试) +pub const SUBDOMAIN_GEN_ATTEMPTS: usize = 5; diff --git a/rust/src/domains.rs b/rust/crates/plugin-domain/src/domains.rs similarity index 91% rename from rust/src/domains.rs rename to rust/crates/plugin-domain/src/domains.rs index d54f2eb..db09a3e 100644 --- a/rust/src/domains.rs +++ b/rust/crates/plugin-domain/src/domains.rs @@ -1,6 +1,6 @@ //! 域名(子域名映射)与申请审核。 //! -//! 对应旧版 `lua/domains.lua`。数据结构见 `models::DomainEntry`。 +//! 数据结构见 `models::DomainEntry`。 //! //! ## 状态机 //! @@ -12,23 +12,21 @@ //! //! 到期不等于删除:临时域名过期后仅「不再转发」,记录保留供查阅。 //! -//! ## 与旧版最大的差异:写穿 +//! ## 写穿 //! -//! 旧版写操作后 `invalidate` 掉缓存,靠「未命中回源读文件」拿到新值; -//! 新版热路径**永不回源**(未命中即 404),所以每个写操作都必须 +//! 热路径**永不回源**(未命中即 404),所以每个写操作都必须 //! **同时更新共享内存与文件**——这就是 `sync_shm` 的存在理由。 //! 漏掉一处,就会出现「审核通过了但立刻 404」。 use serde_json::{Value, json}; +use ipass_core::{state, users, util}; + use crate::config::{ ENTERPRISE_ZONE, KEY_SUB_PREFIX, REJECTED_PURGE_TTL, RESERVED_SUBDOMAINS, SUBDOMAIN_GEN_ATTEMPTS, SUBDOMAIN_MAX_LEN, SUBDOMAIN_PREFIX, SUBDOMAIN_RAND_DIGITS, SUBDOMAIN_SUFFIX, TEMP_DOMAIN_TTL, }; use crate::models::DomainEntry; -use crate::state; -use crate::store; -use crate::util; // =========================================================================== // 校验 @@ -119,20 +117,25 @@ pub fn validate_type(raw: Option<&String>) -> String { /// 把一条记录同步进共享内存。**所有写操作之后必须调用它**。 /// /// 写失败 = 热路径查不到 = 该域名立刻 404,所以失败必须出声 -/// (`state::put_backend` 返回 false:共享内存 zone 满或分配失败)。 +/// (`state::put` 返回 false:共享内存 zone 满或分配失败)。 pub fn sync_shm(entry: &DomainEntry) { let now = util::now(); if entry.is_forwardable(now) { // long 用 0 表示永不过期;temp 用真实到期时刻,热路径读到即知是否还能用 let exp = if entry.dtype == "temp" { entry.expires_at } else { 0 }; - if !state::put_backend(entry.subdomain.as_bytes(), entry.backend.as_bytes(), exp) { + if !state::put( + KEY_SUB_PREFIX, + entry.subdomain.as_bytes(), + entry.backend.as_bytes(), + exp, + ) { util::log_err(&format!( "[domains] 转发映射写共享内存失败 sub={} —— 该域名会 404(共享内存可能已满)", entry.subdomain )); } } else { - state::invalidate(entry.subdomain.as_bytes()); + state::remove(KEY_SUB_PREFIX, entry.subdomain.as_bytes()); } } @@ -144,11 +147,11 @@ pub fn reload_shm() -> usize { let now = util::now(); let mut expected = 0; let mut loaded = 0; - for entry in store::read_domains() { + for entry in crate::store::read_domains() { if entry.is_forwardable(now) { expected += 1; let exp = if entry.dtype == "temp" { entry.expires_at } else { 0 }; - if state::put_backend(entry.subdomain.as_bytes(), entry.backend.as_bytes(), exp) { + if state::put(KEY_SUB_PREFIX, entry.subdomain.as_bytes(), entry.backend.as_bytes(), exp) { loaded += 1; } } @@ -167,14 +170,14 @@ pub fn reload_shm() -> usize { /// 全部记录,按创建时间倒序 pub fn all() -> Vec { - let mut list = store::read_domains(); + let mut list = crate::store::read_domains(); list.sort_by(|a, b| b.created_at.cmp(&a.created_at)); list } pub fn by_owner(owner: &str) -> Vec { let mut list: Vec = - store::read_domains().into_iter().filter(|e| e.owner == owner).collect(); + crate::store::read_domains().into_iter().filter(|e| e.owner == owner).collect(); list.sort_by(|a, b| b.created_at.cmp(&a.created_at)); list } @@ -182,11 +185,11 @@ pub fn by_owner(owner: &str) -> Vec { /// 按 id 取单条记录(当前无调用方,保留为对外查询接口) #[allow(dead_code)] pub fn by_id(id: &str) -> Option { - store::read_domains().into_iter().find(|e| e.id == id) + crate::store::read_domains().into_iter().find(|e| e.id == id) } pub fn count_pending() -> usize { - store::read_domains().iter().filter(|e| e.status == "pending").count() + crate::store::read_domains().iter().filter(|e| e.status == "pending").count() } // =========================================================================== @@ -202,7 +205,7 @@ pub fn apply( backend: &str, dtype: Option<&String>, ) -> Result { - let user = crate::users::get(username).ok_or("账号不存在")?; + let user = users::get(username).ok_or("账号不存在")?; let subdomain = validate_subdomain(subdomain)?; let backend = validate_backend(backend)?; @@ -212,7 +215,7 @@ pub fn apply( let auto = dtype == "temp" && user.has_temp_permission(now); let chosen = subdomain.clone(); - let entry = store::update_domains(move |list| { + let entry = crate::store::update_domains(move |list| { if let Some(idx) = list.iter().position(|e| e.subdomain == chosen) { let existing = &list[idx]; let mine_pending = existing.owner == username && existing.status == "pending"; @@ -260,7 +263,7 @@ pub fn review(id: &str, action: &str, admin: &str) -> Result o.clone(), _ => admin.to_owned(), }; - if crate::users::get(&owner).is_none() { + if users::get(&owner).is_none() { return Err(format!("归属账号不存在:{owner}")); } @@ -343,7 +346,7 @@ fn insert_approved( let owner = owner.to_owned(); let admin = admin.to_owned(); - store::update_domains(move |list| { + crate::store::update_domains(move |list| { if let Some(idx) = list.iter().position(|e| e.subdomain == chosen) { let existing = &list[idx]; let its_expired = @@ -376,7 +379,7 @@ pub fn remove_own(id: &str, username: &str) -> Result { let id = id.to_owned(); let username = username.to_owned(); - store::update_domains(move |list| { + crate::store::update_domains(move |list| { let idx = list.iter().position(|e| e.id == id).ok_or("记录不存在")?; if list[idx].owner != username { return Err("只能删除自己的域名".to_owned()); @@ -385,7 +388,7 @@ pub fn remove_own(id: &str, username: &str) -> Result { Ok(sub) }) .map(|sub| { - state::invalidate(sub.as_bytes()); + state::remove(KEY_SUB_PREFIX, sub.as_bytes()); sub }) } @@ -393,12 +396,12 @@ pub fn remove_own(id: &str, username: &str) -> Result { /// 管理员删除任意域名 pub fn remove(id: &str) -> Result { let id = id.to_owned(); - store::update_domains(move |list| { + crate::store::update_domains(move |list| { let idx = list.iter().position(|e| e.id == id).ok_or("记录不存在")?; Ok(list.remove(idx).subdomain) }) .map(|sub| { - state::invalidate(sub.as_bytes()); + state::remove(KEY_SUB_PREFIX, sub.as_bytes()); sub }) } @@ -406,7 +409,7 @@ pub fn remove(id: &str) -> Result { /// 连带回收某账号名下的全部域名(删除账号时用)。返回回收条数。 pub fn remove_by_owner(owner: &str) -> usize { let mut removed = 0usize; - let result = store::update_domains(|list| { + let result = crate::store::update_domains(|list| { list.retain(|e| { if e.owner == owner { removed += 1; @@ -429,7 +432,7 @@ pub fn purge() -> Result { let now = util::now(); let mut removed = 0usize; - store::update_domains(|list| { + crate::store::update_domains(|list| { list.retain(|e| { let status = e.effective_status(now); let stale_rejected = diff --git a/rust/crates/plugin-domain/src/lib.rs b/rust/crates/plugin-domain/src/lib.rs new file mode 100644 index 0000000..aab3cec --- /dev/null +++ b/rust/crates/plugin-domain/src/lib.rs @@ -0,0 +1,54 @@ +//! plugin-domain —— 动态域名插件。 +//! +//! 职责:子域名 → 后端映射(`sub:` 键空间)、申请与审批、转发决策 +//! (access 阶段查共享内存)。数据文件 `data/domains.json`。 +//! +//! ## 与旧版最大的差异:写穿 +//! +//! 热路径**永不回源**(未命中即 404),所以每个写操作都必须 +//! **同时更新共享内存与文件**——这就是 `domains::sync_shm` 的存在理由。 +//! 漏掉一处,就会出现「审核通过了但立刻 404」。 +//! +//! ## 装配点(gateway) +//! +//! * `preconfig` —— 注册 `$proxy_backend_addr` 变量(`proxy_pass` 依赖) +//! * `postconfig` —— 注册 `ResolveHandler`(access 阶段) +//! * `zone_load` —— 全量装载 `sub:` 映射 +//! * `dispatch_api` —— 认领域名类管理/账号端点 + +pub mod api; +pub mod config; +pub mod domains; +pub mod models; +pub mod resolve; +pub mod store; + +use ngx::core::Status; +use ngx::ffi::{ngx_conf_t, ngx_http_request_t}; + +use ipass_core::plugin::Plugin; + +pub struct DomainPlugin; + +impl Plugin for DomainPlugin { + fn name(&self) -> &'static str { + "domain" + } + + fn preconfig(&self, cf: *mut ngx_conf_t) -> bool { + resolve::preconfig(cf) + } + + fn postconfig(&self, cf: *mut ngx_conf_t) -> bool { + // SAFETY: cf 由 nginx 传入且有效 + ngx::http::add_phase_handler::(unsafe { &mut *cf }).is_ok() + } + + fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { + api::dispatch(r) + } + + fn zone_load(&self) -> usize { + domains::reload_shm() + } +} diff --git a/rust/crates/plugin-domain/src/models.rs b/rust/crates/plugin-domain/src/models.rs new file mode 100644 index 0000000..3d1d8d6 --- /dev/null +++ b/rust/crates/plugin-domain/src/models.rs @@ -0,0 +1,61 @@ +//! 域名持久化模型(`domains.json`:一条记录 = 一个子域名)。 + +use serde::{Deserialize, Serialize}; + +/// 单条域名记录。 +/// +/// 字段名与旧版 `data/domains.json` **逐字对应**,以便新版直接接管旧数据文件。 +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct DomainEntry { + pub id: String, + pub subdomain: String, + /// `host:port` + pub backend: String, + /// `temp`(临时,到时自动停止转发) | `long`(长期) + #[serde(rename = "type")] + pub dtype: String, + /// 归属账号 + pub owner: String, + /// `pending` | `approved` | `rejected` + pub status: String, + #[serde(default)] + pub created_at: i64, + /// 仅 temp 有意义;long 恒为 0 + #[serde(default)] + pub expires_at: i64, + /// `auto` 表示凭临时授权权限免审放行 + #[serde(default)] + pub reviewed_by: String, + #[serde(default)] + pub reviewed_at: i64, +} + +impl DomainEntry { + /// 实际状态:approved 的临时域名过期后视为 `expired`。 + /// + /// 这是「到期不等于删除」语义的落点——记录保留,只是不再转发。 + pub fn effective_status(&self, now: i64) -> &'static str { + if self.status == "approved" && self.dtype == "temp" { + if self.expires_at > 0 && self.expires_at <= now { + return "expired"; + } + } + match self.status.as_str() { + "approved" => "approved", + "rejected" => "rejected", + _ => "pending", + } + } + + /// 转发侧判定:返回该域名当前是否可转发(已放行且未过期) + pub fn is_forwardable(&self, now: i64) -> bool { + if self.status != "approved" { + return false; + } + if self.dtype == "temp" { + // 临时域名必须有明确的、尚未到达的到期时刻 + return self.expires_at > now; + } + true + } +} diff --git a/rust/crates/plugin-domain/src/resolve.rs b/rust/crates/plugin-domain/src/resolve.rs new file mode 100644 index 0000000..c4605c5 --- /dev/null +++ b/rust/crates/plugin-domain/src/resolve.rs @@ -0,0 +1,188 @@ +//! 转发热路径:查共享内存取后端地址,供 nginx 的 `proxy_pass` 使用。 +//! +//! **热路径唯一入口**——只读内存,未命中不产生任何 I/O。 +//! 旧版这里在 miss 时会去读 `domains.json` 并全量 JSON 解码, +//! 那正是「随便发一堆随机子域名就能打穿磁盘」的入口。 + +use core::ptr; +use core::sync::atomic::{AtomicUsize, Ordering}; + +use ngx::core::{Pool, Status}; +use ngx::ffi::{ + NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, ngx_conf_t, ngx_http_add_variable, + ngx_http_get_variable_index, ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, + ngx_uint_t, +}; +use ngx::http::{HTTPStatus, HttpPhase, HttpRequestHandler}; +use ngx::ngx_string; + +use crate::config; +use ipass_core::loc::{self, Switch}; +use ipass_core::state; +use ipass_core::util; + +/// `$proxy_backend_addr` 在 `r->variables` 里的下标 +static BACKEND_VAR_INDEX: AtomicUsize = AtomicUsize::new(usize::MAX); + +/// 查共享内存取后端地址;已过期的条目视为不存在。 +fn resolve_backend(subdomain: &[u8]) -> Option { + let (backend, expires_at) = state::get(config::KEY_SUB_PREFIX, subdomain)?; + if expires_at > 0 && expires_at <= util::now() { + return None; + } + Some(backend) +} + +/// 取 Host 头里第一个点之前的部分作为子域名。 +/// +/// 刻意不走 nginx 的 server_name 正则捕获变量(那需要再算一次变量 hash), +/// 热路径上手工切更省。 +pub fn subdomain_of(r: *mut ngx_http_request_t) -> Option> { + // SAFETY: r 有效;迭代器只在本函数存续期内使用 + let request = unsafe { ngx::http::Request::from_ngx_http_request(r) }; + for (key, value) in request.headers_in_iterator() { + if key.as_bytes().eq_ignore_ascii_case(b"host") { + let host = value.as_bytes(); + // 去掉端口 + let host = match host.iter().position(|&b| b == b':') { + Some(i) => &host[..i], + None => host, + }; + // 取第一段标签 + let label = match host.iter().position(|&b| b == b'.') { + Some(i) => &host[..i], + None => host, + }; + if label.is_empty() { + return None; + } + return Some(label.to_ascii_lowercase()); + } + } + None +} + +/// 把后端地址写进 `r->variables[$proxy_backend_addr]`,供 `proxy_pass` 使用 +fn set_backend_var(r: *mut ngx_http_request_t, backend: &str) { + let idx = BACKEND_VAR_INDEX.load(Ordering::SeqCst); + if idx == usize::MAX { + return; + } + // SAFETY: idx 由 ngx_http_get_variable_index 分配且落在 r->variables 内; + // 值分配在请求池里,随请求回收 + unsafe { + let pool = Pool::from_ngx_pool((*r).pool); + let bytes = backend.as_bytes(); + let data = pool.alloc(bytes.len()) as *mut u8; + if data.is_null() { + return; + } + ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len()); + + let vv: *mut ngx_http_variable_value_t = (*r).variables.add(idx); + (*vv).data = data; + (*vv).set_len(bytes.len() as _); + (*vv).set_valid(1); + (*vv).set_not_found(0); + (*vv).set_no_cacheable(1); + } +} + +/// 变量 get_handler:`proxy_pass` 求值 `$proxy_backend_addr` 时被调用。 +/// +/// 与 access 阶段互补——这里保证「即使 access 未赋值也能取到」, +/// access 阶段则负责决定命中不了时返回 404。 +extern "C" fn backend_get( + r: *mut ngx_http_request_t, + v: *mut ngx_http_variable_value_t, + _data: usize, +) -> ngx_int_t { + // SAFETY: nginx 传入的 r/v 必然有效 + unsafe { + let resolved = subdomain_of(r).as_deref().and_then(resolve_backend); + + let Some(backend) = resolved else { + (*v).set_not_found(1); + return Status::NGX_ERROR.into(); + }; + + let pool = Pool::from_ngx_pool((*r).pool); + let bytes = backend.as_bytes(); + let data = pool.alloc(bytes.len()) as *mut u8; + if data.is_null() { + (*v).set_not_found(1); + return Status::NGX_ERROR.into(); + } + ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len()); + + (*v).data = data; + (*v).set_len(bytes.len() as _); + (*v).set_valid(1); + (*v).set_no_cacheable(1); + (*v).set_not_found(0); + + Status::NGX_OK.into() + } +} + +/// 配置解析前注册 `$proxy_backend_addr`。 +/// +/// 必须在 preconfiguration 阶段调用,否则配置里的 +/// `proxy_pass http://$proxy_backend_addr` 无法解析。 +pub fn preconfig(cf: *mut ngx_conf_t) -> bool { + let mut name = ngx_string!("proxy_backend_addr"); + + let idx = unsafe { ngx_http_get_variable_index(cf, &raw mut name) }; + if idx == -1 { + return false; + } + BACKEND_VAR_INDEX.store(idx as usize, Ordering::SeqCst); + + let var = unsafe { + ngx_http_add_variable( + cf, + &raw mut name, + (NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t, + ) + }; + if var.is_null() { + return false; + } + + // SAFETY: var 非空且由本函数独占初始化 + unsafe { + (*var).get_handler = Some(backend_get); + (*var).set_handler = None; + (*var).data = 0; + } + true +} + +/// 转发热路径:命中则放行(`proxy_pass` 会去取 `$proxy_backend_addr`),未命中直接 404。 +pub struct ResolveHandler; + +impl HttpRequestHandler for ResolveHandler { + const PHASE: HttpPhase = HttpPhase::Access; + type Output = Status; + + fn handler(request: &mut ngx::http::Request) -> Self::Output { + // 未开启该开关的 location 一律放行(管理台/API 走这里) + let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t; + if !loc::enabled(r, Switch::Proxy) { + return Status::NGX_DECLINED; + } + + let Some(host) = subdomain_of(r) else { + return HTTPStatus::NOT_FOUND.into(); + }; + + match resolve_backend(&host) { + Some(backend) => { + set_backend_var(r, &backend); + Status::NGX_DECLINED + } + // 与旧版语义一致:查不到 = 未配置 / 已过期 / 已删除 / 尚未审核通过 + None => HTTPStatus::NOT_FOUND.into(), + } + } +} diff --git a/rust/crates/plugin-domain/src/store.rs b/rust/crates/plugin-domain/src/store.rs new file mode 100644 index 0000000..52a93a6 --- /dev/null +++ b/rust/crates/plugin-domain/src/store.rs @@ -0,0 +1,33 @@ +//! 域名表的文件读写(复用内核 store 的原子写 + 全局文件写锁)。 + +use std::path::PathBuf; + +use ipass_core::{state, store}; + +use crate::models::DomainEntry; + +fn domains_path() -> PathBuf { + store::path_in_data("domains.json") +} + +pub fn read_domains() -> Vec { + store::read_json(&domains_path(), Vec::new()) +} + +pub fn write_domains(data: &[DomainEntry]) -> Result<(), String> { + store::write_json(&domains_path(), &data.to_vec()) +} + +/// 加锁「读-改-写」域名表。 +/// +/// 闭包返回 `Ok(T)` 表示提交,`Err(msg)` 表示放弃(不写盘)。 +pub fn update_domains(f: F) -> Result +where + F: FnOnce(&mut Vec) -> Result, +{ + let _guard = state::file_lock().ok_or("内部错误:状态锁不可用")?; + let mut data = read_domains(); + let out = f(&mut data)?; + write_domains(&data)?; + Ok(out) +} diff --git a/rust/gateway/Cargo.toml b/rust/gateway/Cargo.toml new file mode 100644 index 0000000..ac8f31e --- /dev/null +++ b/rust/gateway/Cargo.toml @@ -0,0 +1,28 @@ +[package] +name = "ipass-gateway" +version = "2.0.0" +edition.workspace = true +publish = false +description = "尚数网 统一网关(iPass 山海关)—— nginx + Rust 扩展模块实现(模块壳 + 插件装配)" + +[lib] +name = "ipass_gateway" +# cdylib 给 nginx 加载;rlib 便于单元测试 +crate-type = ["cdylib", "rlib"] + +[features] +default = ["export-modules"] +# 脱离 nginx 构建系统、单独产出动态模块时必须开启(生成 ngx_modules 表) +export-modules = [] + +[dependencies] +ngx.workspace = true +nginx-sys.workspace = true +ipass-core.workspace = true +plugin-domain.workspace = true + +serde.workspace = true +serde_json.workspace = true +sha2.workspace = true +getrandom.workspace = true +libc.workspace = true diff --git a/rust/build.rs b/rust/gateway/build.rs similarity index 100% rename from rust/build.rs rename to rust/gateway/build.rs diff --git a/rust/gateway/src/api.rs b/rust/gateway/src/api.rs new file mode 100644 index 0000000..a7f80e1 --- /dev/null +++ b/rust/gateway/src/api.rs @@ -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 { + 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 { + 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//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::().ok()) + .unwrap_or_else(stats::trend_default_days); + + let usernames: Vec = users::all().into_iter().map(|u| u.username).collect(); + // API 代理与 LLM 上游共用同一片用量键空间,只是 slot 带 `api/` 前缀 + // (见 `config::APIX_STATS_PREFIX`)——这里一起列出,趋势图才会出现它们 + let slots: Vec = 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::(v) { + arr.into_iter() + .filter_map(|x| x.as_str().map(str::to_owned)) + .collect::>() + } else { + v.split(',').map(str::to_owned).collect::>() + }) + }); + + // 不带 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/`, +/// 复用 `$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 = 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 = 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 = 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::>(), + }), + "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 = 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", + ) +} diff --git a/rust/src/apix.rs b/rust/gateway/src/apix.rs similarity index 100% rename from rust/src/apix.rs rename to rust/gateway/src/apix.rs diff --git a/rust/src/lib.rs b/rust/gateway/src/lib.rs similarity index 82% rename from rust/src/lib.rs rename to rust/gateway/src/lib.rs index 4d32c17..84c471f 100644 --- a/rust/src/lib.rs +++ b/rust/gateway/src/lib.rs @@ -40,186 +40,173 @@ mod api; mod apix; -mod config; -mod domains; -mod http; mod llm; mod llm_audit; mod llm_usage; -mod models; -mod session; -mod state; mod stats; -mod store; mod upstreams; -mod util; -mod users; + +// 内核模块桥接:业务文件里的 `crate::config::X` / `crate::state::…` 等路径 +// 不用改写,直接经此解析到 ipass-core(插件化 P0 的行为等价手段, +// 各业务模块随 P2–P4 迁入插件 crate 后,这里的 re-export 会逐个撤掉)。 +pub use ipass_core::{config, http, models, session, state, store, users, util}; use core::ffi::{c_char, c_void}; use core::ptr; -use core::sync::atomic::{AtomicIsize, AtomicUsize, Ordering}; +use core::sync::atomic::{AtomicIsize, Ordering}; -use ngx::core::{NGX_CONF_ERROR, NGX_CONF_OK, NgxStr, NgxString, Pool, SlabPool, Status}; +use ngx::core::{NGX_CONF_ERROR, NGX_CONF_OK, NgxStr, NgxString, SlabPool, Status}; +use serde_json::{Value, json}; use ngx::ffi::{ NGX_CONF_TAKE1, NGX_CONF_TAKE2, NGX_HTTP_LOC_CONF, NGX_HTTP_LOC_CONF_OFFSET, NGX_HTTP_MAIN_CONF, NGX_HTTP_MAIN_CONF_OFFSET, NGX_HTTP_MODULE, NGX_HTTP_VAR_CHANGEABLE, NGX_HTTP_VAR_NOCACHEABLE, NGX_LOG_EMERG, ngx_command_t, ngx_conf_t, ngx_cycle_t, ngx_http_add_variable, ngx_http_get_indexed_variable, ngx_http_get_variable_index, ngx_http_module_t, - ngx_http_request_t, ngx_http_variable_value_t, ngx_int_t, ngx_module_t, ngx_parse_size, + ngx_http_request_t, ngx_int_t, ngx_module_t, ngx_parse_size, ngx_shared_memory_add, ngx_shm_zone_t, ngx_str_t, ngx_uint_t, }; use ngx::http::{ HTTPStatus, HttpModule, HttpModuleLocationConf, HttpPhase, HttpRequestHandler, Merge, - MergeConfigError, + MergeConfigError, Request, }; use ngx::{ngx_conf_log_error, ngx_string}; -/// `$proxy_backend_addr` 在 `r->variables` 里的下标 -static BACKEND_VAR_INDEX: AtomicUsize = AtomicUsize::new(usize::MAX); +use ipass_core::loc::{self, Switch}; +use ipass_core::plugin::Plugin; // =========================================================================== -// 转发热路径 +// 插件装配(PLUGINS 顺序 = 认领顺序;身份类端点将来必须排最前) // =========================================================================== -/// 查共享内存取后端地址;已过期的条目视为不存在。 -/// -/// **热路径唯一入口**——只读内存,未命中不产生任何 I/O。 -/// 旧版这里在 miss 时会去读 `domains.json` 并全量 JSON 解码, -/// 那正是「随便发一堆随机子域名就能打穿磁盘」的入口。 -fn resolve_backend(subdomain: &[u8]) -> Option { - let (backend, expires_at) = state::get_backend(subdomain)?; - if expires_at > 0 && expires_at <= util::now() { - return None; +/// 过渡期路由插件:api.rs 里暂留的端点由 gateway 自己认领。 +/// P2 起 domain 路由迁 plugin-domain、P3 迁 plugin-llm、P4 迁 plugin-apix, +/// 全部迁完时本插件消失(或只剩 apix 的路由部分并入 ApixPlugin)。 +struct GatewayRoutes; + +impl Plugin for GatewayRoutes { + fn name(&self) -> &'static str { + "gateway-routes" + } + + fn dispatch_api(&self, r: *mut ngx_http_request_t) -> Option { + api::dispatch(r) } - Some(backend) } -/// 取 Host 头里第一个点之前的部分作为子域名。 -/// -/// 刻意不走 nginx 的 server_name 正则捕获变量(那需要再算一次变量 hash), -/// 热路径上手工切更省。 -fn subdomain_of(r: *mut ngx_http_request_t) -> Option> { - // SAFETY: r 有效;迭代器只在本函数存续期内使用 - let request = unsafe { ngx::http::Request::from_ngx_http_request(r) }; - for (key, value) in request.headers_in_iterator() { - if key.as_bytes().eq_ignore_ascii_case(b"host") { - let host = value.as_bytes(); - // 去掉端口 - let host = match host.iter().position(|&b| b == b':') { - Some(i) => &host[..i], - None => host, +/// 插件注册表。**身份类端点(CorePlugin)排在最前**:dispatch 按顺序认领, +/// 先注册者先得。装配顺序:内核(身份)→ 域名 → 过渡期路由(llm/apix)。 +static PLUGINS: &[&dyn Plugin] = &[ + &ipass_core::api::CorePlugin, + &plugin_domain::DomainPlugin, + &GatewayRoutes, +]; + +/// 装配根的插件扩展:把身份端点需要的插件侧数据回填给内核 +/// (内核不认识任何插件,见 `ipass_core::api::CoreExt`)。 +struct GatewayExt; + +impl ipass_core::api::CoreExt for GatewayExt { + /// 管理台账号列表:域名数 + LLM 用量摘要(一次扫表,避免逐账号查共享内存) + fn decorate_admin_users(&self, views: &mut [Value]) { + let mut counts: std::collections::HashMap = std::collections::HashMap::new(); + for d in plugin_domain::domains::all() { + *counts.entry(d.owner).or_insert(0) += 1; + } + + let now = util::now(); + let usage: std::collections::HashMap = + stats::all_users(now).into_iter().map(|u| (u.username.clone(), u)).collect(); + + for v in views { + let Some(username) = v.get("username").and_then(Value::as_str).map(str::to_owned) + else { + continue; }; - // 取第一段标签 - let label = match host.iter().position(|&b| b == b'.') { - Some(i) => &host[..i], - None => host, - }; - if label.is_empty() { - return None; + if let Value::Object(ref mut m) = v { + let mut usage_json = json!({ "today": 0, "total": 0, "last_ts": 0, "last_ts_text": "" }); + if let Some(uu) = usage.get(&username) { + usage_json = uu.usage.json(); + } + m.insert( + "domain_count".to_owned(), + json!(counts.get(&username).copied().unwrap_or(0)), + ); + // 今日 LLM 用量:与热路径同一数据源(共享内存)——注意口径是 + // **已转发**的请求,不含被限流/越权拒掉的那些 + m.insert( + "llm_today".to_owned(), + json!(usage.get(&username).map(|x| x.usage.today).unwrap_or(0)), + ); + m.insert("llm_usage".to_owned(), usage_json); } - return Some(label.to_ascii_lowercase()); } } - None -} -/// 把后端地址写进 `r->variables[$proxy_backend_addr]`,供 `proxy_pass` 使用 -fn set_backend_var(r: *mut ngx_http_request_t, backend: &str) { - let idx = BACKEND_VAR_INDEX.load(Ordering::SeqCst); - if idx == usize::MAX { - return; - } - // SAFETY: idx 由 ngx_http_get_variable_index 分配且落在 r->variables 内; - // 值分配在请求池里,随请求回收 - unsafe { - let pool = Pool::from_ngx_pool((*r).pool); - let bytes = backend.as_bytes(); - let data = pool.alloc(bytes.len()) as *mut u8; - if data.is_null() { + /// `/api/v1/me`:我的域名 + 用量摘要 + 策略 TTL + fn decorate_me(&self, username: &str, view: &mut Value) { + let Value::Object(ref mut m) = view else { return; - } - ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len()); - - let vv: *mut ngx_http_variable_value_t = (*r).variables.add(idx); - (*vv).data = data; - (*vv).set_len(bytes.len() as _); - (*vv).set_valid(1); - (*vv).set_not_found(0); - (*vv).set_no_cacheable(1); - } -} - -/// 变量 get_handler:`proxy_pass` 求值 `$proxy_backend_addr` 时被调用。 -/// -/// 与 access 阶段互补——这里保证「即使 access 未赋值也能取到」, -/// access 阶段则负责决定命中不了时返回 404。 -extern "C" fn backend_get( - r: *mut ngx_http_request_t, - v: *mut ngx_http_variable_value_t, - _data: usize, -) -> ngx_int_t { - // SAFETY: nginx 传入的 r/v 必然有效 - unsafe { - let resolved = subdomain_of(r).as_deref().and_then(resolve_backend); - - let Some(backend) = resolved else { - (*v).set_not_found(1); - return Status::NGX_ERROR.into(); }; - - let pool = Pool::from_ngx_pool((*r).pool); - let bytes = backend.as_bytes(); - let data = pool.alloc(bytes.len()) as *mut u8; - if data.is_null() { - (*v).set_not_found(1); - return Status::NGX_ERROR.into(); - } - ptr::copy_nonoverlapping(bytes.as_ptr(), data, bytes.len()); - - (*v).data = data; - (*v).set_len(bytes.len() as _); - (*v).set_valid(1); - (*v).set_no_cacheable(1); - (*v).set_not_found(0); - - Status::NGX_OK.into() + m.insert( + "domains".to_owned(), + json!(plugin_domain::domains::view_all(&plugin_domain::domains::by_owner(username))), + ); + // 用量摘要(明细走 /api/v1/usage)——让客户端一个请求就能决定要不要自我节流 + m.insert("llm_usage".to_owned(), stats::user(username, util::now()).json()); + m.insert( + "policy".to_owned(), + json!({ + "temp_grant_ttl_hours": config::TEMP_GRANT_TTL / 3600, + "temp_domain_ttl_hours": plugin_domain::config::TEMP_DOMAIN_TTL / 3600, + }), + ); } -} -// =========================================================================== -// 阶段处理器 -// =========================================================================== + /// 删除账号:连带回收该账号名下的域名,避免出现无主映射 + fn reclaim_on_delete(&self, username: &str) -> usize { + plugin_domain::domains::remove_by_owner(username) + } -/// 转发热路径:命中则放行(`proxy_pass` 会去取 `$proxy_backend_addr`),未命中直接 404。 -struct ResolveHandler; - -impl HttpRequestHandler for ResolveHandler { - const PHASE: HttpPhase = HttpPhase::Access; - type Output = Status; - - fn handler(request: &mut ngx::http::Request) -> Self::Output { - // 未开启该开关的 location 一律放行(管理台/API 走这里) - if !Module::location_conf(request).map(|c| c.proxy).unwrap_or(false) { - return Status::NGX_DECLINED; - } - - let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t; - - let Some(host) = subdomain_of(r) else { - return HTTPStatus::NOT_FOUND.into(); - }; - - match resolve_backend(&host) { - Some(backend) => { - set_backend_var(r, &backend); - Status::NGX_DECLINED + /// 账号「可用上游」白名单校验:slot 必须真实存在,否则白名单里会存进 + /// 永远匹配不上的死名字,表现为「账号被授权了却一直 403」 + fn validate_slots(&self, slots: &[String]) -> Result<(), String> { + for slot in slots { + if upstreams::get(slot).is_none() { + return Err(format!("上游 {slot} 不存在")); } - // 与旧版语义一致:查不到 = 未配置 / 已过期 / 已删除 / 尚未审核通过 - None => HTTPStatus::NOT_FOUND.into(), } + Ok(()) } } +/// gateway 注入给 `loc::enabled` 的查询实现:把 Switch 翻译到 ModuleConfig。 +/// 未实现的变体(Iap / Domain)**保守返回 false**,绝不误开。 +fn loc_switch(request: &mut Request, s: Switch) -> bool { + let conf = Module::location_conf(request); + match s { + Switch::Api => conf.map(|c| c.api).unwrap_or(false), + Switch::Proxy => conf.map(|c| c.proxy).unwrap_or(false), + Switch::Llm => conf.map(|c| c.llm).unwrap_or(false), + Switch::Apix => conf.map(|c| c.apix).unwrap_or(false), + Switch::Iap | Switch::Domain => false, + } +} + +/// 管理 API 分发:按 PLUGINS 顺序问每个插件,都不认领才统一 404。 +fn dispatch_api(r: *mut ngx_http_request_t) -> Status { + for p in PLUGINS { + if let Some(s) = p.dispatch_api(r) { + return s; + } + } + let method = http::method_str(r); + let uri = http::uri(r); + http::fail( + r, + HTTPStatus::NOT_FOUND, + &format!("接口不存在:{method} {uri}"), + ) +} /// LLM 代理热路径:鉴权 → 校验上游与白名单 → 放行。 /// /// 刻意**只做决策、不搬数据**:真正的转发交给 nginx 的 proxy 模块, @@ -544,7 +531,7 @@ impl HttpRequestHandler for ApiHandler { /// 请求体就绪回调:执行路由分发并终结请求。 unsafe extern "C" fn api_body_ready(r: *mut ngx_http_request_t) { - let status = api::dispatch(r); + let status = dispatch_api(r); // SAFETY: r 由 nginx 传入且仍然有效;NGX_OK 表示响应已完整发出 unsafe { nginx_sys::ngx_http_finalize_request(r, status.0) }; } @@ -649,34 +636,26 @@ impl HttpModule for Module { /// 必须在配置解析前注册变量,否则 `proxy_pass http://$proxy_backend_addr` 无法解析 unsafe extern "C" fn preconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t { - let mut name = ngx_string!("proxy_backend_addr"); + // 契约层:注入 location 开关查询实现(早于任何请求与 phase handler) + loc::set_switch_fn(loc_switch); + // 装配根注册插件扩展:身份端点所需的插件侧数据经它回填内核 + ipass_core::api::set_ext(&GatewayExt); - let idx = unsafe { ngx_http_get_variable_index(cf, &raw mut name) }; - if idx == -1 { - return Status::NGX_ERROR.into(); - } - BACKEND_VAR_INDEX.store(idx as usize, Ordering::SeqCst); - - let var = unsafe { - ngx_http_add_variable( - cf, - &raw mut name, - (NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t, - ) - }; - if var.is_null() { - return Status::NGX_ERROR.into(); - } - - // SAFETY: var 非空且由本函数独占初始化 - unsafe { - (*var).get_handler = Some(backend_get); - (*var).set_handler = None; - (*var).data = 0; + // 各插件注册自己的 nginx 变量($proxy_backend_addr 归 plugin-domain) + for p in PLUGINS { + if !p.preconfig(cf) { + ngx_conf_log_error!( + NGX_LOG_EMERG, + unsafe { &mut *cf }, + "插件 {} 变量注册失败", + p.name() + ); + return Status::NGX_ERROR.into(); + } } // LLM 三件套。名字里的 `llm_` 前缀不要省:nginx 变量名全局唯一, - // 将来接入别的模块时才不会撞名。 + // 将来接入别的模块时才不会撞名。(P3 随 llm 变量迁入 plugin-llm) let mut target = ngx_string!("llm_target"); let mut host = ngx_string!("llm_host"); let mut auth = ngx_string!("llm_auth"); @@ -715,9 +694,14 @@ impl HttpModule for Module { unsafe extern "C" fn postconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t { let cf = unsafe { &mut *cf }; - if ngx::http::add_phase_handler::(cf).is_err() { - return Status::NGX_ERROR.into(); + + // 各插件注册自己的 phase handler(ResolveHandler 归 plugin-domain) + for p in PLUGINS { + if !p.postconfig(cf) { + return Status::NGX_ERROR.into(); + } } + if ngx::http::add_phase_handler::(cf).is_err() { return Status::NGX_ERROR.into(); } @@ -959,7 +943,12 @@ extern "C" fn state_zone_init(zone: *mut ngx_shm_zone_t, _data: *mut c_void) -> return status.into(); } - let loaded = domains::reload_shm(); + // 插件注册「删账号要清什么」:gateway 装配了 stats(用量账本), + // 就要在这里挂上清理钩子——内核自己不认识 ust:/utt: 这些键(P0 起钩子化)。 + // on_delete 内部按函数指针去重,nginx reload 重复走到这里也安全。 + users::on_delete(stats::forget); + + let loaded = plugin_domain::domains::reload_shm(); util::log_notice(&format!("[ipass] 共享内存已装载 {loaded} 条转发映射")); // 账号 Key 与 LLM 上游必须一起进内存:LLM 热路径未命中即 401 / 404, diff --git a/rust/src/llm.rs b/rust/gateway/src/llm.rs similarity index 100% rename from rust/src/llm.rs rename to rust/gateway/src/llm.rs diff --git a/rust/src/llm_audit.rs b/rust/gateway/src/llm_audit.rs similarity index 100% rename from rust/src/llm_audit.rs rename to rust/gateway/src/llm_audit.rs diff --git a/rust/src/llm_usage.rs b/rust/gateway/src/llm_usage.rs similarity index 100% rename from rust/src/llm_usage.rs rename to rust/gateway/src/llm_usage.rs diff --git a/rust/src/stats.rs b/rust/gateway/src/stats.rs similarity index 100% rename from rust/src/stats.rs rename to rust/gateway/src/stats.rs diff --git a/rust/src/upstreams.rs b/rust/gateway/src/upstreams.rs similarity index 100% rename from rust/src/upstreams.rs rename to rust/gateway/src/upstreams.rs diff --git a/rust/src/api.rs b/rust/src/api.rs deleted file mode 100644 index 6bf7f50..0000000 --- a/rust/src/api.rs +++ /dev/null @@ -1,1018 +0,0 @@ -//! API 统一分发器。 -//! -//! 对应旧版 `lua/api.lua`。两类调用方、两套鉴权: -//! -//! ```text -//! /api/v1/* 账号态:请求头 X-API-Key(用户随机 Key) -//! /api/admin/* 管理员态:登录会话 Cookie(除 login 外均需登录且 role=admin) -//! ``` -//! -//! 所有写操作完成后都会同步共享内存(`domains::sync_shm`),做到 -//! 「审核一通过、立刻可访问」——注意新版**没有**回源读文件这条兜底路径, -//! 所以写穿不是优化而是正确性要求。 - -use std::collections::HashMap; - -use ngx::core::{Pool, Status}; -use ngx::ffi::ngx_http_request_t; -use ngx::http::HTTPStatus; -use serde_json::{Value, json}; - -use crate::apix; -use crate::config; -use crate::domains; -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; - -// =========================================================================== -// 路由 -// =========================================================================== - -/// 鉴权后传给处理器的身份 -pub enum Actor { - /// 公开接口,无身份 - None, - /// 账号态(X-API-Key) - User(User), - /// 管理员态(登录会话) - Admin(User), -} - -impl Actor { - /// 操作者名称:审核记录 `reviewed_by`、审计日志都用它 - fn admin_name(&self) -> &str { - match self { - Actor::Admin(u) => &u.username, - Actor::User(u) => &u.username, - Actor::None => "", - } - } -} - -#[derive(Clone, Copy, PartialEq)] -enum Guard { - Public, - User, - Admin, -} - -type Handler = fn(*mut ngx_http_request_t, Actor) -> Status; - -/// 路由表。刻意用精确匹配而非正则——接口路径是固定的, -/// 正则只会引入「写错锚点导致前缀误匹配」的风险。 -fn route(method: &str, uri: &str) -> Option<(Guard, Handler)> { - let entry: (Guard, Handler) = match (method, uri) { - ("POST", "/api/admin/login") => (Guard::Public, h_login), - ("POST", "/api/admin/logout") => (Guard::Admin, h_logout), - ("GET", "/api/admin/session") => (Guard::Admin, h_session), - ("GET", "/api/admin/users") => (Guard::Admin, h_admin_users), - ("POST", "/api/admin/users/create") => (Guard::Admin, h_admin_user_create), - ("POST", "/api/admin/users/key") => (Guard::Admin, h_admin_user_key), - ("POST", "/api/admin/users/grant") => (Guard::Admin, h_admin_user_grant), - ("POST", "/api/admin/users/password") => (Guard::Admin, h_admin_user_password), - ("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), - ("POST", "/api/admin/domains/delete") => (Guard::Admin, h_admin_domain_delete), - ("POST", "/api/admin/purge") => (Guard::Admin, h_admin_purge), - ("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/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), - ("POST", "/api/v1/domains/delete") => (Guard::User, h_my_delete), - _ => return None, - }; - Some(entry) -} - -/// 一次请求的完整处理:路由 → 鉴权 → 执行 -pub fn dispatch(r: *mut ngx_http_request_t) -> Status { - let method = http::method_str(r); - let uri = http::uri(r); - - let Some((guard, handler)) = route(&method, &uri) else { - return http::fail( - r, - HTTPStatus::NOT_FOUND, - &format!("接口不存在:{method} {uri}"), - ); - }; - - let actor = match guard { - Guard::Public => Actor::None, - - Guard::User => { - let key = http::header(r, "x-api-key").unwrap_or_default(); - match users::find_by_key(&key) { - Some(u) => Actor::User(u), - None => { - util::log_warn(&format!( - "[api] API Key 校验失败 client={}", - http::remote_addr(r) - )); - return http::fail( - r, - HTTPStatus::UNAUTHORIZED, - "API Key 无效或缺失,请在请求头携带 X-API-Key", - ); - } - } - } - - Guard::Admin => { - let cookie = http::header(r, "cookie"); - match session::authenticate(cookie.as_deref()).and_then(|name| users::get(&name)) { - Some(u) if u.is_admin() => Actor::Admin(u), - // 会话有效但非管理员:403 而不是 401,便于前端区分 - Some(_) => return http::fail(r, HTTPStatus::FORBIDDEN, "需要管理员权限"), - None => { - return http::fail( - r, - HTTPStatus::UNAUTHORIZED, - "未登录或会话已过期,请重新登录", - ); - } - } - } - }; - - handler(r, actor) -} - -// =========================================================================== -// 管理员:登录 / 会话 -// =========================================================================== - -fn h_login(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - let ip = http::remote_addr(r); - let now = util::now(); - - if state::get_login_fail(&ip, now) >= config::LOGIN_MAX_FAIL { - return http::fail(r, HTTPStatus::TOO_MANY_REQUESTS, "登录失败次数过多,请 5 分钟后再试"); - } - - let p = http::params(r); - let username = p.get("username").map(|s| util::trim(s).to_owned()).unwrap_or_default(); - let password = p.get("password").cloned().unwrap_or_default(); - - if username.is_empty() || password.is_empty() { - return http::fail(r, HTTPStatus::BAD_REQUEST, "请输入账号和密码"); - } - - let Some(user) = users::get(&username) else { - state::bump_login_fail(&ip, now); - util::log_warn(&format!("[api] 登录失败 user={username} client={ip}")); - return http::fail(r, HTTPStatus::UNAUTHORIZED, "账号或密码错误"); - }; - - if !util::verify_password(&password, &user.salt, &user.pwd_hash) { - state::bump_login_fail(&ip, now); - util::log_warn(&format!("[api] 登录失败 user={username} client={ip}")); - return http::fail(r, HTTPStatus::UNAUTHORIZED, "账号或密码错误"); - } - - if !user.is_admin() { - return http::fail(r, HTTPStatus::FORBIDDEN, "该账号不是管理员,无法登录管理台"); - } - - state::clear_login_fail(&ip); - let token = session::create(&username); - let cookie = session::set_cookie(&token); - util::log_notice(&format!("[api] 管理员登录 user={username} client={ip}")); - - http::ok_with(r, users::view(&user), "登录成功", &[("Set-Cookie", &cookie)]) -} - -fn h_logout(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - let cookie = http::header(r, "cookie"); - session::destroy(cookie.as_deref()); - let cleared = session::clear_cookie(); - http::ok_with(r, json!({}), "已退出登录", &[("Set-Cookie", &cleared)]) -} - -fn h_session(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::Admin(user) = actor else { - return http::fail(r, HTTPStatus::UNAUTHORIZED, "未登录或会话已过期,请重新登录"); - }; - http::ok(r, users::view(&user), "ok") -} - -// =========================================================================== -// 管理员:账号管理 -// =========================================================================== - -fn h_admin_users(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - let mut counts: HashMap = HashMap::new(); - for d in domains::all() { - *counts.entry(d.owner).or_insert(0) += 1; - } - - let now = util::now(); - // 一次扫表拿到所有人的 LLM 用量(含各自的上游明细),避免逐账号查共享内存 - let usage: HashMap = - stats::all_users(now).into_iter().map(|u| (u.username.clone(), u)).collect(); - - let items: Vec = 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 用量:与热路径同一数据源(共享内存)——注意口径是 - // **已转发**的请求,不含被限流/越权拒掉的那些 - m.insert( - "llm_today".to_owned(), - json!(usage.get(&u.username).map(|x| x.usage.today).unwrap_or(0)), - ); - m.insert("llm_usage".to_owned(), usage_json); - } - v - }) - .collect(); - - http::ok(r, json!({ "items": items }), "ok") -} - -fn h_admin_user_create(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - let p = http::params(r); - let grant_temp = util::to_bool(p.get("grant_temp")); - - 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] 创建账号 {} name={} role={} temp_grant={grant_temp}", - user.username, user.display_name, user.role - )); - http::ok(r, users::view(&user), "账号创建成功") - } - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -/// 设置展示名(中文姓名等)。传空串 = 清空,前端回落到账号名。 -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(); - - match users::regenerate_key(&username) { - Ok(key) => http::ok(r, json!({ "username": username, "api_key": key }), "已重置 API Key"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_user_grant(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(); - - if util::to_bool(p.get("revoke")) { - if let Err(e) = users::revoke_temp(&username) { - return http::fail(r, HTTPStatus::BAD_REQUEST, &e); - } - let view = users::get(&username).map(|u| users::view(&u)).unwrap_or(Value::Null); - return http::ok(r, view, "已取消临时授权权限"); - } - - match users::grant_temp(&username, p.get("hours")) { - Ok(_) => { - let view = users::get(&username).map(|u| users::view(&u)).unwrap_or(Value::Null); - http::ok(r, view, "已授予临时授权权限") - } - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_user_password(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(); - let password = p.get("password").map(String::as_str).unwrap_or(""); - - match users::set_password(&username, password) { - Ok(()) => http::ok(r, json!({}), "密码已重置"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_user_delete(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(); - - if let Err(e) = users::delete(&username, actor.admin_name()) { - return http::fail(r, HTTPStatus::BAD_REQUEST, &e); - } - - // 连带回收该账号名下的域名,避免出现无主映射 - let removed = domains::remove_by_owner(&username); - util::log_notice(&format!("[api] 删除账号 {username},连带域名 {removed} 条")); - http::ok(r, json!({ "removed_domains": removed }), "账号已删除") -} - -// =========================================================================== -// 管理员:域名审核 -// =========================================================================== - -fn h_admin_domains(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - http::ok( - r, - json!({ - "items": domains::view_all(&domains::all()), - "pending": domains::count_pending(), - // 子域名命名规则:前端据此渲染「i + 8位数字 + dm」输入框, - // 避免前后端各写一份前缀/后缀/zone 而漂移(真源 = config.rs) - "subdomain_rule": { - "zone": config::ENTERPRISE_ZONE, - "prefix": config::SUBDOMAIN_PREFIX, - "suffix": config::SUBDOMAIN_SUFFIX, - "digits": config::SUBDOMAIN_RAND_DIGITS, - }, - }), - "ok", - ) -} - -fn h_admin_domain_review(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let p = http::params(r); - let id = p.get("id").map(String::as_str).unwrap_or(""); - let action = p.get("action").map(String::as_str).unwrap_or(""); - match domains::review(id, action, actor.admin_name()) { - Ok(entry) => { - let msg = if action == "approve" { "已通过审核" } else { "已驳回" }; - http::ok(r, domains::view(&entry), msg) - } - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_domain_create(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let p = http::params(r); - - // subdomain 缺省(或空串)= 由网关按规则自动生成 `i<8位随机数字>dm`, - // 与面板上「i + 8位随机数 + dm」是同一套规则(见 domains::gen_subdomain)。 - match domains::create_by_admin( - p.get("subdomain").map(String::as_str).unwrap_or(""), - p.get("backend").map(String::as_str).unwrap_or(""), - p.get("type"), - p.get("owner"), - actor.admin_name(), - ) { - Ok(entry) => http::ok(r, domains::view(&entry), "已创建并直接放行"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_domain_delete(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - let p = http::params(r); - let id = p.get("id").map(String::as_str).unwrap_or(""); - - match domains::remove(id) { - Ok(sub) => http::ok(r, json!({ "subdomain": sub }), "已删除"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -fn h_admin_purge(r: *mut ngx_http_request_t, _actor: Actor) -> Status { - match domains::purge() { - Ok(removed) => http::ok( - r, - json!({ "removed": removed }), - &format!("已清理 {removed} 条过期/陈旧记录"), - ), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -// =========================================================================== -// 账号态 API -// =========================================================================== - -fn h_me(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::User(user) = actor else { - return http::fail(r, HTTPStatus::UNAUTHORIZED, "API Key 无效或缺失,请在请求头携带 X-API-Key"); - }; - - let mut v = users::view(&user); - if let Value::Object(ref mut m) = v { - m.insert( - "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!({ - "temp_grant_ttl_hours": config::TEMP_GRANT_TTL / 3600, - "temp_domain_ttl_hours": config::TEMP_DOMAIN_TTL / 3600, - }), - ); - } - http::ok(r, v, "ok") -} - -fn h_my_domains(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::User(user) = actor else { - return http::fail(r, HTTPStatus::UNAUTHORIZED, "API Key 无效或缺失,请在请求头携带 X-API-Key"); - }; - http::ok( - r, - json!({ "items": domains::view_all(&domains::by_owner(&user.username)) }), - "ok", - ) -} - -fn h_apply(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::User(user) = actor else { - return http::fail(r, HTTPStatus::UNAUTHORIZED, "API Key 无效或缺失,请在请求头携带 X-API-Key"); - }; - - let p = http::params(r); - let entry = match domains::apply( - &user.username, - p.get("subdomain").map(String::as_str).unwrap_or(""), - p.get("backend").map(String::as_str).unwrap_or(""), - p.get("type"), - ) { - Ok(e) => e, - Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), - }; - - let view = domains::view(&entry); - util::log_notice(&format!( - "[api] {} 申请 {} type={} status={}", - user.username, - entry.subdomain, - entry.dtype, - entry.effective_status(util::now()) - )); - - let msg = if entry.status == "approved" { - format!( - "已直接放行(临时授权权限生效),{} 小时后自动失效", - config::TEMP_DOMAIN_TTL / 3600 - ) - } else { - "已提交申请,等待管理员审核".to_owned() - }; - http::ok(r, view, &msg) -} - -fn h_my_delete(r: *mut ngx_http_request_t, actor: Actor) -> Status { - let Actor::User(user) = actor else { - return http::fail(r, HTTPStatus::UNAUTHORIZED, "API Key 无效或缺失,请在请求头携带 X-API-Key"); - }; - - let p = http::params(r); - let id = p.get("id").map(String::as_str).unwrap_or(""); - - match domains::remove_own(id, &user.username) { - Ok(sub) => http::ok(r, json!({ "subdomain": sub }), "已删除"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -// =========================================================================== -// 管理员: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 { - 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//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::().ok()) - .unwrap_or_else(stats::trend_default_days); - - let usernames: Vec = users::all().into_iter().map(|u| u.username).collect(); - // API 代理与 LLM 上游共用同一片用量键空间,只是 slot 带 `api/` 前缀 - // (见 `config::APIX_STATS_PREFIX`)——这里一起列出,趋势图才会出现它们 - let slots: Vec = 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::(v) { - arr.into_iter() - .filter_map(|x| x.as_str().map(str::to_owned)) - .collect::>() - } else { - v.split(',').map(str::to_owned).collect::>() - }) - }); - - // 不带 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/`, -/// 复用 `$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 = 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") -} - -/// 设置某账号可用的 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(); - - let slots: Vec = p - .get("models") - .map(|s| { - s.split(',') - .map(|x| x.trim().to_owned()) - .filter(|x| !x.is_empty()) - .collect() - }) - .unwrap_or_default(); - - // 上游必须先存在:否则白名单里会存进永远匹配不上的死名字, - // 表现为「账号被授权了却一直 403」,排查起来很绕 - for slot in &slots { - if upstreams::get(slot).is_none() { - return http::fail(r, HTTPStatus::BAD_REQUEST, &format!("上游 {slot} 不存在")); - } - } - - match users::set_allowed_models(&username, slots) { - Ok(u) => http::ok(r, users::view(&u), "已更新可用上游"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -/// 设置账号的 LLM 限流参数。字段缺省 = 保持现值,`0` = 不限。 -fn h_admin_user_limits(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(); - - let parse_limit = |key: &str| -> Result, String> { - match p.get(key) { - None => Ok(None), - Some(v) if util::trim(v).is_empty() => Ok(None), - Some(v) => util::trim(v) - .parse::() - .map(Some) - .map_err(|_| format!("{key} 必须是非负整数(0 表示不限)")), - } - }; - - let rpm = match parse_limit("rpm") { - Ok(v) => v, - Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), - }; - let daily = match parse_limit("daily") { - Ok(v) => v, - Err(e) => return http::fail(r, HTTPStatus::BAD_REQUEST, &e), - }; - if rpm.is_none() && daily.is_none() { - return http::fail(r, HTTPStatus::BAD_REQUEST, "至少提供 rpm 或 daily 之一"); - } - - util::log_notice(&format!( - "[api] 设置账号 {username} LLM 限流 rpm={rpm:?} daily={daily:?}" - )); - match users::set_llm_limits(&username, rpm, daily) { - Ok(u) => http::ok(r, users::view(&u), "已更新限流参数"), - Err(e) => http::fail(r, HTTPStatus::BAD_REQUEST, &e), - } -} - -/// 账号态接口的公共前置:取账号身份,取不到就回 401。 -fn user_or_401(r: *mut ngx_http_request_t, actor: Actor) -> Result { - 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 { - // 回显的 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 = 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 = 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::>(), - }), - "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 = 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", - ) -}