PXVDI 桌面客户端使用说明
本文介绍 PXVDI 桌面客户端的首次连接、设置及日常操作，适用于 Windows、macOS 和 Linux。界面截图采自 macOS 版 4.1.2；部分选项会根据操作系统、客户端组件和服务器配置显示。
1. 安装
前往梨儿方官网下载与操作系统及处理器架构对应的客户端，并完成安装。使用其他连接协议时，请按部署要求准备对应组件。
2. 使用说明
2.1 首次连接云桌面
- 启动客户端，在首页右上角点击齿轮图标，打开设置。
- 选择左侧的服务器，输入管理员提供的完整服务器地址，例如
https://gw.pxvdi.lierfang.com:16003。地址应包含http://或https://；使用非默认端口时，还需填写端口号。 - 点击测试服务器，确认地址是否可用。测试使用输入框中的地址，测试成功后仍需点击保存配置。
- 如需切换界面语言，进入常规 → 语言设置，选择所需语言。
- 关闭设置弹窗，输入云桌面账户和密码，点击登录。
- 登录成功后，点击分配给您的桌面卡片，开始连接。
保存密码用于记住登录凭据；自动登录用于在下次启动客户端进入云桌面时尝试自动登录。自动登录需要有效的账户信息。没有账户时，可点击立即注册，是否允许注册由服务器决定；扫码登录也需要服务器支持。
2.2 设置的基本操作
新版设置采用统一的侧栏分区弹窗。原来的“高级设置”已合并到常规、RDP、PXVDI、Moonlight等分区中，直接点击左侧菜单即可查看。
| 分区 | 主要用途 |
|---|---|
| 服务器 | 配置云桌面服务器地址、证书选项，测试服务器连接 |
| 常规 | 设置语言、默认连接类型、自动登录、外网模式、视频及显示选项 |
| RDP | 设置 RDP 的画面、声音、麦克风、桌面缩放及网络参数 |
| PXVDI | 设置 PXVDI 传输协议、桌面缩放及 SDL 客户端选项 |
| Moonlight | 设置 Moonlight 编解码、游戏优化及画面选项 |
| 关于 | 查看版本及联系信息、导出日志，使用平台专用功能 |
| 隐私 | 查看隐私政策 |
| 许可 | 查看第三方组件及开源许可 |
修改设置时，请注意以下操作规则：
- 保存配置：一次保存各分区中已修改的设置，无需在每个分区分别保存。协议参数通常在下一次建立连接时使用。
- 重置：重新读取已保存的配置，撤销当前尚未保存的修改。此按钮不会恢复出厂默认值。
- 关闭：点击右上角的 × 或弹窗外部关闭设置；关闭不会自动保存普通设置。
- 即时操作：语言选择立即保存并切换界面；开启全屏模式时，窗口会立即进入全屏。这些操作不应视为尚未生效的普通修改。
- 滚动查看：常规、RDP、PXVDI 等分区可能包含超出窗口高度的内容，请在右侧内容区域向下滚动；底部操作按钮始终可见。
2.2.1 服务器
| 设置项 | 说明 |
|---|---|
| 服务器地址 | 云桌面的登录及服务接口地址。按管理员提供的协议、域名或 IP、端口填写；本地连接的远程主机地址在“本地连接”中单独配置 |
| 忽略SSL证书 | 控制是否忽略服务器证书校验。使用自签名证书的部署环境可按管理员要求设置；使用有效可信证书时建议关闭 |
| 测试服务器 | 检查当前输入地址的服务是否可达。测试通过不代表账户一定能登录，也不代表所有远程桌面协议均可连接 |
如果测试失败，先核对协议、地址和端口，再检查客户端网络、服务运行状态及证书配置。
2.2.2 常规
| 设置项 | 说明 |
|---|---|
| 语言设置 | 切换界面语言，选择后立即生效 |
| 连接类型 | 桌面卡片的默认连接方式。桌面端可提供 FreeRDP2、FreeRDP3、SPICE、Moonlight、PXVDI、VNC；启用相应组件时还可显示 Blast、PCOIP。能否连接取决于服务器及本机组件支持 |
| 自动登录 | 启动客户端进入云桌面时，使用已保存的登录信息尝试登录；与登录卡片上的“自动登录”为同一项偏好 |
| 外网模式 | 用于 PXVDI 连接。开启后通过服务器代理连接，适用于外网访问；关闭后直连虚拟机，适用于能够直接访问虚拟机的内网环境 |
| 比特率 | PXVDI 和 Moonlight 共用的视频码率选项，可选 auto、10M、30M、50M、100M。提高码率通常能改善画面，但需要更多带宽；带宽不足时可适当降低 |
| 帧率 | PXVDI 和 Moonlight 共用，可选 auto、30、60、120、144。高帧率需要服务器、客户端和网络共同支持 |
| 高清显示 | HiDPI 画面选项。桌面端 PXVDI 内嵌客户端和 SDL 客户端均读取此设置；它与协议分区中的“桌面缩放”分别控制画面像素和远端界面缩放 |
默认连接类型的使用顺序为：手动在桌面卡片中选择的协议 → 服务器指定的协议 → 本地默认连接类型。当服务器未指定协议，或桌面池允许全部协议（all）时，才使用本地偏好；共享桌面池另有协议限制。
| 设置项 | 说明 |
|---|---|
| 调试模式 | 保存后启用更详细的 Debug 日志，关闭后使用 Info 日志。建议在排查问题时开启，完成后关闭 |
| 全屏模式 | 开启时立即将主窗口切换到全屏，并可保存该偏好 |
| 多屏 | 全屏模式开启后显示，用于支持多显示器的连接；实际效果取决于协议及组件支持 |
| 显示菜单栏 | 保存连接菜单栏偏好，实际显示取决于所用会话客户端 |
| Mac模式 | 此处的 Mac 指设备 MAC 地址。用于支持按设备 MAC 地址注册和登录的总控部署环境，无需使用普通账户密码；客户端能够获取可用 MAC 地址时才显示该选项 |
| 瘦客户端模式 | 切换为瘦客户端使用方式。首页会提供相应电源操作，并隐藏自主注册入口；系统电源功能取决于平台支持 |
| 隐藏设置 | 保存后隐藏首页的设置入口，适用于集中部署的终端 |
| 串口 | 保留的串口配置入口；无串口需求时留空，具体重定向能力需按所用协议及部署配置确认 |
如需恢复被隐藏的设置入口，先退出客户端，再将当前用户配置文件 ~/.lierfang/pxvdiconfig.json 中的 "hidesetting" 改为 false，保存后重新启动。在 Windows 上，~ 表示当前用户目录，例如 C:\Users\用户名。修改时保留文件中的其他配置及合法 JSON 格式。
2.2.3 RDP
此分区仅用于 RDP 连接。下拉选项中的自动（使用服务器设置）表示沿用服务器提供的对应参数；选择具体值后，使用本地选择的值。
| 设置项 | 可选值及用途 |
|---|---|
| 解码器 | 自动、AVC420（H.264）、AVC444（H.264）、RFX。需要远端及客户端支持所选模式，通常先保持自动 |
| 色深 | 自动、32、24、16、15 位。较高色深可提供更丰富的颜色 |
| 声音 | 自动、开启、关闭；控制远端声音在本地播放 |
| 麦克风 | 自动、开启、关闭；控制本地麦克风向远端重定向 |
| 桌面缩放 | 自动、100%、125%、150%、175%、200%；调整远端桌面中文字和控件的缩放比例 |
| 网络类型 | 自动、Modem、Broadband（low）、Broadband（high）、WAN、LAN；为 RDP 提供相应网络场景参数 |
| Admin 会话 | 请求以管理会话方式连接。仍需远端支持及相应账户权限，此开关不会授予管理员权限 |
2.2.4 PXVDI
| 设置项 | 说明 |
|---|---|
| PXVDI传输协议 | 可选 WebSocket 或 WebRTC，需与服务器能力及网络环境匹配 |
| 桌面缩放 | 使用内嵌 PXVDI 客户端时显示。可选“跟随本地显示缩放”或 100%、125%、150%、175%、200%，用于设置远端 DPI；与 RDP 的桌面缩放独立 |
| 使用中继 | 在“常规 → 外网模式”开启后显示。开启后强制使用 TURN 服务器中继连接；关闭后自动选择连接路径。需服务器提供相应能力 |
| 使用外部 SDL 客户端 | 开启后使用独立的 Pxvdistream SDL 客户端；关闭后，PXVDI 会话在应用内的独立窗口中打开 |
| 解码器 | 外部 SDL 客户端选项：auto、software、H.264、H.265。一般先使用自动，遇到兼容性问题时再调整 |
| 渲染器 | 外部 SDL 客户端选项：auto、OpenGL、SDL Canvas、Sink。一般保留自动；如需调整，按终端图形环境选择 |
| USB 自动重定向 | 建立会话时自动尝试重定向允许连接的 USB 设备，仍受服务器策略、设备支持及本机权限约束 |
码率和帧率统一在“常规 → 视频配置”中设置。 SDL 解码器及渲染器不会配置应用内的客户端；外部 SDL 客户端也不读取此处内嵌客户端的桌面缩放选项。开启自动重定向并不表示所有 USB 设备都可重定向。
2.2.5 Moonlight
| 设置项 | 说明 |
|---|---|
| 编码器 | 可选 auto、AV1、H.264、HEVC，需远端编码能力及本地解码能力支持 |
| 解码器 | 可选 auto、hardware（硬件）、software（软件） |
| 游戏优化 | 启用 Moonlight 的游戏优化选项 |
| 444色深 | 界面中的此选项对应 4:4:4 色度采样，可改善文字和彩色边缘的表现，需两端支持 |
| HDR | 启用 HDR 画面选项，需要服务器、客户端及显示设备共同支持 |
Moonlight 的码率和帧率同样在常规 → 视频配置中设置。没有特殊要求时，可先保持编解码器为 auto。
2.2.6 关于、隐私与许可
关于显示应用名称、版本号、开发商和联系邮箱，并提供以下操作：
- 导出日志：生成日志 ZIP 压缩包，并通过系统保存对话框选择保存位置。无需先开启调试模式；如需更详细的排障信息，可先开启调试模式并保存，复现问题后再导出。
- 版本更新：Windows 专用入口，用于查看和操作客户端更新。
- Sudo权限：macOS 专用入口，通过系统授权对话框以管理员权限启动客户端，供需要额外权限的场景使用，例如部分 USB 重定向操作。
提交故障信息时，建议同时说明客户端版本、操作系统、连接协议、发生时间和复现步骤，并附上导出的日志。
隐私和许可分别位于左侧独立分区。许可分区列出第三方组件名称、版本及许可证，可进一步查看完整许可文本。
2.3 云桌面列表
登录后，首页显示服务器分配的桌面。点击卡片主体即可按默认方式连接；卡片底部的连接类型菜单可手动选择本次使用的协议。
| 操作入口 | 用途 |
|---|---|
| 刷新列表 | 重新获取可用桌面及状态 |
| 卡片右上角星标 | 将桌面设为收藏，用于登录后自动连接；再次点击取消 |
| 连接类型 | 为本次连接选择服务器及本机支持的协议 |
| 电源 | 根据桌面状态及权限，提供启动、关机、强行关机、重启、强制重启或恢复等操作 |
| 快照 | 查看并按权限执行快照操作，例如回滚 |
| 右上角用户菜单 | 注销当前云桌面账户 |
电源和快照入口仅在桌面允许管理时显示；外部桌面和共享桌面池不提供这些操作。快照回滚会恢复到对应时间点的状态，操作前应确认当前工作已保存。
2.4 本地连接
首页右上角的本地连接用于切换到自行添加的远程桌面列表，无需先登录云桌面账户；切换后，可通过云桌面返回云桌面首页。
- 进入本地连接，点击添加。
- 选择 PXVDI 或 RDP，填写远程主机地址、用户名和密码；备注可选，用于识别桌面。
- 保存后，点击对应卡片建立连接；卡片底部可编辑或删除记录。
| 字段或操作 | 说明 |
|---|---|
| 连接类型 | 为此条记录选择 PXVDI 或 RDP，连接时使用卡片保存的协议 |
| 备注 | 可选。填写后作为卡片标题；未填写时以主机地址作为标题 |
| IP或域名 | 远程主机的 IP 地址或域名，与“设置 → 服务器”中的云桌面服务地址分别配置 |
| 用户名、密码 | 远程桌面的登录凭据，并非必须使用云桌面平台账户 |
| 保存、取消 | 保存此条连接记录，或取消本次添加；保存记录后需点击卡片才开始连接 |
| 编辑、删除 | 编辑已有记录，或删除本地保存的连接记录；删除记录不会删除远端桌面 |
本地连接使用每张卡片保存的协议和远程账户。Windows、macOS、Linux 桌面端的 RDP 地址可包含端口；PXVDI 使用默认端口 9923。直接访问 PXVDI 主机时，应保持常规 → 外网模式关闭，以免连接转向云桌面服务器。
2.5 PXVDI 内嵌客户端会话
在设置 → PXVDI中关闭使用外部 SDL 客户端，点击保存配置后，再通过云桌面卡片或本地连接卡片建立 PXVDI 连接，即可使用内嵌客户端。远程桌面在应用的独立会话窗口中打开，顶部悬浮工具栏提供会话控制。
2.5.1 顶部悬浮工具栏（状态栏）
工具栏收起时，点击顶部的三点手柄即可展开。未固定时，工具栏会在空闲后自动收起；需要持续显示时，可点击图钉固定。拖动右侧的六点手柄可调整工具栏的水平位置。
| 操作入口 | 用途 |
|---|---|
| 图钉 | 固定或取消固定工具栏，控制是否自动收起 |
| 全屏图标 | 进入或退出当前会话窗口的全屏模式 |
| 功能 | 打开 USB 重定向、文件管理、相对鼠标及显示参数菜单 |
| 发送按键 | 向远端发送 Ctrl + Alt + Del 或 Alt + F4；后者可关闭远端当前活动窗口 |
| 隐藏 | 完全隐藏工具栏及三点手柄，远程连接继续运行；按 Ctrl + Alt + Shift + S 再次显示 |
| 红色 × | 直接断开当前会话。请先保存远端工作；此操作不会向虚拟机发送关机指令 |
| 六点手柄 | 拖动工具栏，避免遮挡远端操作区域 |
2.5.2 功能菜单与显示参数
| 功能 | 说明 |
|---|---|
| USB 重定向 | 打开 USB 设备重定向界面，将支持的本地设备连接到远端。需要客户端原生组件、服务器策略及本机权限支持 |
| 文件管理 | 打开会话文件管理界面；启用文件传输服务时显示此入口 |
| 相对鼠标 | 切换鼠标相对移动模式，适用于游戏、三维视角等场景。需要本机支持，且会话允许输入；窗口失去焦点或连接结束时会释放鼠标捕获 |
| 分辨率 | 提供自动适应、高清显示及远端支持的分辨率列表。手动选择分辨率后停止随窗口自动调整；可重新启用自动适应 |
| 桌面缩放 | 调整远端文字和控件的 DPI 缩放。可跟随本地显示缩放，或选择 100%、125%、150%、175%、200%、250%、300%；远端支持独立 DPI 调整时显示 |
| 帧率 | 请求远端使用 30、60、90、120、144、165 或 240 FPS；远端支持动态帧率调整时显示，实际帧率受远端性能、解码能力及网络影响 |
| 码率 | 调整当前会话的视频目标码率，预设为 5、10、30、50、100 Mbps；菜单还可能显示远端已确认的当前码率 |
分辨率、高清显示和桌面缩放分别控制不同的显示效果：分辨率决定远端画面的像素尺寸；高清显示（HiDPI）使自动适应时的画面像素考虑本地显示密度；桌面缩放决定远端文字和控件的大小。修改桌面缩放不会同时修改分辨率或帧率。切换高清显示会重新启用自动适应。
打开分辨率菜单时，客户端会请求远端支持的模式；列表尚未返回或远端没有可选模式时，会显示相应提示。分辨率、帧率和码率的调整需要远端处理并确认，最终效果以远端返回的状态和实际画面为准。
工具栏中的帧率、码率调整仅作用于当前连接。如需设置后续连接的默认值，请修改设置 → 常规 → 视频配置并保存。
2.5.3 会话快捷键
在会话窗口获得键盘焦点时，可使用以下快捷键；macOS 上的 Alt 对应 Option 键。
| 快捷键 | 功能 |
|---|---|
Ctrl + Alt + Shift + S | 显示或隐藏本地会话工具栏 |
Ctrl + Alt + Shift + M | 切换相对鼠标模式，需要本机支持且会话允许输入 |
Ctrl + Alt + Shift + Q | 直接断开当前会话，与工具栏红色 × 的行为相同 |
需要向远端发送系统组合键时，建议使用发送按键菜单。上述三组快捷键由本地客户端处理。
3. Pxvdi-thin-client 嵌入式瘦客户端
Pxvdi-thin-client 面向资源受限的嵌入式终端，在 4.x 版本瘦客户端系统中作为默认客户端。部署和配置请参阅瘦客户端说明。
4. Pxvdistream SDL 客户端使用
Pxvdistream 是独立的 PXVDI SDL 客户端，支持硬件解码。可在设置 → PXVDI → 使用外部 SDL 客户端中启用，实际解码能力与性能取决于终端硬件和驱动。
单独下载请前往 Pxvdistream 下载目录。
| 快捷键 | 功能 |
|---|---|
Ctrl + Alt + Shift + Q | 强制关闭客户端 |
Ctrl + Alt + Shift + S | 显示或隐藏悬浮菜单 |
Ctrl + Alt + Shift + M | 切换相对鼠标模式，适用于 FPS 等需要持续捕获鼠标的场景 |
悬浮菜单
悬浮菜单提供 USB 重定向、文件管理和安全键盘等功能，具体可用项取决于会话及服务器配置。
安全键盘用于部分 UKey 重定向后需要物理按键事件的输入场景。它以物理按键事件方式向远端发送输入，能否使用仍取决于 UKey 及其软件要求。
5. Windows RDP 客户端使用
使用 Ctrl + Alt + Shift + S 显示或隐藏悬浮菜单，其余操作可按工具栏上的功能名称使用。RDP 的画面、音频及缩放偏好请在设置 → RDP中配置。