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

189 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。
⚠️ 共享目录必须**可写**(`<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/`),已按本仓实际情况重写——看到别的文档也这么写,八成是同源拷贝,别照抄。