Files
sso/CLAUDE.md
adminandClaude 24e72cd8d3 docs+deploy: 外部入口统一 :88(:188 的 NAT 已停用)
- OAUTH_ISSUER / IDP_BASE / REDIRECT_URI 全部由 :188 改 :88
- 同步层退役后账号表走共享 accounts/ 子目录(IPASS_USERS_PATH),本清单已含该挂载

Co-Authored-By: Claude <[email protected]>
2026-11-12 19:03:05 +08:00

13 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 建目录,业务写盘才炸) ⚠️ 另挂 accounts/ 子目录:那是与 ipass-all 共用的账号表(见下「共享账号表」), 两个部署指向同一份 users.json
  • 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_* / IPASS_USERS_PATH):nginx 默认剥离环境变量, 漏一条 = worker 里恒空,新增 env 必须同步加进这里。 ⚠️ IPASS_SYNC_* 三条仍留在 nginx.conf 里(回滚成本低:只要把 manifest 的 env 加回来就能恢复同步层),只是 manifest 不再设它们 ⇒ 同步层已退役。 ⚠️ IPASS_USERS_PATH 也只在 nginx.conf 里放行,真正取值来自 manifest 的 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:88(路由器 :88 → 192.168.1.26:30089 → pod 18098);NodePort 本身明文,TLS 由上游终结。 ⚠️ :188 的 NAT 已于 2026-11 在路由器停用(:188 会被直接 RST ⇒ 客户端报 ECONNREFUSED),清单/issuer/文档里一律写 :88。
  • OAUTH_ISSUER 必须与浏览器/第三方实际访问地址逐字一致(清单里写死 :88)。
  • ⚠️ WXWORK_REDIRECT 必须是 https://i28868828dm.mayishangshu.cn:88/portal/wxwork/callback ——企微后台该应用(agentid 1000017)的可信域名按 :88 配置,改成其他端口(含 已停用的 :188)会被 authorize 页拒(redirect_uri 与可信域名不一致)。
  • 同步层已退役:manifest 不再设 IPASS_SYNC_* 三条(nginx.conf 里仍留着放行, 只为回滚方便)⇒ 账号表改为与 ipass-all 共用 accounts/users.json (挂 PVC nginx-data 的 accounts/ subPath,env IPASS_USERS_PATH 指定)。 管理台点「同步」按钮会看到「未配置 IPASS_SYNC_SIDE / IPASS_SYNC_PEER / IPASS_SYNC_TOKEN」 ——这是预期的(同步层 fail-closed,不影响任何写操作)。 ⚠️ 共享表缺失时两个 pod 都不会建表(内核 fail-closed)⇒ 切换前必须先跑合并作业 (../ipass-all/scripts/merge-users-tables.py)产出共享表,否则全员 401。 ⚠️ 共享目录必须可写(<users.json>.lock 锁文件要建得出来)。

共享账号表(与 ipass-all 共用,2026-11-11)

  • 只有一份 users.json:本部署挂 PVC nginx-data 的 accounts/ 子目录到 /usr/local/nginx/accounts,env IPASS_USERS_PATH=/usr/local/nginx/accounts/users.json 指定路径 ⇒ 与 ipass-all 共用同一份文件(不再是「两表 + 双向同步」)。
  • ⚠️ IPASS_USERS_PATH 只在进程启动时读一次 ⇒ 改它必须重启 pod; nginx.conf 还要 env IPASS_USERS_PATH; 放行,否则 worker 里恒空。
  • ⚠️ 切换前必须先跑合并作业(../ipass-all/scripts/merge-users-tables.py)产出 accounts/users.json:共享模式下文件缺失 ⇒ 两个 pod 都不会建表(内核 fail-closed) ⇒ 全员 401。任何路径都不得造出空的 users.json(空表 ⇒ 换入空索引 ⇒ 全员 401)。
  • ⚠️ 共享表「存在但为空 {}」与「缺失」同等拒绝(不建表、不播种)⇒ 扫描线程与手动 reload 也会拒绝换入空表、保留旧索引 ⇒ 空表不会导致全员 401。
  • ⚠️ 共享目录必须可写:<users.json>.lock 锁文件要建得出来 ⇒ accounts/ 由 initContainer 以 10106 预建(kubelet 对不存在的 subPath 目录 按 root 建 ⇒ 10106 写不进 ⇒ 业务写盘时才炸)。
  • 锁序(唯一):进程内互斥 → 跨进程 fcntl → 共享内存 file_lock → map 锁。 细节与共享知识见 ../ipass-all/CLAUDE.md 与 ../ipass-core/CLAUDE.md。
  • ⚠️ 发版顺序铁律:先上新镜像,再 apply 本清单(两个仓都一样)。 ipass-sso 没有 conf-patch ⇒ 生效 nginx.conf 完全来自镜像 ⇒ 「清单 tag 是新的」不能证明 conf 里有 env IPASS_USERS_PATH; ⇒ 推 tag 前必须确认新 tag 是用含新 conf 的树构建的, 且 rollout 后要复核容器里的生效 conf(runbook §5 硬门槛①)。 ⇒ 本清单 image: 有 2 处,都要改成新 tag。
  • ⚠️ ipass-sso 的 users_path() 首次读取发生在 worker ⇒ nginx.conf 必须在 main 上下文 放行 env IPASS_USERS_PATH;(nginx 会剥掉 worker env)⇒ 缺了就恒空 ⇒ 静默分叉。
  • ⚠️ 共享账号表走 NFS:跨 pod 的写可见延迟没有 ≤3s 硬保证 ⇒ 以「对端最终出现重建日志」为准。
  • ⚠️ 旧同步 token 的明文仍在本仓 git 历史里(工作树已清干净,历史改不了)。 同步层已退役 + 三个同步 env 已从清单删除 ⇒ 接收端 fail-closed ⇒ 该 token 现无实际权限; 但 回滚会重新激活它(回滚用的旧清单里就是它)⇒ 回滚前评估是否先轮换; 若该值在别处被复用 ⇒ 必须轮换。

边界 / 常见坑

  • 改 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(账号表 subPath = accounts,两边相同) 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/),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。