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

1012 lines
39 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 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/<slot>/*` | access | `ipass_llm` | 查 `ukey:` 鉴权 + `up:` 定上游 |
//! | `llm.yourdomain.com/apix/<slug>` | 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<RbTreeMap<_, _, SlabPool>, _>` 一种安全形态;
//! `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<Status> {
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<String, usize> = 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<String, stats::UserUsage> =
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/<slug>?<参数>`):鉴权 → 查代理 → 放行。
///
/// 与 `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:<slot>` 缓存。
///
/// 为什么在 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 代理(`/<slot>/...` → 上游)
llm: bool,
/// 该 location 走 API 代理(`/apix/<slug>` → 外部供应商)
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::<LlmHandler>(cf).is_err() {
return Status::NGX_ERROR.into();
}
if ngx::http::add_phase_handler::<ApiProxyHandler>(cf).is_err() {
return Status::NGX_ERROR.into();
}
if ngx::http::add_phase_handler::<LlmHealthHandler>(cf).is_err() {
return Status::NGX_ERROR.into();
}
if ngx::http::add_phase_handler::<AuditHandler>(cf).is_err() {
return Status::NGX_ERROR.into();
}
// token 计量:插进 body filter 链头,旁路扫描上游响应的 usage
llm_usage::install();
if ngx::http::add_phase_handler::<ApiHandler>(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<bool> {
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 <path>`: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<SlabPool>) {}