# vmsan-rootfs-builder

**Repository Path**: lu9944_admin/vmsan-rootfs-builder

## Basic Information

- **Project Name**: vmsan-rootfs-builder
- **Description**: 快速构建适合vmsan的自定义镜像
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vmsan-rootfs-builder

> 从现有的 Ubuntu 24.04 ext4 rootfs 构建自定义 Firecracker VM 文件系统的独立工具

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](package.json)

## 📖 简介

vmsan-rootfs-builder 是一个独立的项目，用于构建自定义的 ext4 rootfs 文件系统，专为 [vmsan](https://github.com/angelorc/vmsan) Firecracker 微虚拟机设计。

### ✨ 主要特性

- ✅ **独立项目** - 与 vmsan 完全分离，可独立使用
- ✅ **配置文件驱动** - 使用 JSON 配置文件定义构建参数
- ✅ **灵活定制** - 支持预装软件包、复制文件/目录、执行自定义命令
- ✅ **自动大小检测** - 智能计算所需的镜像大小，也可手动指定
- ✅ **元数据生成** - 自动生成构建信息，便于追踪和管理
- ✅ **简洁输出** - 构建产物统一保存到 `dist/` 目录

## 🚀 快速开始

### 基本使用

```bash
# 使用配置文件构建
./bin/build-custom-rootfs.sh --config examples/config.json

# 输出文件自动保存到 dist/ 目录
dist/bitzh-code.ext4      # 自定义 rootfs 镜像
dist/bitzh-code.meta       # 元数据文件
```

### 与 vmsan 一起使用

```bash
# 使用自定义 rootfs 创建 VM
vmsan create --rootfs dist/bitzh-code.ext4 --memory 512 --vcpus 2
```

## 📋 配置文件

配置文件使用 JSON 格式，支持以下参数：

```json
{
  "source": "/home/ubuntu/.vmsan/rootfs/ubuntu-24.04.ext4",
  "output": "my-image",
  "size": 3072,
  "packages": ["curl", "wget", "vim", "git"],
  "copy_files": ["/host/path:/guest/path"],
  "copy_dirs": ["/host/dir:/guest/dir"],
  "run_commands": ["cmd1", "cmd2"],
  "script": "/path/to/script.sh",
  "keep_temp": false
}
```

### 配置选项说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `source` | string | 否 | 源文件系统路径，默认：`~/.vmsan/rootfs/ubuntu-24.04.ext4` |
| `output` | string | 是 | 输出文件名（相对路径）或绝对路径 |
| `size` | number | 否 | 文件系统大小（MB），默认：自动检测 + 512MB |
| `packages` | array | 否 | 要安装的包列表 |
| `copy_files` | array | 否 | 要复制的文件列表（格式：`host:guest`） |
| `copy_dirs` | array | 否 | 要复制的目录列表（格式：`host:guest`） |
| `run_commands` | array | 否 | 在 chroot 中执行的命令列表 |
| `script` | string | 否 | 在 chroot 中执行的脚本路径 |
| `keep_temp` | boolean | 否 | 是否保留临时文件，默认：`false` |

### 示例配置

#### 基础配置

```json
{
  "source": "/home/ubuntu/.vmsan/rootfs/ubuntu-24.04.ext4",
  "output": "dev-tools",
  "size": 2048,
  "packages": ["curl", "wget", "vim", "git"]
}
```

#### 完整开发环境（Python + Node.js）

```json
{
  "source": "/home/ubuntu/.vmsan/rootfs/ubuntu-24.04.ext4",
  "output": "dev-env",
  "size": 3072,
  "packages": [
    "curl", "wget", "vim", "git",
    "python3", "python3-pip", "python3-venv",
    "build-essential", "ca-certificates"
  ],
  "run_commands": [
    "curl -fsSL https://deb.nodesource.com/setup_24.x | bash -",
    "apt-get install -y nodejs",
    "npm install -g npm@latest"
  ]
}
```

## 📁 项目结构

```
vmsan-rootfs-builder/
├── bin/                        # 可执行脚本
│   └── build-custom-rootfs.sh   # 主构建脚本
├── examples/                   # 示例配置
│   ├── config.json              # 基础配置示例
│   └── production-config.json    # 生产环境配置
├── dist/                       # 构建输出目录（自动生成）
│   ├── bitzh-code.ext4         # 构建的镜像文件
│   └── bitzh-code.meta          # 元数据文件
├── .gitignore                  # Git 忽略文件
└── README.md                   # 项目说明
```

## 🔧 系统要求

- Linux (x86_64 或 aarch64)
- Bash 4.0+
- 需要的命令行工具：
  - `truncate`, `mkfs.ext4`, `tune2fs`
  - `mount`, `umount`, `losetup`
  - `sudo`（用于挂载和 chroot）
  - `jq`（用于解析 JSON 配置文件）

### 安装依赖

```bash
# Ubuntu/Debian
sudo apt-get install jq e2fsprogs

# CentOS/RHEL
sudo yum install jq e2fsprogs
```

## 📝 使用场景

### 1. 开发环境

```json
{
  "output": "dev-env",
  "size": 2048,
  "packages": [
    "git", "vim", "tmux", "htop",
    "python3", "nodejs", "build-essential"
  ]
}
```

### 2. Web 服务器

```json
{
  "output": "web-server",
  "size": 2048,
  "packages": ["nginx", "nodejs"],
  "copy_dirs": ["./app:/var/www/html"],
  "run_commands": ["systemctl enable nginx"]
}
```

### 3. 数据分析环境

```json
{
  "output": "data-analysis",
  "size": 3072,
  "packages": [
    "python3", "python3-pip",
    "python3-venv", "build-essential"
  ],
  "run_commands": [
    "pip3 install pandas numpy scipy matplotlib jupyterlab"
  ]
}
```

### 4. CI/CD Runner

```json
{
  "output": "ci-runner",
  "size": 4096,
  "packages": [
    "docker.io", "kubectl", "terraform",
    "git", "jq", "yamllint", "shellcheck"
  ]
}
```

## 🎯 确定镜像大小

### 自动检测（推荐）

不指定 `size` 参数，脚本会自动计算：

```json
{
  "output": "my-image"
  // size 省略，自动计算
}
```

自动计算公式：`源文件大小 + 512MB 缓冲`

### 手动指定

根据需求手动设置大小：

```json
{
  "output": "my-image",
  "size": 3072  // 3GB
}
```

计算公式：`源文件大小 + 软件包大小 + 预留空间 (20%)`

### 大小参考

| 场景 | 建议大小 |
|------|---------|
| 基础工具 | 2GB (2048MB) |
| Python 开发环境 | 3GB (3072MB) |
| Node.js 开发环境 | 3GB (3072MB) |
| 完整开发栈 | 4GB (4096MB) |
| Web 服务器 | 4GB (4096MB) |

## 📊 输出文件

构建成功后会在 `dist/` 目录生成：

```
dist/
├── <name>.ext4      # 可挂载的根文件系统镜像
└── <name>.meta      # 元数据文件 (JSON 格式)
```

### 元数据示例

```json
{
  "name": "bitzh-code.ext4",
  "created": "2026-03-20T14:38:59Z",
  "source": "/home/ubuntu/.vmsan/rootfs/ubuntu-24.04.ext4",
  "size_mb": 3072,
  "packages": ["curl", "wget", "vim", "git", "python3", "python3-pip"],
  "custom_files": 0,
  "custom_dirs": 0,
  "custom_commands": 3,
  "script": "none"
}
```

## 🧹 清理构建输出

```bash
# 删除所有构建输出
rm -rf dist/

# 删除特定的构建输出
rm -f dist/my-image.ext4 dist/my-image.meta
```

## 📄 许可证

本项目采用 Apache-2.0 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关项目

- [vmsan](https://github.com/angelorc/vmsan) - Firecracker 微虚拟机管理工具
- [Firecracker](https://github.com/firecracker-microvm/firecracker) - 开源虚拟机监控程序

## 💬 支持

- 📖 [文档](https://github.com/your-org/vmsan-rootfs-builder)
- 🐛 [问题反馈](https://github.com/your-org/vmsan-rootfs-builder/issues)
- 💬 [讨论区](https://github.com/your-org/vmsan-rootfs-builder/discussions)

## 🌟 致谢

感谢所有贡献者和 vmsan 社区的支持！

---

Made with ❤️ by vmsan-rootfs-builder contributors