Files
sso/CLAUDE.md
T
adminandClaude Code c3689d501e chore: SSO-only 精简版初始提交(从 ipass-all 派生)
**影响**:新建独立仓 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]>
2026-09-30 12:01:38 +08:00

202 lines
13 KiB
Markdown
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.
# 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/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
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(:30082)镜像里还是旧壳,复现同款空白;要用新壳需按 ipass-sso
仓流程重建镜像重发。