简介
本文件面向 DouPHP 的权限审计系统，系统性说明以下能力：
- 权限操作日志记录机制：登录日志、操作日志、异常日志的写入位置、字段语义与来源。
- 权限违规检测算法：基于中间件鉴权、限流策略与登录失败计数实现的异常行为识别与风险评估。
- 权限使用统计分析：用户活跃度与权限使用情况的数据来源与展示方式。
- 权限审计配置与管理界面：后台模块访问控制、日志查询与筛选。
- 安全告警与通知：结合限流、验证码、登录失败计数等机制的安全事件触发点。
- 最佳实践与安全建议：落地到代码层面的可操作建议。
项目结构
DouPHP 将“鉴权”和“审计”解耦为两条主线：
- 鉴权链路：通过中间件在请求边界完成身份校验与权限判定，未通过则拒绝并返回错误。
- 审计链路：在关键业务节点（登录成功/失败、管理员操作、资源状态变更）统一调用审计服务写入日志表。
graph TB
subgraph "管理端"
A["认证中间件<br/>AuthMiddleware"] --> B["权限中间件<br/>PermissionMiddleware"]
B --> C["授权门控<br/>AdminGate"]
C --> D["控制器/服务"]
D --> E["审计服务<br/>AuditService"]
end
subgraph "API端"
F["API鉴权模式配置<br/>middleware.php"] --> G["会员认证中间件<br/>UserAuthMiddleware"]
G --> H["业务控制器"]
H --> E
end
subgraph "前台"
I["限流中间件<br/>ThrottleMiddleware"] --> J["登录服务<br/>LoginService"]
J --> E
end
E --> K["数据库日志表<br/>user_log / admin_log / book_log"]核心组件
- 审计服务：集中负责三类日志写入（用户日志、预约日志、管理员日志），统一 IP 来源与 XSS 过滤，保证审计数据一致性与安全性。
- 字典常量：用户与管理员日志的 action 与 details 采用集中枚举，避免散乱字符串导致不可维护。
- 中间件链：管理端认证与权限判定、API 端按模块声明式鉴权、前台敏感接口限流。
- 管理端授权门控：基于管理员角色与动作白名单进行细粒度访问控制。
- 日志查询服务：提供后台对日志列表的分页、筛选与渲染。
架构总览
下图展示了从请求进入、鉴权、权限判定到审计日志落库的完整流程，覆盖管理端、API 端与前台。
sequenceDiagram
participant U as "客户端"
participant AM as "管理端认证中间件"
participant PM as "管理端权限中间件"
participant AG as "授权门控"
participant S as "业务服务"
participant AU as "审计服务"
participant DB as "数据库"
U->>AM : 发起管理端请求
AM->>AM : 恢复管理员会话
AM-->>U : 未登录跳转登录页
AM->>PM : 已登录放行
PM->>AG : 判定是否允许访问模块/动作
AG-->>PM : 允许/拒绝
PM-->>U : 无权限重定向首页
PM->>S : 执行业务逻辑
S->>AU : 写入审计日志(管理员/用户/预约)
AU->>DB : INSERT user_log/admin_log/book_log
DB-->>AU : 写入结果
AU-->>S : 完成
S-->>U : 返回响应详细组件分析
审计日志写入服务
- 职责：统一写入用户日志、预约日志、管理员日志；统一处理 IP 来源、XSS 过滤、时间戳。
- 设计要点：
- IP 来源优先显式传入，否则回退到构造注入的请求 IP，确保 CLI/无 Request 场景可用。
- 管理员日志 action 强制使用字典常量，空串立即抛错，防止参数错位写脏数据。
- 管理员日志 module 默认从当前请求路由模块读取，避免硬编码。
flowchart TD
Start(["调用 writeXxxLog"]) --> CheckIP["确定 IP 来源<br/>显式传入 > 构造注入"]
CheckIP --> Sanitize["XSS 过滤 details/action"]
Sanitize --> WriteDB["插入对应日志表"]
WriteDB --> End(["完成"])管理员日志字典与详情标签
- action 字典：集中定义登录成功/失败、增删改、启用禁用、安装卸载、升级、备份还原、清缓存、重放等粗粒度动作。
- details 标签：用于登录失败原因、老密码错误等离散语义，与业务对象 details 共存于同一列，便于审计可读且消除 PII。
用户日志字典与详情标签
- action 字典：登录成功/失败、编辑资料、修改密码等。
- details 标签：空输入、格式非法、IP 限流、账号不存在、账户锁定等，配合 action 形成更细粒度的审计语义。
管理端鉴权与权限判定
- 认证中间件：从会话恢复管理员身份，未登录直接跳转登录页。
- 权限中间件：获取当前模块与动作，交由授权门控判定；超级管理员放行，受限管理员按动作白名单判定。
- 授权门控：维护子资源到父资源的鉴权别名映射，确保子资源继承父模块权限。
classDiagram
class AuthMiddleware {
+handle(next) mixed
}
class PermissionMiddleware {
+handle(next) mixed
-gate AdminGate
}
class AdminGate {
+canAccess(admin, module, action, targetId) bool
-subModuleAliases map
}
PermissionMiddleware --> AdminGate : "依赖"
AuthMiddleware --> PermissionMiddleware : "顺序执行"API 端鉴权模式
- 通过配置文件以模块级声明鉴权模式：public、optional、required，以及 work_required 子策略叠加工作端身份校验。
- 新增 API 模块必须登记三选一，漏登记会被扫描工具拦截，防止新模块静默以匿名形态上线。
- 会员认证中间件从 Authorization 头提取 token，解析登录态后交由通用骨架决策。
登录失败与限流（异常行为识别）
- 登录失败审计：登录失败时记录用户日志，action 为登录失败，details 携带具体原因标签（如账户锁定）。
- 前台限流：对敏感端点按 IP 限流（登录、注册、找回密码、短信验证码等），命中限流会记录审计详情标签。
- 登录失败计数：登录失败时调用登录失败计数服务，结合限流实现风险累积。
sequenceDiagram
participant C as "客户端"
participant T as "限流中间件"
participant L as "登录服务"
participant A as "审计服务"
participant DB as "数据库"
C->>T : 提交登录请求
T-->>C : 若超限则拒绝
T->>L : 未超限放行
L->>L : 校验账号/密码/状态
L-->>A : 记录登录失败/成功日志
A->>DB : 写入 user_log
DB-->>A : 写入结果
A-->>L : 完成
L-->>C : 返回结果权限使用统计与管理界面
- 管理员操作日志列表：支持按管理员账号、动作、模块、IP、日期范围筛选，分页展示，行渲染统一翻译 action 与 module。
- 用户操作日志列表：支持按用户名/ID、动作、IP、日期范围筛选，分页展示，结果列显示成功/失败。
- 最近日志：首页最近日志与日志列表共用渲染逻辑，保证显示一致性。
依赖关系分析
- 审计服务依赖数据库门面与 Session，用于写入日志与兜底管理员 ID。
- 管理端中间件依赖授权门控，后者依赖管理员动作白名单与子资源别名映射。
- 登录服务依赖审计服务与登录失败计数服务，结合限流中间件形成异常行为识别闭环。
- API 鉴权模式由配置文件驱动，中间件根据模块声明决定鉴权强度。
graph LR
Audit["AuditService"] --> DB["DB 门面"]
Audit --> Session["Session 门面"]
Perm["PermissionMiddleware"] --> Gate["AdminGate"]
Login["LoginService"] --> Audit
Throttle["ThrottleMiddleware"] --> Login
ApiCfg["API 鉴权配置"] --> UserAuth["UserAuthMiddleware"]性能考量
- 日志写入为轻量插入，注意在高并发场景下避免同步阻塞主流程；必要时可异步化或批量写入。
- 日志查询服务使用分页与条件过滤，建议在 user_log、admin_log 上建立 created_at、ip、action 等常用查询索引。
- 限流中间件对敏感端点进行窗口计数，需关注存储层（如 Redis/内存）的性能与容量。
- 管理员日志渲染统一翻译 action/module，减少重复计算，提升列表页加载速度。
故障排查指南
- 管理员无法访问某模块：检查认证中间件是否成功恢复会话，权限中间件是否通过授权门控判定，确认管理员动作白名单与子资源别名映射是否正确。
- 日志缺失：确认业务入口是否调用审计服务；管理员日志 action 必须为非空字典常量，否则会在写入前抛错。
- 登录失败频繁：检查前台限流配置与登录失败计数，确认是否命中限流阈值；查看用户日志 details 标签定位失败原因。
- API 鉴权失败：核对 API 鉴权配置中模块的鉴权模式是否登记正确；确认 Authorization 头是否携带有效 token。
结论
DouPHP 的权限审计系统通过“中间件鉴权 + 审计服务 + 字典常量 + 管理端日志查询”形成了完整的闭环：
- 所有关键操作均有据可查，action/details 标准化，便于检索与分析。
- 登录失败与限流机制共同构成异常行为识别与风险评估的基础。
- 管理端提供统一的日志查询与渲染，保障审计数据的可观测性。
- API 端通过声明式鉴权模式降低误配风险，提升整体安全性。
附录
- 权限使用统计分析建议：
- 基于 user_log 统计用户活跃度（登录次数、活跃时段）。
- 基于 admin_log 统计管理员操作频次与高风险动作（删除、禁用、升级、备份还原）。
- 结合 IP 与 details 标签，识别异常登录与批量操作。
- 安全建议：
- 严格登记 API 鉴权模式，避免新模块以匿名形态上线。
- 定期审查管理员动作白名单与子资源别名映射，及时回收冗余权限。
- 对高价值操作（删除、退款、升级）开启二次确认与强审计。
- 对登录失败与限流阈值进行周期性评估与调优。