新增
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 不迁入的理由
4.9 KiB
4.9 KiB
任务计划:MaxKey 能力迁移落地(2026-09-12)✅ 已全部完成(2026-09-13)
依据:
docs/maxkey-migration-analysis.md(P0×7)+docs/roadmap.md(v2 + 用户管理界面) 保障手段:每项实现都带 e2e 断言;可借鉴的 MaxKey 测试用例逐项标注。 约束:零新增 crates.io 依赖(SHA-1、RSA、大数运算全部手写);存储沿用 users.json + 共享内存,不引入 DB。
执行顺序与验收
| # | 任务 | 落点 | 验收(e2e 断言) | 借鉴的 MaxKey 测试 |
|---|---|---|---|---|
| ✅ 1 | 登录失败锁定(账号维度) | models/users/api/oauth/config | 连错 5 次锁定 600s;锁定期间密码正确也 423;到期自解锁;管理台可解锁 | mxk_history_login 失败计数语义 |
| ✅ 2 | 密码策略 | config/users | 短于 8 位拒;纯数字/纯字母拒;改密/建号/重置三入口一致 | mxk_cnf_password_policy 字段 |
| ✅ 3 | 审计日志 JSONL | 新模块 audit.rs + api | 登录成败/发令牌/管理操作都有行;管理台可查;>5MB 自动轮转 | mxk_history_login/event 三分表字段 |
| ✅ 4 | 在线会话查看/踢出 | state/api | sess:/sso: 均可列出(含过期过滤);按 token 或按用户踢;被踢会话立即 401 | SessionController 列表/踢出 |
| ✅ 5 | SVG 图形验证码 | 新模块 captcha.rs + oauth/api | 开关 OAUTH_CAPTCHA=1 时登录页出验证码、错码拒绝;缺省关(存量 e2e 不回归) |
kaptcha 行为(不用其实现) |
| ✅ 6 | TOTP 双因子 | 新模块 otp.rs + users/api/oauth | RFC 4226/6238 标准向量通过;绑定→启用→登录必须带码;码错/缺失拒绝 | maxkey-starter-otp:HmacOTPTest / TimeBasedOTPTest(Base32 seed + 30s 步长 + 6 位截断) |
| ✅ 7 | RS256 + JWKS(roadmap v2) | 新模块 rsa.rs + oauth | JWKS 端点出 n/e(base64url);本地验签通过;alg=none / alg 混淆拒绝;HS256 存量可验;新 e2e 覆盖 | JWS/JWE 签发验签语义(maxkey-crypto) |
| ✅ 8 | 用户管理界面 | www/admin.html | 行内改角色/部门/组;筛选;批量加组;最后管理员禁用降级;组名逗号即时切分 | MaxKey 用户管理页交互 |
| ✅ 9 | 全量回归 + roadmap 更新 | tests/ + roadmap.md | 四套 e2e 全绿;roadmap 勾选 | — |
关键设计决定(偏离/补充说明)
- 验证码缺省关闭(
OAUTH_CAPTCHA=1开启):验证码图形无法被 curl e2e 读取, 缺省开会让全部存量 e2e 失效;生产开启后,浏览器路径正常出码。 - 锁定是账号维度(users.json 新字段
failed_count/locked_until),与既有fail:<ip>IP 维度限速叠加;登录低频路径直接读文件,符合现有分层。 - TOTP 的 HMAC-SHA1 手写(sha2 crate 没有 SHA-1):RFC 6238 主流 authenticator 默认 SHA1/6 位/30s,必须兼容 Google Authenticator。
- RSA 手写范围:
modpow(Knuth D 除法)+ Miller-Rabin 素性 + PKCS#1 v1.5 签名。 私钥存OAUTH_JWK_DIR/active.jwk.json(分量的 base64url JSON,非 .pem—— 手写 ASN.1/PEM 编解码收益低,roadmap 的.pem命名放宽,其余轮换语义照做)。 - 管理台密码策略例外:种子管理员
admin/123456不走 create 校验(历史行为), 但一旦重置即受新策略约束。
完成情况(2026-09-13 收尾)
- 9/9 全部完成;回归从「三套」扩为五套(
scripts/run-local-e2e.sh,全绿 rc=0):- OAuth2/OIDC 基线;2. MaxKey 互通 + demo 接入;3. 管理接口·OAuth 接入方(31 项);
- RS256 + JWKS 本地验签(14 项,含篡改 / alg=none / alg 混淆拒绝);
- 管理接口·账号批量维护(39 项,新增)。
- RS256 内核为手写零依赖 RSA-2048(Miller-Rabin + 扩展欧几里得模逆 + Montgomery CIOS +
CRT + PKCS#1 v1.5),经独立二进制 × Python
pow()互证 3 轮随机密钥 roundtrip 全绿。 因cargo test链接 nginx 符号,单测走/tmp/*_standalone.rs+ rustc 方案。 - 批量维护新增
POST /api/admin/users/batch(单次文件锁内组合:加组/移组/设部门/改角色/解锁, 「至少保留一个管理员」红线在批量口径下同样生效)。 - 用户管理界面:筛选(关键字/角色/部门/组/已锁定)、勾选批量条、行内编辑 (角色下拉即改、部门/用户组点击就地编辑,Enter 保存 / Esc 取消 / 失焦提交)。
- 凭据治理:本地 e2e 口令与签名密钥统一进
.env(gitignore,模板.env.example), 脚本经scripts/load-env.sh加载,命令行不再出现密钥。
遗留(不阻塞,属后续打磨)
- 用户组「标签输入」交互(当前为逗号分隔输入框,与
check_groups分隔符约定一致,功能等价)。 - 统计卡点击下钻到筛选列表。
- 「最后一个管理员」在前端禁用降级选项(当前为 confirm + 后端红线兜底 + 失败回滚)。