ThinkPHP 3.2 緩存寫入失敗 _STORAGE_WRITE_ERROR_ 徹底排查方案

ThinkPHP 3.2 _STORAGE_WRITE_ERROR_ 錯誤深度排查與解決

遇到 _STORAGE_WRITE_ERROR_ 別慌，90% 以上情況是**服務器磁盤空間耗盡**導致緩存文件無法寫入。本文提供標準化排查流程、臨時恢復方案及長期預防機制。

一、錯誤堆棧分析

_STORAGE_WRITE_ERROR_: ./Application/Runtime/Cache/Home/50c9f5d2ef37c2cf131d5cf1381d3a4b.php
FILE: /ThinkPHP/Library/Think/Storage/Driver/File.class.php LINE: 47
TRACE: ... Think\Template->loadTemplate() -> Think\Storage::put() -> File->put()

核心線索：File->put() 寫入緩存文件失敗，路徑指向 Runtime/Cache/ 目錄。

二、標準排查三步走

1. 檢查磁盤空間（最關鍵）

# 查看所有掛載點使用情況
df -Th

# 重點關注 Use% 欄位，超過 90% 即為隱患
# 輸出示例：
# Filesystem     Type      Size  Used Avail Use% Mounted on
# /dev/vda1      ext4       50G   48G  2.0G  96% /export   <-- 這裡滿了

2. 定位大文件/目錄

# 找出 /export 下超過 20MB 的文件
find /export/ -type f -size +20M -exec ls -lh {} \;

# 或統計目錄佔用（找出佔用最大的目錄）
du -h --max-depth=1 /export/ | sort -hr | head -20

3. 常見佔用大戶

三、緊急恢復操作（業務優先）

# 1. 清理 ThinkPHP 緩存（最直接有效）
rm -rf /export/app/admin.xxx.com.cn/Application/Runtime/Cache/*

# 2. 清理舊日誌（保留近 7 天）
find /export/app/admin.xxx.com.cn/Application/Runtime/Logs/ -name "*.log" -mtime +7 -delete

# 3. 重啟 PHP-FPM 釋放可能被佔用的文件句柄
systemctl reload php-fpm  # 或 service php-fpm reload

# 4. 驗證恢復
curl -I https://yourdomain.com/

四、長期預防機制

1. 配置日誌輪轉

# /etc/logrotate.d/thinkphp
/export/app/*/Application/Runtime/Logs/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 0640 www www
    sharedscripts
    postrotate
        systemctl reload php-fpm > /dev/null 2>&1 || true
    endscript
}

2. ThinkPHP 緩存自動清理策略

# 定時任務：每天凌晨 3 點清理過期緩存
# crontab -e
0 3 * * * find /export/app/*/Application/Runtime/Cache/ -type f -mtime +1 -delete

3. 監控告警（Zabbix/Prometheus/Grafana）

• 磁盤使用率 > 80% 觸發預警
• Inode 使用率 > 85% 觸發預警（大量小文件場景）
• 關鍵目錄大小異常增長告警

4. 架構層面優化

• 緩存分離：將 Runtime/Cache 掛載到獨立磁盤或使用 Redis/Memcached 替代文件緩存。
• 日誌集中化：接入 ELK/EFK，業務服務器不落地日誌。
• 容器化部署：Docker 卷掛載，限制容器寫入配額。

五、代碼層面防禦性編程

<?php
// 在入口文件 index.php 最頂部加入磁盤空間檢查
function checkDiskSpace($path, $minFreeMB = 100) {
    $free = disk_free_space($path);
    if ($free < $minFreeMB * 1024 * 1024) {
        // 記錄錯誤日誌、發送告警郵件/釘釘
        error_log("[CRITICAL] Disk space low: {$path} free " . round($free/1024/1024, 2) . " MB");
        // 可選：返回友好錯誤頁，避免拋出醜陋堆棧
        die('系統維護中，請稍後訪問');
    }
}

// 檢查項目 Runtime 目錄所在分區
checkDiskSpace(__DIR__ . '/Application/Runtime');
?>

總結：_STORAGE_WRITE_ERROR_ 本質是**資源耗盡**而非代碼 Bug。建立「監控→告警→自動清理→容量規劃」閉環，才能徹底根治。