docs: 按 sso 实际重写 CLAUDE.md/README(原文整份是 ipass-all 拷贝)
更正为 2 个 named context、18098/NodePort 30089、PVC subPath sso、 PLUGINS=[SsoPlugin,CorePlugin]、4 条指令(无 audit_stats/probe_min); 删掉不存在的 plugin-architecture-analysis.md 死链,/userinfo 改为 /oauth/userinfo。
This commit is contained in:
1 parent
84311e2be8
commit
377636c014
2 files changed
+117
-170
No files matched your search
@@ -1,201 +1,142 @@
|
||||
# CLAUDE.md
|
||||
|
||||
给 AI 协作者的项目说明。本仓是 **ipass-all**:把 iPass 内核与全部插件装配成
|
||||
**一个** nginx 动态模块 / **一个**容器 / **一个** K8s Deployment。
|
||||
给 AI 协作者的项目说明。本仓是 **ipass-sso**:只把 `ipass-core` + `ipass-plugin-sso`
|
||||
装配成**一个** nginx 动态模块 / **一个**容器 / **一个** K8s Deployment 的 SSO-only 精简版。
|
||||
全家桶版在 `../ipass-all`——本仓刻意剔除了 domain / llm / apix / cache / waf 五个插件。
|
||||
|
||||
## 一句话定位
|
||||
|
||||
iPass 的「全家桶」发行版:`ipass-core`(内核)+ 6 个 crate 级插件
|
||||
(sso / domain / llm / apix / cache / waf)+ trend 组合端点,编译期装配进
|
||||
单个 `libipass_all_gateway.so`。单进程、零外部依赖(无 DB / Redis / MQ)。
|
||||
iPass 的「身份网关」:`ipass-core`(内核)+ `ipass-plugin-sso`(OAuth2/OIDC + IAP + 企微),
|
||||
编译期装配进单个 `libipass_sso_gateway.so`。单进程、零外部依赖(无 DB / Redis / MQ)。
|
||||
|
||||
**为什么单 .so**:nginx 动态模块无稳定 ABI,多 .so 会撞共享内存 zone tag 冲突
|
||||
(启动即 EMERG)与同名变量互相覆盖。论证见 `ipass-sso/docs/plugin-architecture-analysis.md`。
|
||||
**为什么单 .so**:nginx 动态模块无稳定 ABI,多 .so 会撞共享内存 zone tag 冲突(启动即
|
||||
EMERG)与同名变量互相覆盖。
|
||||
|
||||
## 依赖布局(兄弟仓库,编译期 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 在其仓内)
|
||||
../ipass-core 内核 + vendored ngx-rust(crates.io/git 版 ngx 不可用,见下)
|
||||
../ipass-plugin-sso 身份:OAuth2/OIDC + IAP(PLUGINS 排第一,认领身份端点)
|
||||
```
|
||||
|
||||
⚠️ `ngx` 必须用 `../ipass-core/rust/vendor/ngx-rust`(path 依赖):crates.io 的
|
||||
0.5.1 没发请求阶段 API;git 依赖会克隆 nginx 仓库在国内容 networks 永久挂起。
|
||||
⚠️ `ngx` 必须用 `../ipass-core/rust/vendor/ngx-rust`(path 依赖):crates.io 的 0.5.1 没发
|
||||
请求阶段 API;git 依赖会克隆 nginx 仓库,国内网络下永久挂起。
|
||||
|
||||
## 本机构建(快速检查用)
|
||||
domain / llm / apix / cache / waf 五个插件仓与本仓**无编译期依赖**,别往 `rust/Cargo.toml`
|
||||
里加(`rust/` 是 workspace,成员只有 `gateway`)。
|
||||
|
||||
## 本机构建(只做编译检查)
|
||||
|
||||
```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
|
||||
cargo check --release # 或 cargo build --release:macOS 只出 .dylib,不能进镜像
|
||||
```
|
||||
|
||||
nginx 源码树不可 `mv`(`objs/Makefile` 里的 `-I` 是绝对路径,挪了要重新 configure)。
|
||||
这里的 `cargo build` 只能验证「编得过」——**产物是 macOS 的 `.dylib`,进不了 Linux 镜像**,
|
||||
原因见下节。
|
||||
|
||||
## 容器构建 / 部署
|
||||
|
||||
```bash
|
||||
bash deploy/build.sh # 收集前端 dist → docker build(7 个 named context)→ push
|
||||
kubectl apply -f deploy/k8s/ipass-all.yaml
|
||||
bash deploy/build.sh # 收集前端 dist → docker build(2 个 named context)→ push
|
||||
bash deploy/build.sh --no-push # 只构建、不推
|
||||
kubectl apply -f deploy/k8s/ipass-sso.yaml
|
||||
```
|
||||
|
||||
镜像 tag 约定:`crpi-...aliyuncs.com/ssw188/nginx:ipass-all-vX.Y.Z`(只推 ssw188/nginx
|
||||
这一个 repo,不建新 repo)。**节点 imagePullPolicy=IfNotPresent,新版必须换新 tag。**
|
||||
- named context 只有 **2 个**:`ipass-core=../ipass-core`、`ipass-plugin-sso=../ipass-plugin-sso`
|
||||
(ipass-all 是 7 个,写脚本时别照抄)。
|
||||
- 镜像 tag:`crpi-...aliyuncs.com/ssw188/nginx:ipass-sso-vX.Y.Z`(只推 `ssw188/nginx` 这一个
|
||||
repo,不建新 repo)。⚠️ `build.sh` 的默认值是 `TAG=ipass-sso-v0.6.0`,而**线上清单已到
|
||||
v0.8.1**——发版必须显式 `TAG=ipass-sso-vX.Y.Z bash deploy/build.sh`,否则打出旧版本号。
|
||||
- 节点 `imagePullPolicy=IfNotPresent`:**同 tag 重推不刷新**,新版必须换新 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)
|
||||
- 无新 PVC 可用 → 复用共享 PVC `nginx-data`,subPath **`sso`**(initContainer 以 10106 预建
|
||||
目录,否则 kubelet 按 root 建目录,业务写盘才炸)
|
||||
- **replicas=1 + strategy=Recreate**:运行期真源是进程内共享内存 + JSON 写穿;多副本或滚动
|
||||
时新旧并存 = 脑裂 + 双写 JSON
|
||||
- 暴露:NodePort **30089** → pod 18098(明文)
|
||||
- `deploy/k8s/iap-demo.yaml` 是 IAP 演示用的上下游(`app-crm-svc` / `app-mobile-svc`)
|
||||
|
||||
### 容器内编译不能去掉(2026-11-04 定案)
|
||||
|
||||
vendored ngx-rust 要求「生产同一份 nginx 源码 + 相同 configure 参数」编译(base 镜像里的
|
||||
`/src/nginx-1.30.4` 是唯一参照物)→ **容器内编译是设计必需**。本机 `cargo build` 产出的是
|
||||
`.dylib` 不是 `.so`;zig 交叉编译卡在 bindgen(本机 `ngxbuild` 是 darwin-configured,缺
|
||||
`sys/filio.h`)——该路线已放弃,`cargo-zigbuild` 已卸。提速改用 builder 段的 BuildKit
|
||||
cache mount(registry/git + target);`target` 不进镜像层,故 `.so` 先复制到 `/out`,
|
||||
runtime 用 `COPY --from=builder /out/libipass_sso_gateway.so`。完整理由与实测数据见
|
||||
`ipass-all/CLAUDE.md` 同节。
|
||||
|
||||
## 装配层(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` + 重启(改文件需重启,不热生效)。
|
||||
- `PLUGINS = [SsoPlugin, CorePlugin]`——精简版只有两个。**SsoPlugin 排第一**:认领
|
||||
login/logout/session/users CRUD/me 等身份端点(带 CAPTCHA、账号锁定、审计与身份字段),
|
||||
CorePlugin 只补 sso 没有的端点。**没有** domain/llm/apix/cache/waf,也**没有**
|
||||
GatewayRoutes(trend) 组合端点。
|
||||
- 指令只注册 **4 条**:main 上下文 `ipass_state`(TAKE2) / `ipass_data_dir`(TAKE1);loc 上下文
|
||||
`ipass_api` / `sso_iap`。⚠️ 精简版**没有** `ipass_audit_dir` / `ipass_stats_persist` /
|
||||
`ipass_probe_min` / `ipass_llm` / `ipass_apix` / `ipass_cache`——conf 里写了就是
|
||||
unknown directive,启动即失败(从 ipass-all 抄 conf 最容易踩这个)。
|
||||
- `state_zone_init`:sso 的 OAuth 接入方表靠 `zone_load()` 回填。
|
||||
|
||||
## 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)。
|
||||
- 单端口 **18098**(明文,NodePort 30089)。SSL 段在 conf 里是**注释状态**,TLS 当前不在
|
||||
sso 侧终结;要启用就取消注释 `listen 18098 ssl default_server` + 三条 ssl_certificate。
|
||||
- `env` 白名单 18 条(`ADMIN_INIT_PASSWORD` / `OAUTH_*` / `SYNC_*` / `PASSWORD_RESET_*` /
|
||||
`WXWORK_*` / `IPASS_SYNC_*`):nginx 默认剥离环境变量,**漏一条 = worker 里恒空**,
|
||||
新增 env 必须同步加进这里。
|
||||
- location 分组:
|
||||
- `/api/` 与 `/` 开 `ipass_api on`——OIDC/身份协议端点都挂在根路径,由 sso 插件认领:
|
||||
`/oauth/*`(authorize/token/userinfo/jwks/introspect)、`/.well-known/*`
|
||||
(openid-configuration、jwks.json)、`/login`、`/logout`、`/apps`、`/reset`、`/cas/*`、
|
||||
`/portal/*`。⚠️ 没有裸 `/userinfo`,是 `/oauth/userinfo`。
|
||||
- `/api/admin/sync/` 额外加 `allow 10.244.0.0/16` + `10.96.0.0/12` + `deny all`:sync/push
|
||||
的请求体带全量 salt + pwd_hash + api_key,绝不出集群(nginx 层与 SyncToken 头两道门)。
|
||||
- 管理台静态 `/`、`/admin`、`/admin/`、`/plugin-`、`/manage/`、`/assets/`、`/static/plugins/`
|
||||
**不开** `ipass_api`(静态文件走 nginx)。
|
||||
- `/legacy/` 纯静态;企微校验走 `~* ^/WW_verify_[A-Za-z0-9_-]+\.txt$`。
|
||||
- IAP 反代 `/proxy/app-crm/*` + `/proxy/app-mobile/*`,upstream 是 K8s Service
|
||||
`app-crm-svc:8000` / `app-mobile-svc:8000`——**本机或集群外跑这份 conf 会 502**,
|
||||
因为这两个名字只在集群 DNS 里解析。
|
||||
|
||||
## 生产入口与企微回调(K8s)
|
||||
|
||||
- 外部入口 `https://i28868828dm.mayishangshu.cn:188`(路由器 :188 → 192.168.1.26:30089 →
|
||||
pod 18098);NodePort 本身明文,TLS 由上游终结。
|
||||
- `OAUTH_ISSUER` 必须与浏览器/第三方实际访问地址**逐字一致**(清单里写死 `:188`)。
|
||||
- ⚠️ `WXWORK_REDIRECT` 必须是 `https://i28868828dm.mayishangshu.cn:88/portal/wxwork/callback`
|
||||
——企微后台该应用(agentid 1000017)的可信域名按 **:88** 配置,改成 `:188` 会被 authorize
|
||||
页拒(redirect_uri 与可信域名不一致)。
|
||||
- 账号同步对端 = ipass-all:`IPASS_SYNC_PEER=http://ipass-all.wuguirong.svc.cluster.local:18097`。
|
||||
|
||||
## 边界 / 常见坑
|
||||
|
||||
- 改 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` + 重新构建镜像。
|
||||
- **会话在共享内存里**:每次 pod 重启,全部管理员/用户会话失效,要重新登录。
|
||||
- 前端壳更新:改完 `ipass-core/www` 或 `ipass-plugin-sso/www` 后重跑 `npm run build` +
|
||||
本仓 `scripts/collect-plugin-dist.sh` + 重建镜像。`deploy/legacy/` 是**可维护副本**,
|
||||
collect 脚本只做首次引导(目标文件已存在则跳过),不会覆盖人工修改。
|
||||
- 本机 `cargo build` 出的 `.dylib` 只能验证编译,**不能进镜像**。
|
||||
|
||||
## 生产迁移与 TLS(2026-09-26 v0.2.9)
|
||||
## 与 ipass-all 的差异速查
|
||||
|
||||
- **生产数据**(`/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)。
|
||||
| 项 | ipass-sso(本仓) | ipass-all |
|
||||
|---|---|---|
|
||||
| 插件 | SsoPlugin + CorePlugin | + domain/llm/apix/cache/waf/trend |
|
||||
| 产物 | `libipass_sso_gateway.so` | `libipass_all_gateway.so` |
|
||||
| 端口 | 18098(NodePort 30089,明文) | 18098/18099(30083 TLS、30084 LLM) |
|
||||
| named context | 2 个 | 7 个 |
|
||||
| 数据 subPath | `sso` | `ipass-all` |
|
||||
| 指令 | 4 条 | 10 条 |
|
||||
|
||||
## 管理台架构定案(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
|
||||
仓流程重建镜像重发。
|
||||
管理台架构定案、壳契约 v2、legacy 集成、WAF 三连坑、TLS 全量策略等**共享知识只在
|
||||
`../ipass-all/CLAUDE.md` 维护**,本仓不再复制。⚠️ 本文件在 2026-11-04 之前是 ipass-all 的
|
||||
整份拷贝(自称 ipass-all、列 6 插件、7 个 context、`ipass-all.yaml`、30083/30084、subPath
|
||||
`ipass-all/`),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。
|
||||
@@ -1,34 +1,40 @@
|
||||
# ipass-all
|
||||
# ipass-sso
|
||||
|
||||
iPass 全插件一体网关:内核 + 6 插件(身份 sso / 域名 domain / LLM 代理 llm /
|
||||
API 代理 apix / 制品缓存 cache / WAF waf)编译期装配成**单个** nginx 动态模块,
|
||||
一个容器跑完。单进程、零外部依赖。
|
||||
iPass **身份网关**(SSO-only 精简版):`ipass-core` 内核 + `ipass-plugin-sso` 编译期装配成
|
||||
**单个** nginx 动态模块(`libipass_sso_gateway.so`),一个容器跑完。单进程、零外部依赖
|
||||
(无 DB / Redis / MQ)。全家桶版见 [`../ipass-all`](../ipass-all)。
|
||||
|
||||
## 端口
|
||||
|
||||
| 端口 | 承载 |
|
||||
|---|---|
|
||||
| 18098 | 管理台 `/admin/` · OIDC(`/.well-known/openid-configuration`)· `/api/*` · apix(`/apix/`、`/apixp/`)· 制品缓存 8 路由(`/go/ /cargo/ /pypi/ /npm/ /maven/ /v2/…`)· 域名转发(`Host: *.ipass.local`) |
|
||||
| 18099 | LLM 数据面 `<base_url>/<slot>/...`(sk_ Key 鉴权,出站换上游真 Key) |
|
||||
| 18098 | 管理台 `/admin/` · OIDC(`/.well-known/openid-configuration`、`/.well-known/jwks.json`、`/oauth/*`)· 账号 API `/api/*` · 门户与企微 `/portal/*` · IAP 反代 `/proxy/app-*` · 集群内账号同步 `/api/admin/sync/` |
|
||||
|
||||
NodePort **30089** → pod 18098(明文,TLS 由上游终结)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
bash deploy/build.sh # 收集前端 + docker build + push 阿里云 CR
|
||||
kubectl apply -f deploy/k8s/ipass-all.yaml # wuguirong 租户 ns(NodePort 30083/30084)
|
||||
curl -fs http://192.168.1.26:30083/.well-known/openid-configuration
|
||||
kubectl apply -f deploy/k8s/ipass-sso.yaml # wuguirong 租户 ns(NodePort 30089)
|
||||
curl -fs http://192.168.1.26:30089/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
首次登录 `admin / 123456`(立即改密)。各插件能力与配置见管理台对应页。
|
||||
⚠️ `build.sh` 默认 `TAG=ipass-sso-v0.6.0`,发版要显式覆盖:`TAG=ipass-sso-vX.Y.Z bash deploy/build.sh`。
|
||||
|
||||
首次登录 `admin / 123456`(`scripts/seed-data.sh` 的 `ADMIN_PASSWORD` 默认值,另有
|
||||
`alice / alice123`)——**上线后立即改密**。
|
||||
|
||||
## 装配清单与顺序
|
||||
|
||||
`SsoPlugin → CorePlugin → DomainPlugin → LlmPlugin → ApixPlugin → CachePlugin → WafPlugin → trend`
|
||||
`SsoPlugin → CorePlugin`
|
||||
|
||||
顺序即端点认领顺序:sso 排第一接管身份端点;trend 组合端点由装配根自己提供。
|
||||
顺序即端点认领顺序:`SsoPlugin` 排第一,接管 login/logout/session/users CRUD/me 等身份端点
|
||||
(带 CAPTCHA、账号锁定、审计);`CorePlugin` 只补 sso 没有的端点。
|
||||
|
||||
## 文档
|
||||
|
||||
- 构建约束、踩坑与边界 → [`CLAUDE.md`](CLAUDE.md)
|
||||
- K8s 清单 → [`deploy/k8s/ipass-all.yaml`](deploy/k8s/ipass-all.yaml)
|
||||
- 各插件自身文档 → 兄弟仓 `ipass-plugin-*/CLAUDE.md`
|
||||
- K8s 清单 → [`deploy/k8s/ipass-sso.yaml`](deploy/k8s/ipass-sso.yaml)、IAP 演示 → [`deploy/k8s/iap-demo.yaml`](deploy/k8s/iap-demo.yaml)
|
||||
- IAP 接入 → [`docs/iap.md`](docs/iap.md)、[`docs/integrate-with-iap.md`](docs/integrate-with-iap.md)
|
||||
- 各插件自身文档 → 兄弟仓 `ipass-plugin-*/CLAUDE.md`;共享架构知识 → `../ipass-all/CLAUDE.md`
|
||||
Reference in new issue
Block a user