# virt-manager-go

**Repository Path**: wangtsingx/virt-manager-go

## Basic Information

- **Project Name**: virt-manager-go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-31
- **Last Updated**: 2025-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Virt-Manager Go

Virt-Manager Go 是一个现代化的、模块化的 virt-manager 重写版本，使用 Go 语言开发，通过 libvirt 提供 RESTful API 来管理 KVM/QEMU 虚拟机。

## 功能特性

- 🚀 **现代化架构**: 基于 Go 1.25.1 和 Gin 框架构建
- 💻 **多架构支持**: 支持 x86_64 和 aarch64 (ARM64)
- 🔒 **启动模式灵活**: 支持 BIOS 和 UEFI (含安全启动)
- 🌐 **RESTful API**: 完整的 HTTP API 用于虚拟机管理
- 📊 **结构化日志**: 使用 logrus 进行 JSON 格式日志记录
- 🔄 **实时虚拟机控制**: 启动、停止、重启、暂停虚拟机
- 📝 **模板系统**: 预构建模板用于快速创建虚拟机
- 🎯 **Libvirt 原生**: 直接集成 libvirt C 库
- 💻 **命令行界面**: 全功能 CLI 工具 (vmctl)
- 🖥️ **控制台访问**: 支持串行、VNC 和 SPICE 控制台
- 🌐 **WebSocket 支持**: 实时控制台代理
- 🔧 **多连接管理**: 管理多个 libvirt 连接

## 架构支持

### x86_64
- BIOS 启动 (传统)
- 使用 OVMF 的 UEFI 启动
- UEFI 安全启动
- Q35 芯片组

### aarch64 (ARM64)
- 使用 AAVMF 的 UEFI 启动
- GICv3 中断控制器
- Virt 机器类型

## 前置要求

- Go 1.25.1 或更高版本
- libvirt >= 9.0.0
- QEMU/KVM
- OVMF 固件 (用于 x86_64 UEFI)
- AAVMF 固件 (用于 aarch64 UEFI)

### 安装依赖 (Ubuntu/Debian)

```bash
sudo apt update
sudo apt install -y \
    libvirt-daemon-system \
    libvirt-dev \
    qemu-kvm \
    qemu-system-x86 \
    qemu-system-arm \
    ovmf \
    qemu-efi-aarch64
```

### 安装依赖 (Fedora/RHEL)

```bash
sudo dnf install -y \
    libvirt-devel \
    qemu-kvm \
    edk2-ovmf \
    edk2-aarch64
```

## 安装

1. 克隆仓库:
```bash
git clone https://github.com/yourusername/virt-manager-go.git
cd virt-manager-go
```

2. 下载依赖:
```bash
make deps
```

3. 构建项目:
```bash
make build
```

## 配置

编辑 `configs/config.yaml`:

```yaml
server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"  # debug 或 release
  read_timeout: 30
  write_timeout: 30

libvirt:
  auto_connect: true
  default_uri: "qemu:///system"

logging:
  level: "info"  # debug, info, warn, error
  format: "json"  # json 或 text
```

## 使用方法

### 启动服务器

```bash
make run
```

或者直接运行:
```bash
./bin/virt-manager-go
```

### 使用 CLI

```bash
# 列出所有虚拟机
./bin/vmctl domain list

# 获取虚拟机详情
./bin/vmctl domain get my-vm

# 启动虚拟机
./bin/vmctl domain start my-vm

# 关闭虚拟机
./bin/vmctl domain shutdown my-vm
```

## API 端点

### 系统

- `GET /api/v1/connections/:connection_id/system/info` - 获取 hypervisor 信息
- `GET /api/v1/connections/:connection_id/system/capabilities` - 获取主机功能

### 连接

- `GET /api/v1/connections` - 列出所有连接
- `POST /api/v1/connections` - 创建新连接
- `POST /api/v1/connections/test` - 测试连接
- `GET /api/v1/connections/:connection_id` - 获取连接详情
- `DELETE /api/v1/connections/:connection_id` - 删除连接
- `GET /api/v1/connections/:connection_id/info` - 获取连接信息
- `GET /api/v1/connections/:connection_id/capabilities` - 获取连接功能
- `POST /api/v1/connections/:connection_id/set-default` - 设置为默认连接
- `POST /api/v1/connections/:connection_id/reconnect` - 重新连接到 libvirt
- `POST /api/v1/connections/reconnect-all` - 重新连接所有连接

### 虚拟机 (域)

- `GET /api/v1/connections/:connection_id/domains` - 列出所有虚拟机
- `POST /api/v1/connections/:connection_id/domains` - 创建新虚拟机
- `GET /api/v1/connections/:connection_id/domains/:name` - 获取虚拟机详情
- `DELETE /api/v1/connections/:connection_id/domains/:name` - 删除虚拟机
- `GET /api/v1/connections/:connection_id/domains/:name/xml` - 获取虚拟机 XML

虚拟机操作:
- `POST /api/v1/connections/:connection_id/domains/:name/start` - 启动虚拟机
- `POST /api/v1/connections/:connection_id/domains/:name/shutdown` - 关闭虚拟机
- `POST /api/v1/connections/:connection_id/domains/:name/reboot` - 重启虚拟机
- `POST /api/v1/connections/:connection_id/domains/:name/force-stop` - 强制停止虚拟机
- `POST /api/v1/connections/:connection_id/domains/:name/suspend` - 暂停虚拟机
- `POST /api/v1/connections/:connection_id/domains/:name/resume` - 恢复虚拟机

虚拟机配置:
- `PUT /api/v1/connections/:connection_id/domains/:name/vcpus` - 设置 vCPU 数量
- `PUT /api/v1/connections/:connection_id/domains/:name/memory` - 设置内存

虚拟机信息:
- `GET /api/v1/connections/:connection_id/domains/:name/stats` - 获取虚拟机统计信息
- `GET /api/v1/connections/:connection_id/domains/:name/status` - 获取虚拟机状态

### 网络

- `GET /api/v1/connections/:connection_id/networks` - 列出所有网络
- `POST /api/v1/connections/:connection_id/networks` - 创建新网络
- `GET /api/v1/connections/:connection_id/networks/:name` - 获取网络详情
- `DELETE /api/v1/connections/:connection_id/networks/:name` - 删除网络
- `POST /api/v1/connections/:connection_id/networks/:name/start` - 启动网络
- `POST /api/v1/connections/:connection_id/networks/:name/stop` - 停止网络

### 存储

存储池:
- `GET /api/v1/connections/:connection_id/storage/pools` - 列出所有存储池
- `POST /api/v1/connections/:connection_id/storage/pools` - 创建新存储池
- `GET /api/v1/connections/:connection_id/storage/pools/:pool` - 获取存储池详情
- `DELETE /api/v1/connections/:connection_id/storage/pools/:pool` - 删除存储池
- `POST /api/v1/connections/:connection_id/storage/pools/:pool/start` - 启动存储池
- `POST /api/v1/connections/:connection_id/storage/pools/:pool/stop` - 停止存储池

存储卷:
- `GET /api/v1/connections/:connection_id/storage/pools/:pool/volumes` - 列出存储池中的所有卷
- `POST /api/v1/connections/:connection_id/storage/pools/:pool/volumes` - 创建新卷
- `GET /api/v1/connections/:connection_id/storage/pools/:pool/volumes/:volume` - 获取卷详情
- `DELETE /api/v1/connections/:connection_id/storage/pools/:pool/volumes/:volume` - 删除卷

### 模板

- `GET /api/v1/templates` - 列出可用模板
- `POST /api/v1/templates/generate` - 从模板生成 XML

### 控制台

- `GET /api/v1/console/serial/:connection_id/:domain_name` - 串行控制台 WebSocket
- `GET /api/v1/console/vnc/:connection_id/:domain_name` - VNC 控制台 WebSocket
- `GET /api/v1/console/spice/:connection_id/:domain_name` - SPICE 控制台 WebSocket

## 项目结构

```
virt-manager-go/
├── bin/                        # 编译后的二进制文件
├── cmd/
│   ├── cli/                    # CLI 工具 (vmctl)
│   │   ├── commands/           # CLI 命令
│   │   └── main.go             # CLI 入口点
│   └── server/                 # HTTP API 服务器
│       └── main.go             # 服务器入口点
├── configs/
│   └── config.yaml             # 配置文件
├── internal/
│   ├── api/
│   │   ├── handlers/           # HTTP 请求处理器
│   │   ├── middleware/         # HTTP 中间件
│   │   └── router.go           # API 路由
│   ├── config/                 # 配置管理
│   ├── models/                 # 数据模型
│   ├── sdk/                    # API 客户端 SDK
│   ├── service/                # 业务逻辑服务
│   └── templates/              # 虚拟机模板构建器
├── web/                        # Web UI (如适用)
├── go.mod
├── go.sum
├── Makefile
└── README.md
```

## 开发

### 运行测试

```bash
make test
```

### 代码格式化

```bash
make fmt
```

### 代码检查

```bash
make lint
```

### 生成 Swagger 文档

```bash
make swag
```

## Docker 支持

### 构建 Docker 镜像

```bash
make docker-build
```

### 在 Docker 中运行

```bash
make docker-run
```

## 贡献

1. Fork 仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request

## 许可证

该项目基于 MIT 许可证 - 详情请见 LICENSE 文件。

## 致谢

- 原版 virt-manager 项目: https://github.com/virt-manager/virt-manager
- libvirt Go 绑定: https://libvirt.org/go/libvirt.html
- Gin Web 框架: https://gin-gonic.com/

## 支持

如有问题和疑问:
- GitHub Issues: https://github.com/yourusername/virt-manager-go/issues
- 文档: https://github.com/yourusername/virt-manager-go/wiki