127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
# BootRepairTool - 项目说明
|
||
|
||
## 项目概述
|
||
|
||
**BootRepairTool** 是一个用于修复 Linux 系统 GRUB 引导的图形化工具。适用于 Live USB/CD 环境，帮助用户修复损坏的 GRUB 引导加载器。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
BootRepairTool/
|
||
├── backend.py # 后端逻辑 - 分区扫描、挂载、GRUB修复
|
||
├── frontend.py # 前端界面 - tkinter GUI
|
||
├── README.md # 项目简介
|
||
└── AGENTS.md # 本文件
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **语言**: Python 3
|
||
- **GUI 框架**: tkinter
|
||
- **运行环境**: Linux Live USB/CD (需要 root/sudo 权限)
|
||
|
||
## 核心功能
|
||
|
||
### 1. 分区扫描 (`backend.py:scan_partitions`)
|
||
- 使用 `lsblk -J` 获取磁盘和分区信息
|
||
- 识别 EFI 系统分区 (ESP)
|
||
- 过滤 Live 系统自身的分区
|
||
|
||
### 2. 系统挂载 (`backend.py:mount_target_system`)
|
||
- 挂载根分区 (/)
|
||
- 挂载独立 /boot 分区（可选）
|
||
- 挂载 EFI 分区（UEFI 模式）
|
||
- 绑定伪文件系统 (/dev, /proc, /sys, /run)
|
||
|
||
### 3. 发行版检测 (`backend.py:detect_distro_type`)
|
||
- 支持: Arch, CentOS/RHEL, Debian, Ubuntu
|
||
- 通过读取 `/etc/os-release` 识别
|
||
|
||
### 4. GRUB 修复 (`backend.py:chroot_and_repair_grub`)
|
||
- **BIOS 模式**: `grub-install /dev/sdX`
|
||
- **UEFI 模式**: `grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB`
|
||
- 更新 GRUB 配置:
|
||
- Debian/Ubuntu: `update-grub`
|
||
- Arch: `grub-mkconfig -o /boot/grub/grub.cfg`
|
||
- CentOS: `grub2-mkconfig -o /boot/grub2/grub.cfg`
|
||
|
||
### 5. 卸载清理 (`backend.py:unmount_target_system`)
|
||
- 逆序卸载绑定的文件系统
|
||
- 卸载 EFI/boot/根分区
|
||
- 清理临时挂载点
|
||
|
||
## 前端界面 (`frontend.py`)
|
||
|
||
### 主要组件
|
||
|
||
1. **分区选择区域**
|
||
- 根分区 (/) - 必选
|
||
- 独立 /boot 分区 - 可选
|
||
- EFI 系统分区 (ESP) - UEFI 模式下推荐
|
||
|
||
2. **目标磁盘选择**
|
||
- 物理磁盘选择 (如 /dev/sda)
|
||
- UEFI 模式复选框（自动检测 Live 环境）
|
||
|
||
3. **日志窗口**
|
||
- 彩色日志输出（信息/警告/错误/成功）
|
||
- 自动滚动
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
扫描分区 → 用户选择分区 → 点击修复 → 挂载系统 →
|
||
检测发行版 → chroot修复GRUB → 卸载分区 → 完成
|
||
```
|
||
|
||
### 线程安全
|
||
|
||
修复过程在独立线程中运行，避免 UI 卡死。使用 `master.after()` 进行线程安全的日志更新。
|
||
|
||
## 代码规范
|
||
|
||
### 后端函数返回值
|
||
所有后端函数统一返回 `(success: bool, ..., error_message: str)` 格式:
|
||
```python
|
||
# 示例
|
||
success, stdout, stderr = run_command([...])
|
||
success, disks, partitions, efi_parts, err = scan_partitions()
|
||
```
|
||
|
||
### 错误处理
|
||
- 命令执行失败时自动清理已挂载的分区
|
||
- 日志记录使用 `[Backend]` 前缀
|
||
- GUI 使用弹窗显示关键错误
|
||
|
||
## 使用限制
|
||
|
||
1. **需要 root 权限**: 所有磁盘操作需要 `sudo`
|
||
2. **Live 环境**: 设计为在 Live USB/CD 中运行
|
||
3. **单线程修复**: 同时只能进行一个修复任务
|
||
4. **UEFI 自动检测**: 根据 Live 环境自动设置 UEFI 模式
|
||
|
||
## 测试
|
||
|
||
直接运行 `backend.py` 可进行基础测试（仅扫描分区）:
|
||
```bash
|
||
sudo python backend.py
|
||
```
|
||
|
||
完整修复测试需要取消注释 `__main__` 块中的测试代码并设置实际分区。
|
||
|
||
## 潜在改进点
|
||
|
||
1. **添加 requirements.txt**: 当前无第三方依赖
|
||
2. **国际化**: 当前仅支持中文界面
|
||
3. **配置文件**: 支持保存/加载常用配置
|
||
4. **日志持久化**: 将日志保存到文件
|
||
5. **多语言发行版支持**: 扩展 detect_distro_type
|
||
6. **Btrfs/LVM 支持**: 当前仅支持标准分区
|
||
|
||
## 注意事项
|
||
|
||
- **数据风险**: 操作磁盘有数据丢失风险，建议备份
|
||
- **EFI 分区警告**: UEFI 模式下未选择 ESP 会弹出警告
|
||
- **临时挂载点**: 使用 `/mnt_grub_repair_<timestamp>` 格式
|
||
- **依赖命令**: 需要系统中存在 `lsblk`, `mount`, `umount`, `grub-install`, `grub-mkconfig`/`update-grub`
|