pve_guest_agent

PVE 通过 qemu-guest-agent 实现主机与虚拟机之间的高效通信与集成

qemu-guest-agent 简介

qemu-guest-agent (QGA) 是运行在虚拟机内部的守护进程，它允许 Proxmox VE 主机与客户机操作系统进行通信，提供高级管理功能。

一、Proxmox VE 后台配置

1. 启用虚拟机代理

在 Proxmox VE 中为虚拟机启用 qemu-guest-agent 支持：

1. 关闭虚拟机（如果正在运行）
2. 选择目标虚拟机，进入"硬件"选项卡
3. 添加"串行端口"设备（如果尚未添加）
   • 型号选择 VirtIO Serial
4. 进入"选项"选项卡
5. 找到"QEMU Guest Agent"选项并设置为"是"

6. 启动虚拟机并安装相应的客户端软件

2. 配置注意事项

• ** VirtIO 驱动**：确保虚拟机已安装 VirtIO 驱动程序（Windows 系统）
• 内存 ballooning：QGA 支持内存 ballooning，可在"硬件"中启用
• 配置文件：QGA 配置位于 /etc/pve/qemu-server/VMID.conf 中
• 备份集成：启用 QGA 后可实现应用程序一致的备份

一键脚本

bash <(curl -sL gitee.com/meimolihan/linux-command_sh/raw/master/pve_guest_agent.sh)

效果预览

脚本源码

#!/bin/bash

list_color_init() {
    export gl_hui=$'\033[38;5;59m'
    export gl_hong=$'\033[38;5;9m'
    export gl_lv=$'\033[38;5;10m'
    export gl_huang=$'\033[38;5;11m'
    export gl_lan=$'\033[38;5;32m'
    export gl_bai=$'\033[38;5;15m'
    export gl_zi=$'\033[38;5;13m'
    export gl_bufan=$'\033[38;5;14m'
    export reset=$'\033[0m'
}
list_color_init

log_info()  { echo -e "${gl_lan}[信息]${gl_bai} $*"; }
log_ok()    { echo -e "${gl_lv}[成功]${gl_bai} $*"; }
log_warn()  { echo -e "${gl_huang}[警告]${gl_bai} $*"; }
log_error() { echo -e "${gl_hong}[错误]${gl_bai} $*" >&2; }

sleep_fractional() {
    local seconds=$1
    if sleep "$seconds" 2>/dev/null; then return 0; fi
    if command -v perl >/dev/null 2>&1; then perl -e "select(undef, undef, undef, $seconds)"; return 0; fi
    if command -v python3 >/dev/null 2>&1; then python3 -c "import time; time.sleep($seconds)"; return 0; fi
    if command -v python >/dev/null 2>&1; then python -c "import time; time.sleep($seconds)"; return 0; fi
    local int_seconds=$(echo "$seconds" | awk '{print int($1+0.999)}')
    sleep "$int_seconds"
}

break_end() {
    echo -e "${gl_lv}操作完成${gl_bai}"
    echo -e "${gl_bai}按任意键继续 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai} \c"
    read -r -n 1 -s -r -p ""
    echo ""
    clear
}

exit_script() {
    echo ""
    echo -ne "${gl_hong}感谢使用，再见！${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}\c"
    sleep_fractional 0.5
    echo -ne "${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}\c"
    sleep_fractional 0.6
    clear
    exit 0
}

handle_invalid_input() {
    echo -ne "\r${gl_huang}无效的输入,请重新输入! ${gl_zi} 1 ${gl_huang} 秒后返回"
    sleep 1
    echo -e "\r${gl_lv}无效的输入,请重新输入! ${gl_zi}0${gl_lv} 秒后返回"
    sleep 0.5
    return 2
}

detect_os() {
    if [ -f /etc/os-release ]; then
        . /etc/os-release
        OS=$ID
        VER=$VERSION_ID
    else
        log_error "无法检测操作系统"
        return 1
    fi
}

install_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 安装 QEMU Guest Agent${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    log_info "开始安装 QEMU Guest Agent ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    case $OS in
        debian|ubuntu)
            apt update
            apt install -y qemu-guest-agent
            ;;
        centos|rhel|almalinux|rocky)
            if command -v dnf >/dev/null 2>&1; then
                dnf install -y qemu-guest-agent
            else
                yum install -y qemu-guest-agent
            fi
            ;;
        opensuse*)
            zypper install -y qemu-guest-agent
            ;;
        *)
            log_error "不支持的操作系统: $OS"
            return 1
            ;;
    esac
    log_ok "QEMU Guest Agent 安装完成"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

start_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 启动 QEMU Guest Agent 服务 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    if command -v systemctl >/dev/null 2>&1; then
        systemctl start qemu-guest-agent
        systemctl enable qemu-guest-agent
        log_ok "服务已启动并设置开机自启"
    else
        if [ -f /etc/init.d/qemu-guest-agent ]; then
            service qemu-guest-agent start
            chkconfig qemu-guest-agent on
            log_ok "服务已启动并设置开机自启"
        else
            log_error "未找到 qemu-guest-agent 服务脚本"
            return 1
        fi
    fi
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

stop_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 停止 QEMU Guest Agent 服务 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    if command -v systemctl >/dev/null 2>&1; then
        systemctl stop qemu-guest-agent
        systemctl disable qemu-guest-agent
        log_ok "服务已停止并禁用开机自启"
    else
        if [ -f /etc/init.d/qemu-guest-agent ]; then
            service qemu-guest-agent stop
            chkconfig qemu-guest-agent off
            log_ok "服务已停止并禁用开机自启"
        else
            log_error "未找到 qemu-guest-agent 服务脚本"
            return 1
        fi
    fi
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

restart_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 重启 QEMU Guest Agent 服务 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    if command -v systemctl >/dev/null 2>&1; then
        systemctl restart qemu-guest-agent
        log_ok "服务已重启"
    else
        if [ -f /etc/init.d/qemu-guest-agent ]; then
            service qemu-guest-agent restart
            log_ok "服务已重启"
        else
            log_error "未找到 qemu-guest-agent 服务脚本"
            return 1
        fi
    fi
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

status_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 查看 QEMU Guest Agent 服务状态 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    if command -v systemctl >/dev/null 2>&1; then
        systemctl status qemu-guest-agent --no-pager
    else
        if [ -f /etc/init.d/qemu-guest-agent ]; then
            service qemu-guest-agent status
        else
            log_error "未找到 qemu-guest-agent 服务"
            return 1
        fi
    fi
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

test_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 测试 QEMU Guest Agent 通信 ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    
    if [ -S /dev/virtio-ports/org.qemu.guest_agent.0 ]; then
        log_ok "virtio-serial 设备存在"
    else
        log_warn "virtio-serial 设备不存在，请确保虚拟机已启用 QEMU Guest Agent"
    fi
    
    if pgrep -x "qemu-ga" > /dev/null; then
        log_ok "qemu-ga 进程正在运行"
        QGA_VERSION=$(qemu-ga --version 2>/dev/null | head -1)
        log_info "版本信息: $QGA_VERSION"
    else
        log_error "qemu-ga 进程未运行"
    fi
    
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

remove_qga() {
    echo -e ""
    echo -e "${gl_zi}>>> 卸载  QEMU Guest Agent${gl_bai}"
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    read -r -e -p "$(echo -e "${gl_hong}确定要卸载  QEMU Guest Agent 吗？(${gl_lv}y${gl_bai}/${gl_hong}N${gl_bai}): ")" confirm
    case $confirm in
        [Yy])
            log_info "开始卸载 QEMU Guest Agent ${gl_hong}.${gl_huang}.${gl_lv}.${gl_bai}"
            case $OS in
                debian|ubuntu)
                    apt remove -y qemu-guest-agent
                    apt autoremove -y
                    ;;
                centos|rhel|almalinux|rocky)
                    if command -v dnf >/dev/null 2>&1; then
                        dnf remove -y qemu-guest-agent
                    else
                        yum remove -y qemu-guest-agent
                    fi
                    ;;
                opensuse*)
                    zypper remove -y qemu-guest-agent
                    ;;
                *)
                    log_error "不支持的操作系统: $OS"
                    return 1
                    ;;
            esac
            log_ok "QEMU Guest Agent 已卸载"
            ;;
        [Nn])
            log_info "已取消卸载"
            ;;
        *)
            handle_invalid_input
            ;;
    esac
    echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
    break_end
}

main_menu() {
    while true; do
        clear
    
        if ! command -v qm &> /dev/null; then
            echo -e ""
            echo -e "${gl_zi}>>> PVE Guest Agent 管理脚本${gl_bai}"
            echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
            log_error "未检测到Proxmox VE环境，请确保脚本在PVE节点上运行"
            echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
            break_end
            return 1
        fi
    
        echo -e "${gl_zi}>>> PVE Guest Agent 管理脚本${gl_bai}"
        echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
        echo -e "${gl_bufan}1.  ${gl_bai}安装 QEMU Guest Agent"
        echo -e "${gl_bufan}2.  ${gl_bai}启动服务"
        echo -e "${gl_bufan}3.  ${gl_bai}停止服务"
        echo -e "${gl_bufan}4.  ${gl_bai}重启服务"
        echo -e "${gl_bufan}5.  ${gl_bai}查看服务状态"
        echo -e "${gl_bufan}6.  ${gl_bai}测试代理通信"
        echo -e "${gl_bufan}7.  ${gl_bai}卸载 QEMU Guest Agent"
        echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
        echo -e "${gl_hong}0.  ${gl_bai}退出脚本"
        echo -e "${gl_bufan}————————————————————————————————————————————————${gl_bai}"
        read -r -e -p "请输入你的选择: " choice
        
        case $choice in
            1)
                detect_os
                install_qga
                ;;
            2)
                start_qga
                ;;
            3)
                stop_qga
                ;;
            4)
                restart_qga
                ;;
            5)
                status_qga
                ;;
            6)
                test_qga
                ;;
            7)
                detect_os
                remove_qga
                ;;
            0)
                exit_script
                ;;
            *)
                handle_invalid_input
                ;;
        esac
    done
}

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main_menu
fi

主要功能：

• 正常关机：通过 Web 界面安全关闭虚拟机
• 文件系统冻结/解冻：备份时确保数据一致性
• 虚拟机状态查询：获取客户机内部状态信息
• 时间同步：在主机和客户机之间同步时间
• 网络配置：动态配置客户机网络设置

使用优势：

• 提高虚拟机管理效率
• 增强备份可靠性
• 改善虚拟化体验
• 提供更好的监控能力

你知道吗？ qemu-guest-agent 使用 virtio-serial 通道与主机通信，不需要网络连接即可工作，这使其更加可靠和安全。

二、Linux 系统安装指南

1. Debian/Ubuntu 系统

# 更新软件包列表
sudo apt update

# 安装 qemu-guest-agent
sudo apt install qemu-guest-agent

# 启动服务并设置开机自启
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

# 检查服务状态
sudo systemctl status qemu-guest-agent

# 查看日志（如果有问题）
sudo journalctl -u qemu-guest-agent -f

2. CentOS/RHEL 系统

# CentOS/RHEL 7 及以下版本
sudo yum install qemu-guest-agent
sudo service qemu-guest-agent start
sudo chkconfig qemu-guest-agent on

# CentOS/RHEL 8 及以上版本
sudo dnf install qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

# 对于 AlmaLinux/Rocky Linux
sudo dnf install qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

3. OpenSUSE 系统

# OpenSUSE Leap/Tumbleweed
sudo zypper install qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

# 验证安装
sudo systemctl status qemu-guest-agent

三、OpenWRT/iStoreOS 安装

1. 安装步骤

# 更新软件包列表
opkg update

# 安装 qemu-guest-agent
opkg install qemu-ga
# 或者使用 pkg 命令
pkg install qemu-guest-agent

# 设置脚本权限
chmod +x /etc/init.d/qemu-ga

# 启用服务
/etc/init.d/qemu-ga enable

# 启动服务
/etc/init.d/qemu-ga start

# 重启系统（可选）
reboot

2. 服务配置

# 检查服务状态
/etc/init.d/qemu-ga status

# 查看进程
ps | grep qemu-ga

# 检查日志
logread | grep qemu

# 手动测试代理
qemu-ga --version

# 配置高级选项（如果需要）
vi /etc/config/qemu-ga

⚠️ 注意：某些 OpenWRT 版本可能需要手动编译包含 qemu-ga 的镜像，或者从第三方仓库安装。

四、Windows 系统安装

1. 驱动下载

Windows 虚拟机需要安装 VirtIO 驱动程序：

1. 下载 VirtIO 驱动：

   • 访问 Fedora VirtIO 驱动页面
   • 下载最新版本的 virtio-win.iso

2. 挂载驱动镜像：

   • 在 Proxmox VE 中，将 ISO 镜像挂载到虚拟机的 CD/DVD 驱动器
   • 启动虚拟机并访问光驱

2. 安装方法

方法一：通过设备管理器安装

1. 打开"设备管理器"
2. 找到带有黄色感叹号的未知设备
3. 右键选择"更新驱动程序"
4. 选择"浏览我的电脑以查找驱动程序"
5. 指向 VirtIO ISO 镜像中的 guest-agent 目录
6. 完成安装

方法二：运行安装程序

1. 打开 VirtIO ISO 镜像
2. 运行 virtio-win-guest-tools.exe 安装程序
3. 按照向导完成安装
4. 重启系统

方法三：命令行安装

# 使用 PowerShell 安装
Mount-DiskImage -ImagePath "路径\to\virtio-win.iso"
$driveLetter = (Get-DiskImage -ImagePath "路径\to\virtio-win.iso" | Get-Volume).DriveLetter
Start-Process -FilePath "${driveLetter}:\guest-agent\qemu-ga-x86_64.msi" -Wait

验证安装：

# 检查服务状态
Get-Service -Name QEMU-GA

# 启动服务
Start-Service -Name QEMU-GA

# 设置自动启动
Set-Service -Name QEMU-GA -StartupType Automatic

五、验证与测试

1. 基础验证

在 Proxmox VE 主机上验证 QEMU Guest Agent 是否正常工作：

# 列出所有虚拟机
qm list

# 检查特定虚拟机的代理状态
qm agent <VMID> ping

# 获取虚拟机信息
qm agent <VMID> info

# 获取网络信息
qm agent <VMID> network-get-interfaces

# 获取操作系统信息
qm agent <VMID> get-osinfo

2. 高级测试

# 测试文件系统冻结/解冻（用于备份）
qm agent <VMID> fsfreeze-freeze
qm agent <VMID> fsfreeze-thaw

# 执行客户机命令
qm agent <VMID> exec "echo 'Hello from Guest'"

# 获取时间同步状态
qm agent <VMID> get-time

# 设置时间（需要权限）
qm agent <VMID> set-time

# 关机测试
qm agent <VMID> shutdown

六、高级配置与优化

1. 自定义配置

在客户机中自定义 QEMU Guest Agent 配置：

Linux 系统配置：

# 编辑配置文件
sudo vi /etc/sysconfig/qemu-ga
# 或
sudo vi /etc/default/qemu-ga

# 常见配置选项
DAEMON_ARGS="-d -v -p /dev/virtio-ports/org.qemu.guest_agent.0"
# -d: 守护进程模式
# -v: 详细输出
# -p: 指定 virtio-serial 端口

# 重启服务使配置生效
sudo systemctl restart qemu-guest-agent

Windows 系统配置：

• 注册表路径：HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\QEMU-GA
• 可配置项：日志级别、超时设置、黑名单命令等

2. 性能优化

# 调整日志级别（减少日志量）
# 在配置文件中添加：
LOG_LEVEL="warning"

# 限制资源使用（在内存有限的系统中）
# 创建系统服务限制
sudo mkdir -p /etc/systemd/system/qemu-guest-agent.service.d/
sudo vi /etc/systemd/system/qemu-guest-agent.service.d/limits.conf

# 添加内容：
[Service]
MemoryMax=50M
CPUQuota=20%

七、故障排除

1. 常见问题

1. 代理未响应：

   • 检查虚拟机中服务是否运行
   • 验证 VirtIO 串行端口是否已添加

2. 权限问题：

   • 确保客户机中的代理有足够权限执行操作

3. 时间同步问题：

   • 检查时间同步配置是否正确

4. 文件系统冻结失败：

   • 确认文件系统支持冻结操作

2. 解决方案

# 诊断连接问题
# 在客户机中检查 virtio-serial 设备
ls -la /dev/virtio-ports/

# 检查内核消息
dmesg | grep virtio

# 手动测试串行端口
cat /dev/virtio-ports/org.qemu.guest_agent.0

# 重新安装代理
sudo apt remove qemu-guest-agent
sudo apt install qemu-guest-agent

# 检查防火墙设置（某些系统可能需要）
sudo ufw status

Windows 故障排除：

# 检查事件日志
Get-EventLog -LogName Application -Source QEMU-GA | Select-Object -First 10

# 重新注册服务
sc delete QEMU-GA
"路径\to\qemu-ga.exe" -s install

八、最佳实践

1. 安全建议

1. 最小权限原则：

   • 限制 QEMU Guest Agent 的执行权限
   • 使用黑名单限制敏感命令执行

2. 网络隔离：

   • 虽然 QGA 不依赖网络，但仍需确保虚拟机网络安全

3. 定期更新：

   • 保持客户机中的代理软件为最新版本
   • 定期更新 VirtIO 驱动程序

4. 审计日志：

   • 定期检查 QEMU Guest Agent 的日志文件
   • 监控异常活动

2. 维护技巧

1. 备份前准备：

   # 在备份脚本中添加冻结/解冻命令
   qm agent <VMID> fsfreeze-freeze
   # 执行备份操作
   qm agent <VMID> fsfreeze-thaw
   

2. 监控集成：

   • 将 QGA 状态监控集成到现有监控系统中
   • 设置警报当代理不可用时

3. 自动化部署：

   • 使用配置管理工具（Ansible、Puppet）自动化代理安装
   • 创建自定义镜像预装 QEMU Guest Agent

4. 性能基准测试：

   • 定期测试代理响应时间
   • 监控资源使用情况

🎉 总结：通过正确安装和配置 qemu-guest-agent，您可以显著提升 Proxmox VE 虚拟化环境的可管理性和可靠性。无论是 Linux、Windows 还是 OpenWRT 系统，QGA 都能提供一致的管理体验。

🛠️ 实践建议：

1. 在新虚拟机模板中预装 QEMU Guest Agent
2. 定期测试代理功能以确保其正常工作
3. 将 QGA 集成到您的备份和监控流程中
4. 关注安全最佳实践，确保环境安全