新增
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 不迁入的理由
133 lines
7.9 KiB
Markdown
133 lines
7.9 KiB
Markdown
# 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`
|