first commit

readme.md

@@ -0,0 +1,107 @@
+# Linux 日志删除助手
+
+一个用于在 UOS LiveCD 环境中快速清理 Linux 系统磁盘空间的 GUI 工具。
+
+## 适用场景
+
+同事的 Linux 系统磁盘满了，无法进入桌面。使用 UOS LiveCD 启动后，运行本工具快速清理日志和大文件，恢复系统正常运行。
+
+## 功能特性
+
+- 🔍 **自动检测磁盘分区** - 列出所有可用分区，自动排除 EFI、swap 和 LiveCD USB 分区
+- 📊 **目录大小统计** - 扫描并显示每个目录的占用空间，支持后台线程不阻塞界面
+- 📁 **文件浏览器** - 支持浏览子目录，查看文件详情，支持前进/后退/上级目录导航
+- 🗑️ **右键删除** - 支持删除文件和目录，带二次确认防误删
+- ⚡ **快捷删除系统日志** - 检测 /var/log 下大于 1GB 的日志文件，提供一键清理按钮
+- 🔐 **自动处理 sudo 权限** - 启动时自动检测 sudo 是否需要密码，需要则弹窗提示
+
+## 系统要求
+
+- Linux 系统（推荐 UOS LiveCD）
+- Python 3.6+
+- PyQt5
+
+## 快速开始
+
+### 方法 1: 直接运行 Python 脚本
+
+```bash
+# 安装依赖
+sudo apt update
+sudo apt install python3-pyqt5
+
+# 运行
+sudo python3 main.py
+```
+
+### 方法 2: 打包为可执行文件
+
+```bash
+# 在 UOS 环境中打包
+chmod +x build.sh
+./build.sh
+
+# 运行打包后的程序
+sudo ./dist/log-cleaner
+```
+
+## 操作流程
+
+```
+启动程序 → 输入 sudo 密码 → 选择分区 → 浏览文件 → 删除大文件 → 完成
+```
+
+1. **选择分区** - 程序启动后自动弹出分区选择对话框，显示各分区容量和使用率
+2. **浏览文件** - 双击文件夹进入子目录，工具栏支持后退/前进/上级目录
+3. **统计目录大小** - 点击"📊 统计目录大小"扫描各目录占用
+4. **删除文件** - 右键文件/目录 → 选择删除 → 勾选确认 → 执行删除
+5. **快捷删除日志** - 若 /var/log 日志 > 1GB，顶部显示红色快捷按钮
+
+## 项目结构
+
+```
+├── main.py                 # 程序入口，初始化 QApplication 和 sudo 权限
+├── disk_manager.py         # 磁盘分区检测、挂载、卸载
+├── file_scanner.py         # 目录大小扫描、文件列表、日志检测
+├── utils.py                # 工具函数（sudo 检测、命令执行、格式化）
+├── gui/
+│   ├── __init__.py
+│   ├── main_window.py      # 主窗口（工具栏 + 文件浏览器 + 状态栏）
+│   ├── partition_dialog.py # 分区选择对话框（表格显示分区信息）
+│   ├── file_browser.py     # 文件浏览器组件（表格 + 导航 + 右键菜单）
+│   ├── confirm_dialog.py   # 删除确认对话框（含日志清理确认）
+│   └── sudo_dialog.py      # sudo 密码输入对话框
+├── build.sh                # UOS 环境打包脚本（PyInstaller）
+├── requirements.txt        # Python 依赖
+├── readme.md               # 本文件
+└── HANDOVER.md             # 交接文档（代码架构详解）
+```
+
+## 注意事项
+
+- **删除不可撤销** - 请谨慎操作，重要数据先备份
+- **需要 sudo 权限** - 挂载分区和删除文件需要 root 权限
+- **自动跳过虚拟文件系统** - 扫描时自动跳过 /proc、/sys、/dev 等目录
+- **退出时自动卸载** - 程序退出时会卸载由本工具挂载的分区
+
+## 常见问题
+
+**Q: 为什么看不到某些分区？**
+A: 程序自动排除 EFI (vfat)、swap、LiveCD USB、光盘镜像 (iso9660) 等分区。
+
+**Q: 删除文件时提示权限不足？**
+A: 请确保以 sudo 运行：`sudo python3 main.py`
+
+**Q: 程序在 UOS LiveCD 上无法运行？**
+A: 安装 PyQt5：`sudo apt install python3-pyqt5`
+
+## 开发说明
+
+- 开发环境：Windows 10/11
+- 测试/打包环境：UOS LiveCD
+- 依赖管理：`pip3 install -r requirements.txt`
+- 打包：在 UOS 中运行 `./build.sh`
+
+## 许可证
+
+内部工具，仅供学习和工作使用。