# 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`)。 ## 本机构建(只做编译检查) ```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:macOS 只出 .dylib,不能进镜像 ``` nginx 源码树不可 `mv`(`objs/Makefile` 里的 `-I` 是绝对路径,挪了要重新 configure)。 这里的 `cargo build` 只能验证「编得过」——**产物是 macOS 的 `.dylib`,进不了 Linux 镜像**, 原因见下节。 ## 容器构建 / 部署 ```bash 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。 ⚠️ 共享目录必须**可写**(`.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。 - ⚠️ 共享目录必须**可写**:`.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/`),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。