- OAUTH_ISSUER / IDP_BASE / REDIRECT_URI 全部由 :188 改 :88 - 同步层退役后账号表走共享 accounts/ 子目录(IPASS_USERS_PATH),本清单已含该挂载 Co-Authored-By: Claude <[email protected]>
13 KiB
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,subPathsso(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 Serviceapp-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(挂 PVCnginx-data的accounts/subPath,envIPASS_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:本部署挂 PVCnginx-data的accounts/子目录到/usr/local/nginx/accounts,envIPASS_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/),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。