# lvm-manager

**Repository Path**: wangtsingx/lvm-manager

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LVM Manager - Libvirt Virtual Machines Manager

![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

生产级的 Libvirt 虚拟机管理工具，使用 Go 语言开发，提供 REST API、CLI 和事件驱动架构。

## ✨ 特性

- 🚀 **完整的虚拟机生命周期管理** - 创建、启动、停止、暂停、恢复、重启、删除
- 🔌 **REST API** - 标准化的 HTTP 接口，易于集成
- 💻 **CLI 工具** - 强大的命令行界面，便于运维管理
- 📊 **事件驱动** - 实时监听虚拟机状态变化
- 📈 **Prometheus 指标** - 内置监控指标导出
- 🔄 **自动重连** - 连接断开时自动恢复
- 🛡️ **安全设计** - 支持认证、审计日志

## 📋 系统要求

### 运行时依赖
- Linux 系统（推荐 Ubuntu 20.04+, CentOS 8+, Debian 11+）
- libvirt >= 7.0.0
- QEMU/KVM
- Go 1.21+ （仅构建时需要）

### 开发依赖
```bash
# Ubuntu/Debian
sudo apt-get install -y libvirt-dev pkg-config gcc

# RHEL/CentOS
sudo yum install -y libvirt-devel

# macOS (仅用于开发，不支持 KVM)
brew install libvirt
```

## 🚀 快速开始

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

### 2. 构建
```bash
make all
```

### 3. 运行 Daemon
```bash
# 前台运行（需要 root 或 libvirt 组权限）
sudo ./build/lvm-daemon

# 或使用环境变量配置
sudo LISTEN_ADDR=:9090 LOG_LEVEL=debug ./build/lvm-daemon
```

### 4. 使用 CLI
```bash
# 列出所有虚拟机
./build/lvm-cli domain list

# 获取虚拟机详情
./build/lvm-cli domain get myvm

# 启动虚拟机
./build/lvm-cli domain start myvm

# 创建新虚拟机
./build/lvm-cli domain create \
  --name testvm \
  --memory 2048 \
  --vcpus 2 \
  --disk /var/lib/libvirt/images/testvm.qcow2 \
  --network-type network \
  --network-name default
```

## 📖 API 文档

### 基础 URL
```
http://localhost:8080/api/v1
```

### 端点列表

#### 健康检查
```bash
GET /health
```

#### 列出所有虚拟机
```bash
GET /domains?inactive=true

Response:
{
  "domains": [
    {
      "uuid": "...",
      "name": "myvm",
      "state": "running",
      "memory": 2097152,
      "cpus": 2,
      "autostart": false,
      "persistent": true
    }
  ],
  "count": 1
}
```

#### 获取虚拟机详情
```bash
GET /domains/{name}?xml=true

Response:
{
  "uuid": "...",
  "name": "myvm",
  "state": "running",
  "max_memory": 2097152,
  "memory": 2097152,
  "cpus": 2,
  "cpu_time": 12345678,
  "autostart": false,
  "persistent": true,
  "xml_config": "<?xml version='1.0'?>..."
}
```

#### 创建虚拟机（高层规格）
```bash
POST /domains
Content-Type: application/json

{
  "name": "newvm",
  "memory": 2048,
  "vcpus": 2,
  "disk_path": "/var/lib/libvirt/images/newvm.qcow2",
  "network_type": "network",
  "network_name": "default",
}
```

#### 创建虚拟机（XML）
```bash
POST /domains
Content-Type: application/json

{
  "xml": "<?xml version='1.0'?><domain type='kvm'>...</domain>"
}
```

#### 执行虚拟机操作
```bash
POST /domains/{name}/action
Content-Type: application/json

{
  "action": "start"  // start, shutdown, destroy, reboot, suspend, resume
}
```

#### 删除虚拟机
```bash
DELETE /domains/{name}
```

## 🏗️ 架构

```
┌─────────────────┐
│   CLI / UI      │
└────────┬────────┘
         │ REST API
┌────────▼────────┐
│  lvm-daemon     │
│  ┌───────────┐  │
│  │ API Layer │  │
│  └─────┬─────┘  │
│  ┌─────▼─────┐  │
│  │  Services │  │
│  └─────┬─────┘  │
│  ┌─────▼─────┐  │
│  │ libvirt-go│  │
│  └───────────┘  │
└────────┬────────┘
         │ CGO
┌────────▼────────┐
│   libvirtd      │
└────────┬────────┘
         │
┌────────▼────────┐
│   QEMU/KVM      │
└─────────────────┘
```

### 模块说明

- **internal/libvirtconn** - 连接管理，自动重连
- **internal/domain** - 虚拟机 CRUD 操作
- **internal/events** - 事件监听与分发
- **internal/api** - REST API 处理器
- **pkg/client** - Go SDK 客户端库
- **cmd/lvm-daemon** - Daemon 主程序
- **cmd/lvm-cli** - CLI 工具

## 🔧 配置

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `LISTEN_ADDR` | `:8080` | HTTP 监听地址 |
| `LIBVIRT_URI` | `qemu:///system` | Libvirt 连接 URI |
| `LOG_LEVEL` | `info` | 日志级别 (debug, info, warn, error) |

### Libvirt URI 示例

```bash
# 本地系统连接
qemu:///system

# 本地会话连接
qemu:///session

# 远程 SSH 连接
qemu+ssh://user@host/system

# 远程 TLS 连接
qemu+tls://host/system
```

## 📦 部署

### Systemd 服务

```bash
# 安装
sudo make install
sudo make systemd-install

# 启动服务
sudo systemctl start lvm-daemon
sudo systemctl enable lvm-daemon

# 查看状态
sudo systemctl status lvm-daemon

# 查看日志
sudo journalctl -u lvm-daemon -f
```

### Docker 部署

```bash
# 构建镜像
make docker-build

# 运行容器（需要特权模式访问 libvirt socket）
docker run -d \
  --name lvm-daemon \
  --privileged \
  -v /var/run/libvirt:/var/run/libvirt \
  -p 8080:8080 \
  lvm-manager:latest
```

## 🧪 测试

```bash
# 运行所有测试
make test

# 生成覆盖率报告
make test-coverage

# 代码检查
make lint

# 格式化代码
make fmt
```

## 📝 开发指南

### 项目结构

```
lvm-manager/
├── cmd/
│   ├── lvm-daemon/       # Daemon 主程序
│   └── lvm-cli/          # CLI 工具
├── internal/
│   ├── libvirtconn/      # 连接管理
│   ├── domain/           # Domain 服务
│   ├── events/           # 事件管理
│   └── api/              # REST API
├── pkg/
│   └── client/           # SDK 客户端
├── configs/              # 配置文件
├── docs/                 # 文档
├── Makefile              # 构建脚本
├── Dockerfile            # 容器构建
└── README.md
```

### 添加新功能

1. 在 `internal/` 下创建新的服务模块
2. 在 `internal/api/` 添加 REST API 处理器
3. 在 `cmd/lvm-cli/` 添加 CLI 命令
4. 在 `pkg/client/` 添加客户端方法
5. 编写测试并更新文档

## 🤝 贡献

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [Libvirt 官方文档](https://libvirt.org/docs.html)
- [libvirt-go 绑定](https://pkg.go.dev/libvirt.org/go/libvirt)
- [libvirt-go-xml](https://pkg.go.dev/libvirt.org/go/libvirtxml)

## 📞 支持

- 提交 Issue: https://github.com/yourusername/lvm-manager/issues
- 讨论: https://github.com/yourusername/lvm-manager/discussions

## 🗺️ 路线图

- [x] 第一阶段：基础 Domain CRUD + REST API + CLI
- [ ] 第二阶段：快照管理、存储/网络管理
- [ ] 第三阶段：RBAC、审计日志、任务队列
- [ ] 第四阶段：Web UI、多宿主机管理
- [ ] 第五阶段：Live Migration、高级监控