简介

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

• APM 工具集成：New Relic、Sentry、阿里云 ARMS 的接入思路与关键埋点位置。
• 指标采集：响应时间、吞吐量、错误率等应用级指标。
• 数据库监控：慢查询、连接池、锁等待。
• 服务器资源：CPU、内存、磁盘 IO。
• 日志分析：错误日志、性能日志、用户行为追踪。
• 压测工具：JMeter、LoadRunner 的使用方法与场景设计。

本项目已内置日志与审计能力，可作为 APM 数据源与指标采集的基础设施。

项目结构

DouPHP 采用多入口（前台 front、后台 admin、API）+ 核心框架 core 的分层结构。与性能监控密切相关的代码集中在：

• 核心日志：core/infra/log/Log.php
• API 日志配置：_/.api/config/log.php
• 审计日志：core/service/audit/AuditService.php
• API 限流中间件：api/middleware/ThrottleMiddleware.php
• 数据库连接池（插件 SDK 示例）：plugin/alipay/sdk/.../DbConnectionManager.php

graph TB
subgraph "入口"
FRONT["前台入口"]
ADMIN["后台入口"]
API["API 入口"]
end
subgraph "核心"
LOG["日志 Log"]
AUDIT["审计 AuditService"]
THROTTLE["限流 ThrottleMiddleware"]
end
subgraph "外部系统"
DB["数据库"]
APM["APM 平台"]
OS["操作系统指标"]
end
FRONT --> LOG
ADMIN --> LOG
API --> THROTTLE
API --> LOG
LOG --> DB
AUDIT --> DB
LOG --> APM
THROTTLE --> APM
OS --> APM

核心组件

• 统一日志 Log：支持分级、采样、限流、上下文自动补全、敏感信息脱敏、按日落盘。
• 审计服务 AuditService：记录会员、预约、后台操作审计日志，便于行为追踪与合规审计。
• API 限流 ThrottleMiddleware：对关键接口进行 IP 维度的限流，保护后端并产出限流事件指标。
• 日志配置 log.php：定义启用开关、最小级别、通道白名单、采样率、保留天数等。

架构总览

下图展示请求从进入入口到日志、审计、限流以及外部 APM 的交互路径。

sequenceDiagram
participant C as "客户端"
participant M as "中间件(限流)"
participant APP as "业务处理"
participant L as "日志 Log"
participant A as "审计 AuditService"
participant D as "数据库"
participant P as "APM 平台"
C->>M : HTTP 请求
M->>M : 匹配限流规则
alt 超限
M-->>C : 429 限流
M->>P : 上报限流事件
else 未超限
M->>APP : 放行
APP->>L : 写入请求/错误日志
APP->>A : 写入审计日志
A->>D : 持久化审计记录
APP->>P : 上报性能指标(耗时/状态码)
APP-->>C : 响应
end

详细组件分析

日志子系统（Log）

• 功能要点
  • 分级输出：emergency/alert/critical/error/warning/notice/info/debug。
  • 采样与限流：支持 sample_rate 与 max_per_minute_per_key，避免日志风暴。
  • 自动上下文：自动注入 request_id、scene、ip、route、method、module、action、user/admin/work 身份等。
  • 安全脱敏：对敏感键名与 URL 查询串参数进行掩码处理。
  • 落盘策略：按日生成 log_YYYY-MM-DD.log，支持清理保留天数。
• 与 APM 的结合点
  • 将 error/critical 级别日志作为错误事件上报至 APM。
  • 在关键业务节点写入 info/debug 日志，附带 request_id，用于链路追踪。
  • 通过 channel 区分前端/后台/API，便于分端看板。

flowchart TD
Start(["调用 write"]) --> CheckEnabled{"是否启用?"}
CheckEnabled --> |否| End
CheckEnabled --> |是| LevelCheck{"级别是否达标?"}
LevelCheck --> |否| End
LevelCheck --> |是| ChannelCheck{"通道是否允许?"}
ChannelCheck --> |否| End
ChannelCheck --> |是| AutoCtx["自动补全上下文"]
AutoCtx --> Sample{"采样丢弃?"}
Sample --> |是| End
Sample --> |否| RateLimit{"每分钟同key限流?"}
RateLimit --> |是| End
RateLimit --> |否| Write["格式化并落盘"]
Write --> End(["结束"])

审计服务（AuditService）

• 功能要点
  • 会员登录/注册等行为审计：writeUserLog。
  • 预约变更审计：writeBookLog。
  • 后台操作审计：writeAdminLog，包含模块、IP、结果与详情。
• 与用户行为追踪
  • 结合 Log 的 request_id，可将审计记录与请求日志关联，形成“用户行为轨迹”。
  • 在登录失败、账号锁定等分支写入审计日志，便于安全与风控分析。

classDiagram
class AuditService {
+writeUserLog(userId, action, result, details, ip)
+writeBookLog(bookId, action, beforeStatus, afterStatus, remark, operatorType, operatorId, ip)
+writeAdminLog(adminId, action, result, details, module, ip)
}
class DB {
+table(name)
+data(fields)
+insert()
}
AuditService --> DB : "写入审计表"

API 限流中间件（ThrottleMiddleware）

• 功能要点
  • 针对登录、注册、短信验证码、匿名写接口、防伪查询、LLM 成本端点进行 IP 维度限流。
  • 超限返回 429，并设置 Retry-After。
• 与性能监控
  • 将限流事件作为可用性/错误率指标上报 APM。
  • 统计各路由的限流次数，识别异常流量或攻击。

sequenceDiagram
participant R as "请求"
participant T as "限流中间件"
participant S as "业务"
R->>T : 访问受保护路由
T->>T : 计算窗口内计数
alt 超过配额
T-->>R : 429 + Retry-After
T->>APM : 上报限流事件
else 未超限
T->>S : 放行
S-->>R : 正常响应
end

数据库连接池（示例）

• 说明
  • 插件 SDK 中的 DbConnectionManager 展示了连接池的基本形态：获取连接、缓存连接、过期时间管理。
  • 可用于理解连接复用与生命周期管理，为后续接入数据库监控提供参考。
• 监控建议
  • 监控连接池大小、活跃连接数、获取/释放耗时、连接泄漏告警。
  • 结合数据库慢查询日志与执行计划优化热点 SQL。

flowchart TD
Get["获取连接"] --> New{"新建连接?"}
New --> |是| Create["创建连接"]
New --> |否| Cache["从缓存取连接"]
Create --> Use["使用连接"]
Cache --> Use
Use --> Release["释放/回收"]
Release --> TTL{"是否过期?"}
TTL --> |是| Close["关闭连接"]
TTL --> |否| Pool["放回连接池"]

依赖关系分析

• 日志与审计
  • Log 负责通用日志，AuditService 负责结构化审计记录，二者互补。
  • 建议在关键业务处同时写入 Log 与审计日志，并通过 request_id 关联。
• 中间件与业务
  • ThrottleMiddleware 位于请求早期，拦截异常流量，减少下游压力。
• 配置驱动
  • log.php 控制 API 侧日志通道与级别，便于按环境精细化控制。

graph LR
LOG["Log"] --> FILE["日志文件"]
AUDIT["AuditService"] --> DB["审计表"]
THROTTLE["ThrottleMiddleware"] --> API["API 路由"]
LOG -.-> APM["APM 平台"]
AUDIT -.-> APM
THROTTLE -.-> APM

性能注意事项

• 日志采样与限流
  • 生产环境建议开启采样与每分钟单 key 限流，避免日志风暴影响性能。
  • 合理设置最小级别与通道白名单，聚焦关键日志。
• 敏感信息脱敏
  • 利用内置脱敏机制，防止凭据泄露；URL 查询串中的敏感参数会被掩码。
• 审计日志写入
  • 审计写入为同步 I/O，注意在高并发场景下评估写入开销，必要时异步化或批量写入。
• 限流阈值调优
  • 根据业务峰值与第三方限制调整限流窗口与配额，平衡用户体验与系统稳定性。
• 数据库连接池
  • 关注连接池大小与超时配置，避免连接耗尽；结合慢查询日志持续优化 SQL。

故障排查指南

• 无法写入日志
  • 检查存储路径权限与磁盘空间；确认 enabled、min_level、enabled_levels/channels 配置。
  • 参考日志落盘流程定位问题。
• 审计记录缺失
  • 核对业务分支是否正确调用审计方法；检查数据库表结构与写入权限。
• 限流误杀
  • 复核路由键与配额配置；观察 429 事件分布，必要时放宽阈值或拆分路由。
• 数据库连接异常
  • 检查连接池配置与数据库可达性；查看连接获取/释放耗时与泄漏情况。

结论

DouPHP 已具备完善的日志与审计基础，配合限流中间件与合理的配置，即可快速构建可观测体系。在此基础上接入 APM、数据库与系统指标，可实现端到端的性能监控与问题定位。

附录

APM 工具集成指南（New Relic / Sentry / 阿里云 ARMS）

• 通用步骤
  • 安装对应 PHP Agent/SDK。
  • 在应用启动时初始化并传入应用名、密钥等配置。
  • 确保 request_id 透传到日志与 APM，以便链路关联。
• 关键埋点
  • 入口/出口：记录请求开始与结束时间，上报响应时间与状态码。
  • 数据库：上报慢查询、连接池指标。
  • 错误：捕获异常并上报堆栈与上下文。
• 与现有组件结合
  • 将 Log 的 error/critical 事件映射为 APM 的错误事件。
  • 将审计日志与 APM 的用户行为事件关联。
  • 将限流事件作为可用性/错误率指标上报。

指标采集清单

• 应用级
  • 响应时间：P50/P90/P99、QPS、错误率。
  • 吞吐：各路由 QPS、错误占比。
• 数据库
  • 慢查询数量、平均耗时、连接池使用率、锁等待。
• 服务器
  • CPU 使用率、内存占用、磁盘 IO、网络带宽。

日志分析与用户行为追踪

• 错误日志收集
  • 基于 Log 的 error/critical 级别，聚合到日志系统或 APM。
• 性能日志分析
  • 在关键路径写入 info/debug 日志，附带耗时与上下文。
• 用户行为追踪
  • 通过 AuditService 记录登录、注册、预约、后台操作等事件，结合 request_id 串联。

性能测试工具与场景设计

• JMeter
  • 场景：登录、下单、搜索、导出报表。
  • 指标：并发数、响应时间、错误率、吞吐量。
  • 实践：先小规模验证，再逐步加压；关注限流与错误率拐点。
• LoadRunner
  • 场景：复杂业务流程编排、混合协议测试。
  • 指标：事务成功率、资源利用率、瓶颈定位。
• 与系统联动
  • 压测期间开启更细粒度日志与 APM 指标，观察限流、错误率、数据库负载变化。