new

2026-02-11 04:37:13 +08:00
parent 6645d8dea3
commit a859956597
5 changed files with 2476 additions and 409 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,8 @@

 **BootRepairTool** 是一个用于修复 Linux 系统 GRUB 引导的图形化工具。适用于 Live USB/CD 环境，帮助用户修复损坏的 GRUB 引导加载器。

+**v2.0 更新**: 参考 Calamares 安装程序的引导安装模块进行了全面优化，新增多架构支持、EFI fallback、混合启动模式、btrfs 子卷支持等功能。
+
 ## 项目结构

 ```
@@ -25,58 +27,127 @@ BootRepairTool/
 ### 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, CentOS/RHEL, Debian, Ubuntu
- 通过读取 `/etc/os-release` 识别
+支持以下发行版：
+- **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 /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`)
+#### 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. **分区选择区域**
+1. **系统信息区域**
+   - 显示 CPU 架构
+   - 显示 EFI 位数（32/64）
+   - 显示 Live 环境状态
+   - 显示 Secure Boot 状态
+
+2. **分区选择区域**
   - 根分区 (/) - 必选
+   - **NEW**: btrfs 子卷选择（自动显示）
   - 独立 /boot 分区 - 可选
   - EFI 系统分区 (ESP) - UEFI 模式下推荐

-2. **目标磁盘选择**
-   - 物理磁盘选择 (如 /dev/sda)
-   - UEFI 模式复选框（自动检测 Live 环境）
+3. **目标磁盘选择**
+   - 物理磁盘选择
+   - UEFI 模式复选框（根据 Live 环境自动设置）

-3. **日志窗口**
-   - 彩色日志输出（信息/警告/错误/成功）
+4. **高级选项**
+   - **NEW**: 混合启动模式（同时安装 BIOS + UEFI）
+   - **NEW**: EFI Fallback 选项
+   - **NEW**: 自定义 EFI 启动项名称
+   - **NEW**: 强制安装选项
+
+5. **日志窗口**
+   - 彩色日志输出（调试/信息/警告/错误/成功/步骤）
+   - 时间戳显示
   - 自动滚动
+   - 使用等宽字体（Consolas）

 ### 工作流程
-
 ```
-扫描分区 → 用户选择分区 → 点击修复 → 挂载系统 → 
+扫描分区 → 用户选择分区 → 检测系统信息 → 
+配置高级选项 → 点击修复 → 挂载系统 → 
 检测发行版 → chroot修复GRUB → 卸载分区 → 完成
 ```

-### 线程安全
-
-修复过程在独立线程中运行，避免 UI 卡死。使用 `master.after()` 进行线程安全的日志更新。
+### 自动功能
+- **自动选择目标磁盘**: 根据根分区路径推断父磁盘
+- **自动检测 btrfs**: 显示子卷选择器
+- **自动检测 LVM**: 提示手动选择磁盘
+- **UEFI 模式建议**: 根据 Live 环境给出建议

 ## 代码规范

@@ -88,10 +159,26 @@ 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)
+```
+
 ### 错误处理
 - 命令执行失败时自动清理已挂载的分区
- 日志记录使用 `[Backend]` 前缀
- GUI 使用弹窗显示关键错误
+- 详细的错误信息返回
+- 多重回退策略（如 GRUB 安装）

 ## 使用限制

@@ -100,27 +187,42 @@ success, disks, partitions, efi_parts, err = scan_partitions()
 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` 可进行基础测试（仅扫描分区）:
+直接运行 `backend.py` 可进行基础测试：
 ```bash
 sudo python backend.py
 ```

-完整修复测试需要取消注释 `__main__` 块中的测试代码并设置实际分区。
+完整修复测试需要设置实际分区参数。
+
+## 参考
+
+本工具 v2.0 参考了以下项目：
+- **Calamares**: https://calamares.io
+  - 引导安装模块 (`bootloader/main.py`)
+  - EFI 参数获取逻辑
+  - 多重安装策略

 ## 潜在改进点

-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`
+1. **systemd-boot 支持**: 添加 systemd-boot 安装选项
+2. **rEFInd 支持**: 添加 rEFInd 安装选项（后端已支持）
+3. **ZFS 支持**: 完善 ZFS 文件系统处理
+4. **LUKS 解锁**: 集成 LUKS 解锁功能
+5. **图形化分区**: 添加分区可视化显示
+6. **多语言**: 国际化支持
+7. **日志持久化**: 将日志保存到文件