# kvmManager

**Repository Path**: luonannet/kvmManager

## Basic Information

- **Project Name**: kvmManager
- **Description**: 适合高校ICT专业，特别是云计算专业的教学管理平台，包含主要目的是把学生创建云主机的功能交给学生自己管理，
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教育云平台 - 项目功能说明

## 项目概述

基于 Go + Gin + MySQL 开发的教育云平台，采用 Center-Agent 分布式架构，提供虚拟机管理、在线考试、面试评估等核心功能。

**技术栈**: Go | Gin | MySQL | WebSocket | Go Templates | noVNC | libvirt | dnsmasq | systemd

---

## 架构

```
┌──────────────────────────────────────────┐
│                  Center                   │
│  HTTP :80  │  WebSocket  │  MySQL         │
│  模板渲染   │  Agent 注册  │  数据持久化    │
└──────────────┬───────────────────────────┘
               │ WebSocket (心跳 + 指令)
    ┌──────────┼──────────┬──────────┐
    ▼          ▼          ▼          ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│ Agent │ │ Agent │ │ Agent │ │ Agent │
│ :8081 │ │ :8081 │ │ :8081 │ │ :8081 │
│KVM/QEMU│       │ │       │ │       │
│dnsmasq│ │       │ │       │ │       │
└───────┘ └───────┘ └───────┘ └───────┘
```

- **Center**：Web 管理端，处理用户请求，通过 WebSocket 向 Agent 下发指令
- **Agent**：部署在 KVM 宿主机上，管理 libvirt 虚拟机，通过 WebSocket 上报心跳和状态
- Agent 安装后通过 MAC 地址自动注册，无需预先分配 ID

---

## 用户角色

| 角色 | 权限范围 | 访问路径 |
|------|---------|---------|
| **管理员 (admin)** | 全局：用户、班级、服务器、镜像、日志、所有 VM | `/admin/*` |
| **教师 (teacher)** | 负责班级：学生管理、考试/面试创建与批阅、VM 管理 | `/teacher/*` |
| **学生 (student)** | 个人：创建/操作虚拟机、参加考试、完成面试 | `/student/*` |

认证方式：Cookie 会话（`kvm_session`）+ 角色中间件。

---

## 核心功能

### 一、虚拟机管理

#### 创建流程

```
用户请求 → 负载均衡选 Agent → 分配 VNC 端口 → 数据库记录
→ Agent 收到 WebSocket 指令 → qemu-img convert 独立拷贝
→ cloud-init 配置（用户/密码/SSH/GRUB/VGA）
→ VM 启动 → dnsmasq DHCP 分配 IP
→ Agent 轮询 lease 回传真实 IP → 更新数据库
```

#### QCOW2 云镜像初始化

- 用户名/密码可自定义，默认 `root / 123456`
- 自动放开 SSH 认证（PermitRootLogin + PasswordAuthentication）
- BIOS 启动 + `console=tty0` + `getty@tty0`，VNC 可见登录提示
- 首次启动约 90 秒（cloud-init → 自动重启 → 就绪）

#### 网络架构

```
校园网 172.40.0.0/16
    ├── Agent 宿主机 (br0 Linux bridge)
    │   ├── dnsmasq DHCP: 172.40.2.100-200
    │   └── VM 直连 br0 → 获得 172.40.2.x
    └── 学生直接 SSH 172.40.2.x
```

Agent 通过 `br0` bridge 接入物理网络，VM 获得校园网真实 IP。

#### 实时状态同步

- Agent 每 5 秒通过 WebSocket 向 Center 发送心跳（含 CPU/内存/磁盘使用率）
- Center 在内存中维护 VM 实时状态，通过 WebSocket 推送到前端
- VM 列表页面实时显示运行/停止/创建中状态

---

### 二、服务器 & 镜像管理

- 服务器自动注册（Agent WebSocket + MAC 标识），无需手动添加
- 心跳检测 + 实时状态同步（CPU、内存、磁盘、VM 数量）
- QCOW2 / ISO 镜像上传、启用/禁用（支持断点续传和大文件分片）
- 支持 Rocky 10、openEuler、Ubuntu 等操作系统

---

### 三、考试系统

- 五种题型：单选、多选、判断、填空、简答
- 倒计时 + 自动保存进度 + 一次性提交
- 考试与班级绑定，删除考试不删除学生答卷
- AI 自动评分预留接口（DeepSeek API）

---

### 四、面试系统

- 教师创建面试模板（题目/评分标准）
- 学生录制回答并提交
- 教师在线评分和反馈

---

## 部署

### 编译

```bash
./build.sh
```

编译 Center 和 Agent 二进制到 `build/` 目录，同时打包模板、静态资源、配置文件和 systemd 服务单元。

### 安装

**Center（管理服务器）**：

```bash
bash install.sh center
```

**Agent（KVM 宿主机）**：

```bash
bash install.sh agent
```

install.sh 会自动：
- 检测操作系统（Rocky/Ubuntu/Debian/openEuler）
- 安装系统依赖（KVM/QEMU/libvirt/dnsmasq、MySQL 等）
- 部署二进制、配置、模板到 `/var/www/sptc/`
- 安装并启用 systemd 服务（`kvm-center` / `kvm-agent`）
- 配置防火墙端口

可选参数：

| 参数 | 作用 |
|------|------|
| `--no-database` | 跳过 MySQL 安装 |
| `--no-firewall` | 跳过防火墙配置 |
| `--no-update` | 跳过系统包索引更新 |
| `--skip-copy` | 跳过文件复制（文件已在目标位置） |

### 批量部署

```bash
bash deploy.sh              # 内网全量部署
bash deploy.sh external     # 外网部署（通过跳板机）
bash deploy.sh center       # 仅部署 Center
```

`deploy.sh` 流程：
1. rsync/scp 上传文件
2. 执行 `install.sh` 安装依赖和 systemd 服务
3. NFS 服务端/客户端配置
4. `systemctl stop → fuser -k 释放端口 → systemctl start` 重启服务
5. 健康检查（`systemctl is-active`）

跳板机配置：编辑 `deploy.sh` 中的 `JUMP_HOST_CFG`、`JUMP_PORT`、`JUMP_USER`。

### 服务管理

```bash
# 查看状态
systemctl status kvm-center
systemctl status kvm-agent

# 启停
systemctl start kvm-center
systemctl stop kvm-agent

# 查看日志
journalctl -u kvm-center -f
journalctl -u kvm-agent -f

# 开机自启
systemctl enable kvm-center
systemctl enable kvm-agent
```

### 首次手动部署（无 deploy.sh）

```bash
# Center 服务器
scp build/center build/config.toml build/kvm-center.service build/install.sh \
    build/templates/ build/static/ root@172.40.0.2:/var/www/sptc/
ssh root@172.40.0.2 "cd /var/www/sptc && bash install.sh center"

# Agent 服务器
scp build/agent build/agent.toml build/kvm-agent.service build/install.sh \
    root@172.40.0.4:/var/www/sptc/
ssh root@172.40.0.4 "cd /var/www/sptc && bash install.sh agent"
```

---

## Nginx 反向代理

生产环境建议在 Center 前加 Nginx：

```nginx
server {
    listen 80;
    server_name cloud.example.com;

    location /ws/ {
        proxy_pass http://127.0.0.1:80;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400s;
    }

    location / {
        proxy_pass http://127.0.0.1:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 配置

### Center (`config.toml`)

```toml
[server]
port = 80
mode = "debug"          # debug | release
log_file = ""           # 留空输出到 journal

[database]
host = "127.0.0.1"
port = 3306
user = "root"
password = "123456"
dbname = "kvm_manager"

[session]
secret = "your-secret-key"
max_age = 86400         # 会话有效期（秒）

[storage]
iso_path = "/var/lib/libvirt/images/iso"
qcow2_path = "/var/lib/libvirt/images/qcow2"
vnc_base_port = 6100

[[dhcp_pool]]
network = "172.40.3"
netmask = "255.255.0.0"
dns = "114.114.114.114"
start_offset = 2
```

### Agent (`agent.toml`)

```toml
[server]
port = 8081
mode = "release"
log_file = "/var/log/kvm-agent.log"

[agent]
name = ""               # 留空使用 MAC 地址自动注册
libvirt_uri = "qemu:///system"
advertise_ip = ""       # 多网卡时指定注册 IP

[center]
host = "172.40.0.2"     # Center 地址
port = 80
ws_path = "/ws/agent"
heartbeat_interval = 5

[kvm]
default_bridge = "virbr0"
storage_pool = "default"
vnc_base_port = 6100

[vm]
machine_type = ""       # 留空自动检测
emulator = "/usr/bin/qemu-system-x86_64"

[storage]
vm_disk_path = "/home/libvirt/media_images/"
iso_path = "/var/lib/libvirt/images/iso"
disk_mount_path = "/home/"
```

### 调试模式

- `mode = "debug"` → 所有级别日志输出到 stderr（journalctl 可见）
- `mode = "release"` → 仅 Error 级别日志输出（到 log_file 或 stderr）

---

## 目录结构

```
/var/www/sptc/
├── center              # Center 二进制
├── agent               # Agent 二进制
├── config.toml         # Center 配置
├── agent.toml          # Agent 配置
├── install.sh          # 安装脚本
├── kvm-center.service  # Center systemd 单元
├── kvm-agent.service   # Agent systemd 单元
├── templates/          # Go 模板
└── static/             # 静态资源 (noVNC, CSS, JS)

/etc/systemd/system/
├── kvm-center.service
└── kvm-agent.service
```

---

## 注意事项

- Agent 二进制需 `GODEBUG=asyncpreemptoff=1`（已内置在 systemd 单元中，规避 Go 1.25 多核崩溃）
- 部署时 `rsync` 排除 `*.toml`，不会覆盖生产环境已修改的配置
- 服务启动前会自动 `fuser -k` 释放端口，防止旧进程残留导致端口冲突
- 健康检查失败时部署流程会中止（Center）或标记该节点为失败（Agent）