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]>
202 lines
13 KiB
Markdown
202 lines
13 KiB
Markdown
# 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>/` 首段即 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
|
||
仓流程重建镜像重发。
|