RustDesk Server 自托管部署完全指南:从源码构建、Docker 镜像到密钥管理与环境变量配置
RustDesk Server 自托管部署完全指南:从源码构建、Docker 镜像到密钥管理与环境变量配置
本指南以仓库根目录的 README.md 为主线,系统讲解 RustDesk 自托管服务器的三种主流落地方式——源码手动构建、经典 Docker 镜像与基于 S6-overlay 的超级镜像,并结合
hbbs(ID/会合服务器)、hbbr(中继服务器)与rustdesk-utils(命令行工具)的真实源码实现,深入解析密钥对生成、密钥管理、端口规划与环境变量配置。读完本文,你将能够独立完成一套生产可用的 RustDesk 自托管服务器搭建,并掌握故障排查与调优的基本手段。
RustDesk Server 是 RustDesk 远程桌面方案的服务端程序,完全免费且开源,允许任何人自行搭建属于自己的中继与信令基础设施,从而不依赖公共服务器。仓库编译产物包含三个可执行程序:hbbs(RustDesk ID/会合服务器,负责客户端身份注册与 NAT 穿透打洞)、hbbr(RustDesk 中继服务器,负责流量转发)以及 rustdesk-utils(RustDesk 命令行工具)。下文所有路径均以仓库根目录为基准。
如何自行构建(源码手动编译)
构建 RustDesk Server 只需要一个命令:
cargo build --release
执行后会在 target/release 目录下生成三个对应平台的可执行程序:
- hbbs —— RustDesk ID/会合服务器(Rendezvous Server),负责客户端 ID 注册、在线状态维护与 NAT 穿透协调;
- hbbr —— RustDesk 中继服务器(Relay Server),负责在两台设备无法直连时代为转发音视频与控制数据流;
- rustdesk-utils —— RustDesk 命令行工具,提供密钥对生成、密钥对校验与服务器连通性诊断等实用功能。
如果需要最新的官方预编译二进制,可以从仓库 Release 页面获取;如果希望获得更丰富的管理功能,可以评估 RustDesk Server Pro;如果目标是自己二次开发一套服务端,rustdesk-server-demo 是比本仓库更轻量的起点(本文不展开)。
三个可执行程序的分工与源码对应关系
从源码结构看,三个程序对应仓库中的不同入口:
hbbs的入口在 src/main.rs,它解析命令行参数后调用RendezvousServer::start()启动会合服务,相关逻辑见 src/rendezvous_server.rs;hbbr的入口在 src/hbbr.rs,解析参数后调用relay_server::start()启动中继服务,相关逻辑见 src/relay_server.rs;rustdesk-utils的完整实现位于 src/utils.rs,支持genkeypair、validatekeypair、doctor三个子命令。
三者共用 src/common.rs 中的参数初始化、.env 文件加载与密钥读取逻辑。
Docker 镜像
Docker 镜像会在每次 GitHub 发布新 Release 时自动构建并推送到 Docker Hub 与 GitHub Container Registry。仓库共提供两种镜像:Classic 传统镜像与基于 S6-overlay 的镜像。
提示:在中国大陆使用
rustdesk/rustdesk-server:latest时,建议将其替换为 Docker Hub 上的具体版本号(如rustdesk-server:1.1.10-3),否则可能因镜像加速机制拉到旧版本。若从 Docker Hub 拉取遇到问题,可改用 GitHub Container Registry 拉取。
Classic 传统镜像
经典镜像基于 busybox 构建(对应仓库 docker-classic/Dockerfile),仅包含 hbbs 和 hbbr 两个可执行程序,支持以下架构:
- amd64
- arm64v8
- armv7
镜像 tag 规则如下:
| 版本 | image:tag |
|---|---|
| latest | rustdesk/rustdesk-server:latest |
| 主版本 | rustdesk/rustdesk-server:1 |
使用 --net=host 直接启动
docker run --name hbbs --net=host -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbs -r <relay-server-ip[:port]>
docker run --name hbbr --net=host -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbr
使用 --net=host 时容器直接共享宿主机网络栈,UDP 穿透打洞相关端口无需手工映射,P2P 直连可以正常工作。如果不使用 --net=host,P2P 直连将无法工作。
对于使用 SELinux 的系统,需要把 /root 替换为 /root:z 才能让容器正常运行;也可以添加参数 --security-opt label=disable 完全禁用 SELinux 容器隔离。
使用端口映射启动(无 host 网络)
docker run --name hbbs -p 21115:21115 -p 21116:21116 -p 21116:21116/udp -p 21118:21118 -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbs -r <relay-server-ip[:port]>
docker run --name hbbr -p 21117:21117 -p 21119:21119 -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbr
这里 relay-server-ip 参数是运行这些容器的服务器的 IP 地址(或 DNS 名称)。可选的 port 参数只在 hbbr 使用非 21117 端口时需要指定,此时需要把实际的中继端口一起告诉 hbbs。
使用 docker-compose 编排
仓库根目录自带的 docker-compose.yml 就是可直接使用的模板,与 README 中的示例一致:
version: '3'
networks:
rustdesk-net:
external: false
services:
hbbs:
container_name: hbbs
ports:
- 21115:21115
- 21116:21116
- 21116:21116/udp
- 21118:21118
image: rustdesk/rustdesk-server:latest
command: hbbs -r rustdesk.example.com:21117
volumes:
- ./data:/root
networks:
- rustdesk-net
depends_on:
- hbbr
restart: unless-stopped
hbbr:
container_name: hbbr
ports:
- 21117:21117
- 21119:21119
image: rustdesk/rustdesk-server:latest
command: hbbr
volumes:
- ./data:/root
networks:
- rustdesk-net
restart: unless-stopped
需要修改的关键位置是 hbbs 的 command 行,把 rustdesk.example.com:21117 指向你的中继服务器(即监听 21117 端口的那台机器);volumes 挂载目录(第 18 行与第 33 行)也可以按需调整。注意 hbbs 通过 depends_on: hbbr 保证中继服务先启动。
基于 S6-overlay 的镜像
这类镜像基于 busybox:stable 构建(见 docker/Dockerfile),在加入 hbbs、hbbr 两个二进制的同时集成了 S6-overlay 进程监督器,支持以下架构:
- amd64
- i386
- arm64v8
- armv7
tag 规则:
| 版本 | image:tag |
|---|---|
| latest | rustdesk/rustdesk-server-s6:latest |
| 主版本 | rustdesk/rustdesk-server-s6:1 |
S6-overlay 在这里充当监督器(supervisor),保证 hbbs 与 hbbr 两个进程同时在容器内运行,因此使用这类镜像时不需要像经典镜像那样分别启动两个容器。
单容器启动
使用 --net=host 启动:
docker run --name rustdesk-server \
--net=host \
-e "RELAY=rustdeskrelay.example.com" \
-e "ENCRYPTED_ONLY=1" \
-v "$PWD/data:/data" -d rustdesk/rustdesk-server-s6:latest
不使用 --net=host 时,需要显式映射全部端口(P2P 直连将无法工作):
docker run --name rustdesk-server \
-p 21115:21115 -p 21116:21116 -p 21116:21116/udp \
-p 21117:21117 -p 21118:21118 -p 21119:21119 \
-e "RELAY=rustdeskrelay.example.com" \
-e "ENCRYPTED_ONLY=1" \
-v "$PWD/data:/data" -d rustdesk/rustdesk-server-s6:latest
docker-compose 方式:
version: '3'
services:
rustdesk-server:
container_name: rustdesk-server
ports:
- 21115:21115
- 21116:21116
- 21116:21116/udp
- 21117:21117
- 21118:21118
- 21119:21119
image: rustdesk/rustdesk-server-s6:latest
environment:
- "RELAY=rustdesk.example.com:21117"
- "ENCRYPTED_ONLY=1"
volumes:
- ./data:/data
restart: unless-stopped
S6 镜像专属环境变量
除了下文通用 ENV 环境变量表中的变量之外,S6-overlay 镜像额外支持以下变量:
| 变量 | 是否可选 | 描述 |
|---|---|---|
| RELAY | 否 | 运行此容器的宿主机 IP 地址 / DNS 名称 |
| ENCRYPTED_ONLY | 是 | 若设置为 "1",将不接受未加密的连接 |
| KEY_PUB | 是 | 密钥对中的公钥(Public Key) |
| KEY_PRIV | 是 | 密钥对中的私钥(Private Key) |
从源码看,这些变量的实际作用链路非常清晰:
ENCRYPTED_ONLY=1时,hbbs/run 与 hbbr/run 两个启动脚本会追加参数-k _,表示"强制使用任意密钥",即拒绝未加密的明文连接;RELAY会被拼进hbbs的启动命令/usr/bin/hbbs -r $RELAY $PARAMS;- 两个服务进程由 S6-overlay 统一托管,容器健康检查脚本 healthcheck.sh 通过
s6-svstat同时检查hbbr与hbbs两个服务目录的运行状态。
S6 镜像中的密钥管理(Secret Management)
密钥对可以保存在 Docker volume 中,但最佳实践是不要把密钥明文写在文件系统上,因此镜像提供了两种注入方式。
容器启动时(见 key-secret/up.real)的完整校验流程如下:
- 检查密钥对是否存在(
/data/id_ed25519.pub与/data/id_ed25519); - 若其中一个密钥缺失,则从 Docker Secrets 或环境变量(
KEY_PUB/KEY_PRIV)重建缺失的那个; - 校验密钥对有效性:如果公钥与私钥不匹配,容器将停止(调用
halt退出); - 若两个密钥都不提供,则由
hbbs在默认位置自动生成一个。
同时该脚本还会对密钥文件执行 chmod 0600 并设置属主为 root:root,并通过 /usr/bin/rustdesk-utils validatekeypair 验证公钥私钥是否成对。
方式一:使用环境变量(ENV)存储密钥对
docker run --name rustdesk-server \
--net=host \
-e "RELAY=rustdeskrelay.example.com" \
-e "ENCRYPTED_ONLY=1" \
-e "DB_URL=/db/db_v2.sqlite3" \
-e "KEY_PRIV=FR2j78IxfwJNR+HjLluQ2Nh7eEryEeIZCwiQDPVe+PaITKyShphHAsPLn7So0OqRs92nGvSRdFJnE2MSyrKTIQ==" \
-e "KEY_PUB=iEyskoaYRwLDy5+0qNDqkbPdpxr0kXRSZxNjEsqykyE=" \
-v "$PWD/db:/db" -d rustdesk/rustdesk-server-s6:latest
对应 docker-compose 写法:
version: '3'
services:
rustdesk-server:
container_name: rustdesk-server
ports:
- 21115:21115
- 21116:21116
- 21116:21116/udp
- 21117:21117
- 21118:21118
- 21119:21119
image: rustdesk/rustdesk-server-s6:latest
environment:
- "RELAY=rustdesk.example.com:21117"
- "ENCRYPTED_ONLY=1"
- "DB_URL=/db/db_v2.sqlite3"
- "KEY_PRIV=FR2j78IxfwJNR+HjLluQ2Nh7eEryEeIZCwiQDPVe+PaITKyShphHAsPLn7So0OqRs92nGvSRdFJnE2MSyrKTIQ=="
- "KEY_PUB=iEyskoaYRwLDy5+0qNDqkbPdpxr0kXRSZxNjEsqykyE="
volumes:
- ./db:/db
restart: unless-stopped
方式二:使用 Docker Secrets 存储密钥对
如果你使用 docker-compose 或 Docker Swarm,推荐用 Docker Secrets 保存密钥:
cat secrets/id_ed25519.pub | docker secret create key_pub -
cat secrets/id_ed25519 | docker secret create key_priv -
docker service create --name rustdesk-server \
--secret key_priv --secret key_pub \
--net=host \
-e "RELAY=rustdeskrelay.example.com" \
-e "ENCRYPTED_ONLY=1" \
-e "DB_URL=/db/db_v2.sqlite3" \
--mount "type=bind,source=$PWD/db,destination=/db" \
rustdesk/rustdesk-server-s6:latest
docker-compose 中挂载 Secrets 的写法:
version: '3'
services:
rustdesk-server:
container_name: rustdesk-server
ports:
- 21115:21115
- 21116:21116
- 21116:21116/udp
- 21117:21117
- 21118:21118
- 21119:21119
image: rustdesk/rustdesk-server-s6:latest
environment:
- "RELAY=rustdesk.example.com:21117"
- "ENCRYPTED_ONLY=1"
- "DB_URL=/db/db_v2.sqlite3"
volumes:
- ./db:/db
restart: unless-stopped
secrets:
- key_pub
- key_priv
secrets:
key_pub:
file: secrets/id_ed25519.pub
key_priv:
file: secrets/id_ed25519
如何生成密钥对
加密需要一对密钥。hbbs 会在启动时读取当前目录下的 id_ed25519 私钥文件,若不存在则自动生成一对新密钥并写入 id_ed25519 与 id_ed25519.pub(对应 src/common.rs 中 gen_sk() 的实现;密钥生成会循环重试,直到公钥中不包含 / 与 : 字符,以避免后续参数解析歧义)。但如果你希望自己掌控密钥,可以使用 rustdesk-utils 生成:
/usr/bin/rustdesk-utils genkeypair
如果系统上没有安装 rustdesk-utils 包,也可以用 Docker 调用同一个命令:
docker run --rm --entrypoint /usr/bin/rustdesk-utils rustdesk/rustdesk-server-s6:latest genkeypair
输出类似如下:
Public Key: 8BLLhtzUBU/XKAH4mep3p+IX4DSApe7qbAwNH9nv4yA=
Secret Key: egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hfgNICl7upsDA0f2e/jIA==
rustdesk-utils 的三个子命令(源码级说明)
src/utils.rs 是 rustdesk-utils 的完整实现,除 README 中重点介绍的 genkeypair 外,还包含两个对排障极其有用的命令:
| 命令 | 用法 | 作用 |
|---|---|---|
genkeypair |
rustdesk-utils genkeypair |
生成一对新的 Ed25519 签名密钥,输出公钥与私钥的 Base64 编码 |
validatekeypair |
rustdesk-utils validatekeypair <公钥> <私钥> |
校验给定的公钥/私钥是否构成有效密钥对(内部用私钥签名一段测试数据再用公钥验签) |
doctor |
rustdesk-utils doctor <rustdesk-server> |
对服务器进行连通性诊断 |
doctor 子命令的排查逻辑非常实用:它先对服务器地址做 DNS 解析,列出解析到的全部 IP;然后对每个 IP 依次发起 TCP 连接测试,覆盖以下端口并打印耗时或错误:
21114—— API 端口21115—— hbbs 额外端口(NAT 测试用)21116—— hbbs 主端口21117—— hbbr TCP 端口21118—— hbbs WebSocket 端口21119—— hbbr WebSocket 端口
同时还会检查目标 IP 是 IPv4 还是 IPv6,并做反向 DNS 解析,与传入的服务器域名对比是否匹配。S6 镜像的密钥校验脚本正是复用了 validatekeypair 命令来完成容器启动时的密钥一致性检查。
.deb 套件
仓库为每个可执行文件都提供了独立的 .deb 包,可在 Release 页面下载,适用于以下发行版:
- Ubuntu 24.04 LTS
- Ubuntu 22.04 LTS
- Ubuntu 20.04 LTS
- Ubuntu 18.04 LTS
- Debian 12 bookworm
- Debian 11 bullseye
- Debian 10 buster
从 debian/control.tpl 可以看出包分为三个:
rustdesk-server-hbbs—— 包含hbbs主程序(依赖 systemd);rustdesk-server-hbbr—— 包含中继服务器hbbr(依赖 systemd);rustdesk-server-utils—— 包含rustdesk-utils命令行工具。
仓库的 debian/ 目录下还有对应的 .install、.postinst、.postrm、.prerm 脚本,用于处理安装、卸载时的服务启停。装好 .deb 包后,系统会注册 systemd 服务:示例单元文件 systemd/rustdesk-hbbs.service 将 hbbs 以 Type=simple 方式运行,工作目录为 /var/lib/rustdesk-server/,设置了 LimitNOFILE=1000000 并配置了崩溃自动重启(Restart=always、RestartSec=10),日志追加写入 /var/log/rustdesk-server/hbbs.log。仓库 rcd/ 目录还提供了 rustdesk-hbbs 与 rustdesk-hbbr 的 OpenRC 脚本,供非 systemd 发行版使用。
ENV 环境变量
hbbs 与 hbbr 均可以通过环境变量进行配置。你可以像平常一样直接指定变量,也可以使用 .env 文件——从 src/common.rs 的 init_args() 实现看,程序启动时会优先加载当前目录下的 .env 文件,把其中的键值写入环境变量(键名会被转为大写并以下划线替换连字符),因此命令行参数与环境变量是等效的配置入口。
| 变量 | 可执行文件 | 描述 |
|---|---|---|
| ALWAYS_USE_RELAY | hbbs | 若设置为 "Y",将禁用点对点直连,强制所有流量走中继 |
| DB_URL | hbbs | 数据库文件路径(SQLite) |
| DOWNGRADE_START_CHECK | hbbr | 降级检查之前的延迟时间(秒) |
| DOWNGRADE_THRESHOLD | hbbr | 降级检查的阈值(bit/ms) |
| KEY | hbbs/hbbr | 若设置则强制使用指定密钥;若设置为 "_" 则强制使用任意密钥(即不接受未加密连接) |
| LIMIT_SPEED | hbbr | 速度限制(Mb/s) |
| PORT | hbbs/hbbr | 监听端口(hbbs 默认为 21116,hbbr 默认为 21117) |
| RELAY | hbbs | 运行 hbbr 的机器 IP 地址 / DNS 名称(逗号分隔多个) |
| RUST_LOG | 全部 | 设置日志级别(error|warn|info|debug|trace) |
| SINGLE_BANDWIDTH | hbbr | 单条连接的最大带宽(Mb/s) |
| TOTAL_BANDWIDTH | hbbr | 最大总带宽(Mb/s) |
命令行参数与端口的源码级细节
hbbs的命令行参数在 src/main.rs 中定义,支持-c/--config(自定义配置文件)、-p/--port(监听端口,默认 21116)、-s/--serial(配置更新序列号)、-R/--rendezvous-servers(会合服务器列表)、-u/--software-url(RustDesk 软件下载地址)、-r/--relay-servers(默认中继服务器)、-M/--rmem(UDP 接收缓冲区大小,需先通过sysctl调大net.core.rmem_max)、--mask(局域网掩码,如192.168.0.0/16,用于判断连接是否来自局域网)以及-k/--key(仅允许携带相同密钥的客户端连接)。启动时还会在后台线程每天检查一次软件新版本(check_software_update())。hbbr的参数定义在 src/hbbr.rs,支持-p/--port(监听端口,默认 21117)与-k/--key。值得注意的是:hbbr读取环境变量PORT时,实际监听端口会是PORT + 1(见src/hbbr.rs中port = v + 1的逻辑),因此部署中继服务器时应留意环境变量与命令行参数在端口语义上的差异,避免端口冲突。- 客户端接入时通过
-r参数获知中继服务器地址,hbbs会把该地址下发给客户端;因此中继端口(默认 21117)必须能被所有客户端访问到。
端口规划速查
综合 README 与 rustdesk-utils doctor 源码,自托管部署涉及的核心端口如下:
| 端口 | 协议 | 用途 |
|---|---|---|
| 21115 | TCP | hbbs 额外端口,NAT 类型测试 |
| 21116 | TCP/UDP | hbbs 主端口(信令与会合) |
| 21117 | TCP | hbbr 中继端口 |
| 21118 | TCP | hbbs WebSocket 端口 |
| 21119 | TCP | hbbr WebSocket 端口 |
自托管完成后,在 RustDesk 客户端设置中把 "ID/中继服务器" 填写为你的服务器地址,并在"密钥"一栏填入 id_ed25519.pub 中的公钥内容,即可让客户端与自建服务器完成加密握手。若你的服务端使用默认生成的密钥,务必通过 rustdesk-utils genkeypair 或查看 /data/id_ed25519.pub 获取公钥并配置到各客户端,否则客户端将因密钥不一致而无法通过服务器校验。