# 启镜

**Repository Path**: deepin20/BootISO

## Basic Information

- **Project Name**: 启镜
- **Description**: 启镜 BootISO：图形化的 ISO 引导管理工具，让您轻松将 Linux 发行版 ISO 添加到 GRUB 启动菜单，无需手动编写引导命令。支持统信 UOS、Deepin、Ubuntu、Debian 等系统。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 启镜 BootISO

图形化的 ISO 引导管理工具，让您轻松将 Linux 发行版 ISO 添加到 GRUB 启动菜单，无需手动编写引导命令。支持统信 UOS、Deepin、Ubuntu、Debian 等系统。

**当前版本：v1.8.0**（PyQt5 原生界面，适配统信 UOS / Deepin 25 应用商店规范）

---

## ✨ 特性

- **一键添加 ISO**：选择本地 ISO 文件，自动复制到指定目录并更新 GRUB 菜单。
- **网络下载 ISO**：直接输入 URL，下载并自动添加远程 ISO。
- **拖拽支持**：从文件管理器拖拽 `.iso` 文件到主窗口即可添加（Qt 原生拖拽，无需额外依赖）。
- **智能内核提取**：自动从 ISO 中提取 `vmlinuz` 和 `initrd`，避免 GRUB `loopback` 内存耗尽问题，尤其适用于大型镜像（如 GXDE-OS）。
- **多发行版适配**：自动识别 Debian Live（`/live/vmlinuz`）和 Ubuntu 系列（`/casper/vmlinuz`），生成正确的引导参数。
- **双模式菜单**：为每个 ISO 生成“直引”（正常启动）和“调试模式”（显示详细日志）两个菜单项，便于问题排查。
- **GRUB 高级设置**：可视化修改默认启动项、超时时间、背景图片、字体、颜色等。
- **菜单预览**：查看当前 GRUB 中的所有菜单项，一目了然。
- **完全可卸载**：一键卸载工具，清理 GRUB 脚本和配置文件，不影响 ISO 文件。
- **宽屏适配**：界面尺寸 1024×680，支持窗口自由拉伸，按钮均匀分布。

### v1.8.0 新增

- **GRUB 菜单排序**：ISO 列表里「上移 / 下移」直接改菜单顺序，改动立即写回并 `update-grub`；「reorder-reset」清除手动顺序、回到按文件名排序。此前 `_list_iso_files()` 完全没有排序，菜单顺序取决于 `os.walk` 的文件系统返回顺序——换机器就可能变，现在按 `(sort_order, 文件名)` 稳定排序。
- **ISO 显示名（别名）**：只改 GRUB 菜单标题，不动磁盘文件名；列表里显示「别名 — 文件名」便于对照。标题会拒绝换行/制表符——`menuentry` 字符串里一个换行就能把菜单写坏。别名与排序都存在 `/etc/bootiso_kernels.json`，与内核提取结果同一条记录，重新提取内核不会冲掉。
- **GRUB 配置备份/回滚（补全）**：原来只备份 `/etc/default/grub`，现在一次备**三件套**——`/etc/default/grub`、`/boot/grub/grub.cfg`、`/etc/bootiso_menu`，落到 `/var/backups/bootiso/<时间戳>/` 并附 `manifest.json`（时间、版本、大小、sha256）。**还原前自动把当前状态快照一份**，回滚错了还能再回去。
- **CI 自动发版**：推 tag 即构建 → 建发行版 → 传 deb，脚本 `.gitee/workflows/ci.yml` + `scripts/publish_release.py`（幂等：重复跑不会产生第二个发行版或重复附件）。需要在仓库 Secrets 里配 `GITEE_TOKEN`。

关于 `restore` 的一个细节：**默认不跑 update-grub**。`grub.cfg` 还原后立刻生效，此时再 `update-grub` 会用当前的 `/etc/default/grub` 重新生成、把刚还原的菜单覆盖掉。确实需要应用 `default/grub` 的改动时，用 `--apply`（GUI 里是勾选框）显式要求。

### v1.7.0 新增

- **UEFI 安全启动检测**：启动即读 efivars（mokutil 兜底）判断安全启动状态，状态栏与日志直接给出结论；开启时会提示「未签名内核会被固件拒绝」「WinPE/memdisk 一定失败」，不再让你对着黑屏猜。安装菜单时同步写入系统日志。
- **文件管理器右键集成**：一键安装用户级 MIME 关联，右键 ISO →「打开方式」→「添加到 BootISO」即可；桌面入口支持 `--add %F`，双击 ISO 直接打开界面并开始添加（走 pkexec 授权，不额外提权）。
- **系统托盘常驻**：关闭窗口收进托盘（首次会提示），`QFileSystemWatcher` 监控 ISO 目录，增删镜像后自动刷新列表并气泡提醒。
- **中英双语（i18n）**：标准库 gettext，中文即 msgid 原文，英文译文见 `bootiso/locale/en_US`；托盘/工具菜单可切换语言，`BOOTISO_LANG=en_US` 或偏好文件也可控制。`scripts/compile_po.py` 是纯 Python 的 po→mo 编译器，不依赖系统 gettext 工具链；`scripts/extract_messages.py --check` 在 CI 里挡住「加了文案没翻译」。
- **CI 与覆盖率门槛**：`.gitee/workflows/ci.yml` 提交即跑 py_compile、翻译检查、pytest（覆盖率 **≥80% 强制失败**）并构建 deb 存档；当前实测 **91%**、376 个用例。
- **交互细节**：文件选择框的 `_` 变量覆盖 i18n 函数导致的崩溃已修（点「导入校验值」会直接抛异常）；`/boot/grub`、`/etc/bootiso_menu` 等路径抽成常量，便于测试与排查。

### v1.6.0 新增

- **ISO 完整性校验**：添加后自动比对 SHA256 与官方校验值；不匹配会明确提示「文件可能已损坏」，避免带着坏镜像去重启。内置常用发行版校验库（Ubuntu / Debian / Kali / Arch，由 `scripts/update_checksums.py` 从镜像站官方 SUMS 生成），也可导入官方 `SHA256SUMS` 扩展。
- **常用参数模板**：「自定义参数」改为勾选式（`nomodeset`、`toram`、`text`、`acpi=off`、`noapic`、`nouveau.modeset=0` 等），保留手动补充输入框，勾选与手写互不覆盖。
- **GRUB 语法校验**：菜单内容落盘前检查括号配平、引号闭合、行尾悬挂反斜杠、`menuentry` 缺 `{`；不通过则**拒绝写入并阻止 update-grub**，菜单预览窗口同时显示校验结果。
- **镜像源选择**：下载 ISO 时可切换清华 TUNA / 阿里云 / 中科大，自动改写官方 URL（认不出的地址原样使用，不会拼出 404）。
- **日志轮转**：`RotatingFileHandler`，单文件 1MB、保留 3 份历史，避免日志无限增长。

---

## 📷 界面预览

```
+----------------------------------------------------------------------+
|  启镜 BootISO v1.0                                                    |
+----------------------------------------------------------------------+
|  [██████████████████████████████████████████████████████████] 进度条  |
|  +------------------------------------------------------------------+ |
|  | 📌 欢迎使用启镜 BootISO 图形工具                                 | |
|  | 📂 当前 ISO 存放目录: /iso                                       | |
|  | ✅ 自动扫描脚本已安装                                            | |
|  | ✅ 拖拽添加支持已启用                                            | |
|  | ✅ 已提取内核: vmlinuz-GXDE-OS_25.4.1                          | |
|  |                                                                  | |
|  | （更多日志内容...）                                              | |
|  +------------------------------------------------------------------+ |
|                                                                        |
|  [📂选择ISO] [🌐下载ISO] [🔄更新GRUB] [🗑️清空ISO] [⚙️设置目录] [🎨GRUB设置] [👁️预览菜单] [🧹卸载工具] |
+----------------------------------------------------------------------+
```

---

## 🚀 安装

### 从源码运行（推荐开发测试）

```bash
# 克隆或下载项目后，进入项目根目录
git clone https://github.com/yourname/bootiso.git
cd bootiso

# 安装依赖
sudo pip install -r requirements.txt   # 或 sudo apt install python3-requests

# 运行（需 root 权限）
sudo ./run.sh
```

### 构建并安装 DEB 包（适用于统信 UOS / Deepin / Ubuntu）

```bash
# 安装打包依赖
sudo apt install devscripts debhelper python3-all

# 构建 DEB 包
dpkg-buildpackage -us -uc

# 安装
sudo dpkg -i ../bootiso_1.0.0-1_all.deb
```

安装后，可在终端执行 `sudo bootiso` 启动，或从系统菜单中启动“启镜 BootISO”。

---

## 📖 使用说明

### 首次启动

1. 以 root 权限运行（`sudo ./run.sh` 或 `sudo bootiso`）。
2. 程序会自动创建 `/iso` 目录（默认 ISO 存放位置）。
3. 如果未安装 GRUB 扫描脚本，添加第一个 ISO 时会自动安装。

### 添加 ISO

- **本地添加**：点击 **“📂 选择ISO并添加”**，选择 `.iso` 文件。
- **网络下载**：点击 **“🌐 下载ISO”**，输入 URL（如 `http://releases.ubuntu.com/.../ubuntu.iso`）。
- **拖拽**：直接将 `.iso` 文件拖拽到主窗口（需 `tkinterdnd2` 支持）。

添加后，程序会自动提取内核并更新 GRUB，重启后即可在启动菜单中选择。

### GRUB 高级设置

点击 **“🎨 GRUB设置”** 打开设置窗口，可修改：

- **默认启动项**：从下拉列表选择，或输入数字（如 `0`）或 `saved`。
- **超时时间**：GRUB 菜单等待秒数。
- **背景图片**：选择 `.png`/`.jpg`/`.tga` 图片。
- **字体**：选择 `.pf2` 字体文件。
- **颜色**：设置普通/高亮文本的前景/背景色（格式 `#RRGGBB/#RRGGBB`）。

点击“应用设置”即可生效。

### ISO 完整性校验

主界面列表选中 ISO → 「校验完整性」：

- 有参考值：显示 ✅ 通过 / ❌ 与官方值不符（判定损坏）
- 无参考值：显示实际 SHA256 并提示导入官方 `SHA256SUMS`（**不会**误判为损坏）

命令行：`bootiso verify <iso路径>`（不匹配时退出码 2）、`bootiso import-sums <SHA256SUMS路径>`。

### 菜单排序 / 显示名 / 配置备份

```bash
# 只改菜单标题，不动文件名；留空则恢复为文件名
… rename /path/to/ubuntu.iso "Ubuntu 24.04 工作站"
… move /path/to/ubuntu.iso up          # up / down
… reorder-reset                        # 清除手动顺序

# 备份三件套 → /var/backups/bootiso/<时间戳>/
… backup --label before-upgrade
… backups                              # 列出（最新在前，缺文件的标"不完整"）
… restore 20261021-101500              # 只还原文件
… restore 20261021-101500 --apply      # 还原后立即 update-grub
… rm-backup 20261021-101500
```

界面入口：列表右侧「重命名 / 上移 / 下移」；GRUB 设置对话框里「备份当前配置 / 从备份恢复…」。

### 安全启动 / 右键集成 / 托盘

```bash
# 查看安全启动状态与引导风险（不需要 root）
/opt/apps/com.gitee.deepin20.bootiso/files/bin/com.gitee.deepin20.bootiso secureboot

# 安装 / 移除文件管理器右键集成（写用户级 ~/.local/share/applications）
… install-integration
… uninstall-integration

# 语言：查看 / 切换（重启生效）
… lang
… lang en_US
```

界面内对应入口：工具 → 安装右键集成 / 安全启动状态 / 语言。

托盘常驻说明：关闭窗口不退出，点托盘图标还原；要真正退出用托盘菜单「退出」或 `Ctrl+Q`。

### 其他功能

- **更新 GRUB 菜单**：手动刷新菜单（添加/删除 ISO 后无需重启）。
- **清空 ISO 目录**：删除 `/iso` 下所有 `.iso` 文件并更新菜单（有二次确认）。
- **设置 ISO 目录**：更改 ISO 存放位置（配置文件保存于 `/etc/bootiso.conf`）。
- **预览菜单**：查看当前 GRUB 所有菜单项。
- **卸载工具**：删除 GRUB 脚本、配置文件和内核映射，保留 ISO 文件。

---

## ⚙️ 配置

- **ISO 存放目录**：默认 `/iso`，可通过 GUI 或编辑 `/etc/bootiso.conf` 修改。
- **内核映射文件**：`/etc/bootiso_kernels.json`，记录每个 ISO 提取的内核路径。
- **GRUB 脚本**：`/etc/grub.d/41_iso_auto`，由工具自动生成，请勿手动编辑。

---

## 🐛 常见问题

### Q：添加 ISO 后，GRUB 菜单没有出现选项？
- 检查 `/iso` 目录下是否存在该 ISO 文件。
- 手动点击“更新 GRUB 菜单”并观察日志。
- 确保 `/etc/grub.d/41_iso_auto` 有执行权限（`sudo chmod +x /etc/grub.d/41_iso_auto`）。

### Q：启动 ISO 时提示“内存耗尽”或“无法识别内核路径”？
- 已针对大型 ISO 内置“直引”模式（提取内核），可显著降低内存占用。
- 如果仍失败，请使用该 ISO 对应的“调试模式”菜单，查看详细错误信息。
- 如为硬件限制，建议使用 Ventoy 的 F2 浏览功能启动。

### Q：如何修改 ISO 存放目录？
- 点击主界面 **“⚙️ 设置目录”** 按钮，选择新目录即可。配置文件会自动更新。

### Q：拖拽功能无效？
- 请安装 `tkinterdnd2`：`sudo pip install tkinterdnd2`。安装后重启工具即可。

---

## 🧪 开发与测试

```bash
# 系统依赖：python3-pyqt5 python3-requests
python3 -m venv --system-site-packages .venv
. .venv/bin/activate
pip install pytest pytest-cov

# 无显示环境也能跑（GUI 走 offscreen）
QT_QPA_PLATFORM=offscreen pytest tests/ -q \
  --cov=bootiso --cov-report=term-missing --cov-fail-under=80

# 文案改动后：提取 → 补译文 → 编译 mo
python3 scripts/extract_messages.py --check   # CI 同款检查
python3 scripts/compile_po.py
```

CI 流水线见 `.gitee/workflows/ci.yml`（Gitee Actions，语法兼容 GitHub Actions）。

### 手动发布（也可直接推 tag 让 CI 代劳）

```bash
GITEE_TOKEN=<私人令牌> python3 scripts/publish_release.py \
  --tag 1.8.0 \
  --name "v1.8.0 菜单排序 / 显示名 / 配置备份" \
  --body-file /tmp/notes.md \
  --file com.gitee.deepin20.bootiso_1.8.0_amd64.deb

# 只检查参数与产物是否存在，不调 API
… --dry-run
```

脚本是幂等的：已有同名 tag 的发行版就 PATCH，已有同名附件就跳过，传完再核对
同名条目数并删掉多余的（HTTP 307/308 会让 urllib 原样重发 POST body，容易传重）。
`--target` 省略时取当前 `git rev-parse HEAD`；**不要**省掉它——Gitee 建发行版时
缺 `target_commitish` 可能挂到默认分支，源码归档就会发错版本。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request。在提交前，请确保代码符合 PEP 8 规范，并包含必要的注释。

---

## 📄 许可证

本项目使用 **GNU General Public License v3.0** 开源许可证。详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- GRUB 团队提供的强大引导工具。
- 统信 UOS 及所有开源社区用户。

**启镜 BootISO** —— 让 ISO 引导更简单。