KVM 节点部署手册
把一台裸金属宿主机变成 KVM 云主机节点,接入小白云IDC 后台:客户在前台下单品,系统自动创建虚机、分配内网 IP、下发 NAT 端口转发,全程无需人工登录宿主机。
装完你能得到什么
一个被你的 IDC 站点纳管的 KVM 节点,具备以下能力:
| 能力 | 说明 |
|---|---|
| 自动开通 | 客户支付成功 → 后台自动创建虚机、注入密码与网络、下发 NAT 转发,秒级到分钟级交付 |
| 客户控制台 | 开关机/重启、一键重装、Web VNC 控制台、快照管理、密码重置、RDP/SSH 连接信息下载 |
| 节点可观测 | 负载、内存、磁盘、虚机分配趋势(每分钟采样,保留 24 小时);服务状态自检 |
| 安全运维 | API 密钥轮换自动重启生效;操作日志(面板 + API)全量落库 |
链路架构一览
客户前台下单
│ 支付成功
▼
IDC 站点(KVM 插件)
│ HTTPS API(节点地址 + 密钥)
▼
kvm-agent 被控端(宿主机 :8787)
│ 本机调用
▼
libvirt / qemu-kvm ── 虚机生命周期(创建/开关机/重装/快照)
│
└── cloud-init:开机自动注入内网 IP、root 密码(无需镜像预装 cloud-init 工具链之外的依赖)
│
└── NAT 转发:由 IDC 侧全量下发,宿主机 iptables 落地
IDC 站点与 kvm-agent 之间只有一组凭据:节点 API 密钥。密钥可在节点设置页轮换,轮换后 agent 自动重启生效。
宿主机要求
硬件
| 项目 | 最低 | 建议 |
|---|---|---|
| CPU | 4 核,支持 VT-x / AMD-V 硬件虚拟化 | 8 核以上,并在 BIOS 开启虚拟化 |
| 内存 | 8 GB | 16 GB+(按虚机套餐规模估算) |
| 磁盘 | 100 GB(系统 + 镜像 + 虚机盘) | SSD / NVMe,独立数据盘更佳 |
| 系统 | CentOS 7.9+(libvirt + qemu) | 与宝塔面板共存无冲突 |
cat /proc/cpuinfo | grep -E "vmx|svm" 有输出才能跑 KVM)。裸金属服务器一般无此问题。网络
- 宿主机需要一个公网 IPv4(客户连接 RDP/SSH 走它),或位于 1:1 NAT 机房(每个虚机端口段映射公网)
- 内网 NAT 网段:agent 安装时自动创建网桥(默认
192.168.0.0/24段可自定义),虚机内网互通、经宿主机出网 - 防火墙需放行:
8787(agent 面板/API);如需 VNC 直连还需放行对应 VNC 端口段(建议仅对管理 IP 开放)
安装 kvm-agent
全程 4 步,复制粘贴即可:
- 上传安装包:从授权中心下载
kvm-agent安装包,上传到宿主机任意目录(宝塔「文件」或 SFTP 均可) - 解压并执行安装:
安装脚本会自动完成:检测/安装 libvirt 与 qemu、注册 systemd 服务(cd /root && mkdir -p kvm-agent && cd kvm-agent unzip -o kvm-agent-v*.zip bash install.shkvm-agent)、初始化工作目录与配置、启动服务。 - 放行防火墙端口:
宝塔用户也可在「安全」页面放行 8787/TCP。firewall-cmd --permanent --add-port=8787/tcp && firewall-cmd --reload - 验证服务:
systemctl status kvm-agent # active (running) 即正常 curl -s http://127.0.0.1:8787/api/ping # 返回 JSON 即服务可用
http://宿主机IP:8787,输入安装时设置的访问密钥即可进入 agent 面板(虚机列表、资源监控、节点设置)。接入 IDC 后台
- IDC 后台 → 插件管理 → 安装并启用 KVM 虚拟化插件
- 进入插件的 节点管理 → 新增节点,填写:
- 节点名称:自定义(如「上海宿主机 01」)
- API 地址:
http://宿主机公网IP:8787 - API 密钥:与 agent 安装时设置的访问密钥一致
- 点击 连通测试,返回版本号与资源信息即接入成功
- 在节点详情里确认 资源上报(CPU/内存/磁盘/负载)与 虚机列表 同步正常
镜像与系统模板
- 系统镜像为
qcow2格式,放入 agent 配置的镜像目录(安装完成页有路径,默认/var/lib/kvm-agent/images) - 在 IDC 后台 kvm 插件的「镜像管理」中登记镜像(名称 + 文件名 + 系统类型 Windows/Linux),客户重装系统时按此列表选择
- Windows 镜像建议预装 VirtIO 驱动;Linux 镜像带 cloud-init 可自动注入密码与网络(不带时 agent 走配置注入兜底)
- 客户开通时磁盘/内存/CPU 由后台「商品配置」决定:商品 → 开通参数 → 选择 KVM 节点并绑定规格
NAT 网络与端口转发
- 宿主机内网网段在 agent 安装时规划(默认
192.168.0.0/24,网关 .1,宿主机为 NAT 出口) - 虚机默认无独立公网 IP,通过 NAT 端口转发对外服务:
公网IP:外部端口 → 虚机内网IP:内部端口 - 转发规则由 IDC 侧全量下发(客户在控制台增删,后台自动同步到宿主机 iptables),无需手工维护
- Windows 虚机自动生成 RDP 转发(3389),Linux 自动生成 SSH 转发(22),客户控制台可直接复制连接信息或下载 .rdp 文件
客户买到的体验
| 动作 | 客户在哪里做 | 背后发生什么 |
|---|---|---|
| 下单云主机 | 前台商品页 → 支付 | 自动创建虚机 + 注入 IP/密码 + 下发转发,控制台显示连接信息 |
| 开关机/重启 | 客户中心 → 我的服务 → 控制台 | 调用 agent 生命周期接口,状态实时回显 |
| 重装系统 | 控制台 → 重装 | 销毁系统盘重建 + 重新注入,数据盘可选保留 |
| Web VNC | 控制台 → 控制台按钮 | 浏览器直开 noVNC(临时令牌 5 分钟有效,不暴露 VNC 端口) |
| 快照回滚 | 控制台 → 快照 | qemu 外部快照,创建/回滚/删除,运行中可用 |
| 密码重置 | 控制台 → 重置密码 | 在线改密,无需进 VNC |
安全建议
- 8787 来源限制:防火墙仅放行 IDC 站点出口 IP 访问 8787,杜绝全网扫描
- 密钥轮换:定期(季度)在 agent 节点设置页轮换密钥
- VNC 收紧:Web VNC 经 agent 代理并使用一次性令牌,请勿单独开放 libvirt 的裸 VNC 监听到公网
- 备份节奏:对运行中虚机定期快照;宿主机层面建议每周对
/var/lib/kvm-agent配置目录做一次备份 - 系统加固:宿主机 SSH 改密钥登录、宝塔改默认端口与安全入口
排错手册
连通测试失败 / 节点显示离线
① 防火墙未放行 8787;② API 密钥与 agent 不一致(节点设置页核对或重设);③ agent 服务未运行(systemctl status kvm-agent);④ IDC 站点出口 IP 被宿主机防火墙拦截(来源限制白名单核对)。
开通成功但虚机起不来
① CPU 未开硬件虚拟化(grep -E "vmx|svm" /proc/cpuinfo);② 嵌套虚拟化未开启(虚机宿主场景);③ 镜像文件缺失或损坏(agent 镜像目录核对,重传);④ 磁盘池空间不足(节点资源页查看)。
Web VNC 打开黑屏/超时
① 虚机未开机;② 令牌过期(重新从控制台打开);③ 反代环境未开启 WebSocket 支持(宝塔反代需在配置中允许 Upgrade 头);④ agent 版本过旧,升级到与插件匹配的版本。
NAT 转发不生效
① 宿主机 iptables 被 Docker 等接管(iptables -L -n 核对链);② 机房 1:1 NAT 场景机房侧端口未放行;③ 转发端口已被占用(控制台换一个外部端口);④ 下发失败看 agent 面板「操作日志」的报错详情。
后台登录 agent 提示 CSRF 校验失败
清浏览器 cookie 后重新登录;若经反向代理访问,确认代理未丢失 Host 头。
资源监控没有曲线
res_history 表按分钟采样、保留 24 小时,刚接入的节点需要几分钟积累;确认 agent 服务持续运行(重启会重置采样窗口)。
上线检查表
- ☐
systemctl status kvm-agent为 running,且重启宿主机后自启 - ☐ 8787 仅对 IDC 站点出口 IP 放行
- ☐ IDC 后台连通测试通过,资源与虚机列表同步正常
- ☐ 至少一个系统镜像登记并可重装成功
- ☐ 用测试商品完整走一遍:下单 → 开通 → 控制台开关机 → 重装 → 快照 → 删除
- ☐ 客户侧 RDP/SSH 连接信息复制可用,Web VNC 可打开
- ☐ 密钥已从安装默认值修改为强随机串
小白云IDC KVM 节点部署手册 · 与产品同版本发布 · 站点安装见《安装部署手册》,日常使用见《使用手册》