229 lines
7.1 KiB
Markdown
229 lines
7.1 KiB
Markdown
# BootRepairTool - 项目说明
|
||
|
||
## 项目概述
|
||
|
||
**BootRepairTool** 是一个用于修复 Linux 系统 GRUB 引导的图形化工具。适用于 Live USB/CD 环境，帮助用户修复损坏的 GRUB 引导加载器。
|
||
|
||
**v2.0 更新**: 参考 Calamares 安装程序的引导安装模块进行了全面优化，新增多架构支持、EFI fallback、混合启动模式、btrfs 子卷支持等功能。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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)
|
||
- **NEW**: 支持 LVM 逻辑卷检测
|
||
- **NEW**: 支持 LUKS 加密分区检测
|
||
- **NEW**: 支持 btrfs 子卷检测
|
||
- 过滤 Live 系统自身的分区
|
||
|
||
### 2. 系统挂载 (`backend.py:mount_target_system`)
|
||
- 挂载根分区 (/)
|
||
- **NEW**: 支持 btrfs 子卷挂载
|
||
- 挂载独立 /boot 分区（可选）
|
||
- 挂载 EFI 分区（UEFI 模式）
|
||
- 绑定伪文件系统 (/dev, /proc, /sys, /run)
|
||
|
||
### 3. 发行版检测 (`backend.py:detect_distro_type`)
|
||
支持以下发行版：
|
||
- **Arch 系**: Arch Linux, Manjaro, EndeavourOS, Garuda, CachyOS
|
||
- **Debian 系**: Debian, Ubuntu
|
||
- **RHEL 系**: CentOS, RHEL, Rocky Linux, AlmaLinux, Fedora
|
||
- **openSUSE**: Leap, Tumbleweed
|
||
- **NEW**: Void Linux
|
||
- **NEW**: Gentoo
|
||
- **NEW**: NixOS
|
||
|
||
### 4. GRUB 修复 (`backend.py:chroot_and_repair_grub`)
|
||
|
||
#### BIOS 模式
|
||
- `grub-install --target=i386-pc --recheck --force /dev/sdX`
|
||
|
||
#### UEFI 模式 (参考 Calamares 实现)
|
||
- 自动检测系统架构 (x86_64/i386/arm64/loongarch64)
|
||
- 获取正确的 EFI 参数 (target, grub_file, boot_file)
|
||
- **多重安装策略**（自动回退）：
|
||
1. 标准安装（带 NVRAM）
|
||
2. Live 环境/可移动模式（`--removable`）
|
||
3. 无 NVRAM 模式（`--no-nvram`）
|
||
- **NEW**: EFI Fallback 安装（复制到 `/EFI/Boot/bootx64.efi`）
|
||
- **NEW**: 支持自定义 EFI 启动项名称
|
||
|
||
#### 混合启动模式 (Hybrid GRUB)
|
||
- **NEW**: 同时安装 BIOS 和 UEFI 引导
|
||
- 适用于需要在不同固件模式下启动的场景
|
||
|
||
#### GRUB 配置更新
|
||
根据发行版自动选择正确的命令：
|
||
- Debian/Ubuntu: `update-grub` 或 `grub-mkconfig`
|
||
- Arch: `grub-mkconfig -o /boot/grub/grub.cfg`
|
||
- CentOS/RHEL/Fedora/openSUSE: `grub2-mkconfig -o /boot/grub2/grub.cfg`
|
||
|
||
### 5. 系统检测功能
|
||
|
||
#### EFI 检测 (`backend.get_efi_word_size`)
|
||
- 读取 `/sys/firmware/efi/fw_platform_size`
|
||
- 支持 32 位和 64 位 EFI
|
||
|
||
#### 架构检测 (`backend.get_grub_efi_parameters`)
|
||
支持多种架构：
|
||
| 架构 | EFI Target | GRUB 文件 | Boot 文件 |
|
||
|------|-----------|-----------|-----------|
|
||
| x86_64 | x86_64-efi | grubx64.efi | bootx64.efi |
|
||
| i386 | i386-efi | grubia32.efi | bootia32.efi |
|
||
| arm64 | arm64-efi | grubaa64.efi | bootaa64.efi |
|
||
| loongarch64 | loongarch64-efi | grubloongarch64.efi | bootloongarch64.efi |
|
||
|
||
#### Secure Boot 检测 (`backend.check_secure_boot_status`)
|
||
- 通过 `mokutil --sb-state` 检测
|
||
- 通过 EFI 变量检测
|
||
- 显示 Secure Boot 状态
|
||
|
||
#### Live 环境检测 (`backend.is_live_environment`)
|
||
- 检测 `/sys/firmware/efi/efivars` 可访问性
|
||
- 自动调整安装策略
|
||
|
||
### 6. 卸载清理 (`backend.py:unmount_target_system`)
|
||
- 逆序卸载绑定的文件系统
|
||
- 卸载 EFI/boot/根分区
|
||
- 清理临时挂载点
|
||
- **NEW**: 重试机制处理繁忙资源
|
||
|
||
## 前端界面 (`frontend.py`)
|
||
|
||
### 主要组件
|
||
|
||
1. **系统信息区域**
|
||
- 显示 CPU 架构
|
||
- 显示 EFI 位数（32/64）
|
||
- 显示 Live 环境状态
|
||
- 显示 Secure Boot 状态
|
||
|
||
2. **分区选择区域**
|
||
- 根分区 (/) - 必选
|
||
- **NEW**: btrfs 子卷选择（自动显示）
|
||
- 独立 /boot 分区 - 可选
|
||
- EFI 系统分区 (ESP) - UEFI 模式下推荐
|
||
|
||
3. **目标磁盘选择**
|
||
- 物理磁盘选择
|
||
- UEFI 模式复选框（根据 Live 环境自动设置）
|
||
|
||
4. **高级选项**
|
||
- **NEW**: 混合启动模式（同时安装 BIOS + UEFI）
|
||
- **NEW**: EFI Fallback 选项
|
||
- **NEW**: 自定义 EFI 启动项名称
|
||
- **NEW**: 强制安装选项
|
||
|
||
5. **日志窗口**
|
||
- 彩色日志输出（调试/信息/警告/错误/成功/步骤）
|
||
- 时间戳显示
|
||
- 自动滚动
|
||
- 使用等宽字体（Consolas）
|
||
|
||
### 工作流程
|
||
```
|
||
扫描分区 → 用户选择分区 → 检测系统信息 →
|
||
配置高级选项 → 点击修复 → 挂载系统 →
|
||
检测发行版 → chroot修复GRUB → 卸载分区 → 完成
|
||
```
|
||
|
||
### 自动功能
|
||
- **自动选择目标磁盘**: 根据根分区路径推断父磁盘
|
||
- **自动检测 btrfs**: 显示子卷选择器
|
||
- **自动检测 LVM**: 提示手动选择磁盘
|
||
- **UEFI 模式建议**: 根据 Live 环境给出建议
|
||
|
||
## 代码规范
|
||
|
||
### 后端函数返回值
|
||
所有后端函数统一返回 `(success: bool, ..., error_message: str)` 格式:
|
||
```python
|
||
# 示例
|
||
success, stdout, stderr = run_command([...])
|
||
success, disks, partitions, efi_parts, err = scan_partitions()
|
||
```
|
||
|
||
### 日志系统
|
||
使用分级日志系统：
|
||
```python
|
||
log_debug(msg) # 调试信息（灰色）
|
||
log_info(msg) # 一般信息（黑色）
|
||
log_warning(msg) # 警告（橙色）
|
||
log_error(msg) # 错误（红色）
|
||
log_success(msg) # 成功（绿色）
|
||
log_step(msg) # 步骤（蓝色加粗）
|
||
```
|
||
|
||
支持日志回调，可将日志实时显示到前端：
|
||
```python
|
||
backend.set_log_callback(callback_function)
|
||
```
|
||
|
||
### 错误处理
|
||
- 命令执行失败时自动清理已挂载的分区
|
||
- 详细的错误信息返回
|
||
- 多重回退策略（如 GRUB 安装）
|
||
|
||
## 使用限制
|
||
|
||
1. **需要 root 权限**: 所有磁盘操作需要 `sudo`
|
||
2. **Live 环境**: 设计为在 Live USB/CD 中运行
|
||
3. **单线程修复**: 同时只能进行一个修复任务
|
||
4. **UEFI 自动检测**: 根据 Live 环境自动设置 UEFI 模式
|
||
|
||
## 故障排除
|
||
|
||
### EFI 启动问题
|
||
1. **标准模式安装失败**: 工具会自动尝试 removable 模式
|
||
2. **无法找到启动项**: 启用 EFI Fallback 选项
|
||
3. **Secure Boot 问题**: 需要在 BIOS 中禁用 Secure Boot
|
||
4. **固件不兼容**: 某些固件需要特定的 EFI 文件路径
|
||
|
||
### 分区问题
|
||
1. **LVM 逻辑卷**: 需要手动选择目标磁盘
|
||
2. **LUKS 加密**: 需要预先解锁加密分区
|
||
3. **btrfs 子卷**: 工具会自动检测并显示选择器
|
||
|
||
## 测试
|
||
|
||
直接运行 `backend.py` 可进行基础测试：
|
||
```bash
|
||
sudo python backend.py
|
||
```
|
||
|
||
完整修复测试需要设置实际分区参数。
|
||
|
||
## 参考
|
||
|
||
本工具 v2.0 参考了以下项目：
|
||
- **Calamares**: https://calamares.io
|
||
- 引导安装模块 (`bootloader/main.py`)
|
||
- EFI 参数获取逻辑
|
||
- 多重安装策略
|
||
|
||
## 潜在改进点
|
||
|
||
1. **systemd-boot 支持**: 添加 systemd-boot 安装选项
|
||
2. **rEFInd 支持**: 添加 rEFInd 安装选项（后端已支持）
|
||
3. **ZFS 支持**: 完善 ZFS 文件系统处理
|
||
4. **LUKS 解锁**: 集成 LUKS 解锁功能
|
||
5. **图形化分区**: 添加分区可视化显示
|
||
6. **多语言**: 国际化支持
|
||
7. **日志持久化**: 将日志保存到文件
|