定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。 代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖) - IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password 四种 grant,含 discovery / introspect / userinfo / jwks 占位 - IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖 - MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段 - 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存 - 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap, Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话 配置(source/conf) - nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式) - nginx.test.conf 本机验证配置(明文 18095-18099) - tls/README.md 证书约定与公钥比对校验 前端(source/www/admin.html) - 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计 测试与脚本 - tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿 - tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势 - scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录 文档 - README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查 - docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
17 KiB
CLAUDE.md
给 AI 协作者(Claude Code / WorkBuddy 等)的项目说明。人读文档见 README.md,
设计细节见 docs/design.md,待办见 docs/roadmap.md。
一句话定位
统一认证服务(SSO):nginx 动态模块(ngx-rust)+ Rust,单进程,无数据库 / Redis / MQ。
- IdP:OAuth2.0 / OIDC 授权服务器 —— 发 token、登录、introspect、discovery。
- IAP:nginx
access阶段门禁,把身份以X-Auth-*注入后端,业务系统零改造。 - 协议对齐 MaxKey:端点别名 + 扁平响应,照抄 MaxKey 文档的应用可直接对接。
状态 = data/ 下两个 JSON(users.json / oauth_clients.json);
客户端注册表与会话常驻共享内存,热路径零文件 I/O。
定位差异(不要越界):本项目不做动态域名转发、LLM 上游代理、用量计费。 代码由内部网关项目剥离而来(
refs/ipass,仅本地参考、不入库)。 因此这里没有$proxy_backend_addr这类动态上游变量,proxy_pass由 nginx 配置写死。
构建与运行(踩过的坑都在这)
硬约定:ngx 必须用 vendored 源码,不能走 crates.io,也不能走 git
- crates.io 直接编译失败。
ngx = "0.5"(crates.io 0.5.1)只发布了配置阶段接口HttpModule; 请求阶段 API(add_phase_handler/HttpPhase/HttpRequestHandler)尚未发版, 报unresolved imports ngx::http::HttpPhase。 - git 依赖会永久挂起(最隐蔽的坑)。
ngx-rust挂了一个指向完整 nginx 仓库的 submodule, cargo 解析 git 依赖时会update_submodules去克隆几十 MB 的 nginx 仓库。国内网络下卡死 —— 实测 5 分钟 0% CPU、无网络活动、无产物,sample抓栈停在GitCheckout::update_submodules → fetch → wait4。 - 正解:源码 vendor 到
source/rust/vendor/ngx-rust/(已剥离.git,103 个文件 / 696K),Cargo.toml用path依赖;[workspace] exclude = ["vendor/ngx-rust"]处理嵌套 workspace。
为什么要 --with-pcre=<绝对路径>,以及路径不能随便挪
ngx-rust 的 nginx-sys/build/main.rs 会从 objs/Makefile 抽出编译参数去预处理 ngx_core.h,
其中带 -I <pcre>/src/。所以:
- nginx 的
./configure --with-pcre=...路径,与模块编译时的源码树必须同一份; - 把源码树
mv到别处后,必须重新./configure && make(只改环境变量不够)。 不重新 configure 的报错形态是模块编译期:fatal error: 'pcre2.h' file not found(-I还指着旧路径)。
本机构建
cd source/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib # macOS,bindgen 需要
export NGINX_SOURCE_DIR=/tmp/sso-build/src/nginx-1.30.4
export NGINX_BUILD_DIR=/tmp/sso-build/src/nginx-1.30.4/objs
cargo build --release
# 产物:source/rust/target/release/libsso_gateway.{dylib,so}
冷编译约 40 秒,增量 1~2 秒。
source/rust/build.rs不可删:macOS 必须-undefined dynamic_lookup——动态模块引用的 nginx 运行时符号由主程序在load_module时提供,链接时必然未定义。ngxcrate 的 build.rs 也设了,但rustc-link-arg只对设置它的 crate 生效、不传给依赖方。
跑测试
bash scripts/run-local-e2e.sh # 三套 e2e 全跑(自动起停 nginx + demo 系统)
bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
目录地图(改代码前先看这里)
| 路径 | 职责 |
|---|---|
source/rust/src/lib.rs |
模块入口:指令解析、共享内存建表(state_zone_init,fork 前一次)、变量注册、两个阶段处理器(IAP access / API content)、init_process 播种 admin |
source/rust/src/api.rs |
API 统一分发器:路由表(精确匹配)+ 鉴权分流(Guard::Public/User/Admin)+ 全部 handler |
source/rust/src/oauth.rs |
OAuth2 AS 全部逻辑:client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析 |
source/rust/src/oauth_clients.rs |
接入方注册表(reload_shm / get / all / upsert / delete / view) |
source/rust/src/users.rs |
账号:播种 admin、创建、改密、重置 Key、角色、部门/用户组校验 |
source/rust/src/session.rs |
管理员登录会话(sess: 键 + HttpOnly Cookie,滑动续期) |
source/rust/src/state.rs |
共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 |
source/rust/src/store.rs |
JSON 原子读写(.tmp + rename)+ 跨 worker 文件锁 + data 目录 |
source/rust/src/http.rs |
请求辅助:参数合并、两段式请求体读取、JSON 响应输出 |
source/rust/src/util.rs |
随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志 |
source/rust/src/config.rs |
全部策略常量:TTL、长度上限、共享内存键前缀、cookie 名 |
source/rust/src/models.rs |
User / OAuthClient 结构;groups 用宽容反序列化(同时接受 ["a"] 与 "a,b") |
其余:
| 路径 | 职责 |
|---|---|
source/conf/nginx.conf |
生产模板:IdP + 管理台 443、IAP 子域、80→443、含 auth_sub 的日志格式 |
source/conf/nginx.test.conf |
本机/CI 验证配置(明文 18095-18099),scripts/run-local-e2e.sh 会渲染它 |
source/conf/tls/README.md |
证书约定、acme.sh 签发、公钥比对校验(ECC 不能用 openssl rsa -modulus) |
source/www/admin.html |
管理台单页(三个 tab:账号 / 接入方 / 接入指南),纯静态 + fetch |
source/data-seed/ |
种子模板(进版本库):oauth_clients.json + users.json.example |
source/data/ |
运行时数据(不进版本库,含真实口令散列与 API Key) |
scripts/seed-data.sh |
物化数据目录:data-seed/ → data/,并生成 admin/alice 真实散列 |
tests/demo-system/ |
演示用「简单业务系统」(Python 标准库),验证两种接入姿势 |
refs/ |
不入版本库:refs/ipass(来源项目)、refs/MaxKey(协议对齐参考) |
容器内路径约定:模块装 /usr/local/nginx/modules/,data 默认 /usr/local/nginx/data
(sso_data_dir 可覆盖)。别在宿主机上按容器路径找文件。
核心机制(理解这几条就够)
-
请求分流靠「location 开关 + 阶段」。阶段处理器注册在 http 主配置上(全局生效), 必须靠 location 指令收敛,否则管理台与静态页也会走认证逻辑:
- IAP(access,
sso_iap on):取 Bearer 或sso_sidcookie → 校验 → 写$auth_*→ 放行/401。 - API/协议(content,
sso_api on):先异步读请求体再分发(access 阶段拿不到 body)。
- IAP(access,
-
共享内存是运行期真源,JSON 文件只是持久化副本。所有写操作同时写 shm 与文件 (write-through)。写穿不是优化,是正确性要求:漏掉
sync_shm等于配置没生效, 而且没有缓存 TTL 兜底——漏了就一直是错的,直到重启。- ⚠️ 语义代价:绕过 API 直接改
data/*.json不热生效,需重启或走管理接口。
- ⚠️ 语义代价:绕过 API 直接改
-
两套身份、两套会话,别混:
- 终端用户:共享内存
sso:前缀 + Cookiesso_sid(OAUTH_SESSION_COOKIE)。 - 管理员:共享内存
sess:前缀 + Cookiesso_admin_session(COOKIE_NAME)。 键前缀还有fail:(登录失败计数)、oac:(授权码)、ocl:(接入方登记)。
- 终端用户:共享内存
-
nginx 变量注册必须两步,缺一步就读成空:
- 先
ngx_http_add_variable(登记名字 +get_handler),再ngx_http_get_variable_index(取写入槽位)。只调后者:变量被推进cmcf->variables但get_handler=NULL,ngx_http_variables_init_vars会直接exit()报「unknown variable」。 - 只调前者:拿不到 index,
r->variables[idx]没地方写。 - 注入变量不能标
NGX_HTTP_VAR_NOCACHEABLE,否则ngx_http_get_flushed_variable每次读取都清缓存并回调 get_handler,而 handler 拿不到注入值 → 变量读成空。 - 注册时机在 preconfiguration:request 阶段才
add_variable时,proxy_pass http://$auth_user之类早就解析失败了。
- 先
-
IAP 防伪造靠「覆盖」而不是「过滤」。
X-Auth-*是网关断言,由proxy_set_header写入,客户端伪造的同名头会被覆盖。新增注入头时必须同时在这两处加:lib.rs的AUTH_VAR_NAMES/set_auth_vars,以及每个受保护 location 的proxy_set_header。 -
IAP 重签令牌的 aud / scope 有专用常量:
IAP_TOKEN_AUDIENCE = "sso-gateway"、IAP_TOKEN_SCOPE = "openid profile email"。改动会影响所有依赖方,改前先全局搜索。 -
口令哈希必须逐位一致:
sha256("salt:password")之后再迭代HASH_ROUNDS(=1000) 次sha256(x + salt)。注意第一轮有冒号。 改轮数或拼接顺序会让存量users.json全部登录失败 (已用独立 Python 实现逐字节核对;scripts/seed-data.sh里是同一套算法的 Python 版)。
硬约定(改代码必须遵守)
安全与生命周期
- 不要在 worker 里 panic。
Cargo.toml设了panic = "abort"——一次 panic 直接打死整个 worker (不是 500,是 worker 进程消失)。热路径禁止unwrap()/expect()/ 越界索引, 错误一律走Result+ 显式降级。管理接口也照此办理。 - 不要在 worker 里起子进程或 shell。文件落盘靠
store的原子写(.tmp+rename)。 - 热路径禁止同步文件 I/O。
users::get会读文件 + 全表解码,只能用在管理接口, 不要顺手用在 IAP 鉴权(IAP 走共享内存会话)。
改配置/接口时的硬规矩
- 新增接口三步:① 在
api.rs写 handler,统一用http::ok/fail; ② 在route()表加一行,Guard选Public/User/Admin; ③ 涉及接入方/账号变更的,必须调对应的sync_shm。鉴权由分发器统一兜底, 不要在单个 handler 里重复实现。 - 所有写操作必须同时更新 shm 与 JSON 文件。只写一边 = 「重启后回滚」或「改了不生效」。
- 写共享内存失败必须出声。
state::put_*返回false(zone 满 / 分配失败)时要log_err(带对象标识与后果);reload_shm要核对「期望条数 vs 实际装载」。别丢掉返回值—— 没有回源兜底,写失败就是「刚建好却调不通,日志里什么都没有」,属于最难查的一类形态。 env白名单必须在nginx.confmain 上下文。缺env OAUTH_ISSUER;会导致 discovery 的issuer与第三方实际校验的值不一致——这是最容易踩的坑。client_body_buffer_size必须大于最大 API 请求体,否则超出的部分落到临时文件, 而collect_body只读内存 buf → body 被静默截断(表现为 JSON 解析失败)。 当前管理 server 设 1m。- JSON 空数组必须序列化成
[]。serde_json对空Vec本来就输出[], 但别用json!({})顶替列表字段——前端直接.map/.filter,拿到{}会报错。 - 改
source/rust/或source/conf/后必须重启 nginx。动态模块在load_module时载入, reload 不会重新加载.so;data/是写穿语义,重启后从文件重建。 location @name不能写成location = @name。带=时 nginx 会把它注册成 「精确匹配普通 location」而clcf->named仍为 0,于是error_page 401 = @oauth_login的内部跳转在named_locations[]里找不到该 location → 500。- 自建 nginx 不能
--without-http_rewrite_module:return/error_page内部跳转都来自它。 - 前端隐藏元素必须靠
[hidden]{display:none!important}兜底:author 样式的display会盖掉 UA 的display:none。
文档与仓库卫生
- 不要在文档里写真实口令、API Key 或内网拓扑明细。
- 不要把
source/data/(含口令散列与全部 Key)提交进版本库;refs/、.workbuddy/、target/已忽略。 - 改行为后同步更新
docs/design.md对应小节;待办项写进docs/roadmap.md,别散在代码注释里。
排障速查
| 现象 | 原因 / 处置 |
|---|---|
| 改了代码但行为没变 | 90% 是没重启。动态模块 load_module 时载入,reload 不重载 .so |
| worker 进程静默消失 / 全站 502 | worker 里 panic 了(panic = "abort")。看 error.log 的 panic 栈,多半是热路径 unwrap() |
编译报 unresolved imports ngx::http::HttpPhase |
又用 crates.io 的 ngx 0.5.1 了。必须用 source/rust/vendor/ngx-rust |
cargo build 卡住数分钟 0% CPU |
又把 ngx 改回 git 依赖了 —— 它挂的 submodule 会去克隆完整 nginx 仓库 |
链接报 ld: symbol(s) not found |
source/rust/build.rs 的 -undefined dynamic_lookup 被删了(macOS 必需) |
nginx 启动即报 unknown "auth_user" variable |
变量注册漏了 add_variable 那一步(见「核心机制」第 4 条) |
proxy_set_header X-Auth-User $auth_user; 注入成了空 |
变量被标了 NGX_HTTP_VAR_NOCACHEABLE,或注册时机不在 preconfiguration |
授权码换发报 invalid_client |
接入方注册表没热加载(写操作漏 sync_shm),或回调地址逐字符不一致 |
管理接口 401 |
管理员会话 Cookie 缺失/过期(重启会清空会话,属预期) |
终端用户 401 但 Cookie 看着在 |
两套身份别混:终端用户看 sso_sid,管理员看 sso_admin_session |
| 新增客户端「管理台显示已保存,授权时报未知 client_id」 | 写穿共享内存时把旧值原样写回了。tests/admin-oauth-clients-e2e.sh 第 4 组专门盯这个 |
429 登录失败次数过多 |
同一 IP 窗口内失败次数超限(fail: 前缀),等窗口过期或重启 |
第三方报 issuer mismatch |
env OAUTH_ISSUER; 缺失,或值与浏览器实际访问的 host 不一致 |
| 跨子域登录不生效(每个子域都要重新登录) | 没设 OAUTH_COOKIE_DOMAIN(不设 = 主机级 cookie) |
| 证书看着没过期却报 TLS 错 | 先 openssl s_client -servername <域名> 看链路实际收到的证书;acme.sh 产物在 ~/.acme.sh/,与 conf/tls/ 是两份,续期后必须拷过去再 reload |
--with-pcre 源码树挪位置后编译报 pcre2.h not found |
见「构建」小节:必须重新 ./configure && make |
常用操作
# ---- 本机 ----
bash scripts/run-local-e2e.sh # 三套 e2e 全跑
bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
bash scripts/seed-data.sh # 物化 source/data/
bash scripts/seed-data.sh --force # 重建 users.json(丢已有账号)
# 手工打几个关键接口(网关在跑时)
curl -s http://127.0.0.1:18098/.well-known/openid-configuration | python3 -m json.tool
curl -s -D- -o/dev/null -X POST http://127.0.0.1:18098/login \
--data-urlencode 'username=alice' --data-urlencode 'password=alice123' # 看 Set-Cookie: sso_sid
curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me
# ---- 生产 ----
/usr/local/nginx/sbin/nginx -t && /usr/local/nginx/sbin/nginx # 改完先 -t 再起
边界:不要做的事
- 不要引入数据库、Redis、消息队列或额外常驻进程 —— 本项目的价值就是单进程、零依赖。
- 不要把流量层能力搬回来(动态域名转发、LLM 上游代理、用量计费)。这是与来源项目的定位分界。
- 不要在
source/data/里手工改文件后期待热生效 —— 共享内存才是运行期真源,改文件需重启。 - 不要把
source/data/提交进版本库,也不要在refs/里提交参考项目。 - 不要重写整个
nginx.conf—— 它很短,逐点修改。 - 不要在未确认需求前动
source/data/users.json,那会直接影响登录。 - 不要为了「顺手」把 HS256 换成 RS256(或反之):签名算法是给第三方的契约,
切换要走
docs/roadmap.md里的 v2 计划(新旧并行 +kid轮换)。 - 测试不要复用生产 data 目录:用
source/data/+ 非特权端口(18095-18099),不要占用 80/443。