简介
本方案为 DouPHP 构建完整的磁盘存储监控体系，覆盖以下目标：
- 存储目录使用量监控：uploads、缓存、备份等关键目录的空间占用与增长趋势。
- 日志文件监控与清理：错误日志、访问日志、业务日志的大小监控与自动清理策略。
- 临时文件管理：会话文件、上传临时文件、缓存文件的清理机制。
- 存储空间预警：阈值配置、自动清理规则、存储空间报告生成。
- 文件权限与安全：目录权限检查与安全性校验。
该方案基于现有文件系统抽象、附件服务、日志子系统与后台工具能力进行设计与落地。
项目结构
DouPHP 的存储与日志相关的关键位置如下：
- 运行时存储根目录：storage（含 log、cache、session、backup 等子目录）。
- 上传与图片目录：images/upload 及 images 下各模块目录。
- 日志输出：按日写入 storage/log/log_YYYY-MM-DD.log。
- 文件系统抽象：通过 FilesystemManager 解析 disk 配置并构造 Disk。
- 附件上传：AttachmentService 与 ChunkedUploadHandler 负责落盘与元数据记录。
- 后台工具：ToolService 提供关键目录读写权限检测。
- 备份功能：BackupController 与视图用于数据库备份与大小统计。
graph TB
A["应用请求"] --> B["附件上传<br/>AttachmentService"]
B --> C["文件系统管理器<br/>FilesystemManager"]
C --> D["本地磁盘适配器<br/>LocalAdapter(images/upload)"]
B --> E["附件元数据入库<br/>AttachmentRepository"]
A --> F["日志记录<br/>Log::write"]
F --> G["日志目录<br/>storage/log/log_YYYY-MM-DD.log"]
A --> H["后台健康检查<br/>ToolService"]
H --> I["目录权限检测<br/>storage/images/theme 等"]
A --> J["备份流程<br/>BackupController"]
J --> K["备份文件<br/>storage/backup"]核心组件
- 文件系统管理器（FilesystemManager）
- 职责：解析 disk 名到磁盘配置与实例；支持命名约定推导与显式声明覆盖；提供 build 动态构造磁盘。
- 关键点：默认驱动 local；upload_defaults 统一上传策略；disks.local.root 指向 images/upload。
- 附件服务（AttachmentService）
- 职责：处理图片水印、缩略图生成、文件大小计算与持久化；与存储系统交互。
- 关键点：通过 FilesystemManager 获取磁盘；记录附件尺寸与缩略图尺寸。
- 分片上传处理器（ChunkedUploadHandler）
- 职责：处理分片上传落盘与元数据插入；记录 last_used_at、created_at、size 等字段。
- 关键点：clearstatcache 后读取真实文件大小；状态机 draft/owned。
- 日志子系统（Log）
- 职责：分级日志写入；自动上下文补全；采样与限流；敏感信息脱敏；按日文件输出。
- 关键点：日志路径 storage/log；clean 方法支持保留最近 N 天日志。
- 后台工具（ToolService）
- 职责：关键目录存在性与可写性检测；确保 storage/state 等运行态目录存在。
- 关键点：扫描 storage 及其子目录，结合 images、theme 等目录进行权限校验。
- 备份控制器（BackupController）
- 职责：数据库备份入口；表列表与大小统计；配合视图展示备份容量。
- 关键点：与备份视图协作显示总量与分卷大小设置。
架构总览
下图展示了从请求到存储落盘、日志写入、权限检查与备份的整体流程，以及各组件之间的依赖关系。
sequenceDiagram
participant Client as "客户端"
participant App as "应用层"
participant FS as "文件系统管理器"
participant Disk as "本地磁盘"
participant Att as "附件服务"
participant Log as "日志子系统"
participant Tool as "后台工具"
participant Backup as "备份控制器"
Client->>App : 上传/访问/操作
App->>FS : 获取磁盘配置/实例
FS-->>App : Disk(Images/Upload)
App->>Att : 执行附件处理
Att->>Disk : 写入文件/缩略图
Att-->>App : 返回URL/尺寸
App->>Log : 记录业务/错误日志
Log->>Log : 写入storage/log/log_YYYY-MM-DD.log
App->>Tool : 触发目录权限检查
Tool-->>App : 返回可写性结果
App->>Backup : 触发备份
Backup-->>Client : 返回备份大小/进度详细组件分析
存储目录使用量监控（uploads、缓存、备份）
- 监控范围
- uploads：images/upload 目录（由 filesystems.disks.local.root 指定）。
- 缓存：storage/cache（如启用缓存模块或第三方缓存驱动时）。
- 备份：storage/backup（数据库备份 SQL 文件）。
- 实现要点
- 使用 FilesystemManager.getDiskConfig 获取 disks.local.root 作为 uploads 根路径。
- 遍历 storage 子目录，汇总各目录大小与文件数量。
- 对备份文件按日期或分卷统计大小，结合 BackupController 的表大小统计进行交叉验证。
- 指标建议
- 目录总大小、当日新增大小、文件数增长率、最大单文件大小。
- 备份文件数量与总大小、分卷大小配置。
- 可视化建议
- 仪表盘展示各目录大小占比与趋势折线图。
- 告警阈值：超过磁盘容量的 80% 或单目录日增超过阈值。
日志文件监控与自动清理
- 日志位置与格式
- 路径：storage/log/log_YYYY-MM-DD.log。
- 内容：时间戳、级别、消息与上下文（已脱敏）。
- 监控项
- 日志文件大小、当日写入条数、错误级别占比、采样率与限流效果。
- 自动清理策略
- 使用 Log::clean(keepDays) 清理历史日志，保留最近 N 天。
- 建议生产环境 keepDays=30，调试环境可调高。
- 安全与质量
- 敏感字段掩码（password、token、secret 等）。
- URL 查询串中的敏感参数值被替换为占位符。
- 可通过 setSampleRate 与 setMaxPerMinutePerKey 控制日志量。
flowchart TD
Start(["开始"]) --> CheckEnabled["检查日志是否启用"]
CheckEnabled --> |否| End(["结束"])
CheckEnabled --> |是| InitPath["初始化日志路径(storage/log)"]
InitPath --> FormatMsg["格式化消息与上下文"]
FormatMsg --> SampleCheck{"采样丢弃?"}
SampleCheck --> |是| End
SampleCheck --> |否| RateLimit{"限流丢弃?"}
RateLimit --> |是| End
RateLimit --> |否| WriteFile["追加写入log_YYYY-MM-DD.log"]
WriteFile --> End临时文件管理监控（会话、上传临时、缓存）
- 会话文件
- 位置：通常位于 storage/session（若使用文件会话）。
- 监控：会话文件数量、过期会话清理策略（结合 PHP session 配置与定时任务）。
- 上传临时文件
- 位置：PHP upload_tmp_dir（独立于 images/upload）。
- 监控：临时文件数量与大小；断点续传残留文件清理。
- 缓存文件
- 位置：storage/cache（若启用文件缓存）。
- 监控：缓存命中率、缓存目录大小、过期键清理。
- 清理机制建议
- 定时任务：每小时扫描并删除超过阈值的临时文件与会话文件。
- 分片上传：在 ChunkedUploadHandler 中记录 last_used_at，定期清理长时间未使用的分片。
存储空间预警配置（阈值、自动清理、报告）
- 阈值设置
- 磁盘使用率：建议 80% 警告、90% 严重。
- 目录级阈值：uploads 日增 > 500MB、日志日增 > 100MB、备份集 > 2GB。
- 自动清理规则
- 日志：Log::clean(keepDays)。
- 临时文件：基于 last_used_at 与创建时间清理。
- 备份：保留最近 N 份，删除旧备份。
- 报告生成
- 每日生成存储报告：各目录大小、增长量、告警事件、清理结果。
- 通过后台任务或外部监控平台采集指标并推送通知。
文件权限监控与安全性检查
- 权限检查
- ToolService 会确保 storage/state 存在并检测 storage、images、theme 等目录的可写性。
- 建议将 storage 设置为仅 Web 用户可写，其他用户只读。
- 安全性检查
- 禁止直接访问 storage 下的敏感目录（如 log、session）。
- 限制上传扩展名（allow_extensions），避免 SVG 等高风险类型。
- 日志脱敏防止凭据泄露。
classDiagram
class ToolService {
+buildDirectoryCheckData() array
-buildWriteableListRows() array
}
class FilesystemManager {
+disk(name) Disk
+getDiskConfig(name) array
+build(relativeRoot, overrides) Disk
}
class AttachmentService {
+store(...)
-buildWatermarkOptions(...)
}
ToolService --> FilesystemManager : "读取磁盘配置"
AttachmentService --> FilesystemManager : "获取磁盘实例"依赖关系分析
- 组件耦合
- AttachmentService 依赖 FilesystemManager 获取磁盘；与 ImageManager 协作处理图片。
- Log 依赖 STORAGE_PATH 常量确定日志目录；与 Session 关联获取用户上下文。
- ToolService 依赖文件系统函数与常量进行权限检测。
- 外部依赖
- 文件系统驱动：local（可扩展 oss/s3）。
- 操作系统：文件 IO、目录遍历、权限模型。
- 潜在循环依赖
- 当前未发现循环依赖；各组件职责清晰，依赖方向单向。
graph LR
AS["AttachmentService"] --> FM["FilesystemManager"]
AS --> IM["ImageManager"]
LOG["Log"] --> SP["STORAGE_PATH"]
TS["ToolService"] --> FS["文件系统IO"]
BC["BackupController"] --> DB["数据库"]性能考量
- 日志写入
- 使用 FILE_APPEND | LOCK_EX 保证并发安全。
- 通过采样与限流降低高频日志对 IO 的影响。
- 附件处理
- 缩略图生成与水印处理可能耗时，建议在队列中异步执行。
- clearstatcache 确保文件大小准确，但频繁调用会影响性能，应合理控制。
- 目录扫描
- 大目录遍历成本高，建议增量扫描与缓存统计结果。
- 备份
- 大库备份可能阻塞主进程，建议使用分卷与后台任务。
故障排查指南
- 日志无法写入
- 检查 storage/log 目录是否存在且可写。
- 确认日志级别与白名单配置是否正确。
- 上传失败
- 检查 images/upload 目录权限与磁盘空间。
- 查看附件服务日志与分片上传状态。
- 权限问题
- 使用 ToolService 的目录检查功能定位不可写目录。
- 修正文件系统权限与所有者。
- 备份异常
- 检查数据库连接与备份目录权限。
- 查看备份控制器日志与视图输出的大小统计。
结论
本方案基于 DouPHP 现有的文件系统抽象、附件服务、日志子系统与后台工具，构建了覆盖存储目录、日志、临时文件、备份与权限安全的完整监控体系。通过合理的阈值配置、自动清理策略与报告生成，可有效预防磁盘耗尽风险，提升系统稳定性与可维护性。
附录
- 配置参考
- 文件系统默认配置与上传策略：filesystems.upload_defaults、filesystems.disks.local.root。
- 日志路径与清理：Log::setPath、Log::clean。
- 实施建议
- 在生产环境启用日志采样与限流。
- 定期执行存储报告与清理任务。
- 对关键目录进行权限加固与访问控制。