简介

本指南面向 DouPHP 应用，提供一套完整的“监控与告警”落地方案。内容覆盖：

• 应用性能监控：请求响应时间、错误率、资源使用等指标采集与可视化
• 日志收集与分析：错误日志、访问日志、业务日志的集中管理与检索
• 系统健康检查：数据库连接状态、磁盘空间、内存使用等关键指标
• 告警规则与通知：阈值设置与多渠道通知（邮件、短信、钉钉等）
• 监控仪表板与数据可视化：统一看板搭建建议
• 故障诊断与问题定位：基于现有日志与健康端点的排障方法

本指南既适用于运维人员，也便于开发者快速接入与扩展。

项目结构

DouPHP 在基础设施层提供了统一的日志能力，并在三端（前台 front、后台 admin、API）通过中间件和控制器暴露可观测性入口。健康模块已具备后台管理界面与 API 入口，可作为健康检查的数据源。

graph TB
A["前端/客户端"] --> B["Web 入口<br/>index.php"]
B --> C["路由分发<br/>front/admin/api"]
C --> D["中间件链<br/>安全头/鉴权/限流等"]
D --> E["控制器/服务<br/>业务逻辑"]
E --> F["日志记录器<br/>core/infra/log/Log.php"]
E --> G["数据存储<br/>数据库/缓存/文件"]
H["外部监控/告警系统"] < --> I["日志文件<br/>storage/log/*.log"]
H --> J["健康检查接口<br/>admin/api health"]

核心组件

• 日志子系统：提供分级日志、自动上下文补全、敏感信息脱敏、采样与限流、按日归档等能力，是监控与排障的基础。
• 安全响应头中间件：在 HTTP 边界下发基线安全头，有助于合规与安全审计。
• 健康检查模块：后台提供健康档案与随访管理；API 提供健康模块入口，可用于健康探针或集成外部监控系统。
• 配置中心：站点运行开关、安全策略、系统参数等集中在 config 目录，便于环境隔离与灰度发布。

架构总览

下图展示了从请求进入、到日志落盘、再到外部监控系统的整体链路。

sequenceDiagram
participant U as "用户/客户端"
participant W as "Web 入口"
participant M as "中间件"
participant C as "控制器/服务"
participant L as "日志记录器"
participant S as "存储(文件/DB)"
participant O as "外部监控/告警"
U->>W : "HTTP 请求"
W->>M : "进入中间件链"
M->>C : "调用业务处理"
C->>L : "记录结构化日志"
L->>S : "写入 storage/log/*.log"
C-->>U : "返回响应"
O->>S : "采集日志/指标"
O-->>U : "告警/看板展示"

详细组件分析

日志子系统（核心可观测性基础）

• 功能要点
  • 分级日志：支持 emergency/alert/critical/error/warning/notice/info/debug
  • 自动上下文：自动注入 request_id、scene、ip、route、module、action、user_id、admin_id、work_id 等
  • 敏感信息保护：对常见敏感键名进行掩码，并对 URL 查询串中的敏感参数值进行脱敏
  • 采样与限流：支持按采样率丢弃与每分钟同 key 最大条数限制，避免日志风暴
  • 日志归档：按日生成 log_YYYY-MM-DD.log，并提供清理工具方法
• 监控价值
  • 错误率统计：基于 error/critical/alert/emergency 级别聚合
  • 性能指标：可在关键路径埋点记录耗时，结合 request_id 串联追踪
  • 访问与业务日志：通过 channel 区分不同场景（front/admin/api），便于分渠道治理
• 接入建议
  • 在关键业务方法前后记录耗时，输出 context 包含 route、user_id、trace 等
  • 生产环境开启采样与限流，调试时降低最小级别并关闭采样
  • 将 storage/log 目录纳入日志采集系统（如 ELK/Loki/云日志服务）

flowchart TD
Start(["写入日志入口"]) --> CheckEnabled{"是否启用"}
CheckEnabled --> |否| End
CheckEnabled --> |是| LevelCheck{"级别是否满足阈值"}
LevelCheck --> |否| End
LevelCheck --> |是| ChannelCheck{"通道是否在白名单"}
ChannelCheck --> |否| End
ChannelCheck --> |是| AutoCtx["自动补全上下文"]
AutoCtx --> Normalize["规范化上下文/脱敏"]
Normalize --> Sample{"采样/限流判定"}
Sample --> |丢弃| End
Sample --> |保留| Write["写入 storage/log/*.log"]
Write --> End(["结束"])

安全响应头中间件（安全与审计）

• 作用：在匹配路由的请求中下发基线安全响应头（如 X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy），HTTPS 且配置允许时下发 HSTS
• 监控价值：可通过响应头与访问日志关联，辅助安全审计与合规检查
• 配置来源：读取 security.headers 配置项

健康检查模块（系统健康探针）

• 后台健康：提供健康档案列表、详情、字段配置、随访管理等页面与操作
• API 健康：提供健康模块入口，可用于健康探针或作为外部监控系统的数据源
• 建议扩展：在 HealthController 中增加系统级健康检查（数据库连通性、磁盘空间、内存使用、队列积压等），并以 JSON 形式返回，供 Prometheus Node Exporter 或自定义采集器抓取

sequenceDiagram
participant P as "监控探针"
participant A as "API Health"
participant S as "HealthService"
participant DB as "数据库"
participant FS as "文件系统"
P->>A : "GET /api?route=health"
A->>S : "执行健康检查"
S->>DB : "尝试连接/执行简单查询"
S->>FS : "检查关键目录/文件可写"
S-->>A : "返回健康状态与指标"
A-->>P : "JSON 健康结果"

配置与环境（站点开关与安全策略）

• 站点运行开关：小程序侧 site.ts 提供 debug_enable、rewrite_enable 等开关，便于灰度与调试控制
• 安全策略：security.php 定义安全相关配置，中间件据此下发响应头
• 系统配置：config.php、system.php 用于站点与系统级参数管理

依赖关系分析

• 日志子系统依赖
  • 会话与身份：通过 Session 获取 user_id、admin_id、work_id 等上下文
  • 容器与 Request：在可用时读取当前路由字符串，以增强上下文
  • 文件系统：写入 storage/log 目录下的按日日志文件
• 中间件依赖
  • 配置中心：读取 security.headers 下发安全头
• 健康模块依赖
  • 服务层：HealthService 负责数据组装与业务逻辑
  • 数据库与文件系统：可扩展为健康检查的数据源

graph LR
Log["日志记录器"] --> Session["会话/身份"]
Log --> Container["容器/Request"]
Log --> FS["文件系统(storage/log)"]
MW["安全头中间件"] --> Config["配置中心"]
Health["健康模块"] --> Service["HealthService"]
Service --> DB["数据库"]
Service --> FS

性能考虑

• 日志采样与限流：在高并发场景下，合理设置采样率与每分钟单 key 最大条数，避免日志风暴影响性能
• 上下文裁剪：非 DEBUG 模式下对 trace 长度进行裁剪，减少日志体积
• 异步化建议：对于高吞吐场景，可将日志写入改为异步队列（如消息队列）以降低主流程延迟
• 健康检查节流：对外暴露的健康接口应加入频率限制，避免被频繁探测导致负载升高

故障排查指南

• 定位错误
  • 查看 storage/log 目录下当日日志文件，过滤 error/critical/alert/emergency 级别
  • 使用 request_id 串联一次请求的完整日志，便于跨模块追踪
• 常见问题
  • 数据库连接失败：在健康检查中增加连通性检测，异常时记录 critical 日志并触发告警
  • 磁盘空间不足：监控 storage/log 目录大小，设置轮转与清理策略
  • 内存使用过高：结合系统监控与 PHP 进程内存指标，定位热点代码
• 利用健康接口
  • 通过 API 健康入口返回的状态与指标，集成到外部监控系统，实现自动化巡检

结论

DouPHP 已在基础设施层提供强大的日志能力，并通过健康模块暴露了可观测性入口。结合外部监控与告警系统，可以构建覆盖性能、错误、资源与安全的完整监控体系。建议在关键路径完善埋点、统一日志格式、建立告警规则与看板，形成闭环的运维保障。

附录

应用性能监控（APM）配置建议

• 指标采集
  • 请求响应时间：在控制器或服务层记录开始与结束时间，计算耗时并写入日志
  • 错误率：统计 error/critical/alert/emergency 日志占比
  • 资源使用：结合系统监控（CPU、内存、磁盘、网络）与 PHP-FPM 指标
• 可视化
  • 将日志与指标接入 ELK/Loki/Prometheus/Grafana 等平台，构建统一看板
• 接入方式
  • 在关键业务方法前后埋点，输出结构化日志（包含 route、user_id、耗时等）

日志收集与分析配置建议

• 日志分类
  • 错误日志：error/critical/alert/emergency
  • 访问日志：结合路由与 IP、User-Agent 等上下文
  • 业务日志：通过 channel 区分 front/admin/api 及业务域
• 集中管理
  • 将 storage/log 目录纳入日志采集系统，按天滚动与保留策略
• 检索与分析
  • 基于 request_id 进行全链路追踪
  • 对高频错误进行聚合与告警

系统健康检查配置建议

• 检查项
  • 数据库连接：尝试连接并执行轻量查询
  • 磁盘空间：检查关键目录可写性与剩余空间
  • 内存使用：读取系统或 PHP 进程内存指标
• 暴露方式
  • 在 HealthController 中新增健康检查接口，返回 JSON 状态与指标
• 集成方式
  • 外部监控系统定时调用健康接口，异常时触发告警

告警规则与通知配置建议

• 阈值设置
  • 错误率：例如 5 分钟内错误率超过 5%
  • 响应时间：P95 响应时间超过阈值
  • 资源使用：内存使用率超过 80%，磁盘使用率超过 90%
• 通知渠道
  • 邮件、短信、钉钉机器人等
• 实施建议
  • 在外部监控系统中配置规则与通知模板
  • 结合 request_id 与日志上下文，提升告警可定位性

监控仪表板与数据可视化建议

• 看板维度
  • 流量与响应时间、错误率、资源使用、业务指标（订单量、转化率等）
• 工具推荐
  • Grafana + Prometheus/Loki，或云厂商监控平台
• 数据源
  • 日志：ELK/Loki
  • 指标：Prometheus Exporter（Node Exporter、PHP-FPM Exporter 等）
  • 健康：自定义健康接口