# diskhound

**Repository Path**: tomlen/diskhound

## Basic Information

- **Project Name**: diskhound
- **Description**: 磁盘元凶猎手: 一条命令找出磁盘满了但 du 找不到的元凶(幽灵文件/日志膨胀/docker垃圾). 零依赖单文件.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# diskhound — 磁盘元凶猎手

磁盘报警了，`du` 却说啥都没占多少？八成是「幽灵文件」——文件早就删了，但进程还攥着句柄，空间死活不释放。`du` 永远看不见它们，`df` 却实打实扣着空间。

diskhound 一条命令把五类元凶一次列清：

1. **幽灵文件**（已删除未释放）——`df` 与 `du` 差值的头号来源
2. **目录大头**——常见膨胀点 TOP 排行
3. **巨型文件**——超过阈值的 TOP 文件
4. **日志膨胀**——大日志 + 是否配了 logrotate
5. **环境杂项**——journald / Docker / core dump（在啥环境用啥，缺了自动跳过）

最后给出**可释放空间估算 + 处置命令清单**。只给计划，不自动执行——删什么重启什么，决定权在你。

## 为什么不用 du

| | du | diskhound |
|---|---|---|
| 已删除未释放的幽灵文件 | ❌ 永远看不见 | ✅ lsof 抓现行，连占用进程一起报 |
| 健康分与水位告警 | ❌ | ✅ 退出码 2 可直接接 cron |
| 可释放空间估算 | ❌ | ✅ 幽灵+日志+journal+core 合计 |
| Docker/journal/core | 各装各的 | ✅ 一屏列清 |

## 安装

零依赖，仅 Python 标准库。Linux / macOS 通用：

```bash
curl -fsSL https://gcore.jsdelivr.net/gh/tomlen045/diskhound@main/diskhound.py -o diskhound.py
chmod +x diskhound.py
```

## 用法

```bash
# 基本扫（默认 /var/log /tmp, macOS 自动换 ~/Library/Logs）
python3 diskhound.py

# 指定目录 + TOP8 + 50M 阈值（默认值）
python3 diskhound.py /var /home --top 8

# 大小阈值写成人类单位
python3 diskhound.py --min-size 200M

# 存快照, 下次对比增量（哪个文件在偷偷长大）
python3 diskhound.py --json snap.json
python3 diskhound.py --baseline snap.json

# 自测
python3 diskhound.py --selftest
```

**退出码**：0 正常；2 有挂载点水位 > 90%。直接接 cron：

```cron
0 9 * * * python3 /opt/diskhound.py / && echo "磁盘水位超90" | mail -s disk-alert you@corp.com
```

## 输出长什么样

```
[2] 幽灵文件 (已删除未释放, 进程还攥着)
   13.6M  .../com.apple.LaunchServices-...csstore  pid=638 cmd=Wallpaper
   小计: 2.7G —— 关掉/重启对应进程即释放

[6] 环境杂项
   docker Images   大小 70.98GB  可回收 39.93GB (56%)

磁盘健康分: 86/100 🟢  (最高水位 89%, 可释放估算 2.7G)
```

（以上为真机实拍数据：macOS 上 Wallpaper/chronod 攥着已删除的 LaunchServices 索引不放，2.7G；Docker 70.98GB 镜像里 39.93GB 可回收。）

## 三分钟上手

```bash
python3 diskhound.py --selftest        # 1. 自测应 6/6 PASS
sudo python3 diskhound.py /            # 2. 全盘首扫（幽灵文件要 root 才能看全）
python3 diskhound.py --json snap.json  # 3. 存基线
python3 diskhound.py --baseline snap.json  # 4. 一周后对比增量
```

## 设计边界（不吹牛）

- 扫描有深度（6 层）与时间（25s/根）预算，超大目录自动截断——给方向不给逐字节审计
- 幽灵文件检测依赖 `lsof`，容器里需 `--privileged` 才看得全
- 处置计划**只建议不执行**，rm 和重启请自己来
- 健康分是启发式不是 SLA

## 工具链

`cronguard`（盯定时任务）→ `logwhisperer`(考古日志) → **`diskhound`（磁盘元凶）** → `debugkit`(立案修复) → `porteye`(查暴露面)

## LICENSE

MIT