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