# 闪启

**Repository Path**: deepin20/VentoyGo

## Basic Information

- **Project Name**: 闪启
- **Description**: 闪启 VentoyGo是一款基于Ventoy 的图形化启动盘制作工具。它将 Ventoy 强大的多镜像启动能力与清爽的图形界面相结合，让你无需记忆繁琐的命令行，只需点击几下鼠标，就能制作出属于自己的“系统维护瑞士军刀”。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 闪启 VentoyGo

**让系统维护像闪电一样快**

基于 [Ventoy](https://www.ventoy.net/) 的图形化启动盘制作工具，面向统信 UOS、Deepin、其他 Linux 发行版以及
**Windows 10 / 11**。无需记忆命令行：扫描 U 盘 → 安装 Ventoy → 拖入镜像，即可得到一把多镜像启动的"系统维护瑞士军刀"。

**当前版本：0.6.0（Linux / Windows 11）** —— 更新内容见 [CHANGELOG.md](CHANGELOG.md)。

![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows-lightgrey.svg)

---

## 功能特性

- **三栏界面**：设备与状态 / U 盘镜像列表 / 快捷入口，底部彩色日志与进度条
- **UOS/deepin 原生应用**：PyQt5 界面跟随系统深浅色；appid/图标/WM_CLASS 按统信应用商店规范注册，可直接打包上架
- **四语言界面**：右键「高级设置 → 界面语言」可切「跟随系统 / 简体中文 / English /
  日本語 / Русский」，也可用 `VENTOYGO_LANG=ja_JP` 环境变量强制指定；**切换后立即生效，
  不要求重启**（0.5.4 起就地重译整窗，只有已打出来的日志行保持原样）。
  界面文案走 gettext，中文即 msgid（缺译文自然回落中文），另维护英 / 日 / 俄三份翻译。
  覆盖范围是**全量**的 1900 条文案：控件、表头、下拉项、任务中心、健康度报告、对话框，
  连同底部控制台的后端日志与控制器提示语
- **设备识别**：`lsblk` 解析 U 盘、SD 卡、eMMC、移动硬盘/SSD（不再只认 USB 总线），
  自动跳过系统盘；多分区设备优先选择数据分区（不会误选 32MB 的 VTOYEFI）；
  内置 NVMe / SATA 默认不列出，需在「高级设置」显式勾选「允许操作内置磁盘」；
  **写保护设备单独标记**（`【只读】` 前缀 + 状态行红字），下拉框里看得见但点不动写盘按钮
- **安装状态识别不挑装机系统**：按「分区卷标 `VTOYEFI`」或「数据分区有 `ventoy/` 目录」
  判定，任一命中即算已装。前者读 `lsblk` 即可，不需要挂载、不需要 root——
  所以**在 Windows 下用 `Ventoy2Disk.exe` 装的盘也能认出来**（这类盘的数据分区里
  没有 `ventoy/` 目录，旧版会误报"未安装"）；版本读不到时显示「版本未知」而不是
  编一个数字，点「升级」时再用 `Ventoy2Disk.sh -l` 实测引导分区
- **Ventoy 管理**：一键安装、升级、还原；安装前可选分区方案（MBR/GPT）、Secure Boot、
  尾部保留空间与卷标；**内置 Ventoy 1.1.18 发行包**，离线即可用，
  需要其他版本时才联网下载（工具包按官方 `sha256.txt` 校验，哈希不符直接拒绝执行）；
  升级前用 `Ventoy2Disk.sh -l` 读**设备上的真实版本**，
  与本地工具/线上最新做对比，**只升不降**（设备比工具新时明确拦住，不把盘刷回旧版）；
  当前版本不支持的能力（vlnk、数据持久化、Syslinux ISO、SteamOS 恢复镜像）
  会在状态行 tooltip 里点名，升级对话框还会预告「升级后解锁：…」
- **写盘互斥**：安装 / 升级 / 还原 / 拷贝镜像 / 删除 / 下载 / 导入配置包
  共享一把进程级独占锁，同一时刻只有一个动作能碰 U 盘——不会出现
  "正在拷贝 8GB 镜像时又点了安装"，两条命令同时改同一块盘
- **启动菜单配置（ventoy.json）**：可视化编辑全部十个插件段——`control`、`menu_alias`、
  `menu_tip`、`menu_class`、`theme`、`persistence`、`auto_install`、`injection`、
  `conf_replace`、`password`；未在界面暴露的键与未知段（`image_blacklist`、
  `conf_replace_uefi` 等）原样保留，保存走原子写
- **持久化数据文件**：在配置对话框里直接创建 `persistence.dat`（1024MB 整数倍、
  自动 `mkfs.ext4`、卷标可选 `casper-rw` / `persistence`），不必手工 `dd` + 格式化；
  FAT32 的 4GB 上限与剩余空间都在创建前检查
- **内置自动安装模板**：Windows `autounattend.xml`、Debian `preseed.cfg`、
  RHEL 系 `ks.cfg`、Ubuntu 23.04+ `autoinstall.yaml` 四份模板随包分发，
  一键复制到 U 盘 `ventoy/templates/` 并填好路径；同名不覆盖，占位参数以 `TODO` 标注
- **设备安全护栏**：写盘前逐层检查——整盘/分区/越界路径、本次扫描范围、
  虚拟设备与光驱、系统盘与系统目录、设备类别策略（与列表共用）、
  写保护（`/sys/block/*/ro`）、容量指纹（防拔插换盘）；
  受限时按钮直接置灰并说明原因，完整解法在状态行 tooltip 里
- **镜像管理**：添加、删除、重命名、校验；支持 Ventoy 全部镜像类型
  （`.iso` / `.img` / `.wim` / `.vhd` / `.vhdx` / `.efi` / `.vtoy`），
  列表带「类型」列，格式判定优先看文件头魔数（ISO9660/WIM/VHD/VHDX/PE）；
  **递归扫描子目录**（`Linux/`、`Windows/` 分类存放照常识别，列表用「目录」列
  标出所在子目录，自动跳过 `ventoy/`、`EFI/`、回收站等系统目录，深度 5 层、
  目录项 2 万个封顶）
- **外部修改自动刷新**：用文件管理器往 U 盘拷镜像、或在另一个窗口里删文件，
  列表会在 0.8 秒内自己跟上（`inotify` 逐目录监听 + 去抖）；程序自身写盘期间
  自动静音，不会把刚弹出的确认框冲掉；盘被拔走时干净地回到空态
- **校验状态列**：每个镜像一行一个结论——`— 未校验` / `✔ 通过` / `✗ 不匹配` /
  `✔ 无对照`（清单里查不到官方哈希），带颜色与 tooltip；结论会缓存，
  换掉同名文件（大小变化）后自动作废，不会挂着旧的"通过"骗人
- **本地镜像库**：中间面板「镜像库」一次扫出硬盘上所有 ISO（可选多个搜索目录，
  记住上次选择），逐条标注`可创建 / 已存在 / 在 U 盘上 / 文件过小`，
  勾选后批量生成 vlnk——几十个镜像只占几十 KB，不必逐个点「创建链接」
- **vlnk 镜像链接**：一键把**本机磁盘**上的镜像做成 32KB 的 vlnk 文件放到 U 盘，
  大镜像不必再拷一遍（需 Ventoy 1.0.66+）；列表用「→」与「（链接）」标注，
  校验时检查链接格式与目标可达性，而不是对壳文件算哈希
- **Ventoy 主题编辑器（图形 + 文本）**：`theme.txt` 分「图形 / 文本」两页，同一份内容。
  图形页有组件树（含 `+ hbox → + label` 嵌套）、属性表（颜色可取色）和 16:9 预览，
  **菜单框能在预览里直接拖动改 `left`/`top`**；文本页保留全文编辑，图形页没登记的
  GRUB2 指令照写不误。底层以**原文行列表为唯一真相**，没碰过的行逐字节不变——
  只改一个颜色，diff 就只有一行。预览是**示意图**：字体度量与 pixmap 九宫格拉伸不复刻，
  最终效果以重启后的 Ventoy 菜单为准。内置模板可一键插入，保存前校验
  花括号/分隔符/颜色/背景图是否存在，
  路径强制落在 `ventoy/` 之下（写在数据区根目录是**静默失效**），保存走原子替换
- **网络位置（SMB / NFS）**：镜像放在 NAS 上时，在「镜像库」里点「网络位置…」添加
  `smb://nas/iso` 即可——走系统 GVfs（用户态，不需要 root、不保存任何凭据，密码在
  系统密钥环里），连上的共享会作为**普通目录**参与扫描与「添加镜像」复制。
  网络上的镜像**不能做 vlnk**（vlnk 要靠磁盘签名回本机磁盘找真身），列表里会标成
  `网络位置` 并提示改用「添加镜像」；没有 gvfs 的机器可以自己 `mount -t cifs`
  再把挂载点当普通目录加进来
- **U 盘配置包**：把 `ventoy/` 配置（菜单别名、自动安装、主题、密码…）连同镜像清单
  打包成一个 `.vtoybundle`，换台机器一键还原；导入前预览「会覆盖哪些文件 / 本盘缺
  哪些镜像 / 哪些文件没跟过来」，可选合并或整目录替换，覆盖前自动备份，
  逐文件 SHA256 校验、原子写入；镜像内容默认不打包（已压缩，且 zip 受 FAT32 4GB 限制）
- **镜像商店（12 条）**：Deepin 23.1 / 25.2.0、Ubuntu 26.04.1（桌面 / 服务器）、
  Debian 13.7.0（netinst / DVD-1）、Arch 2026.10.01、Fedora 44、Clonezilla、
  openKylin 3.0、SystemRescue 13.02、GParted Live 1.8.1-6 直接下载到 U 盘；
  地址、大小与 SHA256 来自内置清单 `resources/catalog/catalog.json`，
  下载完成自动校验；右侧「检查镜像源」可探测哪个源当前可用
- **滚动版本自动取最新**：Fedora 的 build 号、Clonezilla 的点版本、openKylin 的
  构建日期都会变，清单里不写死文件名，而是给一条**目录解析规则**（列目录 →
  按正则筛 → 按版本/日期取最新），点下载时才去读一次目录页；
  解析失败自动退回清单里的固定地址并告知原因。静态条目照旧不联网
- **没有官方哈希就说清原因**：SourceForge 只给 MD5、openKylin 镜像目录里没有
  校验文件——这类条目在清单里带 `hash_note`，下载确认框原样展示，
  不会让"官方没公布"和"清单填错了"长得一模一样
- **版本门控**：组合包与镜像按钮按**盘上那块 Ventoy 的实际版本**决定可用性，
  版本不够就置灰、tooltip 写明"需要 Ventoy ≥ x"，面板顶部再挂一条汇总说明
- **下载队列**：排队下载、暂停 / 继续 / 取消，中断后保留 `.part` 续传
- **真实进度**：解析 Ventoy 输出百分比；解析不到时自动回退不确定动画
- **空间预检**：应用组合包前计算"需要 / 剩余 / 缺少"，不足直接阻止
- **占用检测**：写盘前检查挂载与占用进程，避免对正在使用的 U 盘误操作
- **组合包**：预置"运维三件套 / 装机必备 / 救援工具 / 桌面精选 / 服务器装机 /
  国产系统 / 备份还原"，条目引用镜像清单 key；组合包按钮悬停可看说明，
  自定义预设写在 `~/.config/ventoygo/presets/combo_presets.json`
- **U 盘健康度**：左栏「健康度…」读 SMART（NVMe 的已消耗寿命/备用空间/介质错误，
  SATA SSD 的磨损均衡计数与坏块计数），给出结论、原始事实与判定依据；普通 U 盘的
  USB 桥接芯片通常不转发 SMART，此时**按"未知"显示并说明原因**，只展示
  「本程序累计写入」（拷贝镜像 / 安装 / 还原的次数与字节数），**不折算成寿命百分比**
- **断点续传**：下载中断后保留 `.part` 文件，下次接着下；服务端不支持 Range 时自动重下，不会写坏文件
- **主题**：跟随系统深浅色（Qt 原生，UOS/deepin 平台主题接管），无需手动切换
- **配置与日志**：JSON 配置（原子写入、损坏自动备份）；日志落盘按 1MB×3 滚动，界面可打开日志目录
- **更新提示**：启动时检查 Release（需配置 `update_api_url`），分 **stable / beta 双通道**；
  有可校验的包就一键更新（下载 → SHA256 → 备份 → 替换 → 可回滚），没有则打开发布页
- **线程安全**：所有耗时操作在后台线程执行，界面更新统一回到主线程

---

## 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | **Linux**（UOS / Deepin / Ubuntu / Debian 等）与 **Windows 10 / 11**；其它平台启动时给出提示并退出 |
| Python | 3.8 及以上（GUI 为 PyQt5）；Windows 用户可直接用打包好的 `VentoyGo.exe`，无需装 Python |
| 权限 | 安装/升级/还原 U 盘需要提权：Linux 为 **root 或免密 sudo**，Windows 为 **管理员身份运行**（程序会在需要时提示并引导重启） |
| 依赖工具 | Linux：`parted`（或 `sfdisk`）与 `mkfs.exfat`（或 `mkfs.vfat`）——「还原 U 盘」重建分区与格式化必需，缺失时**在动盘之前**就拒绝。Windows：无需额外工具（还原走系统自带的 PowerShell 存储命令） |

Python 依赖：`PyQt5`、`psutil`、`requests`。

```bash
# Debian / Ubuntu / UOS / Deepin（推荐走系统源）
sudo apt install python3-pyqt5 python3-psutil python3-requests
# 或者
pip install -r requirements.txt
```

> 如果 pip 报 `error: externally-managed-environment`（Debian 12 / Deepin 23 默认开启 PEP 668）：
>
> ```bash
> # 方案一：允许 pip 写入用户目录（个人电脑常用）
> python3 -m pip install --user --break-system-packages PyQt5 psutil requests
>
> # 方案二：用虚拟环境（更干净）
> python3 -m venv .venv
> .venv/bin/pip install -r requirements.txt
> .venv/bin/python run.py
> ```
>
> 启动时若缺依赖，`run.py` 会直接列出缺失模块和安装命令，不再抛裸 Traceback。

---

## 快速开始

### 方式一：源码运行

```bash
python3 run.py
```

### 方式二：构建并安装 .deb（统信 UOS / Deepin 25 应用商店规范）

```bash
python3 build_deb.py                 # 生成 com.gitee.deepin20.ventoygo_0.6.0_all.deb
sudo apt install ./com.gitee.deepin20.ventoygo_0.6.0_all.deb
                                     # 或: sudo dpkg -i *.deb && sudo apt --fix-broken install
ventoygo 进程名为 com.gitee.deepin20.ventoygo，从开始菜单启动"闪启 VentoyGo"
```

- 程序安装到 `/opt/apps/com.gitee.deepin20.ventoygo/`，菜单入口由系统触发器自动建立（若暂未出现，重新登录一次即可）；
- 纯 Python 载荷不含 ELF，不受 `deepin-elf-verify` 未签名拦截影响；
- UOS 首次安装第三方 deb 需在「控制中心 → 通用」打开开发者模式、关闭「仅允许签名应用」。

### 方式三：构建 Linux 便携包 .AppImage（跨发行版，免安装）

适合 Fedora / Arch / openSUSE，或者"只想在别人的机器上试一下"：

```bash
python3 build_appimage.py             # 生成 dist-release/VentoyGo-0.6.0-x86_64.AppImage
chmod +x VentoyGo-0.6.0-x86_64.AppImage && ./VentoyGo-0.6.0-x86_64.AppImage
```

- 必须在 **Linux** 上压（需要 `appimagetool`）；在其它平台上 `--appdir-only`
  仍会铺出 AppDir 并自检，只是不出 `.AppImage` 本体；
- 与 deb 载荷完全一致：纯 Python，用**系统的** `python3` + `PyQt5`，不打包解释器；
- 缺依赖时 AppRun 会弹窗告诉你装什么（`sudo apt install python3-pyqt5` 等），
  而不是闪退。

### 方式四：打包 Windows 可执行程序（Windows 10 / 11）

在**Windows 上**执行（PyInstaller 不支持交叉编译）：

```powershell
python -m pip install -r requirements.txt
python build_win.py                  # 生成 dist\VentoyGo\VentoyGo.exe（onedir）
python build_win.py --onefile        # 单文件版：dist\VentoyGo.exe，启动更慢

python build_msi.py                  # 安装包：dist-release\VentoyGo-0.6.0-x64.msi（需 WiX v3）
```

- 免安装包默认是 **onedir**（`VentoyGo.exe` + `_internal\`），冷启动比 onefile 快数秒——
  本程序是"插上 U 盘就打开"的工具，这个差别很明显；
- exe 内嵌清单（`asInvoker` + Per-Monitor V2 DPI + longPathAware）、图标与版本资源，
  「属性 → 详细信息」里能看到 0.6.0；
- 程序**不需要安装**，解压即用；卸载就删目录（数据在 `%LOCALAPPDATA%\VentoyGo`）；
- `.msi` 装到 `Program Files`、建开始菜单与桌面快捷方式、可在「应用和功能」里卸载，
  企业环境可用组策略分发。**安装时申请一次管理员权限，运行期仍以普通权限启动**，
  只有真正写盘时才由程序按需提权；
- 三种产物均**未签名**，首次运行 SmartScreen 会提示；正式分发需要 EV 证书。

> **打包环境提醒**：PyInstaller 的窗口模式引导器 `runw.exe` 是杀软的高频误报对象，
> 少数安全软件会在解压后把它直接隔离，表现为打包在 `Building EXE from EXE-00.toc`
> 阶段报 `PyInstaller does not include a pre-compiled bootloader`。
> 遇到时把 PyInstaller 换成 6.11.x 一类的其它版本即可（`build_win.py` 会打印实际使用的版本）。

> 五种发行形态的构建机要求、签名状态与已知局限，见 [docs/release-forms.md](docs/release-forms.md)。

---

## 界面示意

```
+---------------------+------------------------------------------+-------------------+
| 闪启 VentoyGo v0.6.0 — 让系统维护像闪电一样快                            [—][□][×] |
+---------------------+------------------------------------------+-------------------+
| 设备与状态          | U 盘镜像列表                             | 常用组合包        |
| [SanDisk (32.0 GB)] | 选择 状态       文件名              大小 | [运维三件套]      |
| 设备: /dev/sdb      | [ ]  — 未校验  ubuntu-22.04.iso  4.7 GB  | [装机必备]        |
| 容量: 32.0 GB       | [ ]  ✔ 通过    systemrescue.iso  800 MB  | [救援工具]        |
| 剩余: 12.5 GB       | [ ]  ✗ 不匹配  debian-13.iso     3.2 GB  | 镜像商店          |
| Ventoy: 已安装      | [ ]  ✔ 无对照  alpine.iso        210 MB  | [Deepin 25.2.0]   |
|                     | 剩余空间: 12.5 GB / 32.0 GB              | [SystemRescue]    |
| [刷新设备]          | [添加镜像][删除选中][校验镜像]           | U 盘配置包        |
| [安装 Ventoy]       | [重命名][创建链接][镜像库]               | [导出][导入]      |
| [启动菜单配置]      |                                          | 界面跟随系统主题  |
| [升级 Ventoy]       |                                          |                   |
| [还原 U 盘]         |                                          |                   |
+---------------------+------------------------------------------+-------------------+
| 实时日志                                                          [清空][导出日志] |
| 01:23:09 [INFO] 发现 1 个可用设备                                                  |
| 01:23:15 [SUCCESS] 拷贝完成: ubuntu-22.04.iso (4.7 GB)                             |
| 01:23:20 [INFO] 检测到外部修改，已刷新镜像列表                                     |
| 进度: 下载 ubuntu-22.04.iso: 72%  ███████████████████████░░░░░░░                   |
+---------------------+------------------------------------------+-------------------+
```

---

## 使用说明

1. **插入 U 盘 / SD 卡** → 点击「刷新设备」，下拉框选择目标设备（左侧会显示型号、容量、剩余空间、Ventoy 状态）。
2. **安装 Ventoy** → 点击「安装 Ventoy」，在参数面板里选择分区方案（MBR/GPT）、
   是否启用 Secure Boot、尾部保留空间与分区卷标，勾选"我已知晓"后开始安装。
   文件系统由 Ventoy 固定为 exFAT（无 4GB 单文件限制）。应用已内置 Ventoy 1.1.18，
   离线即可安装；请求其他版本时才从 GitHub 下载。
3. **添加镜像** → 点击「添加镜像」选择本地 `.iso` / `.img` / `.wim` / `.vhd` / `.vhdx` / `.efi` / `.vtoy`
   文件；也可以从右侧「镜像商店」或组合包直接下载。镜像商店里 Fedora / Clonezilla /
   openKylin 这类**版本会滚动的条目**，点下载时会先去目录页问"现在最新的是哪个文件"，
   解析不到才退回清单里的固定地址（控制台会写清原因）。
   右侧按钮变灰说明这块盘的 Ventoy 版本还不够用，悬停可看需要哪个版本。
4. **创建链接（vlnk，可选）** → 镜像已经在本机硬盘上、不想再拷一份时，点击「创建链接…」
   选中该镜像，程序会在 U 盘根目录生成 `xxx.vlnk.iso` 这样的 32KB 小文件；
   启动时 Ventoy 会去本机磁盘读真身（需 Ventoy 1.0.66+，镜像与 U 盘要在同一台机器上）。
5. **校验镜像** → 勾选条目后点击「校验镜像」，按文件名查清单里的官方 SHA256 再比对
   （清单里没有的镜像只显示哈希并注明"无可比对值"）；对 vlnk 文件则校验其格式与指向是否仍有效。
   结论直接写进列表的「状态」列：`✔ 通过`（绿）/ `✗ 不匹配`（红）/
   `✔ 无对照`（清单里没有该文件的官方哈希，算过但没得比）/ `— 未校验`（灰）。
   结论会缓存到下次刷新，但**文件大小一变就作废**——换掉同名镜像后需要重新校验。
6. **升级 / 还原** → 「升级 Ventoy」先读设备真实版本并弹窗对比（`设备版本 → 目标版本`，
   只有升级才允许继续，已是最新/降级/读不到版本都会禁用按钮并说明原因），确认后保留数据更新引导；
   若目标版本会带来新能力，弹窗底部会多一行「升级后解锁：Syslinux 引导的 ISO、SteamOS 恢复镜像」；
   「还原 U 盘」会卸载分区、清除分区表并重建单个数据分区（优先 exFAT，装得下大镜像；缺 `exfatprogs` 时回退 FAT32）。
7. **启动菜单配置** → 安装完成后点击「启动菜单配置」，十个 Tab 分别对应 Ventoy 的十个插件段：
   启动控制、菜单别名、菜单提示、菜单分组、外观主题、数据持久化、自动安装、注入文件、
   替换配置、密码保护；保存后下次引导即生效。
   「数据持久化」页可现场创建 persistence 数据文件（选 1~4GB、卷标、一键格式化），
   「自动安装」页可用内置模板生成应答文件——两者都会把路径自动填进表格，
   不用先去文件管理器里手工准备文件。
   「外观主题」页的 `theme.txt` 行右侧有「编辑 / 预览…」：左边写、右边按 16:9 实时预览
   （底色、标题、菜单条目颜色与位置都取自文本），`插入模板` 可一键写回默认样式，
   `检查` 会报出花括号不配平、缺分隔符、颜色非法、背景图不存在等问题，
   有错误时拒绝保存。**theme.txt 必须放在 U 盘的 `ventoy/` 目录下**，放到数据区根目录会静默失效。
8. **换盘 / 换机：导出配置包** → 右侧「U 盘配置包 → 导出配置包」生成一个
   `.vtoybundle`（默认只含配置与镜像清单，可勾选连镜像一起打包）。在新盘上点
   「导入配置包」，预览里会列出将覆盖的文件与本盘缺少的镜像；选「合并」或
   「替换」后一键还原，原配置自动改名备份。
9. **批量建链接：镜像库** → 点中间面板的「镜像库」，程序会扫 `~/ISO`、`~/下载/ISO`、
   `~/Desktop/ISO`、`/data/iso` 等常见位置（可自己加目录，选择会被记住）。
   列表逐条标注 `可创建` / `已存在` / `在 U 盘上` / `文件过小`，只有「可创建」的能勾，
   默认全勾；底部汇总会算出「U 盘将写入约 X KB」。确认后批量生成 vlnk，
   硬盘上的几十个镜像只占几十 KB，重启进 Ventoy 就能看到菜单。
10. **列表会自动刷新** → 用文件管理器、`cp`、解压工具改动 U 盘内容后，
   列表在 0.8 秒内自己更新（控制台可见"检测到外部修改"）。程序自己写盘时会静音，
   不会打断你手上的操作；把盘拔掉则会直接回到空态，不会留一份点不动的幽灵列表。

> **风险提示**：安装 Ventoy 与还原 U 盘都会**销毁 U 盘上的全部数据**；程序会在执行前确认，
> 并拒绝操作挂载了 `/`、`/boot`、`/usr` 等系统目录的磁盘。请仍然先备份重要资料。

### 运行期文件位置

| 内容 | 位置 |
|------|------|
| 下载的 Ventoy 工具 | `~/.local/share/ventoygo/binaries/ventoy/` |
| 解压出的 `vlnk` 工具 | `~/.local/share/ventoygo/binaries/vlnk/` |
| 组合包缓存 | `~/.cache/ventoygo/combo/`（以真实文件名保存，支持复用与续传） |
| 配置（主题/日志级别等） | `~/.config/ventoygo/config.json` |
| 镜像库搜索目录 | 同上，`config.json` 的 `library_dirs` 字段 |
| 用户镜像清单（可选，覆盖内置） | `~/.config/ventoygo/catalog.json` |
| 用户组合包预设（可选） | `~/.config/ventoygo/presets/combo_presets.json` |
| 日志（滚动） | `~/.local/share/ventoygo/logs/ventoygo.log` |

（均遵循 `XDG_DATA_HOME` / `XDG_CACHE_HOME` / `XDG_CONFIG_HOME`。）

### 更新检查配置（维护者）

更新检查不会向任何地址发请求，除非在 `config.json` 中配置了 `update_api_url`：

```json
{
  "update_api_url": "https://gitee.com/api/v5/repos/deepin20/VentoyGo/releases/latest"
}
```

（GitHub 用 `https://api.github.com/repos/<owner>/<repo>/releases/latest`。）

配置后启动时会（延迟 3 秒、24 小时缓存、可关闭）检查新版本。程序在请求时会自动
把地址换成**列表**接口（`.../releases`）来查——单条接口在 GitHub 上只返回正式版，
在 Gitee 上却可能返回预发布版，两边语义不一致。

分两条通道，在「高级设置 → 更新通道」切换（或直接写 `"update_channel": "beta"`）：

| 通道 | 收哪些版本 |
|---|---|
| `stable`（默认） | 只收正式发布版，例如 `0.5.4` |
| `beta` | 额外收 `0.5.1-beta.1` 这类预发布版，正式版照收 |

稳定通道**不会**因为远端存在更高的测试版而提示升级。发现新版本时右侧出现按钮：
有带 SHA256 的可校验包就直接下载 → 校验 → 备份 → 原地替换（完成后重启生效，
异常时可「回滚上次更新」）；没有可校验的包则退回"打开浏览器到发布页"。
从测试版退回稳定版不会自动降级，需重装稳定版安装包。

---

## 项目结构

```
闪启VentoyGo/
├── build_deb.py               # 一键打包 .deb
├── build_appimage.py          # 一键打包 .AppImage（AppDir + appimagetool）
├── build_win.py               # 一键打包 Windows（PyInstaller，onedir / onefile）
├── build_msi.py               # 一键打包 Windows .msi（生成 wxs + WiX candle/light）
├── build_incremental.py       # 增量更新包（两个 tag 之间 diff）
├── packaging/windows/         # Windows 清单文件（DPI / 长路径 / supportedOS）
├── docs/
│   ├── developer_guide.md     # 架构、线程模型、扩展指南
│   ├── release-forms.md       # 五种发行形态、构建机要求、签名状态
│   ├── ci.md                  # 跨平台 CI 矩阵、隔离清单、打包与覆盖率门禁
│   └── user_manual.md         # 使用手册与 FAQ
├── icons/                     # 应用图标
├── pyproject.toml             # 项目元数据（setuptools / GUI 入口）
├── requirements.txt
├── run.py                     # 入口（把 src/ 加入 sys.path）
├── scripts/                   # 维护脚本（不随包安装）
│   ├── extract_messages.py    # 抽取 _() 文案；--check 是 CI 门禁
│   ├── compile_po.py          # 纯 Python 编 .mo（不依赖 msgfmt）
│   ├── translations_en.py     # 英文译文种子（唯一人工维护点）
│   └── ci/                    # 门禁脚本：跑测试、查包、查覆盖率
├── src/ventoygo/
│   ├── app.py                 # 应用装配：视图 ↔ 控制器
│   ├── i18n.py                # 语言探测 / 加载 .mo / _()
│   ├── locale/                # 翻译产物（en_US 的 po/mo，随包发布）
│   ├── controllers/           # 设备、启动菜单、ISO、下载、设置控制器 + 公共基类
│   ├── models/                # UsbDevice / IsoItem / ComboPreset / InstallOptions / VentoyConfig
│   ├── resources/             # 预设、图标、内置 Ventoy 发行包
│   ├── services/              # 设备扫描与安全、Ventoy 引擎、ventoy.json、ISO、下载、
│   │                          #   组合包、镜像清单、目录解析、主题解析、本地镜像库、能力门控
│   ├── utils/                 # 日志、路径、主线程调度、子进程、主题、目录监听
│   └── views/                 # 主窗口 + 左/中/右面板 + 安装参数/启动菜单/升级/
│                              #   主题编辑/镜像库对话框
└── tests/                     # 单元测试（无需 GUI 环境）
```

---

## 技术栈

| 组件 | 技术 |
|------|------|
| GUI | [PyQt5](https://www.riverbankcomputing.com/software/pyqt/)（Qt5，UOS/deepin 原生，跟随系统主题） |
| 系统信息 | [psutil](https://github.com/giampaolo/psutil)、`lsblk` |
| HTTP | [Requests](https://requests.readthedocs.io/) |
| 启动盘核心 | [Ventoy](https://www.ventoy.net/)（`Ventoy2Disk.sh` / `Ventoy2Disk.exe`） |
| 打包 | dpkg-deb（Linux）/ PyInstaller（Windows） |

---

## 开发与测试

当前版本的功能范围与验收记录见 [CHANGELOG.md](CHANGELOG.md)；
历史版本计划（`docs/v0.2-plan.md`、`docs/regression-v0.2.md`）仅作归档，不再维护。

```bash
# 单元测试（不需要桌面会话；需已安装 PyQt5/psutil/requests）
QT_QPA_PLATFORM=offscreen PYTHONPATH=src python3 -m pytest tests -q

# 语法检查
python3 -m compileall -q src run.py build_deb.py
```

> **测试只支持 pytest。** `tests/conftest.py` 里的三条自动 fixture
> （重置写盘锁、清空设备版本探测缓存、伪造 USB 硬件事实）都是
> `@pytest.fixture`，**`python -m unittest discover` 下不会生效**，
> 会连锁导致写盘锁跨用例泄漏、`guard_device` 因读不到 `/dev/sdb` 事实
> 返回 `NO_FACTS` 而假失败。请统一用上面这条 pytest 命令。
>
> （单独跑某个测试文件时，文件末尾的 `unittest.main()` 是可用的；
> 但**不要**把 `unittest.main()` 写在文件中段——它之后定义的测试类
> 在脚本直跑时不会被收集。`tests/test_test_file_structure.py` 守着这一点。）

测试覆盖：`lsblk`/PowerShell 解析、分区选择、系统盘过滤、ISO 增删改查与失败清理、
下载续传（用假 requests，不联网）、组合包缓存命名与本地安装、主题持久化、UI 线程调度、
以及"视图不直接调用服务层"的静态结构断言。

> **在 Windows 上跑测试**：这套用例是**以 Linux 为基准**写的——大量用例靠 mock
> `os.geteuid`、`os.makedev`、`/dev/sdX`、`mount`、软链与 `0o111` 来模拟真实设备。
> 在 Windows 上跑全量会有约 160 条失败，**全部**是这类 POSIX 专用用例（报错形如
> `module 'os' has no attribute 'geteuid'`），不是回归。Windows 侧的适配由
> `tests/test_windows_support.py`（66 条，跨平台可跑）与
> `test_platform_support.py` 覆盖：
>
> ```powershell
> $env:PYTHONPATH="src"; $env:QT_QPA_PLATFORM="offscreen"
> python -m pytest tests/test_windows_support.py tests/test_platform_support.py -q
> ```

---

## 已知限制

- Windows 版的少数增强功能不可用（Linux 桌面基础设施依赖）：**创建 vlnk**
  （需读磁盘签名的 Linux 工具链，已有 vlnk 仍能识别与启动）、**GVfs 网络位置**
  （Windows 请用「映射网络驱动器」或 UNC 路径）、**文件关联注册**（由安装包处理）；
  SMART 健康度在 Windows 上需要管理员权限与 `smartctl`（smartmontools Windows 版）。
- Windows 版**不支持程序内自动更新**：可执行文件运行期间被系统锁住，替换必然失败，
  程序会引导到发布页下载安装包手动覆盖。
- 镜像商店地址随上游发布变动：滚动版本（Fedora / Clonezilla / openKylin）由
  `resolve` 规则现取，一般不用管；纯静态条目（Ubuntu / Debian）出了新的点版本
  仍需改 `src/ventoygo/resources/catalog/catalog.json`
  （改完跑 `VENTOYGO_TEST_REAL_CATALOG=1 pytest tests/test_catalog_service.py` 联网核对哈希与可达性）。
- 右栏 19 个按钮（7 组合包 + 12 镜像）在 250px 面板里需要滚动才能看到「高级设置」，
  内容高度约 1110px；窗口足够高时一屏可见。
- Secure Boot、Ventoy 插件（`ventoy.json`）、分区布局等高级配置尚未提供图形界面，可手动修改 U 盘上的 `ventoy/` 目录。
- "还原 U 盘"依赖 `parted`（或 `sfdisk`）与 `mkfs.exfat` / `mkfs.vfat`；缺失时会明确提示，不会假装成功。
- **健康度在普通 U 盘上读不到 SMART**：USB 桥接芯片一般不转发 SMART 命令（硬件限制），
  此时只显示「本程序累计写入」，且不会给出任何寿命百分比。读得到 SMART 的盘需要
  `smartmontools`（`sudo apt install smartmontools`）与 root / 免密 sudo。
  该功能**尚未在真实 U 盘/SSD 上实测**，解析逻辑以真机抓取的失败输出与按 schema
  构造的样本覆盖（`tests/test_drive_health.py`）。
- 非中文界面下**仍有少量中文是设计如此**：语言下拉里的「简体中文」「日本語」「Русский」
  （母语名不自译）、以及代码里的比较判据。此外 `--install-mime` 等**终端子命令的输出保持中文**——
  它们不是 GUI 文案，不进 gettext 表。

---

## 许可证与免责声明

本项目采用 MIT 许可证。

- 本工具仅用于学习与个人用途。
- 操作 U 盘前请确认设备路径正确并备份数据；误操作可能导致数据丢失。
- 使用本工具造成的任何数据丢失，开发者不承担责任。

---

## 致谢

- [Ventoy](https://www.ventoy.net/)：强大的多镜像启动方案
- [Qt / PyQt5](https://www.riverbankcomputing.com/software/pyqt/)：跨平台 GUI 框架
- 统信 UOS / Deepin 社区