本地部署

工作原理

HopToDesk 使用两种服务器。信令服务器帮助设备互相发现并建立会话。TURN 中继只在两台设备无法直接连接时才转发会话流量。

会话是端到端加密的，因此任何一台服务器都无法查看您的屏幕、文件或聊天内容。信令服务器只能看到设备 ID 和连接请求。

本页的安装程序负责部署信令服务器。中继流量默认经由 HopToDesk 中继，如果您提供了自己的 TURN 服务器，则经由它转发。

仪表板仍是托管服务。自托管网络中的设备仍可关联到仪表板进行管理，仪表板也可以把网络设置推送给它们。

开始之前

• 一台运行 Ubuntu 18.04 到 24.04 的服务器，或一台 Windows 服务器。
• 该服务器的 root 或 sudo 权限。
• 一个所有设备都能访问的 IP 地址或主机名。如果网络不会离开您的局域网，使用内网地址即可。
• 服务器防火墙上已为您的设备放行 TCP 80 端口。
• 如果您想使用自己的中继：TURN 服务器的主机、端口、用户名和密码。

第 1 步：在 Linux 上安装信令服务器

1. 以 root 或具有 sudo 权限的用户登录服务器。
2. 在本页顶部选择 LAN + Default Relay 或 Custom TURN Server。安装命令会随您的选择而变化。
3. 点击 Copy，把命令粘贴到终端并按回车。
4. 等待脚本运行完成。在全新的服务器上，安装软件包可能需要几分钟。
5. 脚本结束时会输出 HopSignal Setup Complete，随后是您的服务器地址和一段可直接使用的网络设置。请保留这段输出，第 3 步会用到。

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh

使用自己的 TURN 服务器时，按以下顺序把四个值追加到命令末尾：主机、端口、用户名、密码。

sh hsinstall.sh turn.example.com 443 myuser mypassword

脚本做了什么

• 使用 apt 安装所需的编译工具和 OpenSSL 库。
• 把信令服务器二进制文件下载到 /home/hopsignal 文件夹。
• 创建一个名为 hopsignal 的 systemd 服务，并在每次开机时启动它。
• 添加一个 cron 看门狗：服务停止响应时自动重启，日志超过 100 MB 时自动轮转。
• 当 ufw 启用时，在 ufw 中放行 TCP 80 端口。

Windows 上的第 1 步：运行信令服务器

1. 把本页顶部的 OS 开关切换到 Windows 并点击 Download。您会得到一个名为 hopsignal.exe 的文件。
2. 创建一个文件夹，例如 C:\hopsignal，并把 hopsignal.exe 移入其中。
3. 在同一文件夹中创建一个名为 fedlist.txt 的空文本文件。
4. Windows 版本还需要 PEM 格式的 TLS 证书及其私钥。任何一对都可以，包括自签名的。把它们以 cert.pem 和 key.pem 的名称保存在同一文件夹。
5. 以管理员身份打开命令提示符并启动服务器。

cd C:\hopsignal
hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT cert.pem --KEY key.pem --FEDLIST fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE hs.log

如果您有 OpenSSL，下面的命令可以生成一对自签名证书：

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 3650 -subj "/CN=hopsignal"

在 Windows 防火墙中放行该端口：

netsh advfirewall firewall add rule name="HopSignal" dir=in action=allow protocol=TCP localport=80

要让服务器在重启后继续运行，请把它注册为在开机时以 SYSTEM 账户启动的计划任务：

schtasks /Create /TN HopSignal /SC ONSTART /RU SYSTEM /TR "C:\hopsignal\hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT C:\hopsignal\cert.pem --KEY C:\hopsignal\key.pem --FEDLIST C:\hopsignal\fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE C:\hopsignal\hs.log"
schtasks /Run /TN HopSignal

第 2 步：确认服务器正在运行

在 Linux 上检查服务和日志：

sudo systemctl status hopsignal
tail /home/hopsignal/hs.log

在 Windows 上确认端口正在监听：

netstat -an | find ":80 "

在任意一台电脑上测试 WebSocket 端口。把 SERVER_IP 换成您的服务器地址。正常的服务器会回应 HTTP/1.1 101 Switching Protocols。

curl -i -N -m 5 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" http://SERVER_IP:80/

第 3 步：让设备指向该服务器

每台设备都从一个小的 JSON 文档读取网络设置。这就是安装程序在第 1 步结束时输出的那段内容。把 SERVER_IP 换成您的服务器地址；如果您运行自己的中继，请填写 TURN 部分。

{
  "turnservers": [
    {
      "protocol": "turn",
      "host": "turn.hoptodesk.com",
      "port": "443",
      "username": "hoptodesk",
      "password": "hoptodesk1234"
    }
  ],
  "rendezvous": {
    "host": "SERVER_IP",
    "port": "80"
  },
  "winversion": "1.0.0",
  "macversion": "1.0.0",
  "linuxversion": "1.0.0",
  "none": "none"
}

rendezvous 部分就是您的信令服务器。当通过 TLS 访问服务器时，例如 Cloudflare Worker 或 AWS 部署，请使用 rendezvousssl 键代替 rendezvous。turnservers 列表包含一个或多个中继。普通连接把协议设为 turn，TLS 连接设为 turn-tls。版本键保持原样即可。

把这份文档交给设备有三种方式。请选择适合您环境的一种。

方式 A：在每台设备上放置 api.json 文件

把该文档保存为名为 api.json 的文件，放到 HopToDesk 的配置文件夹中，然后重启 HopToDesk。应用会在启动时读取该文件，不再访问 HopToDesk API。

在 Linux 上，后台服务以 root 运行并读取 /root 下的文件，而您打开的应用读取您自己主目录中的文件。请在两处各放一份。

方式 B：把文件托管到一个 URL，并在应用中选择它

1. 把 api.json 上传到任意一台设备可访问的 Web 服务器。建议使用 HTTPS。
2. 在 HopToDesk 中点击齿轮图标打开设置。
3. 在 Network 下点击 Choose Network。
4. 选择 Custom Network Settings，粘贴您文件的 URL 并确认。
5. HopToDesk 会下载该文件，检查其中是否包含有效的 rendezvous 条目和 turnservers 列表，然后通过您的服务器重新连接。

要切回公共网络，再次打开 Choose Network 并选择 HopToDesk Network。

方式 C：从仪表板推送设置

如果您的设备已关联到 HopToDesk 仪表板，您可以为整个账户一次性设置网络。从仪表板生成的定制客户端会内置这些设置。

1. 以所有者或管理员身份登录仪表板并打开设置。
2. 在 Network Settings 下选择 Custom Network。
3. 输入信令服务器的主机、端口，协议选择 WS。如果您运行自己的中继，请添加 TURN 服务器；留空则继续使用 HopToDesk 中继。
4. 点击 Save Network Settings。每台已关联的设备都会收到新设置并自动应用，无需重新安装。

运行自己的 TURN 中继（可选）

无法直接连接的会话默认通过 HopToDesk 中继转发。要让所有流量都留在您自己的基础设施内，请运行一台 TURN 服务器。任何标准 TURN 服务器都可以，在 Linux 上 coturn 是常见的选择。

1. 在中继服务器上安装 coturn。

sudo apt install coturn

2. 编辑 /etc/turnserver.conf，至少设置下面这些值。把 realm、凭据和公网 IP 换成您自己的。

listening-port=443
fingerprint
lt-cred-mech
user=myuser:mypassword
realm=example.com
external-ip=PUBLIC_IP

3. 如果 /etc/default/coturn 中有 TURNSERVER_ENABLED 这一行，请取消注释。然后启用并启动服务。

sudo systemctl enable --now coturn
sudo systemctl restart coturn

4. 在中继的防火墙上放行监听端口的 TCP 和 UDP，以及 49152 到 65535 的 UDP 中继端口范围。
5. 把中继下发给设备：带上四个 TURN 值重新运行安装程序，或编辑网络设置中的 turnservers 部分。如果您的中继终止 TLS，协议请使用 turn-tls。

在 Linux 上管理服务器

sudo systemctl status hopsignal
sudo systemctl restart hopsignal
sudo systemctl stop hopsignal
tail -f /home/hopsignal/hs.log

要更新服务器，请先停止服务，再重新运行安装命令。它会下载最新的二进制文件并重写服务。

要连同服务和 cron 条目一起删除服务器：

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh remove

故障排除

• ID 一直停留在 Generating，或应用一直在尝试连接网络：设备无法访问信令服务器。请检查服务是否在运行、80 端口是否开放，以及网络设置中的地址是否正确。
• 设备在局域网内能连接但从外部无法连接：中继不可达。使用默认中继时，设备需要能通过 443 端口出站访问 turn.hoptodesk.com。使用自有中继时，请检查其防火墙规则和凭据。
• 应用忽略了 api.json：请确认文件是有效的 JSON 且没有多余的逗号，位于正确的文件夹中，并且您已重启 HopToDesk。文件被读取后，应用日志中会出现 Loaded local api.json 这一行。
• 82 端口是用于联合多台自有信令服务器的端口。请不要对互联网开放。
• 信令服务器不保存任何会话数据。如果看起来卡住了，重启服务即可。设备会在大约一分钟内自行重新连接。