**影响**:新建独立仓 ipass-sso 作为 ipass-all 的 SSO-only 精简发行版—— 剔除了 domain / llm / apix / cache / waf 5 个插件及对应的 nginx location 与 LLM/域名数据面 server,PLUGINS 数组只剩 sso + core,单 .so 体积与编 译时间同步下降。镜像名沿用 ssw188/nginx(同 repo 加 tag),新 tag `ipass-sso-v0.6.0`,K8s 部署在 wuguirong ns NodePort 30082,与生产 ipass-all-v0.5.2 (30083/30084/30085) 并存互不干扰。 **改动**: - `rust/Cargo.toml` + `rust/gateway/Cargo.toml`:删 5 个 plugin path 依赖, package/lib 重命名为 `ipass-sso-gateway` / `libipass_sso_gateway` - `rust/gateway/src/lib.rs`:PLUGINS 只剩 `&SsoPlugin` + `&CorePlugin`; GatewayExt 4 个方法改为 no-op / 返回默认值(无 domain/llm 装饰); ModuleConfig 只剩 api + iap 两个开关;NGX_HTTP_COMMANDS 数组 11→4 条; init_process / exit_process 删 llm audit / stats persist 调用; state_zone_init 删 domain/upstreams/apix 的预装载 - `rust/gateway/src/api.rs`:删除(h_admin_trend 依赖 llm + apix) - `deploy/nginx.conf`:删 server 498 (LLM) + server 565 (域名); 主 server 删 `/apix/` `/apixp/` `/_apix_probe/` 等 7 个 location; 删 6 条 `proxy_cache_path` 与 8 个 cache location;删 `ipass_audit_dir` 指令 - `deploy/Dockerfile`:删 5 个 plugin named context 的 COPY 块; .so 文件名改 `libipass_sso_gateway.so` - `deploy/build.sh`:TAG 默认 `ipass-sso-v0.6.0`; 5 个 plugin build-context 删除;删 collect-legacy.sh 调用 - `data-seed/plugin-config.json`:只保留 `sso` 一个 plugin - `scripts/collect-plugin-dist.sh`:PLUGINS 默认值改 `sso` - `scripts/container-entrypoint.sh`:删 cache/audit 目录预创建 - `deploy/legacy/` `tests/` `docs/` `deploy/custom/` `deploy/compose.yml`: 精简版不需要,删除 - `deploy/k8s/ipass-sso.yaml`:新建精简版 K8s manifest (NodePort 30082 单端口;replicas=1;同 10106 准入 + nginx-data PVC sso/ subPath; 探针用 `/admin/` try_files 兜底,与 ipass-all 同款止血方案) **设计**:保留 ipass-core("core 是网关身份底座,永不跳过")+ ipass-plugin-sso, 其余插件整链剥离;不再维护 ssow/ssw 时代的多插件装配文档。剔除 ipass_audit_dir 是因为精简版没有 LLM 对话审计,剔除 proxy_cache_path 同理。K8s 部署沿用 nginx-data PVC + subPath 隔离模式(sso/ 与 ipass-all/ 互不干扰)。 **已知约束**:精简版仍是单进程共享内存,pod 重启使所有管理员/用户会话失效 (与 ipass-all 同款代价)。精简版不带单元/E2E 测试,老管理台 iframe 集成 也未引入。 Co-Authored-By: Claude Code <[email protected]>
13 KiB
CLAUDE.md
给 AI 协作者的项目说明。本仓是 ipass-all:把 iPass 内核与全部插件装配成 一个 nginx 动态模块 / 一个容器 / 一个 K8s Deployment。
一句话定位
iPass 的「全家桶」发行版:ipass-core(内核)+ 6 个 crate 级插件
(sso / domain / llm / apix / cache / waf)+ trend 组合端点,编译期装配进
单个 libipass_all_gateway.so。单进程、零外部依赖(无 DB / Redis / MQ)。
为什么单 .so:nginx 动态模块无稳定 ABI,多 .so 会撞共享内存 zone tag 冲突
(启动即 EMERG)与同名变量互相覆盖。论证见 ipass-sso/docs/plugin-architecture-analysis.md。
依赖布局(兄弟仓库,编译期 path 依赖)
../ipass-core 内核 + vendored ngx-rust(crates.io/git 版 ngx 不可用,见下)
../ipass-plugin-sso 身份:OAuth2/OIDC + IAP(dispatch 排第一,认领身份端点)
../ipass-plugin-domain 动态域名($proxy_backend_addr)
../ipass-plugin-llm LLM 代理($llm_* + 用量统计 + 对话审计)
../ipass-plugin-apix API 代理($apix_* / $apixp_*;依赖 plugin-llm)
../ipass-plugin-cache 制品缓存($cache_*;上游表管理台配,改上游不 reload)
../ipass-plugin-waf WAF(默认 enabled + 内置规则随 .so 分发;vendor/zentinel-modsec 在其仓内)
⚠️ ngx 必须用 ../ipass-core/rust/vendor/ngx-rust(path 依赖):crates.io 的
0.5.1 没发请求阶段 API;git 依赖会克隆 nginx 仓库在国内容 networks 永久挂起。
本机构建(快速检查用)
cd rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib
export NGINX_SOURCE_DIR=$HOME/Desktop/workspace/ipass/ngxbuild/nginx-1.30.4
export NGINX_BUILD_DIR=$NGINX_SOURCE_DIR/objs
cargo check --release # 或 cargo build --release 出 .dylib
nginx 源码树不可 mv(objs/Makefile 里的 -I 是绝对路径,挪了要重新 configure)。
容器构建 / 部署
bash deploy/build.sh # 收集前端 dist → docker build(7 个 named context)→ push
kubectl apply -f deploy/k8s/ipass-all.yaml
镜像 tag 约定:crpi-...aliyuncs.com/ssw188/nginx:ipass-all-vX.Y.Z(只推 ssw188/nginx
这一个 repo,不建新 repo)。节点 imagePullPolicy=IfNotPresent,新版必须换新 tag。
K8s 约束(wuguirong 租户,细节见 Claude 技能 k8s-tenant-wuguirong):
- 容器级
runAsUser: 10106(准入强制,pod 级无效);非 root → conf 里 pid/temp 全在 /tmp - 无新 PVC 可用 → 复用共享 PVC
nginx-data,subPathipass-all/(initContainer 以 10106 预建目录,否则 kubelet 按 root 建目录,业务写盘才炸) - replicas 必须 = 1:运行期真源是进程内共享内存 + JSON 写穿,多副本 = 脑裂
- 暴露:NodePort 30083(管理台/IdP/apix/cache)+ 30084(LLM)
装配层(rust/gateway/src/lib.rs)要点
PLUGINS数组顺序 = preconfig/postconfig/dispatch 顺序:SsoPlugin 第一 (认领 /api/admin|v1 身份端点,带 CAPTCHA/锁定/审计),core 补 sso 没有的端点, 之后 domain → llm → apix → cache → waf → GatewayRoutes(trend)。- 指令集中在 gateway(10 条):main
ipass_state/ipass_data_dir/ipass_audit_dir/ ipass_stats_persist/ipass_probe_min;locipass_api/sso_iap/ipass_proxy/ipass_llm/ipass_apix。 ⚠️ cache 插件没有ipass_cache指令(legacy 独立仓形态才有)——它靠路由前缀- R19 总闸生效,conf 里写
ipass_cache on会 unknown directive 启动失败。
- R19 总闸生效,conf 里写
state_zone_init两层都要:显式装载(domains/users/llm upstreams/apix)+ 各插件zone_load()回调(sso 的 OAuth 接入方表靠它)。GatewayExt承 ssw 完整版(decorate_admin_users / decorate_me / reclaim_on_delete 回收域名 / validate_slots)。llm 的 usage_filter 用r->ctx[ctx_index]请求槽, sso 不用请求槽 → 合流无冲突。- WAF 默认
enabled:true且规则include_str!进 .so;误拦时改data/plugin-config.json里waf.enabled=false+ 重启(改文件需重启,不热生效)。
nginx.conf(deploy/nginx.conf)要点
- 端口分工:18098 主(管理台/IdP/API/apix/cache 路由/域名 Host 转发)、18099 LLM
(
/<slot>/首段即 slot,不能挂在带前缀的 location 下)。 - 管理台静态 location 不开
ipass_api;/_apix_probe//_apixp_probe//_upstream_test/三个 internal 探针必须与/api/同 server(内部重定向不出 server)。 - cache location 不写
ipass_cache(见上);proxy_cache_path必须use_temp_path=off(/var/tmp root 属主,10106 写不进)。 ipass_audit_dir必须显式指进数据卷(缺省 = data 兄弟目录,不可写)。- env 白名单在 main 上下文(sso 的 9 个 env;llm/apix/cache/waf 不读 env)。
边界 / 常见坑
- 改 conf 或 .so 后必须重启(reload 不重载动态模块;JSON 是写穿持久化)。
- 会话在共享内存里:每次 pod 重启全部管理员/用户会话失效,要重新登录。
KNOWN_PLUGINS(ipass-core)目前没有 "cache" → 壳菜单不显示制品缓存页, 插件本身照常工作;要上菜单需给 ipass-core 补登记(上游改动,暂缓)。plugin-cache仓没有 www/(管理页待重写),壳里自然没有它的菜单。- 前端壳更新:改完 ipass-core/www 或各插件 www 后重跑
npm run build+ 本仓scripts/collect-plugin-dist.sh+ 重新构建镜像。
生产迁移与 TLS(2026-09-26 v0.2.9)
- 生产数据(
/Users/xs/Desktop/ipass-88-data:22 账号 / 5 域名 / 4 LLM 上游 / 3 API 代理 / 用量快照)已灌入 PVCipass-all/;此前 dev 数据备份在同目录backup-dev-20260926.tar.gz。⚠️ 直接改 data/*.json 不热生效——改完必须重启。 - TLS:证书放数据目录
data/tls/(fullchain.cer / tls.key / ca.cer), 换证书 = 换文件 + 重启,不重打镜像。证书为多域名证书(SAN 含*.mayishangshu.cn等,2026-11-04 到期,来源 ipass-ssw/conf/tls)。 - 端口分工:30083 = TLS only(SNI:mdm/lm/
*dm.mayishangshu.cn,路由器 WAN:188 → 节点 30083,外部入口https://mdm.mayishangshu.cn:188);30085 = 管理台/域名代理明文(内网调试);30084 = LLM 明文。⚠️ nginx 同一端口不能 既明文又 TLS(duplicate listen 启动即炸)。⚠️ 容器端口改名后 Service 的targetPort必须同步(v0.2.9 实测漏改 → 30083 悬空)。 - issuer =
https://mdm.mayishangshu.cn:188;OAUTH_COOKIE_DOMAIN=mayishangshu.cn只影响 sso 终端用户 cookie;admin 会话 cookie 恒为 host-only,IP 直连登录不受影响。 - 生产域名后端(192.168.1.222:23 / .2:8080 / .22:88 / .15:8787)在本环境不在线
→ 域名转发 404 属预期,后端上线即通;ssw 测试域名
i29214898dm → 192.168.1.7:89已并入(.7 同样待开机)。 - 向数据目录写文件(certs/JSON)可用一次性 busybox Pod 挂 subPath + base64 内嵌
manifest(
kubectl run -i的 stdin 在 overrides 场景不可靠;准入要求 pod 级 fsGroup=10106 + 容器级 runAsUser=10106)。
管理台架构定案(2026-09-26,v0.4.0)
- ipass-core 壳只带核心域原生页:账号管理(
AccountAdmin.vue,唯一可 添加/删除/解锁/Key/密码 的地方,只管身份与凭据)+ 插件管理 (PluginAdmin.vue,POST /api/core/plugins/set即时生效 + 落盘)。 插件域的用户绑定功能归插件自己:临时授权在域名管理(grants.html)、 上游白名单/限额在 LLM 网关(llm-users.html)——core 账号页不再出现这些列。 - 装配默认用 core 壳,可整体覆写:装配仓放
shell/dist/即覆盖默认 (collect-plugin-dist.sh 已实现);装配自定义页用deploy/custom/custom-pages.json清单(group/path/label/url),core 壳 boot 时拉取注册(无此文件静默跳过), 如 ipass-all 的 数据总览/我的用量。 - 插件启用即出顶部菜单(装载清单驱动);插件自带左侧菜单(契约 v2
{title, pages})。 - 与用户绑定的功能,插件可有自己的账号列表/按钮(如 sso 身份页),但
添加/删除/启用等生命周期操作一律跳转 core 账号管理页(sso.html 已改:
del-user/unlock/创建表单 →top.location = /manage/users)。 - 插件页不与 core 页交叉读写——跨域数据靠 API(各插件认领各自路由)。
管理台壳(2026-09-26 排障定案)
v0.1.5 修复「/admin/ 打开空白」,根因五个、全在上游仓,curl 层全绿只有真浏览器
才暴露(排障用 agent-browser,注意 intranet 要 --proxy-bypass):
- 壳无认证接线 →
AppLayout.vue401 渲染Login.vue(此前 Login 是死代码); - API 信封层级 → 壳读
data.plugins,后端回{code,data:{plugins}},被?? []静默吞掉(登录了也空白); - 面板路由从不注册 → AppLayout 现在
router.addRoute(panel.routes);/路由 此前指回 AppLayout 自嵌套 → 改 redirect; - 插件 UMD 引用
process.env.NODE_ENV→ 壳 main.ts 入口window.process ??= {env:{}}; - 浏览器原生
import()不做 CJS 互操作:UMD 包装的mod.default恒为 undefined(契约对象落在window['ipass-plugin-<name>-admin'])→ loader 按plugin-<name>-admin.es.js → plugin-<name>-admin.umd.js → <name>-admin.umd.js顺序试,必须拿到.default才算成功。插件仓一律用 vite lib 模式 (formats['umd','es'],参考 ipass-plugin-domain/www)出双格式。
管理台 v0.2 布局与 legacy 集成(2026-09-26 拍板)
布局:顶部横向插件条切面板;多页面板自动出左侧页菜单,单页直显;右上退出登录。
老管理台快速集成:ssw 九页(git bf2528d^ 提取)+ sso 五 tab 单页
(git 9de4d67^)+ waf.html(工作树)→ scripts/collect-legacy.sh 聚合进
deploy/legacy/(sed 改 base href=/legacy/ + 注入 #shell{display:none} 藏老
导航),Dockerfile 拷到 www/legacy/,nginx /legacy/ 纯静态。老页面 API 与插件
路由 1:1 兼容、同源同 cookie,IP.api 原样工作。iframe 内 401 落 login.html
独立兜底。
⚠️ deploy/legacy/ 自 2026-09-26 v0.2.6 起是可维护副本:collect 脚本只做
首次引导(目标文件已存在则跳过),人工修改(多选弹窗 / 创建时间列 / https 复制 /
WAF 免 Key 门禁等)不会被构建覆盖;要从上游重提某页,删掉对应文件再跑脚本。
SPA 直链回退要同时覆盖 /plugin- 与 /manage/ 两个前缀(nginx 缺一个就是
直链 JSON 404——实测漏过 /manage/)。
契约 v2(ipass-core/www/src/loader.ts):插件 default export
{ title, pages: [{path, label, url?}] }——url 给了壳就 iframe 原样嵌(老页
/任意同源页),没给用 component。五个插件已全部迁到 v2(各仓 www/src/main.ts
只是清单,面板 UI 全在壳)。壳内置「网关管理」分组(overview/users/me,core 域
无插件 UMD)。⚠️ 聚合去重:内置路由必须带 meta.builtin:true 且 builtinGroups()
只认它——插件页面路由同样带 meta.group,聚合若把 getRoutes() 全算一遍,
每个页面出现两份(实测踩坑)。
新插件接入管理台 = 三步:插件仓 www 用 lib 模式出 es 产物 + main.ts 写
{title, pages} 清单 + plugin_registry::KNOWN_PLUGINS 登记(上游 ipass-core)。
WAF 插件三连坑(2026-09-26,v0.2.3 定案)
控制台「几乎不可用」的元凶是 WAF 默认 CC 限频误封管理员,连带修了两个上游 bug:
- 默认 CC 太紧:
cc_limit=100 次/60s、ban 600s——管理台一屏 iframe + 每页 十几个 API 全从同一 IP 出,几分钟必触发{"code":403,"msg":"cc-ban"};且 CC 封禁不受 observe 模式豁免(handler 在 observe 判定之前短路)。 现状:cc_limit=100000(实际不设限),签名规则仍 observe 记录。 waf_conf.json只写不读(上游 bug,已修):config::store()写穿落盘, 但没人读回 → 重启即回退默认值。修复 =config::bootstrap_from_disk()挂在WafPlugin::zone_load。⚠️ 不能挂 postconfig——那个阶段 shm zone 还没 初始化(zone init 在 fork 时才跑),state::put静默无效(v0.2.2 实测踩坑)。cc_limit=0假确认(上游 bug,已修):校验报错文案说「显式传 cc_window>0 留档即可」,代码里没有该分支 → CC 永远关不掉。已按文案补上确认逻辑。
WAF 管理 API 鉴权用 sk_ API Key(X-API-Key),不认管理员会话 cookie;
读配置用 GET /api/waf/status(/api/waf/config 只有 PUT)。解封单个 IP:
DELETE /api/waf/blocks/<ip>;pod 重启也会清 shm 里的 ban。
注意:ipass-sso(:30082)镜像里还是旧壳,复现同款空白;要用新壳需按 ipass-sso 仓流程重建镜像重发。