简介

本文件面向开发者，系统化说明 DouPHP 的用户认证中间件体系，覆盖前台、API 与后台管理端的会话管理、登录态检查、权限验证与角色授权流程。文档重点解释：

• 中间件如何解析请求、决策鉴权模式、注入身份上下文并执行拒绝策略
• 前台与 API 端在“未登录/无工作身份”时的差异化处理（重定向 vs JSON）
• 后台管理员的会话恢复、超时与续登机制
• 如何通过配置表实现细粒度路由级鉴权与“工作端”身份校验
• 调试方法、安全加固与性能优化建议
• 如何扩展中间件以支持特定业务场景

项目结构

DouPHP 将认证能力拆分为“通用骨架 + 端侧实现 + 策略配置”三层：

• 通用骨架：抽象基类承载模板方法，统一走“策略决策 → 解析上下文 → 注入身份 → 工作端校验 → 放行/拒绝”的流程
• 端侧实现：前台与 API 分别实现 guard 选择、上下文解析、拒绝响应；后台使用独立 session 守卫
• 策略配置：按模块/动作/子段声明 public/optional/required 及 work_required 白名单

graph TB
subgraph "通用骨架"
A["AbstractUserAuthMiddleware<br/>模板方法"]
B["UserAuthPolicy<br/>策略解析器"]
end
subgraph "前台端"
C["Front UserAuthMiddleware"]
F["front/init/middleware.php<br/>auth_modes/work_required"]
end
subgraph "API端"
D["Api UserAuthMiddleware"]
G["api/init/middleware.php<br/>auth_modes/work_required"]
end
subgraph "后台端"
E["Admin AuthMiddleware"]
H["Admin AuthService<br/>会话恢复/超时/续登"]
end
A --> B
C --> A
D --> A
E --> H
C --> F
D --> G

图表来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:21-184
• core/foundation/middleware/UserAuthPolicy.php:21-124
• front/middleware/UserAuthMiddleware.php:26-99
• api/middleware/UserAuthMiddleware.php:25-94
• admin/middleware/AuthMiddleware.php:24-52
• admin/service/auth/AuthService.php:28-461
• front/init/middleware.php:18-132
• api/init/middleware.php:18-147

章节来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:21-184
• core/foundation/middleware/UserAuthPolicy.php:21-124
• front/middleware/UserAuthMiddleware.php:26-99
• api/middleware/UserAuthMiddleware.php:25-94
• admin/middleware/AuthMiddleware.php:24-52
• admin/service/auth/AuthService.php:28-461
• front/init/middleware.php:18-132
• api/init/middleware.php:18-147

核心组件

• 抽象用户认证中间件：定义 handle 模板方法，统一加载配置、调用策略决策、解析/注入上下文、work 身份校验与拒绝分支
• 用户认证策略：根据 module/action/sub/parent 与配置表计算鉴权模式与是否需工作端身份
• 前台认证中间件：基于 front guard 解析 Session，未登录时重定向到登录页（XHR 返回 JSON 跳转）
• API 认证中间件：从 Authorization 头提取 token，解析为 API 会话上下文，未登录/无工作身份直接返回 JSON 错误
• 后台认证中间件：通过 admin guard 恢复会话，未登录抛出异常重定向到登录页
• 后台服务：负责管理员登录、会话恢复、超时清理、remember-me 续登、密码校验与失败锁定

章节来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:21-184
• core/foundation/middleware/UserAuthPolicy.php:21-124
• front/middleware/UserAuthMiddleware.php:26-99
• api/middleware/UserAuthMiddleware.php:25-94
• admin/middleware/AuthMiddleware.php:24-52
• admin/service/auth/AuthService.php:28-461

架构总览

下图展示一次受保护请求的完整认证链路：中间件读取路由信息，策略决定模式，前端或 API 中间件解析上下文并注入身份，必要时校验工作端身份，最终放行或拒绝。

sequenceDiagram
participant Client as "客户端"
participant MW as "认证中间件"
participant POL as "UserAuthPolicy"
participant AUTH as "Auth Guard"
participant CTRL as "控制器"
Client->>MW : "HTTP 请求"
MW->>POL : "resolve(module, action, sub, parent)"
POL-->>MW : "{mode, workRequired}"
alt mode == public
MW-->>Client : "放行"
else 需要解析登录态
MW->>AUTH : "resolveUserContext()"
AUTH-->>MW : "{ok, ...context}"
alt ok == false
alt mode == required
MW-->>Client : "拒绝(401/重定向)"
else optional
MW-->>Client : "放行(匿名)"
end
else ok == true
MW->>AUTH : "hydrate(context)"
alt workRequired && !hasWorkIdentity
MW-->>Client : "拒绝(403/重定向)"
else 通过
MW-->>CTRL : "放行"
end
end
end

图表来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:120-168
• core/foundation/middleware/UserAuthPolicy.php:52-82
• front/middleware/UserAuthMiddleware.php:47-99
• api/middleware/UserAuthMiddleware.php:47-94

详细组件分析

抽象用户认证中间件（模板方法）

• 职责：加载配置、构造候选键、调用策略决策、解析/注入上下文、work 身份校验、拒绝分支
• 关键点：
  • 支持路由级参数覆盖鉴权模式（public/optional/required）
  • 默认模式为 optional，避免新模块静默公开
  • 拒绝分支由子类实现，保证前后端差异隔离

flowchart TD
Start(["进入 handle"]) --> ReadCfg["加载 auth_modes / work_required"]
ReadCfg --> Decision["UserAuthPolicy::resolve(...)"]
Decision --> Mode{"mode"}
Mode --> |public| Next1["直接放行"]
Mode --> |optional|required| Resolve["resolveContext()"]
Resolve --> Ok{"ok ?"}
Ok --> |false| Branch{"mode==required?"}
Branch --> |是| Reject["rejectUnauthenticated()"]
Branch --> |否| Next2["放行(匿名)"]
Ok --> |true| Inject["inject(context)"]
Inject --> Work{"workRequired && !hasWorkIdentity?"}
Work --> |是| RejectF["rejectForbidden()"]
Work --> |否| Next3["放行"]

图表来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:64-184
• core/foundation/middleware/UserAuthPolicy.php:52-82

章节来源

• core/foundation/middleware/AbstractUserAuthMiddleware.php:64-184
• core/foundation/middleware/UserAuthPolicy.php:52-82

前台认证中间件

• 解析方式：调用 front guard 的 resolveUserContext，成功后 hydrate 到当前请求上下文
• 拒绝策略：
  • 普通页面：重定向到登录页，附带 redirect 参数
  • XHR（from=js）：返回 JSON 401 并携带 jump_url，便于前端跳转
• 工作端校验：若命中 work_required 且无工作身份，重定向到用户中心

章节来源

• front/middleware/UserAuthMiddleware.php:47-99
• front/init/middleware.php:18-132

API 认证中间件

• 解析方式：从 Authorization: Bearer <token> 提取 token，调用 api guard 的 resolveUserContext
• 拒绝策略：直接返回 JSON 错误（401/403），不渲染页面
• 工作端校验：若命中 work_required 且无工作身份，返回 403

章节来源

• api/middleware/UserAuthMiddleware.php:47-94
• api/init/middleware.php:18-147

后台认证中间件与会话恢复

• 会话恢复：通过 admin guard 的 restoreFromSession 恢复管理员身份，未登录则重定向到登录页
• 会话超时：AuthService 内部维护 ontime，超过阈值清空会话
• 续登机制：支持 remember-me Cookie，自动重建会话并补发 CSRF 静态令牌
• 安全加固：IP 限流、账号锁定、密码哈希升级（md5→bcrypt）、shell 校验防会话劫持

sequenceDiagram
participant AdminMW as "Admin AuthMiddleware"
participant AdminGuard as "Admin AuthService"
participant Session as "Session/Cookie"
participant DB as "数据库"
AdminMW->>AdminGuard : "restoreFromSession(ip)"
AdminGuard->>Session : "读取 admin_id/shell/ontime"
AdminGuard->>DB : "校验 admin_id+shell"
DB-->>AdminGuard : "管理员行或空"
alt 校验失败
AdminGuard-->>AdminMW : "null"
AdminMW-->>Client : "重定向到登录页"
else 校验成功
AdminGuard->>Session : "touchSession() 刷新心跳"
AdminGuard-->>AdminMW : "payload"
AdminMW-->>Client : "放行"
end

图表来源

• admin/middleware/AuthMiddleware.php:42-50
• admin/service/auth/AuthService.php:199-227
• admin/service/auth/AuthService.php:355-363
• admin/service/auth/AuthService.php:376-403

章节来源

• admin/middleware/AuthMiddleware.php:42-50
• admin/service/auth/AuthService.php:199-227
• admin/service/auth/AuthService.php:355-363
• admin/service/auth/AuthService.php:376-403

依赖关系分析

• 中间件依赖策略：所有用户认证中间件依赖 UserAuthPolicy 进行模式决策
• 配置驱动：auth_modes 与 work_required 集中管理，新增模块必须显式登记
• 端侧差异：前台与 API 仅实现 guard 选择与拒绝策略，逻辑复用度高
• 后台独立：后台使用 session-based 守卫，具备更强的会话管理与安全控制

graph LR
Policy["UserAuthPolicy"] --> AbsMW["AbstractUserAuthMiddleware"]
AbsMW --> FrontMW["Front UserAuthMiddleware"]
AbsMW --> ApiMW["Api UserAuthMiddleware"]
FrontMW --> FrontCfg["front/init/middleware.php"]
ApiMW --> ApiCfg["api/init/middleware.php"]
AdminMW["Admin AuthMiddleware"] --> AdminSvc["Admin AuthService"]

图表来源

• core/foundation/middleware/UserAuthPolicy.php:21-124
• core/foundation/middleware/AbstractUserAuthMiddleware.php:21-184
• front/middleware/UserAuthMiddleware.php:26-99
• api/middleware/UserAuthMiddleware.php:25-94
• front/init/middleware.php:18-132
• api/init/middleware.php:18-147
• admin/middleware/AuthMiddleware.php:24-52
• admin/service/auth/AuthService.php:28-461

章节来源

• core/foundation/middleware/UserAuthPolicy.php:21-124
• core/foundation/middleware/AbstractUserAuthMiddleware.php:21-184
• front/middleware/UserAuthMiddleware.php:26-99
• api/middleware/UserAuthMiddleware.php:25-94
• front/init/middleware.php:18-132
• api/init/middleware.php:18-147
• admin/middleware/AuthMiddleware.php:24-52
• admin/service/auth/AuthService.php:28-461

性能与安全考虑

• 性能
  • 策略决策为纯函数，无 I/O，开销极低
  • 仅在 required/optional 模式下解析登录态，public 直接放行
  • 工作端校验仅在命中 work_required 时执行
  • 后台会话心跳刷新减少频繁写库，超时后批量清理
• 安全
  • 前台：XHR 返回 JSON 跳转，避免敏感信息泄露；重定向带原地址便于体验
  • API：统一 JSON 错误码，便于客户端处理
  • 后台：
    • 会话 shell 校验防止会话劫持
    • IP 限流与账号锁定抵御暴力破解
    • 密码哈希升级（md5→bcrypt）
    • remember-me 续登自动补发 CSRF 静态令牌，避免误判非法操作
    • 超时会话自动清空

故障排查指南

• 前台未登录重定向问题
  • 检查路由是否在 auth_modes 中登记为 public/optional/required
  • 确认 XHR 请求是否携带 from=js，以便返回 JSON 跳转
  • 查看登录页是否正确接收 redirect 参数
• API 401/403 问题
  • 确认 Authorization 头格式正确（Bearer token）
  • 检查对应模块/动作是否在 auth_modes 中登记
  • 若命中 work_required，确认当前 token 是否绑定工作身份
• 后台无法登录或频繁登出
  • 检查 IP 限流与账号锁定状态
  • 确认 remember-me Cookie 是否有效，续登是否成功
  • 查看会话心跳是否被刷新，超时是否被清理
  • 核对 shell 校验与数据库管理员记录一致性

章节来源

• front/middleware/UserAuthMiddleware.php:77-99
• api/middleware/UserAuthMiddleware.php:77-94
• admin/service/auth/AuthService.php:275-303
• admin/service/auth/AuthService.php:376-403

结论

DouPHP 的用户认证中间件采用“策略驱动 + 模板方法 + 端侧实现”的清晰分层，既保证了前后端一致的鉴权流程，又提供了灵活的配置化控制。通过 auth_modes 与 work_required 的组合，可精确表达不同模块/动作的鉴权需求；后台会话管理具备完善的安全与可用性保障。开发者可在不改动核心逻辑的前提下，通过配置与少量实现完成业务扩展。

附录：扩展与自定义规则

• 新增前台/ API 模块的鉴权规则
  • 在前台或 API 的 init/middleware.php 中为该模块登记 auth_modes（public/optional/required）
  • 如需工作端身份，将模块路径加入 work_required 列表
  • 对子控制器或特定动作，可使用 module/sub/action 更精确覆盖
• 自定义拒绝行为
  • 前台：可在 rejectUnauthenticated/rejectForbidden 中调整跳转目标或消息
  • API：可在 rejectUnauthenticated/rejectForbidden 中定制错误码与消息体
• 扩展工作端身份校验
  • 在 hasWorkIdentity 中增加额外条件（如部门、岗位等）
  • 结合 work_required 配置，实现细粒度资源访问控制
• 调试建议
  • 打印策略决策结果（module/action/sub/parent 与命中候选键）
  • 记录解析上下文是否成功、是否注入身份、是否命中 work_required
  • 对后台：检查 IP 限流、账号锁定、remember-me 续登日志

章节来源

• front/init/middleware.php:18-132
• api/init/middleware.php:18-147
• core/foundation/middleware/UserAuthPolicy.php:52-82
• front/middleware/UserAuthMiddleware.php:47-99
• api/middleware/UserAuthMiddleware.php:47-94
• admin/service/auth/AuthService.php:275-303
• admin/service/auth/AuthService.php:376-403