简介

本指南面向 DouPHP 的数据库监控与可观测性建设，围绕以下目标提供落地方案：

• 连接池监控：连接数统计、连接状态检测、连接超时处理。
• 慢查询监控：查询性能分析、执行时间阈值设置、慢查询日志记录。
• 连接池使用率监控：活跃连接数、空闲连接数、等待队列长度。
• 健康检查机制：连接测试、表空间监控、索引使用情况分析。
• 性能指标收集与分析方法，以及异常告警配置建议。

说明：DouPHP 核心框架通过 Connection 类直接管理 mysqli 连接；部分插件（如支付 SDK）内置了连接池实现。本指南将分别给出“基于现有实现的增强”和“推荐扩展”两种路径，确保在不破坏既有行为的前提下完成监控能力补齐。

项目结构

与数据库监控密切相关的代码主要分布在：

• 核心门面与连接层：core/facade/DB.php、core/infra/database/Connection.php
• 配置入口：config/config.php
• 插件级连接池（可选）：plugin//sdk/lotusphp_runtime/DB/
• 升级/诊断脚本：_'/tool/upgrade_v1.9.php

graph TB
A["应用/业务模块"] --> B["DB 门面<br/>core/facade/DB.php"]
B --> C["连接容器单例<br/>core/infra/database/Connection.php"]
C --> D["MySQL 服务器"]
E["插件连接池<br/>DbConnectionManager.php"] --> F["DbHandle / DbConfigBuilder"]
E --> D
G["配置<br/>config/config.php"] --> C
H["诊断脚本<br/>upgrade_v1.9.php"] --> D

核心组件

• DB 门面：对外暴露静态 API，内部委托给 Connection 容器单例，便于统一接入监控与调试。
• Connection：封装 mysqli 连接、事务、查询构建、错误处理、调试开关等，是监控落点的关键位置。
• 插件连接池：在支付等插件中提供进程内连接复用与过期控制，可作为连接池监控的参考实现。
• 配置：集中定义数据库主机、库名、用户、密码、前缀与字符集等。

架构总览

下图展示请求从应用到数据库的调用链，并标注监控埋点位置（连接建立、查询执行、错误处理）。

sequenceDiagram
participant App as "应用"
participant Facade as "DB 门面"
participant Conn as "Connection"
participant MySQL as "MySQL"
participant Pool as "插件连接池(可选)"
App->>Facade : 发起查询/写入
Facade->>Conn : 获取连接/构建查询
alt 使用插件连接池
Conn->>Pool : 获取连接
Pool-->>Conn : 返回连接资源
else 直连模式
Conn->>MySQL : 建立/复用连接
end
Conn->>MySQL : 执行 SQL
MySQL-->>Conn : 结果/错误
Conn-->>Facade : 返回结果
Facade-->>App : 响应数据

详细组件分析

连接池监控（含连接数统计、状态检测、超时处理）

• 现状
  • 核心框架未内置连接池，Connection 以 mysqli 直连为主。
  • 插件中存在 LtDbConnectionManager，具备连接池与 TTL 过期字段，可用于统计与治理。
• 建议方案
  • 在 Connection 层增加轻量“进程内连接池”或“连接复用计数器”，用于统计活跃/空闲连接、等待队列长度。
  • 对连接建立与释放进行计数，结合 PHP-FPM 进程模型，按进程维度统计。
  • 超时处理：在连接建立时设置超时参数，并在连接失败时记录告警。
• 关键埋点
  • 连接创建：记录当前活跃连接数、创建耗时。
  • 连接归还：更新空闲连接数。
  • 连接失败：记录错误码、重试次数、是否触发熔断/降级。
  • 等待队列：当无可用连接且达到上限时，入队并记录等待时长。

flowchart TD
Start(["开始"]) --> CheckPool["检查连接池"]
CheckPool --> HasFree{"有空闲连接?"}
HasFree -- 是 --> UseConn["复用连接"]
HasFree -- 否 --> CreateOrWait{"允许创建新连接?"}
CreateOrWait -- 是 --> NewConn["新建连接"]
CreateOrWait -- 否 --> Enqueue["加入等待队列"]
NewConn --> SetTimeout["设置连接超时"]
SetTimeout --> Exec["执行操作"]
UseConn --> Exec
Exec --> Return["归还连接"]
Return --> End(["结束"])
Enqueue --> TimeoutCheck{"等待超时?"}
TimeoutCheck -- 是 --> Reject["拒绝请求/返回排队中"]
TimeoutCheck -- 否 --> WaitNext["继续等待"]
WaitNext --> CheckPool
Reject --> End

慢查询监控（性能分析、阈值、日志）

• 现状
  • Connection 支持 debug_mode 开关与 last_sql/rawSql 等调试能力，但未内置慢查询统计。
• 建议方案
  • 在 query() 执行前后计时，超过阈值的 SQL 记录到慢查询日志，并附带绑定参数、表名、调用栈片段。
  • 提供阈值配置项（毫秒），支持按模块/路由/控制器维度打标签。
  • 聚合统计：QPS、P95/P99 延迟、Top N 慢查询、慢查询占比。
• 关键埋点
  • 进入 query()：记录开始时间戳。
  • 执行后：计算耗时，若超阈值则写日志并上报指标。
  • 错误分支：记录错误信息与堆栈。

sequenceDiagram
participant App as "应用"
participant Conn as "Connection"
participant DB as "MySQL"
App->>Conn : query(sql, params)
Conn->>Conn : 记录开始时间
Conn->>DB : 执行SQL
DB-->>Conn : 结果/错误
Conn->>Conn : 计算耗时
alt 耗时 > 阈值
Conn->>Conn : 记录慢查询日志
end
Conn-->>App : 返回结果

连接池使用率监控（活跃、空闲、等待队列）

• 指标定义
  • 活跃连接数：当前被占用的连接数量。
  • 空闲连接数：可立即复用的连接数量。
  • 等待队列长度：因无可用连接而排队中的请求数。
  • 使用率：活跃/(活跃+空闲)。
• 采集方式
  • 在连接获取/归还处更新计数器。
  • 在等待队列入队/出队处更新队列长度与等待时长。
• 可视化与告警
  • 仪表盘：实时显示上述指标趋势。
  • 告警：使用率持续高于阈值、等待队列持续增长、连接创建失败率上升。

健康检查机制（连接测试、表空间、索引）

• 连接测试
  • 定时执行轻量查询（如 SELECT 1）验证连通性与延迟。
  • 失败时触发告警并尝试重连。
• 表空间监控
  • 定期统计各表大小、增长速率，识别膨胀热点。
• 索引使用情况分析
  • 利用 INFORMATION_SCHEMA 统计索引命中情况，识别缺失或冗余索引。
• 实现要点
  • 在 Connection 中新增 healthCheck()、tableStats()、indexUsage() 等方法。
  • 通过后台任务或外部调度器周期性执行，并将结果持久化到监控存储。

性能指标收集与分析方法

• 指标清单
  • 连接：创建耗时、失败率、复用率、超时率。
  • 查询：QPS、平均/分位延迟、慢查询比例、错误率。
  • 资源：CPU、内存、IO、锁等待（由数据库侧提供）。
• 分析方法
  • 趋势分析：观察峰值时段与突增原因。
  • 根因定位：结合慢查询日志与执行计划定位瓶颈。
  • 容量规划：根据增长趋势评估扩容需求。

异常告警配置

• 告警规则建议
  • 连接失败率 > 阈值（如 1%）持续 5 分钟。
  • 慢查询占比 > 阈值（如 5%）持续 10 分钟。
  • 连接使用率 > 阈值（如 85%）持续 15 分钟。
  • 等待队列长度 > 阈值（如 50）持续 5 分钟。
• 通知渠道
  • 邮件、企业微信、短信、监控平台告警。
• 降噪策略
  • 分级告警（警告/严重）、合并重复告警、静默窗口。

依赖关系分析

• DB 门面依赖 Connection，作为统一入口。
• Connection 依赖 mysqli 扩展与数据库配置。
• 插件连接池依赖配置构建器与连接适配器，提供进程内连接复用。
• 诊断脚本用于环境校验与基础连通性测试。

graph LR
DBF["DB 门面"] --> CONN["Connection"]
CONN --> CFG["配置 config.php"]
CONN --> MYSQL["MySQL"]
PLM["插件连接池"] --> CFG
PLM --> ADP["适配器/句柄"]
ADP --> MYSQL
DIAG["诊断脚本"] --> MYSQL

性能考量

• 避免在热路径上执行重型监控逻辑，采用异步上报与采样策略。
• 慢查询日志需限制写入频率与保留周期，防止磁盘压力。
• 连接池大小与超时参数需结合业务 QPS 与数据库承载能力调优。
• 使用 EXPLAIN/执行计划优化慢查询，减少全表扫描与大结果集。

故障排查指南

• 连接失败
  • 检查主机、端口、用户名、密码、权限。
  • 查看 Connection 的错误输出与调试日志。
• 慢查询增多
  • 启用慢查询日志，定位 Top SQL。
  • 检查索引、统计信息、执行计划。
• 连接耗尽
  • 检查连接池大小、超时配置、是否存在长事务或未归还连接。
  • 观察等待队列与使用率趋势。
• 诊断工具
  • 使用升级/诊断脚本进行基础连通性检查与环境确认。

结论

通过在 Connection 层补齐慢查询统计、连接复用与等待队列监控，并结合插件连接池的已有能力，DouPHP 可在不侵入业务代码的前提下获得完善的数据库可观测性。配合合理的阈值与告警策略，能够及时发现并缓解数据库层面的风险，保障系统稳定运行。

附录

• 配置项建议
  • 慢查询阈值：默认 500ms，可按环境调整。
  • 连接池最大连接数：根据并发与数据库承载设定。
  • 连接超时：建议 5-10s，避免雪崩。
• 监控面板建议
  • 连接池：活跃/空闲/等待/使用率。
  • 查询：QPS、延迟分布、慢查询占比。
  • 健康：连通性、错误率、表空间增长。