zj/BootRepairTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
85d0f00a483689eaec5b955dbc3ed05664703391
BootRepairTool/AGENTS.md
zj a859956597 new
2026-02-11 04:37:13 +08:00

7.1 KiB
Raw Blame History

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) 格式:

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