# 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 永久挂起。 ## 本机构建(快速检查用) ```bash 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 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,不能挂在带前缀的 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--admin']`)→ loader 按 `plugin--admin.es.js → plugin--admin.umd.js → -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/`;pod 重启也会清 shm 里的 ban。 注意:ipass-sso(:30089)镜像里还是旧壳,复现同款空白;要用新壳需按 ipass-sso 仓流程重建镜像重发。