简介
本指南面向 DouPHP 的日志管理体系，覆盖错误日志、访问日志、业务审计日志三类日志的配置、采集、存储、轮转与清理策略，并提供查询与告警建议。文档基于仓库中现有实现进行说明，确保可落地、可运维。
项目结构
DouPHP 将“应用运行日志”和“业务审计日志”解耦：
- 应用运行日志：由统一日志类写入 storage/log 下的按日文件，支持分级、采样、限流、通道白名单、敏感信息脱敏等能力。
- 业务审计日志：通过审计服务写入数据库表（user_log、book_log、admin_log），用于用户行为、预约变更、后台操作的合规审计。
graph TB
A["业务模块/控制器"] --> B["应用日志 Log"]
A --> C["审计服务 AuditService"]
B --> D["storage/log/log_YYYY-MM-DD.log"]
C --> E["数据库 user_log / book_log / admin_log"]核心组件
- 应用日志 Log：提供分级记录、自动上下文补全、敏感字段脱敏、采样率控制、每分钟同 key 限流、按日落盘、清理工具方法。
- 审计服务 AuditService：封装 user_log、book_log、admin_log 的写入，统一 IP、时间戳、结果码与详情字段。
- API 日志配置：_'/.api/config/log.php 定义 enabled、min_level、enabled_levels、enabled_channels、sample_rate、max_per_minute_per_key、keep_days 以及各 channel 开关。
架构总览
下图展示一次典型请求在 DouPHP 中的日志路径：HTTP 进入后，业务逻辑调用审计服务记录操作到数据库；同时通过应用日志记录结构化运行日志，包含自动注入的请求上下文与敏感信息脱敏。
sequenceDiagram
participant Client as "客户端"
participant App as "业务控制器/服务"
participant Log as "应用日志 Log"
participant Audit as "审计服务 AuditService"
participant DB as "数据库"
participant FS as "文件系统"
Client->>App : HTTP 请求
App->>Audit : writeUserLog/writeAdminLog
Audit->>DB : 插入 user_log/book_log/admin_log
App->>Log : info/warning/error(..., context)
Log->>Log : 自动上下文补全 + 敏感脱敏
Log->>FS : 写入 storage/log/log_YYYY-MM-DD.log
App-->>Client : 响应详细组件分析
应用日志 Log：级别、通道、采样与限流
- 级别体系：emergency/alert/critical/error/warning/notice/info/debug，支持最小级别过滤与级别白名单。
- 通道机制：channel 用于区分不同子系统或场景（如 router/response/download_* 等），可通过 enabled_channels 白名单精确控制。
- 自动上下文：自动补充 request_id、scene、ip、route、request_uri、method、module、action、user_id、admin_id、work_id 等。
- 安全脱敏：对敏感键名（password/token/secret 等）及 URL 查询串中的敏感参数进行掩码处理。
- 采样与限流：支持 sample_rate 与 max_per_minute_per_key，避免高并发下日志风暴。
- 落盘格式：[时间] LEVEL: 消息 JSON(上下文)，按天写入 storage/log/log_YYYY-MM-DD.log。
flowchart TD
Start(["写入日志"]) --> CheckEnabled{"是否启用?"}
CheckEnabled --> |否| End(["结束"])
CheckEnabled --> |是| LevelCheck{"级别是否满足阈值?"}
LevelCheck --> |否| End
LevelCheck --> |是| ChannelCheck{"通道是否在白名单?"}
ChannelCheck --> |否| End
ChannelCheck --> |是| AutoCtx["自动补全上下文"]
AutoCtx --> Redact["敏感信息脱敏"]
Redact --> Sample{"采样通过?"}
Sample --> |否| End
Sample --> |是| RateLimit{"限流通过?"}
RateLimit --> |否| End
RateLimit --> |是| Write["写入 storage/log/log_YYYY-MM-DD.log"]
Write --> End审计服务 AuditService：用户、预约、后台操作日志
- 用户审计：writeUserLog 记录登录成功/失败、关键操作等，含 user_id、action、result、details、ip、created_at。
- 预约审计：writeBookLog 记录状态变更前后值、操作者类型/ID、备注等。
- 后台审计：writeAdminLog 强制 action 为常量字符串，自动回退 module 为当前路由模块，并记录 admin_id、ip、result、details。
classDiagram
class AuditService {
-string requestIp
-Request request
+writeUserLog(userId, action, result, details, ip)
+writeBookLog(bookId, action, beforeStatus, afterStatus, remark, operatorType, operatorId, ip) bool
+writeAdminLog(adminId, action, result, details, module, ip) void
}登录流程中的用户行为日志
- 登录失败：根据原因设置 detailTag（账号不存在、密码错误、账户锁定），调用 audit()->writeUserLog 记录 LOGIN_FAIL。
- 登录成功：调用 audit()->writeUserLog 记录 LOGIN_SUCCESS。
sequenceDiagram
participant U as "用户"
participant L as "LoginService"
participant A as "AuditService"
U->>L : 提交登录
L->>L : 校验凭据/状态
alt 失败
L->>A : writeUserLog(LOGIN_FAIL, detailTag)
L-->>U : 返回错误
else 成功
L->>A : writeUserLog(LOGIN_SUCCESS)
L-->>U : 返回成功
endAPI 运行日志：通道与开关
- 配置文件 _'/.api/config/log.php 定义了 enabled、min_level、enabled_levels、enabled_channels、sample_rate、max_per_minute_per_key、keep_days 与各 channel 开关。
- 控制器中广泛使用 Log::info/warning/notice 记录路由器、下载、版权、扩展列表、订单客户端等事件，便于追踪外部交互与异常。
graph LR
Cfg["_'/\\.api/config/log.php"] --> Log["应用日志 Log"]
Ctrl["_'/\\.api/controller/*"] --> Log
Log --> File["storage/log/log_YYYY-MM-DD.log"]后台 AI 日志查看界面
- 后台视图 admin/view/ai_log.htm 展示了 AI 相关日志的筛选与详情展示，包括管理员、提供者、模型、密钥别名、应用名、错误标记、状态码、令牌用量、耗时、请求 ID、端点、IP、元数据、提示内容等。
依赖关系分析
- 应用日志 Log 依赖文件系统（storage/log）与 Request/Session 以获取上下文。
- 审计服务依赖数据库与 Request（用于后台模块推断）。
- API 控制器依赖统一的 Log 门面进行运行日志记录，并通过配置项控制通道与级别。
graph TB
Log["Log"] --> FS["storage/log"]
Log --> Req["Request/Session"]
Audit["AuditService"] --> DB["数据库"]
Audit --> Req
Controllers["API/业务控制器"] --> Log
Controllers --> Audit性能与容量规划
- 日志级别与通道：生产环境建议将 min_level 设置为 warning 或 notice，并通过 enabled_levels/enabled_channels 仅保留必要通道，降低 I/O。
- 采样与限流：在高并发场景开启 sample_rate < 1 与 max_per_minute_per_key > 0，防止日志风暴。
- 存储路径：默认 storage/log，按日分割 log_YYYY-MM-DD.log，便于归档与清理。
- 清理策略：使用 Log::clean(keepDays) 定期清理历史日志，建议 keepDays=30 或依据合规要求调整。
- 容量估算：根据 QPS、日志级别、采样率、每条日志大小估算每日增量，结合磁盘空间制定保留策略。
故障排查指南
- 无法写入日志：检查 storage/log 目录权限与可用空间；确认 Log::setPath 未覆盖到不可写路径。
- 日志缺失：检查 enabled_levels/enabled_channels/min_level 配置是否正确；确认采样率与限流未丢弃关键日志。
- 敏感信息泄露：确认上下文键名命中敏感规则，URL 查询串已脱敏；必要时自定义敏感键片断。
- 审计日志未入库：检查数据库连接与表结构；确认 AuditService 构造时传入的 requestIp 与 Request 可用。
- API 通道未生效：核对 _'/.api/config/log.php 中 channels 开关与 enabled_channels 白名单。
结论
DouPHP 的日志体系将“运行日志”与“审计日志”清晰分离：前者聚焦系统运行、错误与访问轨迹，后者聚焦用户、预约与后台操作的合规审计。通过分级、通道、采样、限流、脱敏与按日归档，既能满足排障需求，又能兼顾性能与安全。配合合理的清理策略与监控告警，可构建稳定可靠的日志治理方案。
附录：配置清单与最佳实践
- 应用日志
- 级别与通道：设置 min_level、enabled_levels、enabled_channels，按需裁剪。
- 采样与限流：合理设置 sample_rate 与 max_per_minute_per_key。
- 存储与清理：默认 storage/log 按日分割；使用 Log::clean(keepDays) 定期清理。
- 审计日志
- 用户行为：在登录成功/失败、关键操作处调用 audit()->writeUserLog。
- 预约变更：在状态变化处调用 audit()->writeBookLog。
- 后台操作：所有管理端修改操作调用 audit()->writeAdminLog，确保 action 为常量。
- API 日志
- 参考 _'/.api/config/log.php 配置 enabled、min_level、channels 等。
- 在控制器中使用 Log::info/warning/notice 记录关键事件。
- 查询与分析
- 运行日志：按日期检索 storage/log/log_YYYY-MM-DD.log，结合 channel、level 过滤。
- 审计日志：通过数据库表 user_log/book_log/admin_log 进行统计与回溯。
- 后台界面：可使用 admin/view/ai_log.htm 作为日志查看示例。
- 告警建议
- 针对 error/critical/emergency 级别与特定 channel（如 order、download_*）建立告警规则。
- 对审计日志中的失败动作（LOGIN_FAIL、DELETE 等）设置阈值告警。
- 对 API 通道中的异常（如 extend_list_missing_slug、public_zip_invalid_type）设置即时告警。