宿主机 Agent 接入

1. 为每台宿主机生成令牌

在平台点击「添加宿主机」，选择 KVM 或 Hyper-V 并复制令牌。每台宿主机使用独立令牌。建议先以 enable_limits: false 接入，确认虚拟机和网卡归属后再开启写入。

{
  "url": "https://vm.example.com",
  "token": "该宿主机的令牌",
  "enable_limits": false
}

2. Linux KVM

安装 Python 3 和提供 virsh 的 libvirt 客户端。用 virsh -c qemu:///system list --all 确认可访问本机虚拟机。将上面的 JSON 保存为 /etc/vm-bandwidth/kvm.json。可以添加 "guest_agent": true，优先查询已安装 QEMU Guest Agent 的客户机，其他地址来源是 libvirt DHCP 租约和宿主机 ARP。

sudo install -d -m 700 /etc/vm-bandwidth
sudoedit /etc/vm-bandwidth/kvm.json
sudo chmod 600 /etc/vm-bandwidth/kvm.json
sudo install -D -m 644 agents/kvm.py /opt/vm-bandwidth/kvm.py
sudo install -m 644 agents/kvm-bandwidth.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kvm-bandwidth
sudo journalctl -u kvm-bandwidth -n 50 --no-pager

开放限速前先核对目标 TAP 的既有 QoS。libvirt 修改速率可能重建队列和过滤器，已有独立 tc 规则的网卡应继续由原工具管理。此版本限速面向有持久化配置的 TAP 网卡。设置 enable_limits 为 true 后重启服务，策略会同时核对运行配置和启动配置。

3. Windows Hyper-V

在 Hyper-V 宿主机用管理员 Windows PowerShell 5.1 执行。先创建目录并设置权限，再将 agents\hyperv.ps1 复制到 C:\ProgramData\VmBandwidth\hyperv.ps1，将 JSON 配置保存为同目录的 config.json。

New-Item -ItemType Directory -Force C:\ProgramData\VmBandwidth
icacls C:\ProgramData\VmBandwidth /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F'

Get-VM | Get-VMNetworkAdapter | Select-Object VMName, Id, IPAddresses
Set-Location C:\ProgramData\VmBandwidth
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\hyperv.ps1 -Config .\config.json

确认只读接入后按 Ctrl+C 结束前台运行，再注册随系统启动的计划任务。确认脚本来源后，如果 Windows 对上传的脚本标记了下载来源，使用 Unblock-File .\hyperv.ps1。启用限速后，重启任务使配置生效。

$base = 'C:\ProgramData\VmBandwidth'
$argsText = "-NoProfile -NonInteractive -ExecutionPolicy RemoteSigned -File $base\hyperv.ps1 -Config $base\config.json"
$action = New-ScheduledTaskAction -Execute "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -Argument $argsText
$trigger = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) -RestartCount 10 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName VmBandwidth -Action $action -Trigger $trigger -Settings $settings -User SYSTEM -RunLevel Highest
Start-ScheduledTask -TaskName VmBandwidth

IP 来自 Hyper-V 客户机集成服务。如果有网卡但无流量，先核对下方性能计数器。平台只接受唯一匹配，可在配置的 counter_map 中按网卡 Id 指定实际计数器 Name，JSON 中的反斜杠要写为 \\。设置映射前用单网卡测速确认归属。SR-IOV 网卡不参与此版统计和限速。

Get-CimInstance Win32_PerfFormattedData_NvspNicStats_HyperVVirtualNetworkAdapter |
  Select-Object Name, BytesSentPersec, BytesReceivedPersec

Microsoft Hyper-V 性能计数器说明 · Microsoft Hyper-V 原生 QoS 说明

Hyper-V SDN 双向限速

适用于已部署 Windows Server SDN Network Controller 并启用软件 QoS 的环境。安装 NetworkController PowerShell 模块，并给 Agent 运行账户授予操作目标网络接口资源的权限。使用域认证时需要为计划任务选择有权限的账户，或按 Network Controller 配置客户端证书并给任务账户授予私钥权限。

在现有 Hyper-V Agent JSON 增加 sdn。resource_map 的键是 Get-VMNetworkAdapter 返回的网卡 Id，值是同一接口在 Network Controller 中的 ResourceId。可以按需加上 certificate_thumbprint。Agent 会核对资源 MAC，并使用 ETag 更新配置。

"sdn": {
  "url": "https://nc.example.com",
  "resource_map": {
    "Microsoft:VM-GUID\\NIC-GUID": "NC-NetworkInterface-ResourceId"
  }
}

启用 enable_limits 后，已映射网卡的上下行都由 SDN QoS 执行。迁移到 SDN 管理前，先用原管理工具清理该网卡已有的原生上限，避免两处规则叠加。确保目标启用软件 QoS，尤其是下行。读回控制器配置后，用双向测速确认主机上的实际效果。

Microsoft SDN 网卡 QoS 文档

4. 验收与撤销

在同一平台接入至少一台 KVM 和一台 Hyper-V。按地址搜索，核对宿主机和网卡。
在测试虚拟机分别运行 iperf3 -c SERVER_IP 和 iperf3 -c SERVER_IP -R，确认上传和下载的曲线方向。再分别检查 TCP 稳定吞吐和 UDP 接收速率。
配置测试限速后等待界面显示「配置已核对」。例如 KVM 上传 20 Mbps、下载 100 Mbps，Hyper-V 上传 20 Mbps。再次测速并确认另一台虚拟机的策略未被修改。
验证虚拟机重启、地址变化和 Agent 重连。解除平台限速时将相应方向设为 0，再确认回执。若需恢复由其他工具设定的原规则，事前记录原配置，解除平台管理后通过原工具恢复。