简介

本指南面向 DouPHP 项目的开发与运维人员，围绕“如何高效定位问题、提升排障效率”的目标，系统介绍：

• 调试开关与环境识别（前台/后台/API/小程序）
• 日志系统的配置、分级、采样与限流
• 错误追踪与异常处理机制（含 JSON 与 HTML 两种响应模式）
• 网络请求与响应头调试要点
• 数据库与 SQL 调试思路
• API 接口调试方法（Postman、curl）
• 常见问题排查流程与优化建议

项目结构

DouPHP 采用多入口、分层清晰的架构：

• 前台入口 index.php 负责路由分发、异常兜底与响应发送
• 统一日志能力由 core/infra/log/Log.php 提供，支持级别、通道、采样、限流与敏感信息脱敏
• 安全与响应头由中间件与安全配置共同控制
• 小程序端通过环境探测工具判断是否处于调试环境

graph TB
A["浏览器/客户端"] --> B["前台入口 index.php"]
B --> C["路由分发"]
C --> D["业务控制器/服务"]
D --> E["日志 Log"]
D --> F["数据库/缓存/外部服务"]
D --> G["响应 Response"]
G --> H["安全响应头中间件"]
H --> A

核心组件

• 日志系统：提供分级记录、自动上下文补全、敏感字段脱敏、采样与限流、按日归档与清理。
• 异常处理：前台入口捕获未处理异常，依据 site.debug 与请求类型输出调试页或标准错误响应。
• 响应与响应头：统一设置 HTTP 状态码与安全响应头，便于在浏览器开发者工具中观察。
• 小程序调试环境：前端根据运行环境与服务器配置决定是否开启调试 UI。

架构总览

下图展示一次典型请求从进入前台到返回响应的关键路径，以及日志与异常处理的介入点。

sequenceDiagram
participant U as "用户"
participant I as "前台入口 index.php"
participant R as "路由/控制器"
participant L as "日志 Log"
participant S as "服务/数据层"
participant X as "异常处理器"
participant O as "响应 Response"
U->>I : 发起HTTP请求
I->>R : 解析路由并分发
R->>S : 执行业务逻辑
S-->>R : 返回结果或抛出异常
R->>L : 记录info/debug等日志
alt 发生异常
R->>X : 抛出DomainException/HttpResponseException
X-->>I : 交由入口统一处理
end
I->>O : 生成并发送响应
O-->>U : 返回HTML/JSON及响应头

详细组件分析

日志系统（分级、采样、限流、脱敏）

• 级别与权重：内置 emergency/alert/critical/error/warning/notice/info/debug，默认最低级别为 debug。
• 白名单与通道：可限制仅允许写入的级别与 channel，便于按模块隔离日志。
• 自动上下文：自动附加 request_id、scene、ip、route、module、action、user/admin/work 身份等。
• 采样与限流：支持按比例采样与每分钟同 key 最大条数限制，避免日志风暴。
• 敏感信息保护：对常见敏感键名进行掩码；URL 查询串中的敏感参数值也会被替换。
• 落盘与清理：按日生成 log_YYYY-MM-DD.log，并提供清理保留最近 N 天的能力。

flowchart TD
Start(["调用 write(level, message, context)"]) --> CheckEnabled{"是否启用?"}
CheckEnabled --> |否| End
CheckEnabled --> |是| CheckLevel{"级别是否达到阈值?"}
CheckLevel --> |否| End
CheckLevel --> |是| Channel{"通道是否在白名单?"}
Channel --> |否| End
Channel --> |是| AutoCtx["自动补全上下文"]
AutoCtx --> Normalize["规范化上下文(截断trace/脱敏)"]
Normalize --> Sample{"采样丢弃?"}
Sample --> |是| End
Sample --> |否| RateLimit{"限流丢弃?"}
RateLimit --> |是| End
RateLimit --> |否| Write["写入当日日志文件"]
Write --> End(["结束"])

异常处理与错误页面

• 入口统一捕获：前台入口捕获 DomainException、HttpResponseException、RedirectException 以及通用 Exception/Throwable。
• JSON 与 HTML 双模式：根据请求是否期望 JSON，分别返回结构化错误或渲染调试页。
• 调试模式：当站点调试开启时，输出详细的堆栈与上下文；否则回退到友好提示或标准 500 JSON。
• 业务异常：DomainException 会携带错误码与错误详情，便于前端统一处理。

sequenceDiagram
participant C as "客户端"
participant I as "入口 index.php"
participant H as "异常处理器"
participant J as "JSON响应"
participant P as "页面提示"
C->>I : 请求
I->>I : 执行路由/控制器
alt 抛出DomainException
I->>H : 捕获并判断是否JSON请求
alt JSON请求
H->>J : 返回422业务错误
else HTML请求
H->>P : 显示消息提示
end
else 其他异常
I->>H : 捕获并判断site.debug
alt 调试开启
H-->>C : 输出调试页/JSON
else 生产模式
H-->>C : 返回500或友好错误页
end
end

响应与安全响应头

• 响应发送：统一设置 HTTP 状态码与响应头后输出内容。
• 安全响应头：中间件根据安全配置下发基线安全头（如 X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy），并在 HTTPS 且开启时下发 HSTS。
• 调试建议：在浏览器“网络”面板查看响应头，确认安全策略是否生效。

graph LR
A["控制器/服务"] --> B["Response::send()"]
B --> C["设置状态码与头部"]
C --> D["安全响应头中间件"]
D --> E["返回给客户端"]

小程序调试环境

• 环境探测：isDebugEnv() 读取当前小程序版本是否为非正式版（develop/trial）。
• 服务端调试镜像：isServerDebug() 读取服务端 debug_enable 配置，用于控制服务端调试行为。
• 使用建议：在非正式环境下开启更多调试 UI；正式发布时自动静默。

依赖关系分析

• 入口 index.php 依赖路由、异常处理器与响应对象，负责统一异常捕获与响应发送。
• 日志 Log 被各层广泛调用，提供统一的记录能力，并通过配置控制行为。
• 安全响应头中间件依赖安全配置，确保每次命中路由的请求都带上必要的安全头。
• 小程序端依赖运行时环境信息与站点配置，决定调试 UI 的可见性。

graph TB
I["index.php"] --> R["路由/控制器"]
R --> L["Log"]
R --> X["异常处理"]
R --> O["Response"]
O --> M["安全响应头中间件"]
M --> Cfg["security.php"]
MP["小程序 env.ts"] --> SiteCfg["站点配置(debug_enable)"]

性能注意事项

• 日志采样与限流：在高并发场景下，合理设置采样率与每分钟单 key 最大条数，避免磁盘 IO 成为瓶颈。
• 最小化上下文：仅在必要时传递大对象或长堆栈，减少序列化开销。
• 响应头与中间件：安全响应头开销极低，但应确保仅在命中路由时添加，避免对静态资源造成额外处理。
• 数据库慢查询：结合数据库慢查询日志与 EXPLAIN 计划，定位全表扫描与缺失索引。
• 内存使用：关注大数组、循环内频繁对象创建，尽量复用与分批处理。

故障排查指南

• 快速定位问题
  • 打开浏览器“网络”面板，检查请求 URL、请求头、响应状态码与响应体。
  • 若为 JSON 接口，优先查看响应体中的错误码与错误详情。
  • 若为 HTML 页面，检查控制台是否有 JS 报错，并核对响应头是否正确。
• 日志分析
  • 查看 storage/log 下的当日日志文件，过滤 error/critical/alert 级别。
  • 使用 request_id 关联同一请求的多条日志，快速串联调用链。
  • 注意敏感字段已被脱敏，若需进一步排查，可在本地临时提高日志级别并谨慎操作。
• 异常与错误页
  • 在生产环境关闭站点调试，避免泄露敏感信息；开发环境可开启以获取详细堆栈。
  • 对于 JSON 请求，错误会以结构化格式返回，便于前端统一处理。
• 安全与代理
  • 若部署在反向代理之后，需在安全配置中声明可信代理，以确保 IP 与 Host 判定正确。
  • 检查安全响应头是否按预期下发，尤其是 HSTS、X-Content-Type-Options 等。
• 小程序调试
  • 在非正式版环境中启用调试 UI；若服务端调试关闭，部分调试信息可能不可见。
• 数据库调试
  • 使用数据库客户端执行 EXPLAIN 分析慢查询，关注 type、key、rows、Extra 等关键字段。
  • 针对高频查询建立合适索引，避免 SELECT * 与大结果集传输。
• API 调试
  • 使用 Postman 或 curl 构造请求，携带必要的认证头与签名参数。
  • 对比不同环境的请求差异，逐步缩小问题范围。

结论

DouPHP 提供了完善的日志、异常处理与安全响应头机制，配合浏览器开发者工具与小程序调试环境，能够高效定位问题。建议在开发阶段充分利用调试模式与详细日志，在生产环境严格限制日志级别与敏感信息输出，并结合数据库分析与性能监控持续优化。

附录

• 常用调试清单
  • 确认站点调试开关与请求类型（JSON/HTML）
  • 检查响应状态码与安全响应头
  • 抓取 request_id 并检索对应日志
  • 复现问题时记录完整请求与响应
  • 对慢查询执行 EXPLAIN 并评估索引
  • 使用 Postman/curl 构造最小可复现用例
• 相关配置参考
  • 日志级别、通道、采样与限流：core/infra/log/Log.php
  • 云服务 API 日志配置：_'.api/config/log.php
  • 安全响应头与安全策略：config/security.php
  • 小程序调试环境：miniprogram/company/utils/env.ts