Files
sso/CLAUDE.md
T
adminandClaude Opus 4.8 6b323c1e64 docs: 修正 ipass-sso NodePort 30082 → 30089
ipass-sso 已于 2026-10-12 迁到 NodePort 30089,nginx.conf / CLAUDE.md /
iap.md 仍写 30082,按旧端口排查会打错节点。

deploy/k8s/ipass-sso.yaml 与 2026-10-09 spec 已是 30089,仅保留其
历史沿革说明。

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-10-12 11:49:59 +08:00

13 KiB
Raw Blame History

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/Documents/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,subPath ipass-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;loc ipass_api/sso_iap/ipass_proxy/ipass_llm/ipass_apix。 ⚠️ cache 插件没有 ipass_cache 指令(legacy 独立仓形态才有)——它靠路由前缀
    • R19 总闸生效,conf 里写 ipass_cache on 会 unknown directive 启动失败。
  • 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 代理 / 用量快照)已灌入 PVC ipass-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)

  1. ipass-core 壳只带核心域原生页:账号管理(AccountAdmin.vue,唯一可 添加/删除/解锁/Key/密码 的地方,只管身份与凭据)+ 插件管理 (PluginAdmin.vue,POST /api/core/plugins/set 即时生效 + 落盘)。 插件域的用户绑定功能归插件自己:临时授权在域名管理(grants.html)、 上游白名单/限额在 LLM 网关(llm-users.html)——core 账号页不再出现这些列。
  2. 装配默认用 core 壳,可整体覆写:装配仓放 shell/dist/ 即覆盖默认 (collect-plugin-dist.sh 已实现);装配自定义页用 deploy/custom/custom-pages.json 清单(group/path/label/url),core 壳 boot 时拉取注册(无此文件静默跳过), 如 ipass-all 的 数据总览/我的用量。
  3. 插件启用即出顶部菜单(装载清单驱动);插件自带左侧菜单(契约 v2 {title, pages})。
  4. 与用户绑定的功能,插件可有自己的账号列表/按钮(如 sso 身份页),但 添加/删除/启用等生命周期操作一律跳转 core 账号管理页(sso.html 已改: del-user/unlock/创建表单 → top.location = /manage/users)。
  5. 插件页不与 core 页交叉读写——跨域数据靠 API(各插件认领各自路由)。

管理台壳(2026-09-26 排障定案)

v0.1.5 修复「/admin/ 打开空白」,根因五个、全在上游仓,curl 层全绿只有真浏览器 才暴露(排障用 agent-browser,注意 intranet 要 --proxy-bypass):

  1. 壳无认证接线 → AppLayout.vue 401 渲染 Login.vue(此前 Login 是死代码);
  2. API 信封层级 → 壳读 data.plugins,后端回 {code,data:{plugins}},被 ?? [] 静默吞掉(登录了也空白);
  3. 面板路由从不注册 → AppLayout 现在 router.addRoute(panel.routes);/ 路由 此前指回 AppLayout 自嵌套 → 改 redirect;
  4. 插件 UMD 引用 process.env.NODE_ENV → 壳 main.ts 入口 window.process ??= {env:{}};
  5. 浏览器原生 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:

  1. 默认 CC 太紧:cc_limit=100 次/60s、ban 600s——管理台一屏 iframe + 每页 十几个 API 全从同一 IP 出,几分钟必触发 {"code":403,"msg":"cc-ban"};且 CC 封禁不受 observe 模式豁免(handler 在 observe 判定之前短路)。 现状:cc_limit=100000(实际不设限),签名规则仍 observe 记录。
  2. waf_conf.json 只写不读(上游 bug,已修):config::store() 写穿落盘, 但没人读回 → 重启即回退默认值。修复 = config::bootstrap_from_disk() 挂在 WafPlugin::zone_load。⚠️ 不能挂 postconfig——那个阶段 shm zone 还没 初始化(zone init 在 fork 时才跑),state::put 静默无效(v0.2.2 实测踩坑)。
  3. 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(:30089)镜像里还是旧壳,复现同款空白;要用新壳需按 ipass-sso 仓流程重建镜像重发。