Files
sso/docs/maxkey-migration-analysis.md
T
ssw 8e9becaad7 docs: 插件化架构分析与迁移/任务文档,同步 CLAUDE.md 与路线图
新增
  docs/plugin-architecture-analysis.md  内核/插件边界分析、P 阶段拆分与装配契约
  docs/maxkey-migration-analysis.md     MaxKey 端点别名与 context-path 归一化对齐
  docs/task-plan.md                     阶段任务清单与验收口径

同步
  CLAUDE.md    crate 清单与目录地图:plugin-domain 标为「已迁入示例」,
               plugin-llm 明确「不迁入」(LLM 上游代理与配额计费属流量层,
               与本服务「身份层」的定位分界不变,半成品已从 workspace 移除);
               回归口径五套 → 六套;测试配置端口范围 18093-18099
  README.md    结构树补 plugin-domain,端口范围同步
  roadmap.md   P2 标记为已完成(部分)并写明 plugin-llm 不迁入的理由
2026-09-13 10:25:48 +08:00

133 lines
7.9 KiB
Markdown
Raw 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.
# MaxKey 能力迁移分析(refs/maxkey → 本项目)
> 分析日期:2026-09-12
> 参照物:`refs/maxkey/`(dromara MaxKey,Java/Gradle,44 张表的完整 IAM/IDaas)
> 本体:本项目(nginx 动态模块 + Rust,OAuth2/OIDC IdP + IAP,文件+共享内存存储,零外部依赖约定)
## 结论(先看这里)
MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议语义**(直接可移植)、**域模型设计**(表结构即最佳实践文档)、**安全运营闭环**(锁定/审计/策略,本项目完全缺失)。按本项目的硬约束(无 DB、无 Redis、零新增依赖、"身份层不做流量层"),能力分四档:
| 档位 | 数量 | 判断标准 |
| --- | --- | --- |
| P0 建议迁移 | 7 项 | 纯逻辑可 Rust 重写,且补齐 IAP 安全短板 |
| P1 视需求迁移 | 5 项 | 有外部依赖或体积成本,先评估再动 |
| P2 低优先 | 5 项 | 有价值但当前定位用不上 |
| 不建议迁移 | 6 项 | 重度绑定 Java 生态,或与"身份层"定位冲突 |
---
## P0:建议迁移(纯逻辑,直接补短板)
1. **RS256 + JWKS 签发/验签** — 已在 roadmap v2 规划。
MaxKey 实证:`maxkey-commons/maxkey-crypto/`(JWS/JWE 签发验签、X509/keystore)。
抄它的点:JWKS 输出格式、`kid` 轮换语义(旧公钥保留至最后一批旧令牌过期)。
2. **登录失败锁定** — 本项目目前**无任何防爆破机制**,这是 IAP 场景最大安全缺口。
MaxKey 实证:`mxk_history_login` + 登录失败计数策略。移植成本极低:`users.json` 里加
`failed_count / locked_until` 字段,共享内存同步,无需新表。
3. **登录历史 / 审计日志** — MaxKey 用 `mxk_history_login` / `mxk_history_login_apps` /
`mxk_history_event` 三张分表。本项目可落成 append-only JSONL 文件(`data/audit/`),
记录:时间、用户、IP、UA、grant 类型、成功/失败。管理台加一个只读列表即可。
这是"真实流量看板"问题的 SSO 侧基础设施。
4. **密码策略** — MaxKey:`mxk_cnf_password_policy`(长度/复杂度/有效期/历史密码)。
本项目最小集:长度 ≥ 8 + 重置时强制改密 + 可选复杂度,配置进现有 `config.rs`。
纯校验逻辑,半天工作量。
5. **TOTP 双因子** — MaxKey:`maxkey-starter-otp/`(HOTP/TOTP 算法族)。
纯算法(RFC 6238,HMAC-SHA1 + 30s 步长),Rust 用已有 `sha2`+手写 HMAC 即可,
不新增依赖。用户侧字段:`totp_secret` + `totp_enabled`。注意配套要做**绑定流程**
(otpauth:// URI 展示)与登录时的第二因子校验分支。
6. **图形验证码** — MaxKey 用魔改 kaptcha(Java 生态绑定,不抄实现)。
本项目直接生成 **SVG 验证码**(数字/字母干扰线),零依赖可做,
挂在 `/oauth/authorize` 登录页与找回密码入口。
7. **在线会话管理 / 踢出** — MaxKey:`SessionController`(在线会话查看/踢出)。
本项目 session 已在共享内存(`session.rs`),天然支持:管理台列出活跃会话 +
单条踢出 + 全端下线。改动量小,运维价值高。
---
## P1:视需求迁移(先评估成本)
8. **SCIM 2.0 身份供给** — MaxKey:`maxkey-web-apis/maxkey-web-api-scim/`
(User/Group/EnterpriseUser/ServiceProviderConfig 完整资源模型)。
价值:外部系统(HR、上游 IdP)可用标准协议推送用户进来。资源模型清晰,
就是 CRUD,落 `users.json`/`groups` 现有模型可行;工作量主要在过滤语义
(`userName eq "..."`)与分页。**若确定有上游系统对接需求再做。**
9. **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路,
补 `/cas/sso/validate`、`/p3/proxyValidate` 等端点,让 CAS 客户端也能直连。
票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。
10. **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但
Rust 侧需要 LDAP 客户端库(`ldap3` 依赖体积不小,且需 vendor)。
替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。
11. **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey:
`maxkey-synchronizers/maxkey-synchronizer-<name>/`。钉钉/企微/飞书三个就是
HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。
适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。
12. **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider
(阿里云/腾讯云/网易云信,`maxkey-starter-sms/`)。依赖外部发信通道;若做,
建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。
---
## P2:低优先(有价值,当前定位用不上)
13. **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/`
(含 `mxk_user_passkeys` 表)。方向正确但 Rust 零依赖下验签链很重
(COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。
14. **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。
本项目作为**企业内部身份层**,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。
15. **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量
数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。
16. **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。
TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。
17. **ip2location 归属地解析** — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。
---
## 不建议迁移(明确不做)
| 能力 | 理由 |
| --- | --- |
| Kerberos/SPNEGO、Ws-Federation | 重度绑定 JAAS/GSSAPI;IAP 场景可用 nginx 层方案替代 |
| Spring Cloud Gateway 网关(maxkey-gataway) | 本项目定位就是"身份层不做流量层",直接冲突 |
| 多租户(mxk_institutions) | 放大全链路复杂度,当前单租户足够 |
| 树形组织架构 | roadmap 已有明确"不做"决定,维持 |
| MyBatis/JPA 持久层、44 张表整体照搬 | 只抄域模型设计思路,不抄存储形态(本项目文件+共享内存) |
| kaptcha、管理台前端(maxkey-web-frontend) | Java/前端技术栈绑定,重写无参考价值 |
---
## 域模型参考(照抄设计而非表)
MaxKey 的 44 张表里,对本项目最有参考价值的三组设计:
- **应用-协议明细分离**:`mxk_apps` + `mxk_apps_oauth_client_details`/`saml_v20_details`/
`cas_details`/…。本项目现有 `oauth_clients.rs` 已是同构;未来若补 CAS/SCIM,
沿用"应用主表 + 协议明细"的形状,不要往应用主表里塞协议字段。
- **审计三分表**:登录历史 / 应用登录历史 / 事件,按时间append。对应 P0-3。
- **配置表与业务表分离**:`mxk_cnf_*`(密码策略、短信、邮件、LDAP 上下文)独立成表。
本项目对应物是 `config.rs`,未来配置项变多时按此分组,不要混进业务数据。
## MaxKey 源码证据索引
- 认证方式总入口:`maxkey-authentications/maxkey-authentication-provider/…/authn/provider/impl/`
- OAuth2/OIDC 端点:`maxkey-protocols/maxkey-protocol-oauth-2.0/…/endpoint/`(discovery 在 `wellknown/`)
- SCIM:`maxkey-web-apis/maxkey-web-api-scim/`
- 会话管理:`maxkey-webs/maxkey-web-mgt/…/web/access/controller/SessionController`
- 同步连接器:`maxkey-synchronizers/maxkey-synchronizer-{ad,ldap,jdbc,dingtalk,workwechat,feishu}/`
- OTP 算法:`maxkey-starter/maxkey-starter-otp/`
- 全量表结构:`sql/v4.2.0/maxkey.sql`