配置H5 RDP网关

DoraCloud部署H5 RDP网关，支持浏览器访问云桌面

DoraCloud桌面云支持瘦客户机、客户端访问。有一些设备上无法安装客户端。DoraCloud新增了H5 RDP网关功能，可以通过支持HTML5的浏览器访问云桌面。

H5 RDP网关接受浏览器的连接请求，然后向云桌面发起RDP连接。用户在浏览器中操作云桌面。

采用浏览器访问云桌面的另一个好处是可以穿越防火墙，实现外网访问。

一、部署方式和要求

H5 RDP网关支持两种部署。

合并部署：DoraCloud管理系统和H5 RDP网关部署在一个Linux系统中。该方案适合少量用户使用浏览器登录的情况。

独立部署：H5 RDP网关独立部署在一个Linux系统中。该方案适合于大量用户通过浏览器登录的情况。

独立部署时，请准备一个Linux 虚拟机，安装RockyLinux 9.x系统。 H5 RDP网关的部署需要RockyLinux 9.x，如果使用Hyper-V平台的DoraCloud，由于Hyper-V平台的DoraCloud管理系统搭配的Linux版本比较老旧，不满足H5 RDP网关部署要求。需要准备一个运行RockyLinux 9.x的Linux虚拟机，独立部署H5 RDP网关。

密钥的作用

DoraCloud 和 H5 RDP 网关之间用一对 RSA 密钥保护连接信息（其中包含登录桌面的 RDP 账号和密码）：

  • 私钥保存在 H5 RDP 网关上：/home/jieyun/deskpool/h5RDP/config/h5RDP_rsa_private.pem
  • 公钥保存在 DoraCloud 上：配置文件 ~/jy/store.properties 的 h5.rdp.public.key

配置密钥的原则是：密钥对在私钥使用的地方生成，私钥永远不离开网关。 合并部署时由 DoraCloud 在本机生成；独立部署时在网关上生成（安装时自动完成），只把公钥交给 DoraCloud。不要下载、拷贝、通过邮件或聊天工具传递私钥。

网关管理工具 h5rdpctl

2026-09-28 及以后的 H5 RDP 网关自带管理工具 h5rdpctl，安装后可以在网关上直接运行。对接密钥、HTTPS 证书、服务启停和故障诊断都可以通过它完成，不需要手工执行 openssl、systemctl 等命令，详见第四节。

二、【合并部署】DoraCloud for PVE 上部署 H5 RDP网关

H5 RDP的安装包针对RockyLinux 9.x版本开发。Proxmox VE版本的 DoraCloud Linux VM使用的是RockyLinux 9.x，因此可以合并部署H5 RDP。

1、准备工作

DoraCloud for PVE 已经安装部署好。DoraCloud 版本推荐不低于 2025-10-15日。更早的版本可能不支持H5 RDP，或者不支持全部特性。

如果还没有部署DoraCloud for PVE，可以通过如下在线命令安装DoraCloud的最新版本。

cd /var/lib/vz/dump; wget -qO- https://dl.doracloud.cn/dpinstall.pl --referer https://doracloud.cn | perl

2、安装H5 RDP网关并配置密钥（2026-09-28 及以后的版本）

进入DoraCloud后台，打开【系统】【H5 RDP】页面：

  1. 在「部署与地址」中，部署方式选择 本机网关，访问地址填写 https://<DoraCloud地址>:16660，点击【设置】保存。 比如 DoraCloud 地址为 192.168.1.179，访问地址填写 https://192.168.1.179:16660。
  2. 页面顶部「网关状态」显示「尚未安装」时，点击【安装】。安装需要联网，大约 3 分钟。安装过程中会自动生成密钥对：私钥写入网关目录，公钥保存到 DoraCloud，不需要手工处理。
  3. 安装完成后，「网关状态」的三张状态卡（h5-rdp 服务、guacd 服务、管理接口）都应显示为绿色。「密钥」区显示私钥「已配置」和公钥指纹。

安装失败时，点击【安装日志】查看原因。以后如需更换密钥，在「密钥」区点击【重新生成密钥】即可，正在进行的 H5 RDP 会话会断开。

3、用命令行安装和配置（早期版本）

早期版本的 DoraCloud 后台没有【安装】按钮，可以用命令行安装。进入 DoraCloud Linux 系统，执行安装命令，需要联网安装一些库。

curl -fsSL https://dl.doracloud.cn/h5install.sh | bash

安装脚本会先校验下载文件的完整性（SHA256），校验不通过不会安装。安装完成后会自动生成网关的密钥对和 HTTPS 证书，并启动服务。以下是执行结果（有删节）：

[root@vdimgr ~]# curl -fsSL https://dl.doracloud.cn/h5install.sh | bash
H5RDP 在线安装（h5install.sh v2，2026-09-28 21:46:10，vdimgr）

[1/6] 检查运行环境
[2/6] 创建工作目录
[3/6] 下载安装包
[4/6] 校验 SHA256
  OK      h5RDP.tar.gz
  OK      makeH5RDP.sh
  OK      build-info.txt
[5/6] 检查安装包
[6/6] 执行 makeH5RDP.sh
正在安装 tar ...
正在更新epel-release，可能会比较耗时 ...
正在安装 Guacd ...
 Guacd 安装完成 ...
配置防火墙 ...
...
== 2/4 对接密钥 ==
[完成] 已生成新的密钥对
...
== 公钥指纹 ==
SHA256:8AW6r4Gc0U9n2D4tF5Vi87t8WBspS1eI3M6U6xbVZ3w
...
== 3/4 HTTPS 证书 ==
[完成] 已生成自签名证书（CN=192.168.1.179，有效期 10 年）
...
== 4/4 启动服务 ==
[完成] 服务已就绪，版本 2025-12-19 18:00

== 配置完成 ==
 访问地址 : https://192.168.1.179:16660
 公钥指纹 : SHA256:8AW6r4Gc0U9n2D4tF5Vi87t8WBspS1eI3M6U6xbVZ3w
...
部署完成
H5RDP 安装完成。查看状态：h5rdpctl status

安装失败时，脚本会打印失败的步骤和原因，并以非 0 返回码退出。常见原因是网络不通或软件源不可用，处理后重新执行安装命令即可。

离线安装的方法如下：把下面 4 个文件下载到同一个目录，上传到 DoraCloud Linux 系统，在该目录执行安装命令。

#下载地址（4 个文件必须同一批下载）：
#  https://dl.doracloud.cn/h5rdp/h5RDP.tar.gz
#  https://dl.doracloud.cn/h5rdp/makeH5RDP.sh
#  https://dl.doracloud.cn/h5rdp/build-info.txt
#  https://dl.doracloud.cn/h5rdp/SHA256SUMS

sha256sum -c SHA256SUMS && bash makeH5RDP.sh

注意，离线安装时仍需要能访问 RockyLinux 和 EPEL 软件源（安装 guacd 和 JDK），否则请根据提示先准备好依赖包。

安装时网关已经生成了密钥对，接下来把网关的公钥写入 DoraCloud 的配置文件，然后重启：

#公钥写入 ~/jy/store.properties 的 h5.rdp.public.key
NEW_KEY=$(grep -v -e '-----' /home/jieyun/deskpool/h5RDP/config/h5RDP_rsa_public.pem | tr -d '\n\r') && \
(grep -q "^h5.rdp.public.key=" ~/jy/store.properties && \
 sed -i "s#^h5.rdp.public.key=.*#h5.rdp.public.key=$NEW_KEY#" ~/jy/store.properties || \
 echo "h5.rdp.public.key=$NEW_KEY" >> ~/jy/store.properties) && \
chmod 600 ~/jy/store.properties && \
echo "配置完成..."
reboot

DoraCloud Linux VM重启后，进入DoraCloud后台，在【系统】【H5 RDP】页面设置 H5 RDP 地址。由于是合并部署，H5 RDP的地址就是 DoraCloud 管理系统地址，端口为 16660。比如 DoraCloud 地址为 192.168.1.179，那么 H5 RDP的地址填写 https://192.168.1.179:16660。

三、【独立部署】独立部署 H5 RDP网关

独立部署 H5 RDP网关适用于大量用户需要使用 H5 RDP客户端的场景，需要单独部署一个运行 RockyLinux 9.x的虚拟机。

1、部署 RockyLinux 9.x的主机，作为H5 RDP网关服务器

部署方法不详细描述。可以在物理机、虚拟机上安装 RockyLinux 9.x（推荐最小安装）。网关需要固定 IP 地址，并且系统时间要准确（建议开启 chronyd 时间同步）。

2、安装 H5 RDP 网关程序

以 root 登录网关，执行在线安装命令：

curl -fsSL https://dl.doracloud.cn/h5install.sh | bash

离线安装的方法与第二节相同：下载 4 个文件到同一目录，执行 sha256sum -c SHA256SUMS && bash makeH5RDP.sh。

安装过程会自动完成以下配置：

  • 生成对接用的密钥对：私钥只保存在网关上；
  • 生成自签名 HTTPS 证书，证书中包含网关的 IP 地址；
  • 启动 guacd 和 h5-rdp 服务，并放行防火墙端口 16660。

安装完成后，屏幕上会显示公钥、公钥指纹和访问地址，下一步要用到。

如果直接在网关的终端里执行 bash makeH5RDP.sh，安装完成后会进入交互式配置向导：可以选择导入正式证书，并在显示公钥后暂停，等你把公钥粘贴到 DoraCloud 后再继续。

3、查看网关的公钥

以后随时可以在网关上执行下面的命令，再次查看公钥和指纹：

h5rdpctl key show

输出中，“复制下面一行”之下的单行内容就是公钥（使用 PEM 格式的多行内容也可以），最后是公钥指纹，用于下一步核对。

私钥只保存在网关上，不需要、也不应该拷贝到其他机器。

4、在DoraCloud后台配置网关地址和公钥

进入DoraCloud后台，打开【系统】【H5 RDP】页面：

  1. 在「部署与地址」中，部署方式选择 外部网关，访问地址填写 https://<H5 RDP网关地址>:16660，点击【设置】保存。
  2. 在「密钥」区点击【粘贴网关公钥】，粘贴上一步显示的公钥内容，点击【确定】。
  3. 核对「密钥」区显示的公钥指纹，应与网关上 h5rdpctl key show 显示的指纹一致。
  4. 页面顶部「网关状态」的「管理接口」卡片应显示「正常」。如果显示「公钥不匹配」，说明粘贴的公钥与网关上的私钥不是同一对，请重新执行第 3 步和第 4 步。

如果是在外网通过浏览器访问云桌面，需要把 H5 RDP的端口映射到防火墙的外网端口上，然后把H5 RDP外网的域名和端口填写在访问地址中。比如：外网域名 abc.com，在防火墙上把外网 16660 映射到局域网 192.168.1.179 的 16660，那么访问地址应该填写 https://abc.com:16660。使用域名访问时，建议为该域名配置正式证书（见第四节）。

如果 DoraCloud 访问网关的地址与用户浏览器使用的地址不同（例如访问地址是外网域名，而 DoraCloud 在内网），在「高级：管理 API 地址」中填写 DoraCloud 访问网关用的内网地址，例如 https://192.168.1.179:16660。

早期版本的 DoraCloud 后台没有【粘贴网关公钥】，可以在【上传】中粘贴公钥。不要使用早期版本的【创建】按钮为独立部署的网关生成密钥，它会把私钥下载到浏览器。

四、用 h5rdpctl 管理网关

以 root 登录网关，执行 h5rdpctl，会显示网关状态和菜单，按数字选择即可：

==================== H5RDP 网关管理 ====================
 服务   : ✔ 运行中 (pid 1129, 开机自启: 已开启)  端口 16660 ✔
 guacd  : ✔ 运行中 127.0.0.1:4822
 密钥   : ✔ 已配置  SHA256:8AW6r4Gc0U9n2D4tF5Vi87t8WBspS1eI3M6U6xbVZ3w
 证书   : ✔ 自签名  192.168.1.179  剩余 3649 天
 版本   : 2025-12-19 18:00
 地址   : https://192.168.1.179:16660
========================================================
 1) 对接密钥（DoraCloud）
 2) SSL 证书
 3) 服务管理
 4) 故障诊断
 5) 首次配置向导
 0) 退出

有问题的项目会标为 ✘ 或 !，后面会给出处理提示。

常用操作也可以直接用命令完成：

操作 命令
查看状态 h5rdpctl status
故障诊断（逐项检查并给出修复建议） h5rdpctl doctor
查看公钥和指纹 h5rdpctl key show
重新生成密钥对（之后需要把新公钥粘贴到 DoraCloud） h5rdpctl key gen
查看当前证书 h5rdpctl cert show
重新生成自签名证书（网关 IP 变更后使用） h5rdpctl cert self-signed
启动 / 停止 / 重启服务 h5rdpctl start、h5rdpctl stop、h5rdpctl restart
查看日志 h5rdpctl logs；实时跟踪用 h5rdpctl logs -f
全部命令 h5rdpctl help

更换为正式证书

网关默认使用自签名证书，用户浏览器会提示不安全。使用域名访问时，建议更换为受信任的证书。把证书文件上传到网关，然后执行下面其中一条命令：

#PEM 格式：证书文件（可以是含证书链的 fullchain）+ 私钥文件
h5rdpctl cert import --cert /root/rdp.example.com.crt --key /root/rdp.example.com.key

#证书链单独一个文件时
h5rdpctl cert import --cert /root/server.crt --key /root/server.key --chain /root/ca-chain.crt

#PFX / P12 格式（执行后输入 PFX 密码）
h5rdpctl cert import-pfx /root/rdp.example.com.pfx

导入前会检查证书与私钥是否匹配、证书是否过期、证书链是否完整；导入后自动重启服务并检查是否正常。如果新证书导致服务无法启动，会自动恢复原来的证书。

DoraCloud 后台填写的 H5 RDP 访问地址，必须是证书中包含的域名，否则浏览器仍会提示证书错误。

使用 h5rdpctl 配置证书后，证书参数保存在 config/h5rdp-ssl.env 中。这时再手工修改 application-prod.yml 中的 server.ssl 配置不会生效，请始终用 h5rdpctl 更换证书。

五、安全建议

  • 私钥不离开网关：按上面的步骤在网关上生成密钥对。不要下载私钥，不要用 scp、U 盘、邮件或聊天工具传递私钥。
  • 公钥也要保密：DoraCloud 用公钥加密发给网关的连接信息，网关只校验能否用私钥解密。拿到公钥的人可以向网关发送请求，因此不要把公钥贴到工单、聊天记录或文档中。DoraCloud 后台只显示公钥指纹。
  • 文件权限：网关私钥 h5RDP_rsa_private.pem 和 DoraCloud 的 ~/jy/store.properties 都应为 600（只有 root 可读写）。h5rdpctl key check 会检查网关私钥的权限。
  • 每套部署一对密钥：不同客户、不同环境不要共用同一对密钥。
  • 定期或按需更换：怀疑密钥泄露、人员变动时，重新生成密钥对（合并部署点击【重新生成密钥】；独立部署在网关上执行 h5rdpctl key gen，再重复第三节第 4 步）。
  • 外网映射时限制来源：把 16660 映射到外网时，网关的管理接口也会暴露在外网。建议在防火墙上尽量限制访问来源，并定期检查网关日志。
  • 证书：每台网关安装时都会生成自己的自签名证书。旧版本安装包附带的是所有网关共用的证书，其私钥是公开的；h5rdpctl 检测到这种证书时会提示更换，执行 h5rdpctl cert self-signed 即可。正式使用建议更换为受信任的证书（见第四节）。

六、测试浏览器访问

1、测试用户登录

以用户账号登录DoraCloud云桌面系统。

在下拉菜单中，选择 H5 RDP Client，即可打开一个新的浏览器页面，登录到桌面。

1754558102779

H5 RDP 客户端登录桌面时，需要使用桌面虚拟机的RDP账号。

DoraCloud对于虚拟机的RDP账号按照如下逻辑获取：

1、启用AD认证时，以AD账号（用户名、密码）向桌面发起RDP连接。

2、启用本地用户数据库时，H5 RDP Client取绑定账号向桌面发起RDP连接。

3、启用本地用户数据库时，如果未配置绑定账号，H5 RDP Client可能由于缺少正确的账号，无法连接。

2、测试管理员登录

以管理员账号登录DoraCloud管理后台。

在桌面计算机菜单中，选择【操作】【HTML5 RDP Client】。即可登录桌面。

1754559012659

管理员通过HTML5 RDP Client连接桌面时，DoraCloud取桌面对应模板的默认账号登录桌面。

如果用户修改了绑定账号，则无法登录桌面。在启用AD认证时，桌面用户是通过AD账号登录桌面的。管理员是以桌面的默认本地账号登录桌面的。

3、连接失败时的排查

先在网关上执行 h5rdpctl doctor，它会逐项检查 Java、guacd、服务、端口、防火墙、密钥、证书、网关接口和时间同步，并对每个问题给出处理命令。

再在DoraCloud后台【系统】【H5 RDP】页面查看「网关状态」：

  • h5-rdp 服务 或 guacd 服务 显示已停止：本机网关点击【启动】或【重启】；独立部署到网关上执行 systemctl restart guacd（guacd 停止时）和 h5rdpctl restart（h5-rdp 停止时），启动失败的原因用 h5rdpctl logs 查看。
  • 管理接口 显示「连接被拒绝」「连接超时」「地址无法解析」：检查访问地址、端口和防火墙。
  • 管理接口 显示「公钥不匹配」：DoraCloud 保存的公钥与网关私钥不是同一对，按第二节或第三节重新配置密钥。
  • 「当前会话」显示「管理接口不可用」：先按上面的提示恢复管理接口。
  • 用户打开 H5 链接时提示「Url链接超时了」：网关和 DoraCloud 的系统时间不一致，或者链接打开得太晚（默认有效期 2 分钟）。请开启两边的时间同步（h5rdpctl doctor 会检查网关一侧）。
  • 浏览器提示证书错误：网关 IP 变更后，自签名证书中的 IP 与实际不符，执行 h5rdpctl cert self-signed 重新生成；使用域名访问时，请导入该域名的正式证书。