RustDesk Server 自托管部署完全指南:从源码编译到 Docker 密钥管理
RustDesk Server 自托管部署完全指南:从源码编译到 Docker 密钥管理
本文以 RustDesk Server(rustdesk-server)官方 README(荷兰语版 README-NL.md)为骨架,完整覆盖自托管部署的核心链路:源码编译出 hbbs/hbbr/rustdesk-utils 三个可执行文件、两类 Docker 镜像(经典镜像与 S6-overlay 镜像)的拉取与运行、密钥对的生成与安全托管,以及 hbbs/hbbr 的全部 ENV 配置变量。读完本文,你将能够独立完成一套生产可用的 RustDesk 服务器部署,并理解每个配置项背后的源码实现逻辑。
一、三个核心可执行文件与源码编译
RustDesk Server 是免费开源的服务器程序(源码位于 src/ 目录),整个仓库由 Cargo workspace 组织,核心包定义在 Cargo.toml。手把手编译非常简单,只需一条命令:
cargo build --release
编译完成后,target/release 目录下会生成三个可执行文件,它们构成 RustDesk 自托管服务端的全部组件:
| 可执行文件 | 角色 | 说明 |
|---|---|---|
hbbs |
RustDesk ID/Rendezvous 服务器 | 负责客户端 ID 注册、信令与 NAT 穿透协调 |
hbbr |
RustDesk 中继(relay)服务器 | 负责无法直连时的流量中继转发 |
rustdesk-utils |
RustDesk CLI 工具 | 提供密钥对生成、密钥校验、服务器连通性诊断等命令 |
从 Cargo.toml 可以看到这三个二进制分别对应 src/main.rs(默认运行目标 hbbs)、src/hbbr.rs 与 src/utils.rs。编译时默认启用 release 优化(lto = true、codegen-units = 1、strip = true,见 Cargo.toml),因此产物体积更小、运行时性能更好。
hbbs 的命令行参数在 src/main.rs 中定义,可通过 -p/--port 指定监听端口(默认 21116)、-r/--relay-servers 指定默认中继服务器、-k/--key 指定密钥以限制客户端接入等;hbbr 则支持 -p/--port(默认 21117)与 -k/--key(见 src/hbbr.rs)。这些参数同样可以通过环境变量注入,详见本文第七节。
如果你打算基于 RustDesk 做二次开发,官方还提供了更简单的起步仓库 rustdesk-server-demo(README 原文推荐),比本仓库更适合作为开发起点;本文聚焦的是直接部署与运行。
二、经典 Docker 镜像:rustdesk/rustdesk-server
2.1 镜像构成与可用标签
经典镜像(classic image)在每次 GitHub release 时自动构建并发布,基于 ubuntu-20.04 构建,镜像内只包含最核心的两个二进制 hbbr 与 hbbs。其 Dockerfile 见 docker-classic/Dockerfile,从 scratch 起步,仅复制两个二进制到 /usr/bin 并将工作目录设为 /root。镜像发布在 Docker Hub,可用标签如下:
| 架构 | image:tag |
|---|---|
| amd64 | rustdesk/rustdesk-server:latest |
| arm64v8 | rustdesk/rustdesk-server:latest-arm64v8 |
注意该镜像只内置 hbbr 和 hbbs,不包含 rustdesk-utils,也没有进程守护机制,因此需要分别启动两个容器来运行 hbbs 与 hbbr。
2.2 使用 host 网络直接运行
最直接的启动方式是使用 --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
其中 -v "$PWD/data:/root" 将宿主机当前目录下的 data 挂载到容器的 /root,用于持久化 hbbs 生成的密钥与数据库文件;hbbs -r 参数用于告知 hbbs 中继服务器的地址。
如果不用
--net=host,则必须显式做端口映射,但直接 P2P 连接将无法工作(NAT 穿透所需端口无法正确暴露)。
2.3 使用端口映射运行(非 host 网络)
对于无法使用 host 网络的场景(如 Docker Desktop、部分云主机),请使用端口映射方式:
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
各端口用途如下(与 src/utils.rs 中 doctor 命令的诊断口径一致):
| 端口 | 协议 | 服务 | 用途 |
|---|---|---|---|
| 21115 | TCP | hbbs | NAT 类型测试 |
| 21116 | TCP/UDP | hbbs | ID 注册与信令(主端口,UDP 用于穿透) |
| 21117 | TCP | hbbr | 中继服务主端口 |
| 21118 | TCP | hbbs | WebSocket 端口 |
| 21119 | TCP | hbbr | WebSocket 端口 |
relay-server-ip 指的是运行这些容器的服务器 IP(或 DNS 名称);可选的 port 参数仅在你为 hbbr 使用了非默认的 21117 端口时才需要显式指定,即写成 hbbs -r <ip>:<port> 的形式。
2.4 SELinux 系统注意事项
对启用 SELinux 的系统,把卷挂载路径 /root 改为 /root:z 即可让容器正常工作;或者通过添加 --security-opt label=disable 选项完全关闭 SELinux 容器隔离。
2.5 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 端口的机器); hbbr的command(hbbr)与hbbs的command(hbbs -r ...)可按需调整;depends_on: hbbr保证 hbbs 先于 hbbr 完成容器编排依赖。
三、S6-overlay 镜像:rustdesk/rustdesk-server-s6
3.1 镜像构成与可用标签
S6-overlay 镜像基于 busybox:stable 构建,在经典镜像基础上额外加入了 S6-overlay:基础镜像为 busybox:stable,默认 S6-overlay 版本 3.2.0.0,通过 COPY rootfs / 将 s6 服务编排脚本一并打入镜像,并默认声明 RELAY=relay.example.com、ENCRYPTED_ONLY=0 两个环境变量。
镜像发布在 Docker Hub,可用标签覆盖多架构与多个版本线:
| 架构 | 版本 | image:tag |
|---|---|---|
| multiarch | latest | rustdesk/rustdesk-server-s6:latest |
| amd64 | latest | rustdesk/rustdesk-server-s6:latest-amd64 |
| i386 | latest | rustdesk/rustdesk-server-s6:latest-i386 |
| arm64v8 | latest | rustdesk/rustdesk-server-s6:latest-arm64v8 |
| armv7 | latest | rustdesk/rustdesk-server-s6:latest-armv7 |
| multiarch | 2 | rustdesk/rustdesk-server-s6:2 |
| amd64 | 2 | rustdesk/rustdesk-server-s6:2-amd64 |
| i386 | 2 | rustdesk/rustdesk-server-s6:2-i386 |
| arm64v8 | 2 | rustdesk/rustdesk-server-s6:2-arm64v8 |
| armv7 | 2 | rustdesk/rustdesk-server-s6:2-armv7 |
| multiarch | 2.0.0 | rustdesk/rustdesk-server-s6:2.0.0 |
| amd64 | 2.0.0 | rustdesk/rustdesk-server-s6:2.0.0-amd64 |
| i386 | 2.0.0 | rustdesk/rustdesk-server-s6:2.0.0-i386 |
| arm64v8 | 2.0.0 | rustdesk/rustdesk-server-s6:2.0.0-arm64v8 |
| armv7 | 2.0.0 | rustdesk/rustdesk-server-s6:2.0.0-armv7 |
官方强烈建议使用 multiarch 标签配合 major version(如 2)或 latest 标签,以获得架构自适应与滚动更新体验。
3.2 S6-overlay 的监督机制
S6-overlay 充当 supervisor,同时维持 hbbs 与 hbbr 两个进程的运行,因此使用这个镜像时无需像经典镜像那样启动两个独立容器。容器编排脚本位于 docker/rootfs/etc/s6-overlay/s6-rc.d/:
- hbbs/run:进入
/data工作目录,若ENCRYPTED_ONLY=1则附加-k _参数,随后执行/usr/bin/hbbs -r $RELAY $PARAMS; - hbbr/run:同样进入
/data,按ENCRYPTED_ONLY附加参数后执行/usr/bin/hbbr $PARAMS。
镜像自带的 healthcheck.sh 通过 s6 的 s6-svstat 检查 hbbs、hbbr 两个服务目录的存活状态,配合 docker/Dockerfile 中的 HEALTHCHECK 指令每 10 秒检测一次。
3.3 启动方式
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
端口映射方式(不用 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
注意 s6 镜像的数据卷挂载点是 /data(而非经典镜像的 /root),这与 docker/Dockerfile 中声明的 WORKDIR /data、VOLUME /data 一致。
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
3.4 S6 镜像专属环境变量
在通用 ENV 变量(见第七节)之外,s6 镜像额外支持以下变量:
| 变量 | 是否可选 | 说明 |
|---|---|---|
RELAY |
否 | 运行本容器的主机 IP/DNS 名称(即中继地址) |
ENCRYPTED_ONLY |
是 | 若设为 "1",则拒绝接受未加密的连接(等价于给 hbbs/hbbr 附加 -k _) |
KEY_PUB |
是 | 密钥对的公钥部分 |
KEY_PRIV |
是 | 密钥对的私钥部分 |
RELAY 直接作为 /usr/bin/hbbs -r $RELAY 的参数传给 hbbs;ENCRYPTED_ONLY=1 时,hbbs/run 与 hbbr/run 都会追加 -k _,即“随机密钥 + 仅接受加密连接”模式。
四、密钥对:为什么需要、如何生成
4.1 密钥的作用
密钥对用于端到端加密:RustDesk 客户端与服务端之间通过共享密钥协商加密连接。你可以像上文那样把密钥交给服务端(通过环境变量或 secrets),但首先要有一条生成密钥对的途径。
4.2 生成密钥对
如果你安装了 rustdesk-utils 软件包,直接运行:
/usr/bin/rustdesk-utils genkeypair
如果系统上没有安装(或不打算安装)rustdesk-utils,可以用 s6 镜像以一次性容器方式执行同样的命令:
docker run --rm --entrypoint /usr/bin/rustdesk-utils rustdesk/rustdesk-server-s6:latest genkeypair
输出形如:
Public Key: 8BLLhtzUBU/XKAH4mep3p+IX4DSApe7qbAwNH9nv4yA=
Secret Key: egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hfgNICl7upsDA0f2e/jIA==
从源码看,genkeypair 基于 libsodium 的 Ed25519 签名体系实现(src/utils.rs),使用 sodiumoxide::crypto::sign::gen_keypair() 生成密钥对,公钥、私钥分别以 base64 编码输出。而 src/main.rs 中 hbbs 的 -k 参数正是用这把密钥来限制接入客户端——只有携带相同密钥的客户端才能连接,这是防止陌生人蹭用自建服务器的重要防线。
4.3 更多 CLI 子命令
rustdesk-utils 还提供两个实用的诊断命令(帮助文本见 src/utils.rs):
validatekeypair <a href="https://link.gitcode.com/i/e7e76a145f1a421bedf2cfb1ac0d0beb" target="_blank">public key] [secret key]:校验公钥/私钥是否匹配。其实现会尝试用私钥签名一段测试数据再用公钥验签,验签失败即判定密钥对无效([src/utils.rs);doctor <a href="https://link.gitcode.com/i/7ad4ad4bc0f6c9917abaf37f8786e124" target="_blank">rustdesk-server]:对指定服务器执行连通性诊断,依次检查 21114(API)、21115、21116、21117、21118、21119 共六个 TCP 端口的连通性,并输出解析到的 IP 及反向 DNS 比对结果([src/utils.rs)。
五、S6 镜像中的密钥托管与 Docker secrets
虽然可以把密钥对保存在 docker volume 中,但最佳实践建议不要将密钥明文写入文件系统,因此 s6 镜像内置了两套托管方案。容器启动时,key-secret/up.real 脚本会执行完整的密钥初始化流程:
- 检查
/data/id_ed25519.pub与/data/id_ed25519是否存在; - 若任一密钥缺失,则依次尝试从 docker secrets(
/run/secrets/key_pub、/run/secrets/key_priv)恢复,其次从KEY_PUB/KEY_PRIV环境变量恢复; - 校验密钥对有效性:如果两个密钥文件都存在,会修正权限为
0600、属主为root:root,并调用/usr/bin/rustdesk-utils validatekeypair验证公私钥匹配,不匹配则容器直接 halt 退出; - 只提供了其中一个密钥(公私不成对)时同样直接 halt 并提示必须同时提供两个密钥;
- 如果完全没提供密钥,则由 hbbs 在启动时自动生成并写入默认位置。
5.1 通过环境变量托管密钥
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
5.2 通过 Docker secrets 托管密钥
docker secrets 适用于 docker-compose 或 docker swarm 场景,密钥以受控方式挂载到 /run/secrets/,不落盘到镜像层。
先用 docker secret create 从本地密钥文件创建 secret:
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 的写法(secret 定义从本地文件 secrets/id_ed25519.pub、secrets/id_ed25519 读取):
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
结合 key-secret/up.real 的实现可以确认:secrets 的优先级高于环境变量——脚本先检查 /run/secrets/,再检查 KEY_PUB/KEY_PRIV,且只有在对应密钥文件不存在时才会执行恢复动作,已存在的密钥不会被覆盖。
六、Debian 软件包安装
每次 release 都会为每个二进制发布独立的 .deb 包(rustdesk-server-hbbs、rustdesk-server-hbbr、rustdesk-server-utils),适用于以下发行版:
- Ubuntu 22.04 LTS
- Ubuntu 20.04 LTS
- Ubuntu 18.04 LTS
- Debian 11 bullseye
- Debian 10 buster
仓库内 debian/ 目录包含完整的打包配方:三个软件包的元数据定义在 debian/control.tpl,rustdesk-server-hbbs 与 rustdesk-server-hbbr 依赖 systemd(对应 systemd/rustdesk-hbbs.service 与 systemd/rustdesk-hbbr.service 两个单元文件,由 postinst 脚本安装),rustdesk-server-utils 则是纯 CLI 工具包。安装 hbbs/hbbr 包后,服务会以 systemd 方式常驻并自动重启(Restart=always、RestartSec=10),日志分别追加写入 /var/log/rustdesk-server/hbbs.log 与 /var/log/rustdesk-server/hbbs.error,工作目录为 /var/lib/rustdesk-server/。
七、ENV 变量详解(附源码级解析)
hbbs 与 hbbr 都可以通过环境变量配置。除了常规的 export 方式,在启动目录放置一个 .env 文件同样会被读取——src/hbbr.rs 会使用 ini 解析器加载当前目录下的 .env 文件并把键值写入进程环境。完整变量清单如下:
| 变量 | 适用二进制 | 说明 |
|---|---|---|
ALWAYS_USE_RELAY |
hbbs | 若设为 "Y",则不允许客户端直接 P2P 连接 |
DB_URL |
hbbs | 数据库文件路径 |
DOWNGRADE_START_CHECK |
hbbr | 降级(downgrade)检查的延迟时间(秒) |
DOWNGRADE_THRESHOLD |
hbbr | 降级检查的阈值(bit/ms) |
KEY |
hbbs/hbbr | 若设置则强制使用指定密钥;若设为 "_" 则强制使用随机密钥 |
LIMIT_SPEED |
hbbr | 速度限制(Mb/s) |
PORT |
hbbs/hbbr | 监听端口(hbbs 默认 21116,hbbr 默认 21117) |
RELAY_SERVERS |
hbbs | 运行 hbbr 的主机 IP/DNS 名称(逗号分隔) |
RUST_LOG |
全部 | 设置调试级别(error|warn|info|debug|trace) |
SINGLE_BANDWIDTH |
hbbr | 单条连接的最大带宽(Mb/s) |
TOTAL_BANDWIDTH |
hbbr | 中继的总带宽上限(Mb/s) |
以下是每个变量在源码中的具体实现位置与行为细节:
ALWAYS_USE_RELAY:在 src/rendezvous_server.rs 中读取,值转大写后与"Y"比较,命中则把全局原子标志ALWAYS_USE_RELAY置为 true。该标志在 src/rendezvous_server.rs 的穿透决策中生效:ALWAYS_USE_RELAY为真(或双方不在同一局域网)时强制走中继,从而禁止 P2P 直连。DB_URL:在 src/peer.rs 中读取,用于指定 hbbs 持久化数据的 SQLite 数据库文件路径;未设置时默认使用db_v2.sqlite3(位于运行目录)。DOWNGRADE_START_CHECK/DOWNGRADE_THRESHOLD:在 src/relay_server.rs 中读取。DOWNGRADE_START_CHECK以秒为单位,内部换算为毫秒存储(* 1000);DOWNGRADE_THRESHOLD以 bit/ms 为单位,内部放大 100 倍为整数存储(* 100.)。两者用于控制中继在延迟/带宽劣化时的降级判定。LIMIT_SPEED/TOTAL_BANDWIDTH/SINGLE_BANDWIDTH:在 src/relay_server.rs 中读取,单位均为 Mb/s,内部换算为字节(* 1024 * 1024)。SINGLE_BANDWIDTH限制单条连接的带宽,TOTAL_BANDWIDTH限制整个中继的总带宽,LIMIT_SPEED则是在两者之外的速度上限。三者都只在值大于 0 时生效。KEY:hbbr 在 src/hbbr.rs 中读取作为-k参数的兜底值;hbbs 同理。设为"_"时使用随机密钥(s6 镜像的ENCRYPTED_ONLY=1正是通过追加-k _实现只允许加密连接)。PORT:hbbr 在 src/hbbr.rs 中读取,注意一个特殊行为:hbbr 内部监听的是PORT + 1(因为 21116 的主端口被 hbbs 占用,hbbr 默认实际监听 21117),因此设置PORT=21116时 hbbr 实际监听 21117,与 hbbs 的端口体系保持一致。hbbs 侧端口同样受该变量影响(默认 21116)。RELAY_SERVERS:README 中列为 hbbs 的配置项,从源码看与之对应的是 hbbs 的-r/--relay-servers参数(src/main.rs 与 src/rendezvous_server.rs),支持逗号分隔多个中继;src/rendezvous_server.rs 显示 hbbs 会轮询(round-robin)选取其中一个中继服务器分配给客户端。RUST_LOG:由 src/main.rs 与 src/hbbr.rs 中的flexi_logger::Logger::try_with_env_or_str("info")读取,未设置时默认日志级别为info,支持error|warn|info|debug|trace逐级调高输出量。
八、部署要点速查
综合以上内容,完成一套自托管 RustDesk 服务器部署的最小路径如下:
- 准备服务器:一台具有公网 IP 的主机,放行 TCP 21115/21116/21117/21118/21119 与 UDP 21116 端口;
- 选择部署方式:二进制编译(
cargo build --release)、经典 Docker 镜像(双容器)或 S6-overlay 镜像(单容器,推荐)三者任选其一; - 配置密钥:用
rustdesk-utils genkeypair生成密钥对,通过KEY_PUB/KEY_PRIV环境变量或 docker secrets 注入,或直接省略让 hbbs 自动生成; - 告知中继地址:通过
-r参数或RELAY环境变量把 hbbr 所在主机地址交给 hbbs; - 可选加固:设置
ENCRYPTED_ONLY=1拒绝非加密连接;通过SINGLE_BANDWIDTH/TOTAL_BANDWIDTH限制带宽占用;对公网环境用ALWAYS_USE_RELAY=Y强制走中继。
部署完成后,在 RustDesk 客户端中填入服务器地址与密钥(若设置了 KEY),即可让客户端通过你的自建服务器完成注册、穿透与中继,实现完全自主可控的远程桌面服务。