Files
admin 377636c014 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。
2026-11-04 10:43:04 +08:00

8.6 KiB
Raw Permalink Blame History

CLAUDE.md

给 AI 协作者的项目说明。本仓是 ipass-sso:只把 ipass-core + ipass-plugin-sso 装配成一个 nginx 动态模块 / 一个容器 / 一个 K8s Deployment 的 SSO-only 精简版。 全家桶版在 ../ipass-all——本仓刻意剔除了 domain / llm / apix / cache / waf 五个插件。

一句话定位

iPass 的「身份网关」:ipass-core(内核)+ ipass-plugin-sso(OAuth2/OIDC + IAP + 企微), 编译期装配进单个 libipass_sso_gateway.so。单进程、零外部依赖(无 DB / Redis / MQ)。

为什么单 .so:nginx 动态模块无稳定 ABI,多 .so 会撞共享内存 zone tag 冲突(启动即 EMERG)与同名变量互相覆盖。

依赖布局(兄弟仓库,编译期 path 依赖)

../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 仓库,国内网络下永久挂起。

domain / llm / apix / cache / waf 五个插件仓与本仓无编译期依赖,别往 rust/Cargo.toml 里加(rust/ 是 workspace,成员只有 gateway)。

本机构建(只做编译检查)

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:macOS 只出 .dylib,不能进镜像

nginx 源码树不可 mv(objs/Makefile 里的 -I 是绝对路径,挪了要重新 configure)。 这里的 cargo build 只能验证「编得过」——产物是 macOS 的 .dylib,进不了 Linux 镜像, 原因见下节。

容器构建 / 部署

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
  • 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 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 = [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(明文,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 重启,全部管理员/用户会话失效,要重新登录。
  • 前端壳更新:改完 ipass-core/www 或 ipass-plugin-sso/www 后重跑 npm run build + 本仓 scripts/collect-plugin-dist.sh + 重建镜像。deploy/legacy/ 是可维护副本, collect 脚本只做首次引导(目标文件已存在则跳过),不会覆盖人工修改。
  • 本机 cargo build 出的 .dylib 只能验证编译,不能进镜像。

与 ipass-all 的差异速查

项 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 条

管理台架构定案、壳契约 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/),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。