BootRepairTool/AGENTS.md

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
Debian/Ubuntu	grub-efi-amd64
Arch/Manjaro	grub (已包含 EFI 支持)

7. 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 模块
• 获取正确的 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) 格式:

# 示例
success, stdout, stderr = run_command([...])
success, disks, partitions, efi_parts, err = scan_partitions()

日志系统

使用分级日志系统：

log_debug(msg)    # 调试信息（灰色）
log_info(msg)     # 一般信息（黑色）
log_warning(msg)  # 警告（橙色）
log_error(msg)    # 错误（红色）
log_success(msg)  # 成功（绿色）
log_step(msg)     # 步骤（蓝色加粗）

支持日志回调，可将日志实时显示到前端：

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 可进行基础测试：

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. 日志持久化: 将日志保存到文件