316 lines
10 KiB
Markdown
316 lines
10 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. 内核恢复功能 (`backend.py:check_and_restore_kernel`)
|
||
|
||
**NEW v2.1**: 自动检测和恢复缺失的内核文件
|
||
|
||
#### 检测逻辑
|
||
- 检查 `/boot` 目录下的 `vmlinuz-*` 和 `initramfs-*.img` 文件
|
||
- 如果缺失，自动尝试恢复
|
||
|
||
#### 恢复方法
|
||
1. **从 /usr/lib/modules 复制** - 如果根分区包含内核模块目录
|
||
2. **重新安装内核包** - 使用包管理器重新安装内核：
|
||
- CentOS/RHEL/Rocky/Alma: `yum reinstall kernel-core kernel-modules`
|
||
- Debian/Ubuntu: `apt-get install --reinstall linux-image-generic`
|
||
- Arch/Manjaro: `pacman -S linux`
|
||
3. **重新生成 initramfs** - 使用 dracut/mkinitcpio/update-initramfs
|
||
|
||
### 5. BLS 配置恢复 (`backend.py:restore_bls_entries`)
|
||
|
||
**NEW v2.2**: 恢复 Boot Loader Specification (BLS) 启动条目
|
||
|
||
#### 适用系统
|
||
- CentOS/RHEL 8+
|
||
- Fedora 30+
|
||
- Rocky Linux / AlmaLinux
|
||
|
||
#### 问题场景
|
||
当 `/boot` 分区被清空时，BLS 配置文件（`/boot/loader/entries/*.conf`）会丢失，导致 GRUB 菜单为空（`blscfg` 命令加载不到条目）。
|
||
|
||
#### 恢复方法
|
||
1. **使用 kernel-install** - 调用 `kernel-install add` 重新生成 BLS 条目
|
||
2. **手动创建 BLS 文件** - 从 `/etc/os-release` 读取系统信息，生成标准格式的 `.conf` 文件
|
||
3. **重新生成 grub.cfg** - 确保 BLS 支持配置正确
|
||
|
||
#### BLS 文件格式示例
|
||
```
|
||
title CentOS Linux (4.18.0-348.el8.x86_64) 8
|
||
version 4.18.0-348.el8.x86_64
|
||
linux /vmlinuz-4.18.0-348.el8.x86_64
|
||
initrd /initramfs-4.18.0-348.el8.x86_64.img
|
||
options root=/dev/mapper/cl-root ro crashkernel=auto rd.lvm.lv=cl/root rhgb quiet
|
||
```
|
||
|
||
### 6. UEFI 模块自动安装 (`backend.py:check_and_install_efi_modules`)
|
||
|
||
**NEW v2.3**: 自动检测并安装 UEFI GRUB 模块
|
||
|
||
#### 问题场景
|
||
在 UEFI 模式下，`grub-install` 需要 `/usr/lib/grub/x86_64-efi/` 目录下的 EFI 模块。如果缺少这些模块，会报错：
|
||
```
|
||
/usr/lib/grub/x86_64-efi/modinfo.sh doesn't exist
|
||
```
|
||
|
||
这在以下场景常见：
|
||
- 最小化安装的系统
|
||
- 从 BIOS 模式安装后切换到 UEFI 模式
|
||
- `/usr` 被清空或损坏
|
||
|
||
#### 自动安装
|
||
检测到缺少 EFI 模块时，自动安装相应的包：
|
||
| 发行版 | 包名 |
|
||
|--------|------|
|
||
| CentOS/RHEL/Rocky/Alma/Fedora | `grub2-efi-x64`, `grub2-efi-x64-modules`, `shim-x64` |
|
||
| Debian/Ubuntu | `grub-efi-amd64`, `shim-signed` |
|
||
| Arch/Manjaro | `grub`, `efibootmgr` |
|
||
|
||
### 7. 手动 EFI 安装 (`backend.py:_manual_install_efi_files`)
|
||
|
||
**NEW v2.4**: 当 `grub2-install` 因 Secure Boot 不支持时，使用手动方式安装 EFI 文件
|
||
|
||
#### 问题场景
|
||
某些系统（特别是 CentOS/RHEL 8）的 `grub2-install` 会报错：
|
||
```
|
||
this utility cannot be used for EFI platforms because it does not support UEFI Secure Boot.
|
||
```
|
||
|
||
这是因为标准 `grub2-install` 不支持 Secure Boot，需要使用 `shim` 链式加载。
|
||
|
||
#### 手动安装方法
|
||
当 `grub2-install` 失败时，自动尝试：
|
||
1. **查找现有 EFI 文件** - 从 `/boot/efi/EFI/<distro>/` 复制已有的 `grubx64.efi` 或 `shimx64.efi`
|
||
2. **使用 shim 链式加载** - 复制 `shimx64.efi` 并配置它加载 `grubx64.efi`
|
||
3. **使用 grub-mkimage 生成** - 从模块生成新的 EFI 文件
|
||
|
||
### 8. GRUB 修复 (`backend.py:chroot_and_repair_grub`)
|
||
|
||
#### BIOS 模式
|
||
- `grub-install --target=i386-pc --recheck --force /dev/sdX`
|
||
- **NEW**: 独立 `/boot` 分区支持（添加 `--boot-directory=/boot`）
|
||
|
||
#### UEFI 模式 (参考 Calamares 实现)
|
||
- 自动检测系统架构 (x86_64/i386/arm64/loongarch64)
|
||
- **NEW**: 自动检测并安装 UEFI GRUB 模块
|
||
- **NEW**: 当 grub2-install 因 Secure Boot 失败时，自动使用手动 EFI 安装
|
||
- 获取正确的 EFI 参数 (target, grub_file, boot_file)
|
||
- **多重安装策略**（自动回退）：
|
||
1. 标准安装（带 NVRAM）
|
||
2. Live 环境/可移动模式（`--removable`）
|
||
3. 无 NVRAM 模式（`--no-nvram`）
|
||
4. **NEW**: 手动 EFI 文件复制（针对 Secure Boot 限制）
|
||
- **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. **日志持久化**: 将日志保存到文件
|