简介

本指南面向 DouPHP 应用，提供一套可落地的“应用监控”配置与实施方案，覆盖：

• 请求响应时间监控（API 接口性能追踪、页面加载时间统计）
• 数据库查询性能分析
• 错误率监控（异常捕获、错误分类、错误频率统计）
• 资源使用监控（内存占用、CPU 使用率、文件句柄数等）
• Whoops 调试库的配置与使用（开发/生产环境差异化策略）
• 自定义监控指标添加方法与数据收集存储方案

说明：DouPHP 框架未内置统一的 APM 探针或集中式日志系统。本文基于现有中间件、安全头下发、限流存储、Whoops 错误处理以及 API 运行日志配置，给出在框架边界处接入监控的最佳实践与扩展点。

项目结构

围绕监控相关的关键位置如下：

• 中间件层：三端（前台/后台/API）通过中间件管道统一注入安全头、鉴权、限流等横切能力，是插入“计时/埋点/采样”的理想位置。
• 安全配置：security.headers 控制基线安全响应头；throttle.store 提供限流数据存储路径。
• Whoops：作为 PHP 错误/异常的统一处理器，支持注册为全局错误/异常/关闭钩子，并可通过 Handler 栈输出 HTML 堆栈页。
• API 运行日志：_'.api/config/log.php 定义了启用开关、最小级别、通道白名单、采样率、每分钟每 key 上限、保留天数等。

graph TB
Client["客户端"] --> MW["中间件管道<br/>安全头/鉴权/限流"]
MW --> Router["路由分发"]
Router --> Controller["控制器/服务"]
Controller --> DB["数据库"]
Controller --> Log["日志/审计"]
Controller --> Cache["缓存/限流存储"]
subgraph "错误处理"
Whoops["Whoops Run"]
end
Controller --> Whoops

图表来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:23-49
• config/security.php:51-87
• core/library/whoops/src/Whoops/Run.php:195-219

章节来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:23-49
• config/security.php:51-87
• core/library/whoops/src/Whoops/Run.php:195-219

核心组件

• 中间件基类：负责读取 security.headers 并在响应前下发基线安全头，适合在此处增加请求耗时、状态码、用户代理等指标采集。
• 安全配置：包含可信代理、可信 Host、安全头、限流存储路径与会话硬化参数，可作为监控的上下文来源（如 IP、Host、是否 HTTPS）。
• Whoops：统一接管 PHP 错误/异常/致命错误，支持设置 HTTP 状态码、退出码、输出模式、静默规则、帧过滤器等，便于在开发/测试环境展示友好错误页，在生产环境切换为静默+异步上报。
• API 运行日志：提供 channel 级开关、采样率、每分钟每 key 限制、保留天数等，可用于记录路由命中、响应摘要等。

章节来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:23-49
• config/security.php:51-87
• core/library/whoops/src/Whoops/Run.php:245-347
• _'.api/config/log.php:17-47

架构总览

下图展示了从请求进入、中间件处理、业务执行到错误处理的完整链路，并标注了监控埋点建议位置。

sequenceDiagram
participant C as "客户端"
participant M as "中间件(安全头/鉴权/限流)"
participant R as "路由/控制器"
participant S as "服务/ORM"
participant D as "数据库"
participant W as "Whoops"
C->>M : 发起请求
M->>M : 记录开始时间/采样/限流检查
M->>R : 进入路由
R->>S : 执行业务
S->>D : 执行 SQL
D-->>S : 返回结果
S-->>R : 返回数据
R-->>M : 生成响应
M->>M : 计算耗时/记录状态码/写入日志
M-->>C : 返回响应
Note over M,W : 若发生异常/错误，交由 Whoops 处理

图表来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49
• core/library/whoops/src/Whoops/Run.php:367-447

详细组件分析

请求响应时间监控（API/页面）

建议在中间件层实现“请求-响应”全链路计时：

• 在 handle($next) 入口处记录开始时间戳。
• 调用 $next() 执行业务后，记录结束时间戳，计算耗时。
• 结合 Request 信息（IP、Host、URL、方法、UA）与 Response 状态码，构造一条性能指标记录。
• 根据配置进行采样（例如高流量时降低采样率），避免对性能造成过大影响。
• 将指标写入日志文件或外部系统（如 Prometheus Pushgateway、APM 平台）。

参考位置：

• 中间件入口与出口：core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49
• 安全配置中的 Host/IP/HTTPS 判定来源：config/security.php:51-87

flowchart TD
Start(["请求进入"]) --> T0["记录开始时间 t0"]
T0 --> Next["调用下一个中间件/控制器"]
Next --> T1["记录结束时间 t1"]
T1 --> Calc["计算耗时 = t1 - t0"]
Calc --> Sample{"是否采样?"}
Sample -- 否 --> End(["丢弃指标"])
Sample -- 是 --> Build["组装指标: URL/方法/状态码/IP/耗时"]
Build --> Store["写入日志/上报系统"]
Store --> End

图表来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49

章节来源

• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49
• config/security.php:51-87

数据库查询性能分析

• 在 ORM/DB 门面或连接层增加慢查询阈值检测（例如 > 500ms 视为慢查询）。
• 记录关键维度：SQL 文本（脱敏）、执行耗时、影响行数、调用栈（模块/控制器/方法）。
• 结合采样与聚合，避免高频写入导致 I/O 压力。
• 可将慢查询日志与性能指标关联，用于定位热点接口与低效 SQL。

提示：该部分属于通用扩展点，可在 ORM 初始化或 DB 连接建立时注入拦截器。

章节来源

• config/security.php:51-87

错误率监控（异常捕获、错误分类、频率统计）

• 利用 Whoops 统一捕获 PHP 错误、异常与致命错误，按错误类型分类（如语法错误、运行时异常、第三方调用失败）。
• 在 Whoops 中设置 sendHttpCode/sendExitCode/writeToOutput，以适配不同环境的输出策略。
• 将错误事件（类型、消息、堆栈摘要、请求上下文）写入日志或告警系统，并按分钟/小时聚合统计错误率。
• 针对高频错误实施去重与限流，避免日志风暴。

参考位置：

• Whoops 注册与处理流程：core/library/whoops/src/Whoops/Run.php:195-219、core/library/whoops/src/Whoops/Run.php:367-447
• Whoops 模板工具（用于渲染错误页）：core/library/whoops/src/Whoops/Util/TemplateHelper.php:1-60

sequenceDiagram
participant App as "应用"
participant W as "Whoops Run"
participant H as "Handler 栈"
participant L as "日志/告警"
App->>W : 抛出异常/触发错误
W->>W : handleError/handleException
W->>H : 依次调用处理器
H-->>W : 返回处理结果/QUIT
W->>L : 记录错误事件(类型/消息/上下文)
W-->>App : 输出错误或终止

图表来源

• core/library/whoops/src/Whoops/Run.php:195-219
• core/library/whoops/src/Whoops/Run.php:367-447

章节来源

• core/library/whoops/src/Whoops/Run.php:195-219
• core/library/whoops/src/Whoops/Run.php:367-447
• core/library/whoops/src/Whoops/Util/TemplateHelper.php:1-60

资源使用监控（内存/CPU/文件句柄）

• 在中间件或请求生命周期结束时，采集以下指标：
  • 内存：当前进程内存峰值、RSS、可用内存
  • CPU：进程 CPU 使用率（可通过系统命令或扩展获取）
  • 文件句柄：打开的文件描述符数量
  • 队列长度：任务队列积压（如有）
• 将指标写入日志或推送到监控系统（如 StatsD/Prometheus）。
• 结合限流存储路径（security.throttle.store）观察系统负载与限流命中率。

参考位置：

• 限流存储路径：config/security.php:74-77

章节来源

• config/security.php:74-77

Whoops 调试库配置与使用（开发/生产差异）

• 开发/测试环境：
  • 开启 Whoops 并注册为全局错误/异常处理器。
  • 设置 writeToOutput(true)，允许直接输出 HTML 错误页。
  • 可设置 sendHttpCode(5xx) 以便前端识别错误。
  • 使用 addFrameFilter 过滤敏感信息（如密钥、路径）。
• 生产环境：
  • 关闭 writeToOutput(false)，避免向客户端暴露堆栈。
  • 将错误事件写入日志/告警系统，仅返回通用错误响应。
  • 使用 silenceErrorsInPaths 屏蔽第三方库噪声。

参考位置：

• Whoops 注册与输出控制：core/library/whoops/src/Whoops/Run.php:195-219、core/library/whoops/src/Whoops/Run.php:357-364
• Whoops HTTP 状态码与退出码：core/library/whoops/src/Whoops/Run.php:290-347
• Whoops 静默规则：core/library/whoops/src/Whoops/Run.php:254-288

章节来源

• core/library/whoops/src/Whoops/Run.php:195-219
• core/library/whoops/src/Whoops/Run.php:254-347
• core/library/whoops/src/Whoops/Run.php:357-364

自定义监控指标的添加方法与收集存储方案

• 添加位置：
  • 中间件层：请求/响应维度指标（耗时、状态码、带宽、UA）。
  • 控制器/服务层：业务指标（订单创建成功率、支付网关超时率）。
  • 数据库层：慢查询、连接池使用率。
  • 定时任务：资源使用（内存/CPU/句柄）周期性采集。
• 采样与聚合：
  • 使用采样率降低写入开销。
  • 按分钟/小时聚合，减少存储压力。
• 存储方案：
  • 本地日志文件：按日期分片，配合 logrotate 管理。
  • 外部系统：Prometheus/Grafana、ELK、APM 平台。
  • 限流存储：利用 security.throttle.store 作为临时计数载体（需自行设计键值结构）。

参考位置：

• 限流存储路径：config/security.php:74-77
• API 运行日志配置（channel/采样/保留）：_'.api/config/log.php:17-47

章节来源

• config/security.php:74-77
• _'.api/config/log.php:17-47

依赖关系分析

• 中间件与安全配置强耦合：安全头下发依赖 security.headers；限流存储依赖 throttle.store。
• Whoops 与错误处理链：Whoops 注册为全局处理器，接管错误/异常/关闭钩子，并通过 Handler 栈输出。
• API 运行日志与渠道控制：log.php 中的 enabled_channels、sample_rate、max_per_minute_per_key 决定日志写入行为。

graph LR
SecCfg["安全配置<br/>security.php"] --> MWBase["安全头中间件<br/>AbstractSecurityHeadersMiddleware"]
MWBase --> ReqCtx["请求上下文<br/>IP/Host/HTTPS"]
ReqCtx --> Metrics["性能指标"]
Whoops["Whoops Run"] --> ErrLog["错误日志/告警"]
ApiLogCfg["API 日志配置<br/>log.php"] --> ApiLog["API 运行日志"]

图表来源

• config/security.php:51-87
• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49
• core/library/whoops/src/Whoops/Run.php:195-219
• _'.api/config/log.php:17-47

章节来源

• config/security.php:51-87
• core/foundation/middleware/AbstractSecurityHeadersMiddleware.php:41-49
• core/library/whoops/src/Whoops/Run.php:195-219
• _'.api/config/log.php:17-47

性能考虑

• 采样：在高 QPS 场景下，合理设置采样率，避免指标写入成为瓶颈。
• 异步：将指标写入与上报改为异步（队列/批量），降低请求延迟。
• 聚合：在采集侧做初步聚合（如每秒/每分钟计数），减少下游压力。
• 存储：日志文件按天分片，定期清理；外部系统选择合适的时间序列存储。
• 限流：利用 security.throttle.store 作为限流计数器，防止恶意刷接口导致指标爆炸。

故障排查指南

• 无法显示错误页：检查 Whoops 是否已注册，writeToOutput 是否开启，sendHttpCode 是否被禁用。
• 错误过多：启用 silenceErrorsInPaths 屏蔽第三方库噪声；调整采样率与 max_per_minute_per_key。
• 指标缺失：确认中间件是否生效；检查 Request 上下文是否正确；验证采样逻辑。
• 日志堆积：检查 log.php 的 keep_days、max_per_minute_per_key；配置日志轮转。

章节来源

• core/library/whoops/src/Whoops/Run.php:254-347
• _'.api/config/log.php:17-47

结论

通过在中间件层统一采集请求耗时与状态码、在 Whoops 中统一捕获错误、在安全配置中利用限流存储与可信代理/Host 信息，可以在不侵入业务代码的前提下，为 DouPHP 构建一套轻量而有效的应用监控体系。结合采样、聚合与异步上报，可在保证性能的同时获得可观的可观测性收益。

附录

• API 鉴权模式配置（可作为监控的访问控制维度）：api/init/middleware.php:18-146
• 后台初始化中涉及日志运行时与环境设置的位置：admin/init/Init.php:64-76、admin/init/Init.php:181-212

章节来源

• api/init/middleware.php:18-146
• admin/init/Init.php:64-76
• admin/init/Init.php:181-212