# 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. 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)
- 获取正确的 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. **日志持久化**: 将日志保存到文件