白 小白云IDC授权中心
白
小白云IDC · v3.7
KVM 节点部署 · 被控端 kvm-agent

KVM 节点部署手册

把一台裸金属宿主机变成 KVM 云主机节点,接入小白云IDC 后台:客户在前台下单品,系统自动创建虚机、分配内网 IP、下发 NAT 端口转发,全程无需人工登录宿主机。

被控端
kvm-agent(本手册安装)
宿主机系统
CentOS 7+ / Linux
通信方式
HTTP API · 端口 8787
预计耗时
15–25 分钟

装完你能得到什么

一个被你的 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 自动重启生效。

宿主机要求

硬件

项目最低建议
CPU4 核,支持 VT-x / AMD-V 硬件虚拟化8 核以上,并在 BIOS 开启虚拟化
内存8 GB16 GB+(按虚机套餐规模估算)
磁盘100 GB(系统 + 镜像 + 虚机盘)SSD / NVMe,独立数据盘更佳
系统CentOS 7.9+(libvirt + qemu)与宝塔面板共存无冲突
嵌套虚拟化提醒:如果你的宿主机本身是别人的虚机(VPS),必须确认供应商开启了嵌套虚拟化(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 步,复制粘贴即可:

  1. 上传安装包:从授权中心下载 kvm-agent 安装包,上传到宿主机任意目录(宝塔「文件」或 SFTP 均可)
  2. 解压并执行安装:
    cd /root && mkdir -p kvm-agent && cd kvm-agent
    unzip -o kvm-agent-v*.zip
    bash install.sh
    安装脚本会自动完成:检测/安装 libvirt 与 qemu、注册 systemd 服务(kvm-agent)、初始化工作目录与配置、启动服务。
  3. 放行防火墙端口:
    firewall-cmd --permanent --add-port=8787/tcp && firewall-cmd --reload
    宝塔用户也可在「安全」页面放行 8787/TCP。
  4. 验证服务:
    systemctl status kvm-agent          # active (running) 即正常
    curl -s http://127.0.0.1:8787/api/ping   # 返回 JSON 即服务可用
安装完成:浏览器打开 http://宿主机IP:8787,输入安装时设置的访问密钥即可进入 agent 面板(虚机列表、资源监控、节点设置)。

接入 IDC 后台

  1. IDC 后台 → 插件管理 → 安装并启用 KVM 虚拟化插件
  2. 进入插件的 节点管理 → 新增节点,填写:
    • 节点名称:自定义(如「上海宿主机 01」)
    • API 地址:http://宿主机公网IP:8787
    • API 密钥:与 agent 安装时设置的访问密钥一致
  3. 点击 连通测试,返回版本号与资源信息即接入成功
  4. 在节点详情里确认 资源上报(CPU/内存/磁盘/负载)与 虚机列表 同步正常
密钥安全:密钥等同节点 root 级权限,仅在 IDC 后台与 agent 两处保存;怀疑泄露时在 agent「节点设置」页轮换,agent 自动重启生效后到 IDC 后台同步新密钥即可。

镜像与系统模板

  • 系统镜像为 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 文件
机房 1:1 NAT 场景:若宿主机处于 1:1 NAT 机房(内网网卡 + 机房映射公网 IP),需保证转发端口在机房侧同样放行;出网走宿主机 MASQUERADE,安装脚本已自动配置。

客户买到的体验

动作客户在哪里做背后发生什么
下单云主机前台商品页 → 支付自动创建虚机 + 注入 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 节点部署手册 · 与产品同版本发布 · 站点安装见《安装部署手册》,日常使用见《使用手册》