PVE-VDIClient基于 Proxmox 的 VDI 虚拟桌面客户端实战指南【免费下载链接】PVE-VDIClientProxmox based VDI client项目地址: https://gitcode.com/gh_mirrors/pv/PVE-VDIClient员工在家用笔记本办公要连公司 Proxmox 集群里的一台桌面虚拟机。用 Web 管理界面凑合能用但窗口多、权限难收口也不适合长期挂着。PVE-VDIClient 就是一个基于 Proxmox 的 VDI 虚拟桌面客户端它直接调 Proxmox API 拉出你有权限的虚拟机列表你点一下它用 SPICE 协议把桌面打开中间不需要任何网关。一句话定位它和别的 VDI 方案差在哪PVE-VDIClient 是一个 Python 图形客户端负责登录、列出你能碰的 VM、再把 virt-viewer 拉起来连 SPICE 桌面。和Web 门户 中间件代理那套思路比区别就三条客户端直连 Proxmox API没有会话网关层桌面由 virt-viewer 直连 SPICEWindows、Linux 一套 INI 配置通用Windows 端通过 virt-viewer 的 remote-viewer 打开桌面所有运行参数集中在一个 INI 文件里改配置就能调整行为不用动代码。快速上手装好依赖到能登录 Debian/Ubuntu 上先装系统依赖并克隆项目apt install python3-pip python3-tk virt-viewer git git clone https://gitcode.com/gh_mirrors/pv/PVE-VDIClient进入项目目录后跑依赖脚本它只会装 proxmoxer、customtkinter、requests 三个 Python 包然后把客户端复制到 PATHchmod x requirements.sh ./requirements.sh cp vdiclient.py /usr/local/bin chmod x /usr/local/bin/vdiclient.pyWindows 上先装 Python 和 virt-viewer再依次跑requirements.bat装包要自签打包就再用 build_vdiclient.bat 生成 MSIrequirements.bat build_vdiclient.bat配置文件是必需的找不到会直接弹窗退出。客户端按固定顺序搜索Linux 依次找~/.config/VDIClient/vdiclient.ini、/etc/vdiclient/vdiclient.ini、/usr/local/etc/vdiclient/vdiclient.iniWindows 找%APPDATA%\VDIClient\和%PROGRAMFILES%\VDIClient\下的vdiclient.ini。最小可用配置如下[Hosts.组名]里的组名就是登录界面上显示的服务器组名称[General] title VDI Client theme dark [Hosts.PVE] hostpool { 10.10.10.100 : 8006 } auth_backend pve auth_totp false tls_verify false验证方式运行python3 vdiclient.py输入 Proxmox 账号密码。登录成功后会弹出 VM 列表说明 API 连通、权限正常连不上则先看下面的排错一节。登录界面长什么样登录窗口从上到下就这些元素服务器组下拉框配置了多个Hosts.段才会出现、Username、Password、Log In 和 Cancel 按钮。把对应集群段的auth_totp改成true后窗口会多出一行 OTP Key输入六位动态码再登录另外两个可选元素配了pwresetcmd时窗口底部会出现 Password Reset 按钮kiosk true时 Cancel 消失登录框无法关闭。机制拆解配置文件怎么组织[General]段管界面title窗口标题theme取 system/light/darkicon和logo是图标和窗口内 logo 路径guest_type决定列表里显示 qemu、lxc 还是 bothpage_size控制 VM 列表每页条数timeout是分钟级的无操作自动退出时间0 为不退出。每个Hosts.组名段是一个服务器组hostpool是 JSON 字典键为 IP 或 FQDN值为端口多行时必须缩进——客户端用 configparser 解析格式错了会弹窗报错。段内还有auth_backend认证 realm一般就是 pve、auth_totp、tls_verify三个开关。配置文件本身支持两种来源--config_type file默认按固定路径搜索和--config_type http配合--config_location传 URL可用--config_username/--config_password走 Basic 认证适合把配置放在内网服务器统一下发。登录支持哪几种方式代码逻辑一句话概括组装用户身份 → 随机挑节点尝试 → 认证通过就返回失败就换下一个节点继续。密码登录默认方式。auth_totp true时登录框出现 OTP 输入行动态码用 Google Authenticator、Microsoft Authenticator 这类标准 TOTP 应用生成API token在Hosts.段配user、token_name、token_value三项。如果整个文件只有一个集群段客户端会跳过登录界面直接认证密码找回pwresetcmd写一条完整可执行命令比如start chrome --apphttp://pwreset.example.com登录界面就会出现对应按钮点一下执行该命令。凭据是组级别的不同Hosts.段各有自己的 token、TOTP 和 TLS 设置互不影响。SPICE 连接怎么建立点 Connect 后客户端对这台 VM 调 Proxmox 的spiceproxyAPI 拿到 SPICE 连接参数把它们写成一个 virt-viewer INI通过 stdin 传给 remote-viewerWindows 上是 virt-viewer 自带的 remote-viewer。如果 API 返回的proxy地址你这边够不到——典型是反向代理或 NAT 之后——用SpiceProxyRedirect段把host:port重写成可达地址inidebug true时打开桌面前会先把最终 INI 弹出来方便你核对[SpiceProxyRedirect] pve1.example.com:3128 123.123.123.123:6000 [AdditionalParameters] enable-usbredir trueAdditionalParameters段里的每一项会原样追加给 virt-viewer需要更多参数时直接对照 remote-viewer 的 man 页写即可。kiosk 模式下客户端会自动附加--kiosk --kiosk-quit on-disconnect断开即退出。多集群怎么配置再写一个Hosts.组名段就是再定义一个集群组名原样显示在登录窗口的下拉框里第一个定义的组默认选中。每个组独立的hostpool、auth_totp、tls_verify。hostpool里列多个节点时登录会随机打乱顺序逐个尝试连到任意一个就算成功组内节点互为备份。典型场景改哪几个参数就能落地场景一远程办公一台机器只连一台桌面把kiosk true和fullscreen true写进[General]客户端会锁掉关闭按钮、固定窗口位置再在唯一的Hosts.段配auto_vmid用户认证通过后直接连进指定桌面不再显示列表[General] kiosk True fullscreen True [Hosts.PVE] auto_vmid 100效果用户开机点图标一路进桌面中途没有任何可退出的入口。场景二多数据中心共享桌面按数据中心各写一段Hosts.北京、Hosts.上海用户登录时在下拉框里选。guest_type按场景过滤资源办公机显示both容器测试环境显示lxc纯 VM 机房显示qemupage_size调大每页条数减少翻页。VM 列表页每 5 秒刷新一次状态running 的行可点 Connectsuspended 或带锁的会禁用按钮场景三教机房用完一键还原配show_reset true每台 VM 右侧多一个 Reset 按钮点击后客户端先 stop 再 start把桌面恢复到开机初始状态。再配timeout 1515 分钟内没有任何键盘、鼠标或窗口操作列表窗口自动关闭、回到登录界面用户任意一次按键都会重置计时。排错手册常见问题怎么查 ️现象可能原因处理登录弹窗 Unable to connect to any VDI serverhostpool 节点全部不可达确认网络与 8006 端口连通性核对hostpool里的 IP、端口、防火墙Invalid username and/or password凭据错、realm 不匹配或 TOTP 不同步核对 PVE 账号与 realm开 TOTP 时重新取动态码确认auth_backendTLS 证书报错自签证书没信任、CA 不对用企业 CA 签发 PVE 证书把 CA 放进系统信任库保持tls_verify true登录后提示 No desktop instances found用户对该集群 VM 无权限给目标 VM 分配VM.PowerMgmt、VM.Console、VM.Audit权限点 Connect 报 Is SPICE display configured for your VM?VM 没配置 SPICE 显示在 PVE 侧给 VM 配 SPICE 显卡/显示再重试API 连上但桌面连不上NAT/反代后proxy地址不可达inidebug true看实际下发的 SPICE 参数用SpiceProxyRedirect重写地址桌面卡顿链路带宽不足在AdditionalParameters里调 virt-viewer 的 SPICE 压缩参数或排查带宽Windows 提示 virt-viewer missing没装或没注册安装 virt-manager 官方 Virtual Machine Manager 包启动就报找不到配置文件不在默认搜索路径、INI 格式错用--config_location显式指定路径或修正 hostpool 缩进进阶安全、调优和打包安全加固怎么做生产环境把tls_verify改回true用企业 CA 给 PVE 签证书别靠关验证绕过外网暴露时开启auth_totp true强制双因素能用 API token 就用 token 三件套客户端上不留用户明文密码工位机开kiosk true锁死窗口和退出路径。性能怎么调inidebug true打开实际发给 virt-viewer 的 INI核对proxy、端口与 SPICE 参数弱网链路在AdditionalParameters里加 virt-viewer 的 SPICE 压缩相关参数VM 多的集群调大page_size减少翻页等待。生态集成AdditionalParameters透传任意 virt-viewer 参数例如enable-usbredir true、enable-usb-autoshare true做 USB 透传配置放 HTTP 服务器启动时--config_type http --config_location URL免逐台维护Windows 端装好 Python 与依赖后跑 build_vdiclient.bat 出自签 MSILinux 端pyinstaller --onefile打出的单文件在dist/直接分发。收尾它适合谁适合已经在跑 Proxmox、想给员工一个统一桌面入口、又不想再搭一层 VDI 中间件的团队。如果你的需求是会话录像、外设策略矩阵、桌面池化调度这个项目没有覆盖那需要完整的 VDI 平台别硬套。【免费下载链接】PVE-VDIClientProxmox based VDI client项目地址: https://gitcode.com/gh_mirrors/pv/PVE-VDIClient创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考