RustDesk 文档 · Server OSS
RustDesk Server OSS 自托管入门
RustDesk Server OSS 由 hbbs 与 hbbr 两个核心服务组成。hbbs 负责设备 ID、Rendezvous 与 Signaling,hbbr 负责无法直接建立连接时的 Relay 中继。本页从服务器、Docker Compose、端口和公钥开始,完成一套可以被 RustDesk 客户端使用的基础自托管环境。
RustDesk 自托管如何工作
hbbs 与 hbbr 分别负责什么
运行 RustDesk 的设备会向 hbbs 注册当前设备 ID、IP 和端口信息。当一台设备请求连接另一台设备时,hbbs 负责查找目标设备并协调双方建立连接。
- hbbs:RustDesk ID、Rendezvous 与 Signaling Server,负责设备注册、发现、NAT 类型测试和连接协调。
- hbbr:RustDesk Relay Server,在两端无法建立直接连接时转发远程会话。
- P2P:hbbs 会先尝试通过 NAT hole punching 让两端直接连接;穿透失败后才使用 hbbr。
这篇文档会完成什么
完成下面的配置后,RustDesk 客户端将使用你自己的 Server OSS 进行设备注册和连接协调,并在需要中继时使用自己的 hbbr。
- 准备一台运行 Docker 与 Docker Compose 的服务器。
- 启动 hbbs 和 hbbr,并持久化服务器数据。
- 开放 RustDesk Server OSS 需要的 TCP 与 UDP 端口。
- 取得 hbbs 生成的服务器公钥。
- 在客户端填写 ID Server 和 Key,并按需指定 Relay Server。
- 通过两台设备测试注册、直连和 Relay。
Server OSS 与 Server Pro 不要混用
本页针对免费的 RustDesk Server OSS。Web Console、OIDC、LDAP、2FA、设备管理和集中访问控制等属于 Server Pro,不是完成 OSS 自托管连接所必需的组件。
准备 RustDesk Server 主机
服务器至少需要能够运行 Docker 或 Podman,并且客户端能够通过网络访问该服务器。对多数 Linux 服务器,RustDesk 官方推荐使用 Docker Compose;在支持 host networking 的 Linux 环境中,network_mode: "host" 可以减少额外的端口映射配置。
先确认 Docker
确认 Docker 与 Docker Compose 已安装并可以正常运行:
docker --version docker compose version
开放必要端口
RustDesk Server 使用不同端口承担 NAT 测试、设备注册、连接协调和 Relay。基础桌面客户端至少需要保证以下核心端口可以访问:
21115/TCP:NAT 类型测试。21116/TCP:TCP hole punching 与连接服务。21116/UDP:设备 ID 注册与 heartbeat。21117/TCP:hbbr Relay 服务。
官方完整核心端口范围为 TCP 21114–21119 与 UDP 21116。其中 21118 与 21119 主要用于 Web Client 的 WebSocket 连接;如果不使用 Web Client,可以不开放这两个端口。21114 主要与 Server Pro API / Web Console 有关。
使用 Docker Compose 部署 hbbs 与 hbbr
RustDesk Server OSS 不是单独一个 Relay 容器。基础部署需要同时运行 hbbs 和 hbbr,并为服务器数据配置持久化目录。
创建 compose.yml
下面是适合 Linux host networking 环境的基础 Compose 结构:
services:
hbbs:
container_name: hbbs
image: rustdesk/rustdesk-server:latest
command: hbbs
volumes:
- ./data:/root
network_mode: "host"
depends_on:
- hbbr
restart: unless-stopped
hbbr:
container_name: hbbr
image: rustdesk/rustdesk-server:latest
command: hbbr
volumes:
- ./data:/root
network_mode: "host"
restart: unless-stopped
network_mode: "host" 主要适用于 Linux。其他 Docker 环境如果不支持或使用 host network 出现问题,需要移除该配置并按照实际环境显式映射所需端口。
启动 Server OSS
docker compose up -d
启动后可通过下面的命令检查两个容器是否正常运行:
docker compose ps docker logs hbbs docker logs hbbr
找到服务器公钥
hbbs 首次运行时会在数据目录生成服务器密钥。客户端连接自托管服务器时需要使用公钥文件 id_ed25519.pub 中的内容作为 Key。
cat ./data/id_ed25519.pub
这里的 Key 是 hbbs 的连接加密公钥,不是 Server Pro 的商业许可证密钥。
配置 RustDesk 客户端连接自托管服务器
先配置一台客户端测试
安装 RustDesk 客户端后,在主界面设备 ID 旁打开菜单,进入 设置 → 网络 → ID/Relay Server,解锁网络设置后填写自托管服务器参数。
- ID Server:必填,填写运行 hbbs 的域名或 IP,例如
hbbs.example.com或hbbs.example.com:21116。 - Key:必填,填写服务器生成的
id_ed25519.pub公钥。 - Relay Server:通常可以留空,由 RustDesk 自动推断;需要明确指定时填写 hbbr 的地址。
- API Server:Server Pro 功能使用,普通 Server OSS 部署不需要填写。
两端必须使用同一个自托管环境
发起连接的一端和被连接的一端都需要配置到相同的自托管 RustDesk Server。每台设备仍然拥有自己的 RustDesk ID,并不是多台设备共用同一个 ID。
少量设备与批量部署
少量客户端可以直接手动填写服务器信息,也可以从已经配置好的客户端导出 Server Config,再在其他客户端导入。大规模自动部署可以使用部署脚本或 --config 参数;Server Pro 还提供 Custom Client Generator,但它不属于 OSS 的基础配置流程。
测试连接与基础排查
确认设备已经注册到 hbbs
完成客户端配置后重新启动 RustDesk。客户端能够正常获得设备 ID,并且服务器日志能够看到对应注册活动,说明客户端已经能够访问 hbbs。
测试两台设备连接
在两台客户端上配置同一套 ID Server 与 Key,然后使用其中一台设备输入另一台设备的 RustDesk ID 发起连接。服务器会先协调双方尝试直接建立 P2P 连接;如果 NAT 穿透失败,连接会改由 hbbr 中继。
连接失败时先检查这些位置
- 两端客户端填写的 ID Server 是否指向同一个 hbbs。
- 两端使用的 Key 是否与服务器的
id_ed25519.pub一致。 - 防火墙和云安全组是否开放
21115/TCP、21116/TCP+UDP与21117/TCP。 hbbs与hbbr容器是否都在运行。- 服务器域名是否解析到正确的公网或内网地址。
- 客户端与服务器之间是否存在 NAT loopback、双重 NAT 或企业防火墙限制。
不要用“所有流量都经过自己的服务器”判断是否部署成功
RustDesk 的正常连接逻辑是优先尝试设备之间的直接连接。只有无法完成 NAT 穿透时,远程会话才经过 hbbr。因此,自托管的含义是使用自己控制的 ID 与 Relay 基础设施,并不是强制所有远程桌面流量都经过 Relay Server。
需要安装客户端时前往 RustDesk 下载页;遇到常见连接或权限问题可继续查看 常见问题。
rustdesk