//! iPass 山海关(ipass-gateway)—— nginx + Rust 动态模块(v2) //! //! 尚数网 统一网关(动态域名 / LLM API 路由及未来各类统一出口能力)。 //! 本模块承担原 OpenResty + Lua 版的**全部**职责: //! //! | 旧版(Lua) | 新版(Rust) | //! |------------------------------------|-------------------------| //! | `lua_shared_dict proxy_cache` | `state` 共享内存映射表 | //! | `lua_shared_dict admin_sessions` | `state` 会话键 | //! | `lua_shared_dict lua_locks` | `state` 文件写锁 | //! | `store.lua`(cjson + resty.lock) | `store` + serde_json | //! | `users.lua` / `domains.lua` | `users` / `domains` | //! | `api.lua` 路由表 | `api` 精确匹配路由表 | //! | `proxy.lua` 转发热路径 | `ResolveHandler` | //! | —(新增能力) | `LlmHandler` LLM 代理 | //! //! ## 三条热路径 //! //! | 入口 | 阶段 | 开关 | 做什么 | //! | --- | --- | --- | --- | //! | `*.yourdomain.com/*` | access | `ipass_proxy` | 查 `sub:` 决定后端 | //! | `llm.yourdomain.com//*` | access | `ipass_llm` | 查 `ukey:` 鉴权 + `up:` 定上游 | //! | `llm.yourdomain.com/apix/` | access | `ipass_apix` | 同上鉴权,查 `ax:` 定供应商资产 | //! | `proxy-api.yourdomain.com/api/*` | content | `ipass_api` | 管理接口,读体后分发 | //! //! ## 关键实现约束(均为实测/查证确认,详见 CLAUDE.md) //! //! * `ngx_http_add_variable` 必须在 **preconfiguration** 阶段调用, //! 否则配置里的 `proxy_pass http://$proxy_backend_addr` 无法解析。 //! * 阶段处理器在 postconfiguration 阶段注册,且**必须按 location 开关** //! (`ipass_proxy` / `ipass_api` / `ipass_llm`),否则管理台与 API //! 也会被转发逻辑 404 掉。 //! * 共享内存只有 `RwLock, _>` 一种安全形态; //! `SlabPool` 只能在 zone 初始化回调里取出,锁本身也必须用 //! `ngx::allocator::allocate` 放进共享内存,否则各 worker 拿到的是各自的副本。 //! * ngx crate **没有**暴露请求体读取,必须走 //! `ngx_http_read_client_request_body` 的两段式异步接口(见 `ApiHandler`)。 //! **这也是 LLM 代理不按 body 里的 `model` 字段路由的原因**——access 阶段 //! 根本拿不到请求体。 mod api; mod apix; mod llm; mod llm_audit; mod llm_usage; mod stats; mod upstreams; // 内核模块桥接:业务文件里的 `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, Ordering}; 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_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, Request, }; use ngx::{ngx_conf_log_error, ngx_string}; use ipass_core::loc::{self, Switch}; use ipass_core::plugin::Plugin; // =========================================================================== // 插件装配(PLUGINS 顺序 = 认领顺序;身份类端点将来必须排最前) // =========================================================================== /// 过渡期路由插件: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) } } /// 插件注册表。**身份类端点(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; }; 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); } } } /// `/api/v1/me`:我的域名 + 用量摘要 + 策略 TTL fn decorate_me(&self, username: &str, view: &mut Value) { let Value::Object(ref mut m) = view else { return; }; 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) } /// 账号「可用上游」白名单校验:slot 必须真实存在,否则白名单里会存进 /// 永远匹配不上的死名字,表现为「账号被授权了却一直 403」 fn validate_slots(&self, slots: &[String]) -> Result<(), String> { for slot in slots { if upstreams::get(slot).is_none() { return Err(format!("上游 {slot} 不存在")); } } 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 模块, /// 于是 SSE 流式、`proxy_buffering`、上游超时全部是 nginx 原生行为, /// 不需要自己实现 upstream——那正是「按 body 里的 model 路由」代价高昂之处。 /// /// 变量(`$llm_target` / `$llm_host` / `$llm_auth`)不在这里赋值, /// 而由 `llm::var_get` 在 `proxy_pass` 求值时计算,与 `$proxy_backend_addr` 同构。 struct LlmHandler; impl HttpRequestHandler for LlmHandler { const PHASE: HttpPhase = HttpPhase::Access; type Output = Status; fn handler(request: &mut ngx::http::Request) -> Self::Output { if !Module::location_conf(request).map(|c| c.llm).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(slot) = llm::slot_of(r) else { return llm::fail( r, HTTPStatus::BAD_REQUEST, "invalid_request_error", "路径缺少上游段,正确形式:/<上游名>/v1/chat/completions", ); }; let Some(key) = llm::downstream_key(r) else { return llm::fail( r, HTTPStatus::UNAUTHORIZED, "invalid_api_key", "缺少 API Key,请在 Authorization: Bearer 或 x-api-key 中携带", ); }; // 只碰共享内存:这里若改成 users::find_by_key 会每请求读一次 users.json let Some((username, allowed, rpm, daily)) = llm::identity(&key) else { util::log_warn(&format!( "[llm] API Key 校验失败 slot={slot} client={}", http::remote_addr(r) )); return llm::fail( r, HTTPStatus::UNAUTHORIZED, "invalid_api_key", "API Key 无效或已失效", ); }; // 「列出可用模型」是网关自己的元信息接口(OpenAI 兼容形状), // 在查上游之前就地应答——否则 `/v1/models` 会被当成 slot=v1 → 404。 if llm::is_models_probe(r) { return llm::respond_models(r, &allowed); } if state::get_upstream(&slot).is_none() { return llm::fail( r, HTTPStatus::NOT_FOUND, "model_not_found", &format!("上游 {slot} 不存在或已停用"), ); } // 空白名单 = 不限(老账号没有该字段时的语义) if !allowed.is_empty() && !allowed.iter().any(|s| s == &slot) { util::log_warn(&format!("[llm] {username} 无权访问上游 {slot}")); return llm::fail( r, HTTPStatus::FORBIDDEN, "permission_denied", &format!("当前账号无权访问上游 {slot}"), ); } // 限流与每日配额(先增后判,纯共享内存)。放在最后: // 鉴权/白名单都没过的请求不该消耗对方的计数 // SAFETY: r 由 nginx 传入且有效 if let Some(resp) = unsafe { llm::check_quota(r, &username, rpm, daily) } { return resp; } // 用量统计:走到这里说明请求**真的会被转发**,才计入。 // 被拒的请求(401/403/404/429)不进统计——那是给人看的数字, // 把拒绝也算进"用量"只会误导(与配额计数 st: 的语义刻意不同)。 stats::record(&username, &slot, util::now()); Status::NGX_DECLINED } } /// API 代理热路径(`/apix/?<参数>`):鉴权 → 查代理 → 放行。 /// /// 与 `LlmHandler` 是同一套下行契约(同一把 `sk_` Key、同一份限流配额), /// 差别只在查哪张表、以及**请求体由网关拼**(`apix::build_body`)—— /// 资产选择权必须留在服务端,否则客户端能自己挑最贵的模型刷。 struct ApiProxyHandler; impl HttpRequestHandler for ApiProxyHandler { const PHASE: HttpPhase = HttpPhase::Access; type Output = Status; fn handler(request: &mut ngx::http::Request) -> Self::Output { if !Module::location_conf(request).map(|c| c.apix).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(slug) = apix::slug_of(r) else { return http::fail( r, HTTPStatus::BAD_REQUEST, "路径缺少代理名,正确形式:/apix/<代理名>?<参数>", ); }; let Some(key) = llm::downstream_key(r) else { return http::fail( r, HTTPStatus::UNAUTHORIZED, "缺少 API Key,请在 Authorization: Bearer 或 x-api-key 中携带", ); }; let Some((username, _allowed, rpm, daily)) = llm::identity(&key) else { util::log_warn(&format!( "[apix] API Key 校验失败 slug={slug} client={}", http::remote_addr(r) )); return http::fail(r, HTTPStatus::UNAUTHORIZED, "API Key 无效或已失效"); }; // 代理的**可见性**由管理员的启用/停用决定,不再叠一层账号白名单: // 白名单是给「一家厂商一个 slot」设计的,这里再套一层会让 // 「管理员明明启用了、某账号却 403」变得难以解释。 let Some((_base, supplier_key, _asset)) = apix::lookup(&slug) else { return http::fail( r, HTTPStatus::NOT_FOUND, &format!("代理 {slug} 不存在或已停用"), ); }; if supplier_key.is_empty() { util::log_err(&format!( "[apix] 供应商 Key 未配置,slug={slug} 无法转发 —— 请到管理台「API 代理」填写" )); return http::fail( r, HTTPStatus::SERVICE_UNAVAILABLE, "供应商 API Key 未配置,请联系管理员", ); } // SAFETY: r 由 nginx 传入且有效 if let Some(resp) = unsafe { llm::check_quota(r, &username, rpm, daily) } { return resp; } // 用量统计。slot 带 `api/` 前缀,与 LLM 上游在同一片键空间里天然分组 stats::record( &username, &format!("{}{}", config::APIX_STATS_PREFIX, slug), util::now(), ); Status::NGX_DECLINED } } /// `$upstream_status` 的变量索引,postconfiguration 时解析一次(log 阶段复用)。 static UPSTREAM_STATUS_IDX: AtomicIsize = AtomicIsize::new(-1); /// LLM 上游健康标记(log 阶段):把上游**真实**状态码写进 `uh:` 缓存。 /// /// 为什么在 log 阶段:转发决策在 access、响应在 proxy 模块手里,只有 log /// 阶段能同时拿到「slot 是谁」和「上游实际回了什么」。这相当于让**真实流量 /// 自己当探针**——不需要额外的常驻探测进程(项目红线),健康状态也最真实。 /// 管理台「测试」按钮的探测请求走同一条 `proxy_pass` 链路,天然共用本逻辑。 /// /// 写下的缓存**只用于展示**(列表标红 / 模型发现附状态),转发路径不读它, /// 误标不影响任何请求的结果。 /// /// ⚠️ 状态码从 `$upstream_status` 变量读,**不能读 `r->upstream`**—— /// `ngx_http_upstream_finalize_request` 在日志阶段之前就把 `r->upstream` /// 置空了(实测踩过:代码编译通过、跑起来状态永远是 unknown)。 /// access log 模块同款手法:变量在 finalize 时快照,log 阶段仍有效。 struct LlmHealthHandler; impl HttpRequestHandler for LlmHealthHandler { const PHASE: HttpPhase = HttpPhase::Log; type Output = Status; fn handler(request: &mut ngx::http::Request) -> Self::Output { let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t; // 两类请求要标记: // ① LLM server 的真实转发流量(location_conf.llm == true); // ② 管理台探测流量——内部重定向到管理 server 的 /_upstream_test location, // 那里**没有** ipass_llm 指令(有就会重跑 access 鉴权,探测请求只有 // 登录会话没有 API Key),所以只能按 URI 前缀认。 let uri = crate::http::uri(r); let is_llm = Module::location_conf(request).map(|c| c.llm).unwrap_or(false); let is_probe = uri.starts_with("/_upstream_test"); if !is_llm && !is_probe { return Status::NGX_DECLINED; } // SAFETY: r 有效;索引在 postconfiguration 已解析(见 postconfiguration) let code = unsafe { let idx = UPSTREAM_STATUS_IDX.load(Ordering::Relaxed); if idx < 0 { 0 } else { let v = ngx_http_get_indexed_variable(r, idx as ngx_uint_t); if (*v).not_found() != 0 || (*v).data.is_null() { 0 } else { let s = core::str::from_utf8(core::slice::from_raw_parts( (*v).data, (*v).len() as usize, )) .unwrap_or(""); // 内部重定向会有多段(如 "502, 200"),取**最后一段** = 最近一次上游尝试 s.rsplit(',').next().unwrap_or("").trim().parse().unwrap_or(0) } } }; // 没有 upstream(本地应答如 /v1/models)或没拿到状态码(客户端中途 // 断连等)→ 无从判断,不写缓存,留给下一次真实转发 if code == 0 { return Status::NGX_DECLINED; } if let Some(slot) = llm::slot_of(r) { // 上游回了头 = 它活着:2xx~4xx 都算正常(4xx 是它对我们请求的意见, // 不是机器死了);5xx / 连接失败(502) / 等头超时(504) 才算失效 upstreams::mark_health(&slot, (200..500).contains(&code), code); } Status::NGX_DECLINED } } /// LLM 对话审计(log 阶段):把被转发请求的 body 临时文件复制进审计目录。 /// /// 捕获机制与清理策略见 `llm_audit` 模块注释与 docs/llm/AUDIT_LOG.md。 /// 关键点:只依赖 `client_body_in_file_only clean` 留下的临时文件,本阶段 /// **不读请求体、不碰内存缓冲**——热路径与 SSE 透传完全无感知。 struct AuditHandler; impl HttpRequestHandler for AuditHandler { const PHASE: HttpPhase = HttpPhase::Log; type Output = Status; fn handler(request: &mut ngx::http::Request) -> Self::Output { if !Module::location_conf(request).map(|c| c.llm).unwrap_or(false) { return Status::NGX_DECLINED; } let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t; // 身份在 log 阶段重新解析:ukey shm 查询是纯内存读,代价可忽略; // 换取 access→log 之间不挂任何请求级状态(无 ctx、无生命周期问题)。 // 请求已被转发过(有临时文件)才查得到 Key——被拒请求天然不入档。 let user = llm::downstream_key(r) .and_then(|k| llm::identity(&k)) .map(|(u, _, _, _)| u); let slot = llm::slot_of(r).unwrap_or_default(); // token 计量:body filter 旁路抓到的 usage(见 llm_usage 模块注释) let (tin, tout) = llm_usage::take(r); if tin > 0 || tout > 0 { if let Some(name) = user.as_deref() { stats::add_tokens(name, &slot, tin, tout, util::now()); } } // SAFETY: 同上;capture 内部任何失败只记日志,绝不 panic unsafe { llm_audit::capture(r, user.as_deref().unwrap_or("-"), &slot, tin, tout) }; Status::NGX_DECLINED } } /// 管理 API:content 阶段先读请求体,读完后交给 `api::dispatch`。 /// /// 这是本项目唯一需要异步的地方。`ngx_http_read_client_request_body` 是 /// **两段式**接口:请求体已在缓冲区时会**同步**调用 post_handler, /// 否则挂起等 socket 事件后回调。两条路径都必须正确,所以不能假设 /// 「回调一定晚于本次返回」。 struct ApiHandler; impl HttpRequestHandler for ApiHandler { const PHASE: HttpPhase = HttpPhase::Content; type Output = Status; fn handler(request: &mut ngx::http::Request) -> Self::Output { if !Module::location_conf(request).map(|c| c.api).unwrap_or(false) { return Status::NGX_DECLINED; } let r: *mut ngx_http_request_t = request.as_mut() as *mut ngx_http_request_t; // SAFETY: r 有效;回调只会在请求内存池存活期间被调用 let rc = unsafe { nginx_sys::ngx_http_read_client_request_body(r, Some(api_body_ready)) }; // 读体失败(请求体超限等):把原始状态码交回 nginx,由它生成对应错误页 if rc >= nginx_sys::NGX_HTTP_SPECIAL_RESPONSE as ngx_int_t { return Status(rc); } // 响应由回调发出,本阶段到此挂起 Status::NGX_DONE } } /// 请求体就绪回调:执行路由分发并终结请求。 unsafe extern "C" fn api_body_ready(r: *mut ngx_http_request_t) { let status = dispatch_api(r); // SAFETY: r 由 nginx 传入且仍然有效;NGX_OK 表示响应已完整发出 unsafe { nginx_sys::ngx_http_finalize_request(r, status.0) }; } // =========================================================================== // 模块定义 // =========================================================================== struct Module; /// 按 location 生效的开关。 /// /// 必须存在:阶段处理器注册在 http 主配置上,若不按 location 收敛, /// 管理台与 API 也会走转发逻辑并被 404。 #[derive(Debug, Default)] struct ModuleConfig { /// 该 location 走「子域名 → 后端」转发 proxy: bool, /// 该 location 暴露管理 API(/api/admin/*、/api/v1/*) api: bool, /// 该 location 走 LLM 代理(`//...` → 上游) llm: bool, /// 该 location 走 API 代理(`/apix/` → 外部供应商) apix: bool, } unsafe impl HttpModuleLocationConf for Module { type LocationConf = ModuleConfig; } impl Merge for ModuleConfig { fn merge(&mut self, prev: &ModuleConfig) -> Result<(), MergeConfigError> { if prev.proxy { self.proxy = true; } if prev.api { self.api = true; } if prev.llm { self.llm = true; } if prev.apix { self.apix = true; } Ok(()) } } /// 注册一个只读变量,值由 `llm::var_get` 按 `slot` 分派计算。 /// /// 与 `$proxy_backend_addr` 不同,LLM 三件套**不需要** /// `ngx_http_get_variable_index`——它们是纯只读的,模块从不主动写, /// 只有 `proxy_pass` / `proxy_set_header` 求值时触发 get_handler。 unsafe fn add_llm_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> bool { // SAFETY: cf 由 nginx 传入;name 指向本函数调用方栈上的 ngx_str_t,注册时被拷贝 let var = unsafe { ngx_http_add_variable( cf, name, (NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t, ) }; if var.is_null() { return false; } // SAFETY: var 非空且由本函数独占初始化;data 承载分派标记 unsafe { (*var).get_handler = Some(llm::var_get); (*var).set_handler = None; (*var).data = slot; } true } /// 同 [`add_llm_var`],注册一个由 `apix::var_get` 计算的只读变量 unsafe fn add_apix_var(cf: *mut ngx_conf_t, name: *mut ngx_str_t, slot: usize) -> bool { // SAFETY: cf 由 nginx 传入;name 指向本函数调用方栈上的 ngx_str_t,注册时被拷贝 let var = unsafe { ngx_http_add_variable( cf, name, (NGX_HTTP_VAR_CHANGEABLE | NGX_HTTP_VAR_NOCACHEABLE) as ngx_uint_t, ) }; if var.is_null() { return false; } // SAFETY: var 非空且由本函数独占初始化;data 承载分派标记 unsafe { (*var).get_handler = Some(apix::var_get); (*var).set_handler = None; (*var).data = slot; } true } impl HttpModule for Module { fn module() -> &'static ngx_module_t { // SAFETY: 模块定义是静态的,生命周期贯穿进程 unsafe { &*ptr::addr_of!(ngx_http_ipass_module) } } /// 必须在配置解析前注册变量,否则 `proxy_pass http://$proxy_backend_addr` 无法解析 unsafe extern "C" fn preconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t { // 契约层:注入 location 开关查询实现(早于任何请求与 phase handler) loc::set_switch_fn(loc_switch); // 装配根注册插件扩展:身份端点所需的插件侧数据经它回填内核 ipass_core::api::set_ext(&GatewayExt); // 各插件注册自己的 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"); let llm_ok = unsafe { add_llm_var(cf, &raw mut target, llm::VAR_TARGET) && add_llm_var(cf, &raw mut host, llm::VAR_HOST) && add_llm_var(cf, &raw mut auth, llm::VAR_AUTH) }; if !llm_ok { ngx_conf_log_error!(NGX_LOG_EMERG, unsafe { &mut *cf }, "注册 LLM 变量失败"); return Status::NGX_ERROR.into(); } // API 代理六件套。前缀 `apix_` 与 `llm_` 同理:nginx 变量名全局唯一。 let mut ax_target = ngx_string!("apix_target"); let mut ax_host = ngx_string!("apix_host"); let mut ax_key = ngx_string!("apix_key"); let mut ax_body = ngx_string!("apix_body"); let mut ax_ptarget = ngx_string!("apix_probe_target"); let mut ax_pbody = ngx_string!("apix_probe_body"); let apix_ok = unsafe { add_apix_var(cf, &raw mut ax_target, apix::VAR_TARGET) && add_apix_var(cf, &raw mut ax_host, apix::VAR_HOST) && add_apix_var(cf, &raw mut ax_key, apix::VAR_KEY) && add_apix_var(cf, &raw mut ax_body, apix::VAR_BODY) && add_apix_var(cf, &raw mut ax_ptarget, apix::VAR_PROBE_TARGET) && add_apix_var(cf, &raw mut ax_pbody, apix::VAR_PROBE_BODY) }; if !apix_ok { ngx_conf_log_error!(NGX_LOG_EMERG, unsafe { &mut *cf }, "注册 API 代理变量失败"); return Status::NGX_ERROR.into(); } Status::NGX_OK.into() } unsafe extern "C" fn postconfiguration(cf: *mut ngx_conf_t) -> ngx_int_t { let cf = unsafe { &mut *cf }; // 各插件注册自己的 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(); } if ngx::http::add_phase_handler::(cf).is_err() { return Status::NGX_ERROR.into(); } if ngx::http::add_phase_handler::(cf).is_err() { return Status::NGX_ERROR.into(); } if ngx::http::add_phase_handler::(cf).is_err() { return Status::NGX_ERROR.into(); } // token 计量:插进 body filter 链头,旁路扫描上游响应的 usage llm_usage::install(); if ngx::http::add_phase_handler::(cf).is_err() { return Status::NGX_ERROR.into(); } // 预取 `$upstream_status` 索引(upstream 模块 preconfiguration 已注册该内建变量) let mut name = ngx_str_t { len: "upstream_status".len() as usize, data: b"upstream_status\0".as_ptr() as *mut u8, }; let idx = ngx_http_get_variable_index(cf, &mut name); if idx == -1 { return Status::NGX_ERROR.into(); } UPSTREAM_STATUS_IDX.store(idx as isize, Ordering::Relaxed); Status::NGX_OK.into() } } static mut NGX_HTTP_IPASS_COMMANDS: [ngx_command_t; 8] = [ ngx_command_t { name: ngx_string!("ipass_state"), type_: (NGX_HTTP_MAIN_CONF | NGX_CONF_TAKE2) as ngx_uint_t, set: Some(set_state_zone), conf: NGX_HTTP_MAIN_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_data_dir"), type_: (NGX_HTTP_MAIN_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_data_dir), conf: NGX_HTTP_MAIN_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_audit_dir"), type_: (NGX_HTTP_MAIN_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_audit_dir), conf: NGX_HTTP_MAIN_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_proxy"), type_: (NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_flag_proxy), conf: NGX_HTTP_LOC_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_api"), type_: (NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_flag_api), conf: NGX_HTTP_LOC_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_llm"), type_: (NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_flag_llm), conf: NGX_HTTP_LOC_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t { name: ngx_string!("ipass_apix"), type_: (NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1) as ngx_uint_t, set: Some(set_flag_apix), conf: NGX_HTTP_LOC_CONF_OFFSET, offset: 0, post: ptr::null_mut(), }, ngx_command_t::empty(), ]; static NGX_HTTP_IPASS_MODULE_CTX: ngx_http_module_t = ngx_http_module_t { preconfiguration: Some(Module::preconfiguration), postconfiguration: Some(Module::postconfiguration), create_main_conf: None, init_main_conf: None, create_srv_conf: None, merge_srv_conf: None, create_loc_conf: Some(Module::create_loc_conf), merge_loc_conf: Some(Module::merge_loc_conf), }; // 脱离 nginx 构建系统、单独产出 cdylib 时必须靠这个宏导出 ngx_modules 表 #[cfg(feature = "export-modules")] ngx::ngx_modules!(ngx_http_ipass_module); #[used] #[allow(non_upper_case_globals)] pub static mut ngx_http_ipass_module: ngx_module_t = ngx_module_t { ctx: &raw const NGX_HTTP_IPASS_MODULE_CTX as _, commands: unsafe { &raw mut NGX_HTTP_IPASS_COMMANDS[0] }, type_: NGX_HTTP_MODULE as _, init_process: Some(init_process), ..ngx_module_t::default() }; /// 每个 worker 启动后执行一次。管理员播种是**幂等**的: /// 文件里已有任何账号就直接跳过,所以多 worker 同时跑不会重复创建。 unsafe extern "C" fn init_process(_cycle: *mut ngx_cycle_t) -> ngx_int_t { match users::seed_admin() { Ok(true) => util::log_warn( "[ipass] 已创建初始管理员 admin,请首次登录后立即修改密码", ), Ok(false) => {} Err(e) => util::log_err(&format!("[ipass] 初始化管理员失败: {e}")), } // 对话审计:确保目录存在 + 容量巡检一次(此后由请求写入节流触发) llm_audit::startup(); Status::NGX_OK.into() } // =========================================================================== // 指令处理 // =========================================================================== /// 读第 2 个参数并转成 bool(on/off/1/0/yes/no)。 unsafe fn arg_flag(cf: *mut ngx_conf_t, idx: usize) -> Option { let cf_ref = unsafe { cf.as_mut() }?; let args: &mut [ngx_str_t] = unsafe { (*cf_ref.args).as_slice_mut() }; let raw = args.get(idx)?.as_bytes(); let s = core::str::from_utf8(raw).ok()?; Some(matches!(s.to_ascii_lowercase().as_str(), "on" | "1" | "true" | "yes")) } extern "C" fn set_flag_proxy( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, conf: *mut c_void, ) -> *mut c_char { let Some(flag) = (unsafe { arg_flag(cf, 1) }) else { return NGX_CONF_ERROR; }; // SAFETY: nginx 保证 conf 指向本模块的 loc conf 结构 unsafe { (*(conf as *mut ModuleConfig)).proxy = flag }; NGX_CONF_OK } extern "C" fn set_flag_api( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, conf: *mut c_void, ) -> *mut c_char { let Some(flag) = (unsafe { arg_flag(cf, 1) }) else { return NGX_CONF_ERROR; }; // SAFETY: 同上 unsafe { (*(conf as *mut ModuleConfig)).api = flag }; NGX_CONF_OK } extern "C" fn set_flag_llm( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, conf: *mut c_void, ) -> *mut c_char { let Some(flag) = (unsafe { arg_flag(cf, 1) }) else { return NGX_CONF_ERROR; }; // SAFETY: 同上 unsafe { (*(conf as *mut ModuleConfig)).llm = flag }; NGX_CONF_OK } extern "C" fn set_flag_apix( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, conf: *mut c_void, ) -> *mut c_char { let Some(flag) = (unsafe { arg_flag(cf, 1) }) else { return NGX_CONF_ERROR; }; // SAFETY: 同上 unsafe { (*(conf as *mut ModuleConfig)).apix = flag }; NGX_CONF_OK } extern "C" fn set_state_zone( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, _conf: *mut c_void, ) -> *mut c_char { // SAFETY: 配置回调必然拿到有效的 cf let cf_ref = unsafe { cf.as_mut().unwrap() }; let args: &mut [ngx_str_t] = unsafe { (*cf_ref.args).as_slice_mut() }; let mut name: ngx_str_t = args[1]; let size = unsafe { ngx_parse_size(&raw mut args[2]) }; if size == -1 { ngx_conf_log_error!(NGX_LOG_EMERG, cf_ref, "ipass_state: 共享内存大小非法"); return NGX_CONF_ERROR; } let zone = unsafe { ngx_shared_memory_add( cf, &raw mut name, size as usize, (&raw mut ngx_http_ipass_module).cast(), ) }; if zone.is_null() { return NGX_CONF_ERROR; } unsafe { (*zone).init = Some(state_zone_init); } state::set_zone(zone); NGX_CONF_OK } /// 共享内存初始化:由 nginx 在 **fork 之前**调用一次。 /// /// 在这里装载三张表,所有 worker 直接共享结果——比放在 /// `init_process`(每个 worker 各跑一遍)省掉 N-1 次文件读与 JSON 解析。 extern "C" fn state_zone_init(zone: *mut ngx_shm_zone_t, _data: *mut c_void) -> ngx_int_t { let status = state::init_zone(zone); if status != Status::NGX_OK { return status.into(); } // 插件注册「删账号要清什么」: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, // 没有任何回源兜底(同 domains 的写穿语义)。 let keys = users::reload_shm(); let ups = upstreams::reload_shm(); let axs = apix::reload_shm(); util::log_notice(&format!( "[ipass] 已装载 {keys} 个账号 Key、{ups} 个 LLM 上游、{axs} 个 API 代理" )); Status::NGX_OK.into() } extern "C" fn set_data_dir( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, _conf: *mut c_void, ) -> *mut c_char { // SAFETY: 配置回调必然拿到有效的 cf let cf_ref = unsafe { cf.as_mut().unwrap() }; let args: &mut [ngx_str_t] = unsafe { (*cf_ref.args).as_slice_mut() }; match core::str::from_utf8(args[1].as_bytes()) { Ok(dir) => { store::set_data_dir(dir); NGX_CONF_OK } Err(_) => { ngx_conf_log_error!(NGX_LOG_EMERG, cf_ref, "ipass_data_dir: 路径不是合法 UTF-8"); NGX_CONF_ERROR } } } /// `ipass_audit_dir `:LLM 对话审计根目录。缺省 = data 目录的兄弟目录。 extern "C" fn set_audit_dir( cf: *mut ngx_conf_t, _cmd: *mut ngx_command_t, _conf: *mut c_void, ) -> *mut c_char { // SAFETY: 配置回调必然拿到有效的 cf let cf_ref = unsafe { cf.as_mut().unwrap() }; let args: &mut [ngx_str_t] = unsafe { (*cf_ref.args).as_slice_mut() }; match core::str::from_utf8(args[1].as_bytes()) { Ok(dir) => { llm_audit::set_dir(dir); NGX_CONF_OK } Err(_) => { ngx_conf_log_error!(NGX_LOG_EMERG, cf_ref, "ipass_audit_dir: 路径不是合法 UTF-8"); NGX_CONF_ERROR } } } /// 供测试与诊断使用:`NgxStr` 类型在模块里被多处引用,确保编译期链接到正确的符号 #[allow(dead_code)] fn _type_witness(_: &NgxStr, _: &NgxString) {}