GithubFollow/One-KVM
1
0
Fork 0
mirror of https://github.com/mofeng-git/One-KVM.git synced 2026-01-28 16:41:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
mofeng-git
2025-12-28 18:19:16 +08:00
commit d143d158e4
771 changed files with 220548 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

531
libs/ventoy-img-rs/docs/CLI.md Normal file
View File

@@ -0,0 +1,531 @@
# ventoy-img CLI 使用说明
## 安装
### 从源码编译
```bash
# 克隆仓库
git clone https://github.com/user/ventoy-img-rs.git
cd ventoy-img-rs
# 编译 release 版本
cargo build --release
# 二进制文件位于 target/release/ventoy-img
```
### 直接使用
```bash
# 复制到 PATH
sudo cp target/release/ventoy-img /usr/local/bin/
# 或添加别名
alias ventoy-img='/path/to/ventoy-img-rs/target/release/ventoy-img'
```
## 命令概览
```
ventoy-img <COMMAND>
Commands:
create 创建新的 Ventoy IMG 文件
add 添加文件到镜像（支持子目录和覆盖）
list 列出镜像中的文件（支持递归列出）
remove 从镜像删除文件或目录（支持递归删除）
mkdir 创建目录（支持递归创建父目录）
info 显示镜像信息
help 显示帮助信息
```
## 命令详解
### create - 创建镜像
创建新的 Ventoy 可启动 IMG 文件。
```bash
ventoy-img create [OPTIONS]
```
**选项：**
| 选项 | 简写 | 默认值 | 说明 |
|------|------|--------|------|
| `--size` | `-s` | `8G` | 镜像大小 |
| `--output` | `-o` | `ventoy.img` | 输出文件路径 |
| `--label` | `-L` | `Ventoy` | 数据分区卷标 |
**大小格式：**
- `G` 或 `GB`: 千兆字节，如 `8G`, `16G`
- `M` 或 `MB`: 兆字节，如 `512M`, `1024M`
- 纯数字: 字节数，如 `8589934592`
**示例：**
```bash
# 创建 8GB 镜像（默认）
ventoy-img create
# 创建 16GB 镜像，指定输出路径
ventoy-img create -s 16G -o /path/to/my-ventoy.img
# 创建 512MB 小镜像，自定义卷标
ventoy-img create -s 512M -o small.img -L "MyUSB"
# 创建 32GB 镜像
ventoy-img create --size 32G --output ventoy-32g.img --label "Ventoy32"
```
**输出示例：**
```
========================================
Ventoy IMG Creator (Rust Edition)
========================================
[INFO] Creating 8192MB image: ventoy.img
[INFO] Writing boot code...
[INFO] Writing MBR partition table...
Data partition: sector 2048 - 16744447 (8160 MB)
EFI partition: sector 16744448 - 16809983 (32 MB)
[INFO] Writing Ventoy signature...
[INFO] Writing EFI partition...
[INFO] Formatting data partition as exFAT...
[INFO] Ventoy IMG created successfully!
========================================
Image: ventoy.img
Size: 8G
Label: Ventoy
========================================
```
### add - 添加文件
将 ISO/IMG 文件添加到 Ventoy 镜像的数据分区。
```bash
ventoy-img add [OPTIONS] <IMAGE> <FILE>
```
**参数：**
- `IMAGE`: Ventoy IMG 文件路径
- `FILE`: 要添加的文件路径
**选项：**
| 选项 | 简写 | 说明 |
|------|------|------|
| `--dest` | `-d` | 目标路径（支持子目录，如 `iso/linux/ubuntu.iso`） |
| `--force` | `-f` | 覆盖已存在的文件 |
| `--parents` | `-p` | 自动创建父目录 |
**示例：**
```bash
# 添加单个 ISO 到根目录
ventoy-img add ventoy.img ubuntu-22.04-desktop-amd64.iso
# 添加到子目录（目录必须存在）
ventoy-img add ventoy.img ubuntu.iso -d iso/linux/ubuntu.iso
# 添加到子目录并自动创建父目录
ventoy-img add ventoy.img ubuntu.iso -d iso/linux/ubuntu.iso -p
# 覆盖已存在的文件
ventoy-img add ventoy.img new-ubuntu.iso -d iso/linux/ubuntu.iso -f
# 组合使用：创建目录 + 覆盖
ventoy-img add ventoy.img ubuntu.iso -d iso/linux/ubuntu.iso -p -f
```
**批量添加（使用 shell）：**
```bash
# 添加目录下所有 ISO 到根目录
for iso in /path/to/isos/*.iso; do
ventoy-img add ventoy.img "$iso"
done
# 添加到子目录并保持目录结构
for iso in /path/to/isos/*.iso; do
ventoy-img add ventoy.img "$iso" -d "iso/$(basename "$iso")" -p
done
```
### list - 列出文件
列出镜像数据分区中的文件。
```bash
ventoy-img list [OPTIONS] <IMAGE>
```
**选项：**
| 选项 | 简写 | 说明 |
|------|------|------|
| `--path` | | 指定要列出的目录路径 |
| `--recursive` | `-r` | 递归列出所有文件和目录 |
**示例：**
```bash
# 列出根目录
ventoy-img list ventoy.img
# 列出指定目录
ventoy-img list ventoy.img --path iso/linux
# 递归列出所有文件
ventoy-img list ventoy.img -r
```
**输出示例（根目录）：**
```
NAME SIZE TYPE
------------------------------------------------------------
ubuntu-22.04-desktop-amd64.iso 3.6 GB FILE
iso 0 B DIR
```
**输出示例（递归）：**
```
PATH SIZE TYPE
----------------------------------------------------------------------
iso 0 B DIR
iso/linux 0 B DIR
iso/linux/ubuntu.iso 3.6 GB FILE
iso/windows 0 B DIR
iso/windows/win11.iso 5.2 GB FILE
```
**空镜像输出：**
```
No files in image
```
### remove - 删除文件或目录
从镜像中删除指定文件或目录。
```bash
ventoy-img remove [OPTIONS] <IMAGE> <PATH>
```
**参数：**
- `IMAGE`: Ventoy IMG 文件路径
- `PATH`: 要删除的文件或目录路径
**选项：**
| 选项 | 简写 | 说明 |
|------|------|------|
| `--recursive` | `-r` | 递归删除目录及其内容 |
**示例：**
```bash
# 删除根目录的文件
ventoy-img remove ventoy.img ubuntu.iso
# 删除子目录中的文件
ventoy-img remove ventoy.img iso/linux/ubuntu.iso
# 删除空目录
ventoy-img remove ventoy.img iso/empty-dir
# 递归删除目录及其所有内容
ventoy-img remove ventoy.img iso -r
# 文件名大小写不敏感
ventoy-img remove ventoy.img ISO/LINUX/UBUNTU.ISO
```
**注意：**
- 删除非空目录时必须使用 `-r` 选项
- 递归删除会删除目录下的所有文件和子目录
### mkdir - 创建目录
在镜像中创建目录。
```bash
ventoy-img mkdir [OPTIONS] <IMAGE> <PATH>
```
**参数：**
- `IMAGE`: Ventoy IMG 文件路径
- `PATH`: 要创建的目录路径
**选项：**
| 选项 | 简写 | 说明 |
|------|------|------|
| `--parents` | `-p` | 递归创建父目录（类似 `mkdir -p`） |
**示例：**
```bash
# 创建单级目录
ventoy-img mkdir ventoy.img iso
# 递归创建多级目录
ventoy-img mkdir ventoy.img iso/linux/ubuntu -p
# 创建多个目录
ventoy-img mkdir ventoy.img iso -p
ventoy-img mkdir ventoy.img iso/linux -p
ventoy-img mkdir ventoy.img iso/windows -p
```
### info - 显示信息
显示镜像的详细信息。
```bash
ventoy-img info <IMAGE>
```
**示例：**
```bash
ventoy-img info ventoy.img
```
**输出示例：**
```
Image: ventoy.img
Partition Layout:
Data partition:
Start: sector 2048 (offset 1.0 MB)
Size: 16742400 sectors (8.0 GB)
EFI partition:
Start: sector 16744448 (offset 8.0 GB)
Size: 65536 sectors (32 MB)
```
## 使用场景
### 场景 1: 创建多系统启动盘
```bash
# 1. 创建 32GB 镜像
ventoy-img create -s 32G -o multiboot.img
# 2. 添加各种系统 ISO
ventoy-img add multiboot.img ubuntu-22.04.iso
ventoy-img add multiboot.img windows11.iso
ventoy-img add multiboot.img fedora-39.iso
ventoy-img add multiboot.img archlinux.iso
# 3. 查看文件列表
ventoy-img list multiboot.img
# 4. 写入 U 盘
sudo dd if=multiboot.img of=/dev/sdX bs=4M status=progress
```
### 场景 2: 维护现有镜像
```bash
# 查看当前文件（递归）
ventoy-img list ventoy.img -r
# 删除旧版本
ventoy-img remove ventoy.img iso/linux/ubuntu-20.04.iso
# 添加新版本（覆盖）
ventoy-img add ventoy.img ubuntu-24.04.iso -d iso/linux/ubuntu-24.04.iso -f
# 确认更改
ventoy-img list ventoy.img -r
```
### 场景 2.5: 组织文件到子目录
```bash
# 创建目录结构
ventoy-img mkdir ventoy.img iso/linux -p
ventoy-img mkdir ventoy.img iso/windows -p
ventoy-img mkdir ventoy.img iso/tools -p
# 添加文件到对应目录
ventoy-img add ventoy.img ubuntu.iso -d iso/linux/ubuntu.iso
ventoy-img add ventoy.img fedora.iso -d iso/linux/fedora.iso
ventoy-img add ventoy.img win11.iso -d iso/windows/win11.iso
ventoy-img add ventoy.img hiren.iso -d iso/tools/hiren.iso
# 查看目录结构
ventoy-img list ventoy.img -r
```
### 场景 3: 自动化脚本
```bash
#!/bin/bash
# create-ventoy.sh - 自动创建 Ventoy 镜像
ISO_DIR="/path/to/isos"
OUTPUT="ventoy-$(date +%Y%m%d).img"
SIZE="64G"
# 创建镜像
ventoy-img create -s "$SIZE" -o "$OUTPUT" || exit 1
# 添加所有 ISO
for iso in "$ISO_DIR"/*.iso; do
if [ -f "$iso" ]; then
echo "Adding: $(basename "$iso")"
ventoy-img add "$OUTPUT" "$iso" || echo "Failed: $iso"
fi
done
# 显示结果
echo ""
echo "=== Created: $OUTPUT ==="
ventoy-img list "$OUTPUT"
```
### 场景 4: 在没有 root 权限的环境中使用
```bash
# 在用户目录创建镜像
ventoy-img create -s 8G -o ~/ventoy.img
# 添加文件
ventoy-img add ~/ventoy.img ~/Downloads/linux.iso
# 之后可以用 dd 写入 U 盘（需要 root）
# 或者复制到有权限的机器上写入
```
## 写入 U 盘
创建的 IMG 文件可以直接写入 U 盘：
### Linux
```bash
# 查找 U 盘设备
lsblk
# 写入（替换 sdX 为实际设备）
sudo dd if=ventoy.img of=/dev/sdX bs=4M status=progress conv=fsync
# 或使用 pv 显示进度
pv ventoy.img | sudo dd of=/dev/sdX bs=4M conv=fsync
```
### macOS
```bash
# 查找 U 盘
diskutil list
# 卸载
diskutil unmountDisk /dev/diskN
# 写入
sudo dd if=ventoy.img of=/dev/rdiskN bs=4m
# 弹出
diskutil eject /dev/diskN
```
### Windows
使用 [Rufus](https://rufus.ie/) 或 [balenaEtcher](https://www.balena.io/etcher/)：
1. 选择 ventoy.img 文件
2. 选择目标 U 盘
3. 点击写入
## 常见问题
### Q: 镜像最小可以多大？
A: 最小 64MB（32MB EFI 分区 + 32MB 数据分区）。但实际使用建议至少 512MB。
### Q: 支持多大的 ISO 文件？
A: 理论上支持 exFAT 的最大文件大小（约 16 EB）。实际受限于镜像大小和可用空间。
### Q: 为什么添加文件失败？
可能原因：
1. 镜像空间不足
2. 文件名已存在（使用 `-f` 选项覆盖，或先删除）
3. 目标目录不存在（使用 `-p` 选项自动创建）
4. 文件名包含非法字符
5. 镜像文件损坏
### Q: 如何覆盖已存在的文件？
使用 `-f` 或 `--force` 选项：
```bash
ventoy-img add ventoy.img new-file.iso -d existing-file.iso -f
```
### Q: 如何创建多级目录？
使用 `-p` 或 `--parents` 选项：
```bash
# 创建目录
ventoy-img mkdir ventoy.img path/to/deep/dir -p
# 或在添加文件时自动创建
ventoy-img add ventoy.img file.iso -d path/to/deep/file.iso -p
```
### Q: 如何删除整个目录？
使用 `-r` 或 `--recursive` 选项：
```bash
ventoy-img remove ventoy.img directory-name -r
```
### Q: 如何验证镜像是否正确？
```bash
# 检查分区表
fdisk -l ventoy.img
# 检查 Ventoy 签名
xxd -s 0x190 -l 16 ventoy.img
# 应显示: 5654 0047 6500 4844 0052 6400 2045 720d
# 列出文件
ventoy-img list ventoy.img
```
### Q: 可以在 Windows 上使用吗？
A: 可以。编译 Windows 版本：
```bash
cargo build --release --target x86_64-pc-windows-gnu
```
## 退出码
| 码 | 含义 |
|----|------|
| 0 | 成功 |
| 1 | 错误（详见错误信息） |
## 环境变量
目前不使用任何环境变量。
## 另请参阅
- [技术文档](TECHNICAL.md) - 内部实现细节
- [库使用说明](LIBRARY.md) - Rust 库 API
- [Ventoy 官方文档](https://www.ventoy.net/en/doc_start.html)