KubeVirt Web UI 部署文档

最后更新: 2026-08-26
宿主机: ai-ear.cn:6022
Web UI: http://ai-ear.cn:9013
认证: \1xxx\2

---

1. 概述

在 K3s 集群上部署 KubeVirt，并通过宿主机 Python 服务提供 Web UI 管理界面。支持：

• VM 创建/启动/停止/重启/删除
• 模板化创建（Rocky 9 / Ubuntu 22.04）
• Cloud-Init 自动配置
• 登录认证拦截

---

2. 文件清单

文件	说明
/opt/kubevirt-ui/server.py	Python 后端 (HTTP/1.1 + 登录认证)
/opt/kubevirt-ui/index.html	前端单页应用
/etc/systemd/system/kubevirt-ui.service	systemd 服务 (PORT=9013)

---

3. 后端 API

3.1 认证

路由	方法	说明	需认证
/login	GET	登录页面	❌
/api/login	POST	登录 (username/password)	❌
/api/logout	GET	退出	✅
/api/auth/check	GET	检查登录状态	❌
/api/health	GET	健康检查	❌

Session: Cookie session=<token>, HttpOnly, SameSite=Strict, 24h 过期

3.2 业务 API (全部需认证)

路由	说明
/api/vms	获取所有 VM (精简)
/api/vmis	获取所有 VMI
/api/nodes	获取节点信息
/api/templates	获取模板列表
/api/pvcs	获取 PVC 列表
/api/vm/{ns}/{name}	获取 VM 详情
/api/vm/create	POST 创建 VM
/api/vm/{ns}/{name}/{action}	start/stop/restart/pause/unpause/migrate/delete

3.3 环境变量

变量	默认值	说明
PORT	9013	监听端口
KUBECONFIG	/etc/rancher/k3s/k3s.yaml	K8s 配置
AUTH_USER	admin	登录用户名
AUTH_PASS	xxx	登录密码
SESSION_SECRET	随机生成	Session 密钥

---

4. 模板配置

4.1 Rocky Linux 9

• PVC: rocky9-base (default namespace)
• 存储: local PV → /var/lib/rancher/k3s/storage/rocky9-base/disk.img (raw, 20Gi)
• 源镜像: /u02/repo/images/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2
• 默认: 2 CPU / 4Gi RAM
• Cloud-Init:

  user: rocky
  password: xxx
  chpasswd: { expire: false }
  ssh_pwauth: true
  runcmd:
    - systemctl enable sshd
    - systemctl start sshd

4.2 Ubuntu 22.04

• 镜像: quay.io/containerdisks/ubuntu:22.04 (containerDisk)
• 默认: 2 CPU / 4Gi RAM
• Cloud-Init: user=ubuntu / password=xxx

---

5. 存储 (PV/PVC)

# PV
apiVersion: v1
kind: PersistentVolume
metadata:
  name: rocky9-base-pv
spec:
  capacity: { storage: 20Gi }
  accessModes: [ReadWriteOnce]
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual-local
  local:
    path: /var/lib/rancher/k3s/storage/rocky9-base
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values: [yi]

# PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: rocky9-base
  namespace: default
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: manual-local
  resources: { requests: { storage: 20Gi } }
  volumeName: rocky9-base-pv

---

6. systemd 服务

[Unit]
Description=KubeVirt Web UI
After=network.target

[Service]
Type=simple
User=root
Environment=KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Environment=PORT=9013
ExecStart=/usr/bin/python3 /opt/kubevirt-ui/server.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

管理命令:

sudo systemctl restart kubevirt-ui
sudo systemctl status kubevirt-ui
sudo journalctl -u kubevirt-ui -f

---

7. 部署过程记录

7.1 解决的问题

问题	原因	解决
Web UI 无限加载	HTTP/1.0 无 Content-Length	升级 HTTP/1.1 + 后端精简 JSON
前端 fetch 超时死锁	无 AbortController	8s 超时 + abort
NodePort 残留 REJECT 规则	旧 Ingress/Service 未清理	删除残留资源
CDI upload WaitForFirstConsumer 死锁	local-path 绑定策略	改用 local PV 直接绑定
VM 无法 ping/SSH	qcow2 → raw 格式转换	qemu-img convert -O raw
Cloud-Init 包安装失败	Pod 网络无外网访问	移除 packages 段，保留基础配置

7.2 性能优化

• /api/nodes: 39KB → ~151 bytes (后端精简 K8s metadata)
• /api/vms: 完整 VM spec → 仅 name/namespace/status/cpu/memory/volumes
• 前端 fetch 8s AbortController 超时

---

8. 访问方式

http://ai-ear.cn:9013

登录: admin / xxx

防火墙已放行 9013 端口。

---

9. 验证测试 VM

# Rocky 9 测试 VM (已创建)
Name: rocky9-test
IP: 10.42.0.245
SSH: ssh rocky@10.42.0.245  (password: xxx
OS: Rocky Linux 9.8 (Blue Onyx)
Guest Agent: v10.1.0 ✅

---

10. 后续计划

1. 配置 Multus 网络让 VM 获得真实 LAN IP
2. 添加更多模板 (CentOS, Debian, Windows)
3. VM 快照/备份功能
4. 多节点支持 (当前仅单节点 yi)
5. GPU 直通 (HAMi 已部署，待集成)