 sun
|
c4269086fa
|
docs: 按实际代码基线重写 v0.3.0 实施步骤书
初版方案基于四个与代码不符的前提,直接执行会返工:一是要求重命名 AdminSessionMiddleware,但该中间件在本仓库根本不存在(实际只有 Bearer 体制的 RequireAdmin),导致低风险重构实为新建 Cookie 会话层的破坏性变更;二是引用 promhttp.Handler 与 AdminSPAPageHandler/AdminLoginPageHandler,这些 API 项目里都没有(指标走自研 telemetry.Meter.Handler);三是漏点只列 /metrics 与 /health,实测还漏了聚合度最高的 /dashboard 以及 normal 模式仍可达的 /api/setup/status;四是把旧 API 路径迁移写成 301 重定向,而 301 会把 POST 降级为 GET 且被浏览器永久缓存。
重写要点:删去会话与 CSRF 阶段(Bearer 认证免疫 CSRF,CORS 已对非白名单 Origin 返回 403),改为先修 RequireAdmin 空凭证静默放行的前置缺口并新增可选 admin_key 实现管理/业务凭证隔离;/health 拆为匿名 /healthz 与鉴权 /health(必须同批上线以免探针空窗);/metrics 支持 METRICS_ALLOW_CIDR 内网白名单且非白名单返回 404;旧 API 路径改用别名而非重定向,实现零破坏兼容。同时保留初版正确的部分:分阶段与每阶段可回归原则、InstallGuard 不动、Docker 网段警告、v0.4.0 规划与发布流程。附录 A 逐条列出与初版的差异,附录 B 说明不做 Cookie 会话的理由。
另外清理初版的格式问题:补齐 Markdown 标题层级与代码围栏,移除全文的不间断空格(会导致命令粘贴失败)。
|
2026-10-04 00:38:07 +08:00 |
|